vrecko
virtual reality framework
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
hci.h
Go to the documentation of this file.
1 /***************************************************
2  * - - - - - - - IMMERSION CORP. - - - - - - - *
3  * *
4  * Platform-independent software series *
5  * Copyright (c) 1993 *
6  ***************************************************
7  * HCI.C | SDK1-2a | January 1996
8  *
9  * Immersion Corp. Software Developer's Kit
10  * Functions for direct communication with the Immersion HCI
11  * Not for use with the Probe or Personal Digitizer
12  * Requires Microscribe HCI firmware version MSCR1-1C
13  */
14 
15 
16 #ifndef hci_h
17 #define hci_h
18 
19 #include "classes.h"
20 
21 /*-----------*/
22 /* Constants */
23 /*-----------*/
24 
25 #define HCI_CHECK_FGND 1
26 #define HCI_CHECK_BGND 2
27 #define HCI_CHECK_MOTION 3
28 
29 #define NUM_ENCODERS 7 /* Max # encoders supported by Immersion HCI */
30 #define NUM_ANALOGS 8 /* Max # of A/D channels supported */
31 #define NUM_BUTTONS 7 /* Max # of buttons supported */
32 
33 /* These numbers are the maximum numbers available in Immersion HCI hardware.
34  * Various Immersion Corp. products based on the Immersion HCI will
35  * support various subsets of these components.
36  */
37 
38 
39 /*------------*/
40 /* Data Types */
41 /*------------*/
42 
43 /* Constants for hci_result variables */
44 extern char BAD_PORT_NUM[]; /* Port number not valid */
45 extern char CANT_OPEN_PORT[]; /* Can't open the port during start-up */
46 extern char NO_HCI[]; /* No response from HCI during start-up */
47 extern char CANT_BEGIN[]; /* No response to "BEGIN" at start of session */
48 extern char NO_PACKET_YET[]; /* Complete packet not yet recv'd */
49 extern char TIMED_OUT[]; /* Didn't get complete packet in time */
50 extern char BAD_PACKET[]; /* Received packet that did not make sense */
51 extern char BAD_PASSWORD[]; /* Cfg cmd requiring passwd was denied */
52 extern char SUCCESS[]; /* Successful operation */
53 extern char TRY__AGAIN[]; /* Try the operation again */
54 extern char BAD_VERSION[]; /* Feature isn't supported by firmware */
55 extern char BAD_FORMAT[]; /* Parameter block is in unreadable format */
56 
57 
58 /* # of bytes in longest possible packet, plus some extra room */
59 #define MAX_PACKET_SIZE 42
60 
61 /* Max # of args to a special config command */
62 #define MAX_CFG_SIZE 40
63 
64 /* Max length of descriptor string from HCI */
65 #define MAX_STRING_SIZE 32
66 
67 /* Space for arguments to config commands */
68 extern byte cfg_args[MAX_CFG_SIZE];
69 extern int num_cfg_args; /* # of values stored in cfg_args[] */
70 
71 /* Record for packet
72  */
73 typedef struct
74 {
75  int parsed; /* Flag tells whether this packet has been parsed */
76  int error; /* Flag tells whether there has been com error */
77  int num_bytes_needed;
78  byte cmd_byte;
79  byte data[MAX_PACKET_SIZE];
80  byte *data_ptr;
81 } packet_rec;
82 
83 
84 /* Record containing all HCI data
85  * Declare one of these structs for each Immersion HCI in use.
86  * The hci_connect() command will establish communication with an Immersion
87  * HCI and set up an hci_rec corresponding to it.
88  * Example references: (assuming 'hci' is declared as an hci_rec)
89  * hci.button[2] - ON/OFF status of button #2
90  * hci.encoder[1] - total count for encoder #1
91  */
92 class Hci
93 {
94  private:
95  /* Communications parameters */
96  char port[20]; /* This HCI's serial port number */
97  int slow_timeout; /* Timeout period for slow process */
98  int fast_timeout; /* Timeout period for fast process */
99  packet_rec packet; /* The current packet */
100  int packets_expected; /* Determines whether timeout is important */
101 
102  /* Marker field lets you mark different segments of data in incoming
103  * buffer. hci_insert_marker() makes HCI insert a marker into the
104  * data stream, so you can switch modes in a host application
105  * without misinterpreting some data that may still be waiting
106  * in the buffer; just insert a marker, and don't switch modes
107  * until you see the marker come back.
108  */
109  int marker;
110  int marker_updated;
111 
112 
113  /* Encoder "home" position:
114  * The relative encoders supported by the Immersion HCI only report
115  * their NET angular motion from the time they are powered up. If
116  * an encoder's initial angular value is important, it must somehow
117  * be assumed or calibrated at start-up. These fields contain values
118  * to be assumed at start-up. They can be read from or written to the
119  * Immersion HCI EEPROM. If written to the Immersion HCI EEPROM,
120  * these "home" values will be retained even after power is turned off.
121  */
122  int home_pos [NUM_ENCODERS];
123 
124  /* Home position references:
125  * In many cases some calibration procedure will be required to ensure
126  * that the encoder positions truly match the assumed home position.
127  * This array can store any data that is useful for that purpose.
128  */
129  int home_ref [NUM_ENCODERS];
130 
131 
132  /* Extra field available for user's application-specific purpose */
133  long int user_data;
134 
135  /* Conversion between baud rates and 6811 BAUD register codes */
136 /* byte baud_to_code(long int baud);
137  long int code_to_baud(byte code);*/
138  int packetSize(int cmd);
139 
140  public:
141  /* Descriptor strings:
142  * These strings provide information about a particular HCI system.
143  */
144  char serial_number [MAX_STRING_SIZE];
145  char product_name [MAX_STRING_SIZE];
146  char product_id [MAX_STRING_SIZE];
147  char model_name [MAX_STRING_SIZE];
148  char comment [MAX_STRING_SIZE];
149  char param_format [MAX_STRING_SIZE];
150  char version [MAX_STRING_SIZE];
151 
152  /* Primary quantities: */
153  int buttons; /* button bits all together */
154  int button [NUM_BUTTONS]; /* ON/OFF flags for buttons */
155  long timer; /* Running counter */
156  int analog [NUM_ANALOGS]; /* A/D channels */
157  int encoder [NUM_ENCODERS]; /* Encoder counts */
158 
159  /* Status of primary fields:
160  * A zero in any of these fields indicates that the corresponding
161  * primary quantity is out of date (wasn't updated by the
162  * previous packets)
163  * Note: buttons are updated with every packet
164  */
165  int timer_updated;
166  int analog_updated [NUM_ANALOGS];
167  int encoder_updated [NUM_ENCODERS];
168 
169  /* Normalization values for primary quantities:
170  * These values give some reference or normalization quantity
171  * for each field.
172  * A zero in any of these fields means there is no hardware
173  * support for that data in this particular system.
174  */
175  int button_supported [NUM_BUTTONS]; /* zero = butt not supported */
176  int max_timer; /* Max count reached before wrapping */
177  int max_analog [NUM_ANALOGS]; /* Full-scale A/D reading */
178  int max_encoder [NUM_ENCODERS]; /* Max value each encoder reaches
179  * INCLUDING quadrature */
180 
181 
182  /* Function pointers to handle application-specific functions
183  * These pointers are initialized to NULL.
184  * The user can make these point to handlers for each specific condition.
185  * These handlers must be declared as follows:
186  * hci_result my_handler(hci_rec *hci, hci_result condition);
187  * See programmer's guide for more discussion.
188  */
189 
190  /* Handlers for errors */
191  hci_result (*BAD_PORT_handler)(hci_result condition);
192  hci_result (*CANT_OPEN_handler)(hci_result condition);
193  hci_result (*NO_HCI_handler)(hci_result condition);
194  hci_result (*CANT_BEGIN_handler)(hci_result condition);
195  hci_result (*TIMED_OUT_handler)(hci_result condition);
196  hci_result (*BAD_PACKET_handler)(hci_result condition);
197  hci_result (*BAD_PASSWORD_handler)(hci_result condition);
198  hci_result (*BAD_VERSION_handler)(hci_result condition);
199  hci_result (*BAD_FORMAT_handler)(hci_result condition);
200 
201  /* Handler to use for an error if everything above is NULL
202  * The simplest way to get diagnostic reporting is to
203  * set default_handler to a function that outputs the string
204  * that is passed as the 'condition'. This can be implemented
205  * under any operating system or window environment by including
206  * the appropriate o.s. calls in the function pointed to by
207  * this handler pointer.
208  */
209  hci_result (*default_handler)();
210 
211 
212  /*---------------------*/
213  /* Function Prototypes */
214  /*---------------------*/
215 
216  /* Initialize and setup an hci_rec */
217  void init(const char* port);
218  hci_result connect();
219  void disconnect();
220  hci_result getStrings();
221 // void resetCom();
222  hci_result autosynch();
223  hci_result begin();
224  void end();
225  void clearPacket();
226  void comParams(const char* port);
227  void fastTimeout();
228  void slowTimeout();
229 
230 /* Issuing commands to HCI */
231  void stdCmd(int timer_flag, int analog_reports,
232  int encoder_reports);
233  void simpleCfgCmd(byte cmnd);
234  hci_result stringCmd(byte cmnd);
235 // hci_result passwdCmd(byte cmnd);
236 // void insertMarker(byte marker);
237  hci_result getParams(byte *block, int *block_size);
238  hci_result getExtParams(byte *block, int *block_size);
239 /* hci_result setParams(byte *block, int block_size);
240  hci_result getHomeRef();
241  hci_result setHomeRef(int *homeref);*/
242  hci_result goHomePos();
243 /* hci_result setHomePos(int *homepos);*/
244  hci_result getMaxes();
245 /* hci_result factorySettings();
246  void reportMotion(int timer_flag, int analog_reports,
247  int encoder_reports, int delay, byte active_btns,
248  int *analog_deltas, int *encoder_deltas);
249  void endMotion();*/
250 
251  /* Compatibility Checking */
252 // float versionNum();
253 
254  /* Packet monitoring functions */
255  hci_result waitPacket();
256  hci_result checkPacket(int checkType);
257 // hci_result checkMotion();
258  hci_result buildPacket(int checkTYpe);
259 
260  /* Packet parsing functions */
261  hci_result parsePacket();
262  hci_result parseCfgPacket();
263 
264  /* Helper functions */
265  hci_result readString(char *str);
266  hci_result readBlock(byte *block, int *bytes_read);
267  void invalidateFields();
268 /* void strcopy(char *from, char *to);
269  int strcmp(char *s1, char *s2);*/
270 
271  /* Error handling */
272  hci_result error(hci_result condition);
273  hci_result simpleString(hci_result condition);
274 
275 };
276 
277 
278 
279 /* Macro for creating a command byte from a timer flag and the # of analog
280  * and encoder reports desired
281  */
282 #define CMD_BYTE(t, anlg, encd) \
283  ( (t ? TIMER_BIT : 0) \
284  | (anlg > 4 ? ANALOG_BITS : \
285  (anlg > 2 ? ANALOG_HI_BIT : \
286  (anlg ? ANALOG_LO_BIT : 0))) \
287  | (encd > 6 ? ENCODER_HI_BIT : \
288  (encd > 5 ? ENCODER_BITS : \
289  (encd ? ENCODER_LO_BIT : 0))) )
290 
291 
292 /*---------------------*/
293 /* Low-level Constants */
294 /*---------------------*/
295 
296 /* Labels for the Special Configuration Commands */
297 #define CONFIG_MIN 0xC0 /* Minimum cmd byte for a config cmd */
298 #define GET_PARAMS 0xC0
299 #define GET_HOME_REF 0xC1
300 #define HOME_POS 0xC2
301 #define SET_HOME 0xC3
302 #define SET_BAUD 0xC4
303 #define END_SESSION 0xC5
304 #define GET_MAXES 0xC6
305 #define SET_PARAMS 0xC7
306 #define GET_PROD_NAME 0xC8
307 #define GET_PROD_ID 0xC9
308 #define GET_MODEL_NAME 0xCA
309 #define GET_SERNUM 0xCB
310 #define GET_COMMENT 0xCC
311 #define GET_PRM_FORMAT 0xCD
312 #define GET_VERSION 0xCE
313 #define REPORT_MOTION 0xCF
314 #define SET_HOME_REF 0xD0
315 #define RESTORE_FACTORY 0xD1
316 #define INSERT_MARKER 0xD2
317 #define GET_EXT_PARAMS 0xD3
318 
319 /* Command bit-field place values */
320 #define PACKET_MARKER 0x80
321 #define CONFIG_BIT 0x40
322 #define TIMER_BIT 0x20
323 #define FUTURE_BIT 0x10
324 #define ANALOG_BITS 0x0C
325 #define ANALOG_HI_BIT 0x08
326 #define ANALOG_LO_BIT 0x04
327 #define ENCODER_BITS 0x03
328 #define ENCODER_HI_BIT 0x02
329 #define ENCODER_LO_BIT 0x01
330 
331 /* A timeout period is the time to transmit this many chars */
332 #define TIMEOUT_CHARS 2*MAX_PACKET_SIZE
333 
334 /* Time (sec) to wait between signon attempts in 'connect' process */
335 #define SIGNON_PAUSE 15
336 
337 /* Time (sec) to wait after ending session */
338 #define END_PAUSE 15
339 
340 /* Time (sec) to wait for each byte arg to a passwd-protected cfg cmd */
341 #define CFG_ARG_PAUSE 15
342 
343 /* Time (sec) to wait after restoring factory settings */
344 #define RESTORE_PAUSE 2000
345 
346 /* Code sent by HCI to accept a password */
347 #define PASSWD_OK 0xFF
348 
349 
350 #endif /* hci_h */
351