Network Wizards Cellular Telephone Library Routines Copyright (C) 1994 by Network Wizards USING THE PROGRAMMING LIBRARIES The programming library file is CTLIB.OBJ. The module and all other code were written in Borland Turbo C 2.0 using the small memory model, and word alignment (switches "-a -ms"). See the enclosed Makefile for compiling examples. Any programs you write need to include CTLIB.H, and be linked with CTLIB.OBJ, TTY.OBJ, and TTYA.OBJ. If you have trouble linking these with other compilers, please contact us for help. [Note: There is a bug in the delay() function of Turbo C which may cause programs to not work on 486 machines. If you have this problem you can get a patch file from the Borland BBS at (408) 439-9096] CTLIB.H contains function header prototypes, structure element descriptions, and predefined constants. TTY.OBJ and TTYA.OBJ contain serial I/O code used by CTLIB.OBJ to talk to the COM port the interface adapter is attached to. The function descriptions use the following data types: typedef unsigned char bool; typedef unsigned char byte; typedef unsigned int word; /* 16 bits */ ====================================================================== FUNCTION SUMMARY INITIALIZATION ct_lib_init initialize library routines ct_lib_done cleanup after library routines ct_on turn phone on ct_off turn phone off OPERATION ct_keypress "press" a key on phone TRANSMISSION ct_set_channel select channel number ct_set_carrier turn transmitter on or off ct_set_tx_power set transmit power level ct_set_sat select sat tones AUDIO ct_set_audio_path set source/destination of audio signals ct_set_rx_audio mute or unmute received audio ct_set_tx_audio mute or unmute transmitted audio ct_set_volume set audio volume level ct_set_audio_tone select audio alerting tones ct_set_dtmf transmit DTMF tones ct_dtmf_decode receive DTMF tones ct_set_comp_exp turn compressor/expandor circuit on or off DATA AND SIGNALLING ct_fcc_msg receive a Forward Control Channel message ct_fvc_msg receive a Forward Voice Channel message ct_rcc_msg send a Reverse Control Channel message ct_rvc_msg send a Reverse Voice Channel message ct_set_signalling_tone turn signalling tone on or off ct_stream set reception on even or odd data stream ct_get_bi get busy/idle status STATUS ct_get_rss read received signal strength ct_get_battery_level read battery level MEMORIES ct_read_mem read telephones internal memory ct_read_block read memory block from phone ct_set_block write memory block to phone ct_get_esn read ESN from phone ct_get_romver read ROM version number from phone ct_get_prog_pwd read programming password from phone ct_get_cust_msg read custom power on message from phone ct_set_cust_msg write custom power on message to phone ct_get_nams read NAMs out of phone ct_set_nams write NAMs into phone UTILITIES ct_inc_channel increment to next channel ct_dec_channel decrement to next channel ct_channel_type return type of channel ct_decode_fcc_msg decode a forward control channel message ct_decode_fvc_msg decode a forward voice channel message ct_decode_order decode a received order ct_tel2min convert a telephone number to a MIN ct_gen_bch generate a BCH error correction code ====================================================================== PHONE CONTROL FUNCTIONS int ct_lib_init(model,addr,irq) word model; word addr; byte irq; Initializes the cellular library routines and serial I/O routines. This routine must be called only once before any other routine may be used. model is the cellular telephone model number to be accessed, one of: model Description 900 OKI-900 or AT&T-3730 1150 OKI-1150 or AT&T-3760 [either model number can be used and ctlib will figure out what type of phone it is really talking to] addr is the I/O address of the serial port UART. irq is the interrupt request line of the UART. addr and irq are typically set as follows: port (addr,irq) COM1 (0x3f8,4) COM2 (0x2f8,3) Returns TRUE on success. void ct_lib_done() Cleans up the cellular and serial I/O routines. This routine must be called before exiting your program. int ct_on(mode) word mode; Power up the phone in normal or test/debug mode. mode is one of MODE_NORMAL or MODE_TEST. All routines in this library function only in MODE_TEST, except for ct_keypress() which only works in MODE_NORMAL. Returns TRUE on success. void ct_off() Power down the phone. void ct_keypress(key) int key; This function may only be used if the phone is powered up in MODE_NORMAL. A key is "pressed" by sending its keypress code defined in ctlib.h. A key is "released" by sending the release code. void ct_set_carrier(state) bool state; Turns the transmitter on (TRUE) or off (FALSE). void ct_set_tx_power(level) int level; Sets the transmitter power attenuation level, zero being the highest power level (from 0-7). See cellular specs for definition of the attenuation levels. void ct_set_sat(sat) int sat; Controls the transmission of SAT tones. sat is 0 thru 3 as follows: SAT Operation 0 transmit 5970hz SAT 1 transmit 6000hz SAT 2 transmit 6030hz SAT 3 disable transmission of SAT tones void ct_set_dtmf(tone) byte tone; Begins transmission of a DTMF tone. Tone is one of the standard values represented by "1234567890*#ABCD". If tone is an ASCII space, DTMF transmission is stopped. The following special tones "efghijkl" are defined as follows: e 697hz (row1) i 1209hz (col1) f 770hz (row2) j 1336hz (col2) g 852hz (row3) k 1477hz (col3) h 941hz (row4) l 1633hz (col4) void ct_set_signalling_tone(state) bool state; Begins transmitting a 10khz signalling tone (TRUE) or stops it (FALSE). void ct_set_audio_tone(tone,state) int tone; bool state; Turns a tone on (TRUE) or off (FALSE). The tone is sent to the current received audio path. The tone is one of: Tone Value Frequency TONE_LOW 770hz TONE_HIGH 1150hz void ct_set_rx_audio(state) bool state; Mutes (FALSE) or Unmutes (TRUE) the received audio signal. void ct_set_tx_audio(state) bool state; Mutes (FALSE) or Unmutes (TRUE) the transmitted audio signal. void ct_set_comp_exp(state) bool state; Enables (TRUE) or disables (FALSE) the audio compressor and expandor circuits. void ct_set_volume(vol) int vol; Sets the audio output volume (0-7). 0 is the highest level. void ct_set_audio_path(path) int path; Sets the audio path to and from the radio. One of: Path Description AUDIO_EXTERNAL audio routed to external jack AUDIO_EARPIECE input from mic, output to earpiece AUDIO_SOUNDER input from mic, output to earpiece and sounder void ct_set_channel(channel) word channel; Tunes the cellular phone to the specified channel (1-1023). int ct_dtmf_decode(command) int command; Decodes DTMF tones received from the radio. No other commands may be sent to the phone between START and END of decoding period. command is one of: DTMF_DECODE_START Start listening for DTMF tones (always returns TRUE). DTMF_DECODE_GET Returns FALSE if no valid tones received so far, or the ASCII value of one of "1234567890*#ABCD". DTMF_DECODE_END End listening for DTMF tones (always returns TRUE). int ct_fvc_msg(command,data) int command; byte *data; Receives a message sent on the Forward Voice Channel, from the land station to mobile station. MSG_SETUP must be called to get the phone ready to receive the next message. MSG_GET can then be called to find out when it arrives. If a message is not received, MSG_ABORT can be used to end the MSG_SETUP waiting mode. No other commands can be issued to the phone if it is waiting for a message. command is one of: MSG_SETUP Start listening for the next FVC message on the current voice channel. MSG_GET Returns FALSE if no messages have been received so far, or TRUE and the message in the location pointed to by data. MSG_ABORT Abort listening for FVC messages. data is NULL for MSG_SETUP and MSG_ABORT. For MSG_GET, data points to a 5 byte array to put the received message into. int ct_fcc_msg(command,data) int command; byte *data; Receives a message sent on the Forward Control Channel, from the land station to mobile station. MSG_SETUP must be called to get the phone ready to receive the next message. MSG_GET can then be called to find out when it arrives. If a message is not received, MSG_ABORT can be used to end the MSG_SETUP waiting mode. No other commands can be issued to the phone if it is waiting for a message. command is one of: MSG_SETUP Start listening for the next FCC message on the current control channel. MSG_GET Returns FALSE if no messages have been received so far, or TRUE and the message in the location pointed to by data. MSG_ABORT Abort listening for FCC messages. data is NULL for MSG_SETUP and MSG_ABORT. For MSG_GET, data points to a 10 byte array to put the received message into. int ct_rcc_msg(dcc,data) int dcc; byte *data; Sends a Reverse Control Channel message, from the mobile to the land station. dcc is the Digital Color Code received from the land station (0-3). data is a 30 byte array, consisting of five 6-byte words. Returns TRUE if dcc and ESN (in data) are valid. int ct_rvc_msg(data) byte *data; Sends a Reverse Voice Channel message, from the mobile to the land station. data is a 12-byte array, consisting of two 6-byte words. Always returns TRUE. int ct_get_rss() Returns signal strength of currently tuned channel. Value is adjusted for approximate range of 0-99 (99 is strongest). -1 is returned on error. int ct_get_battery_level(volts) float *volts; Returns battery level (0-8). If volts is not NULL, it is set to the estimated battery voltage. int ct_read_mem(dest,addr,n) byte *dest; word addr; int n; Reads a contiguous block of memory from the cellular phone. dest points to a destination area where n bytes will be placed. The block is read from the cellular phones internal memory space starting at addr. Returns TRUE on success, FALSE otherwise. int ct_read_block(dest,addr,n) byte *dest; word addr; int n; Reads a block of memory from the cellular phone. dest points to a destination area where n bytes will be placed. The block is read from the cellular phones internal memory space starting at addr, but not necessarily incrementing addr by one for the next byte, because some phones skip over certain protected addresses in the memory space. Returns TRUE on success, FALSE otherwise. int ct_get_esn(esn) unsigned long *esn; Places the cellular phones Electronic Serial Number (32-bits) into the unsigned long pointed to by esn. Returns TRUE on success, FALSE otherwise. char *ct_get_romver() Returns a pointer to an internal string identifying the cellular telephone ROM version. char *ct_get_prog_pwd() Returns a pointer to an internal string identifying the cellular telephone programming password. char *ct_get_cust_msg() Returns a pointer to an internal string which is displayed by the cellular telephone as a custom power on message. int ct_set_cust_msg(msg) byte *msg; Given a string, sets the custom power on message displayed by the cellular phone. Returns TRUE if ok, FALSE otherwise. int ct_get_nams() Reads NAM information from the cellular telephone. Returns TRUE if ok. The NAM information is placed in the following data structure defined in ctlib.h: struct nam_data { char number[15] ;Tel Num: "(nnn) nnn-nnnn" char sid[6] ;System Id: nnnnn char sys ;System: 'A' or 'B' char ipch[5] ;Initial Paging Channel: nnnn char olc[3] ;Overload Class: nn char gim[3] ;Group ID Mark: nn } nam_info[5] ; for each of 5 NAMs int ct_set_nams() Set NAM information into the cellular telephone. Returns TRUE if ok. The NAM information from the data structure defined above is written into the cellular phone. The data must be formatted the same way as ct_get_nams() returns it. The 'sys' char is not used when writing. This routine must not be interrupted or an invalid NAM block will be sent to the phone causing it to display an error when the phone is returned to normal operating mode. It may also be wise to use ct_get_battery_level() before calling this function and make sure it is at a reasonable level and not about to die, as this function will take a little while to complete. The ct_get_nams() function should be called at least once before changing any information and using ct_set_nams(). If ct_get_nams() has not been called, then ct_set_nams() will return FALSE. int ct_stream(stream) int stream; Sets or returns the status of whether the transceiver is receiving on the even or odd data stream of the control channel. If stream is -1, then the status is returned (0 for even stream, 1 for odd). If stream is 0 or 1, then the stream is changed to correspond to the setting, and its new status is returned (or old status if it couldn't switch). NOTE: Older versions of this function required at least one NAM be programmed as even and one as odd. This is no longer required. int ct_get_bi() Returns the status of the busy/idle bit when tuned to a valid control channel. Returns FALSE if busy and TRUE if idle. This bit indicates the status of the reverse control channel at the instant it was polled, and is already invalid by the time this function reports it. struct ct_state_struct { bool carrier; bool sigtone; bool rxaudio; bool txaudio; bool compexp; int powerlevel; int sat; int volume; int audiopath; int channel; int stream; int namindex; int oldnam; } ct_state; This structure contains internal state kept by the library routines. It may be read but should not be changed. ====================================================================== UTILITY ROUTINES word ct_inc_channel(channel) word channel; Given a channel number, returns next voice channel number in the current system (A/B), then the next system, then wraps around. word ct_dec_channel(channel) word channel; Given a channel number, returns previous voice channel number in the current system (A/B), then the next system, then wraps around. int ct_channel_type(channel,system,type) word channel; byte *system; byte *type; Given a channel number, returns two bytes indicating: system 'A' system A 'B' system B type 'A' audio channel 'C' control channel Returns TRUE if valid channel number was given, FALSE otherwise. int ct_decode_fvc_msg(msg,scc,pscc,order,ordq,local,chan,vmac) byte *msg; int *scc,*pscc,*order,*ordq,*local,*chan,*vmac; Given a pointer to a 5-byte Forward Voice Channel message in msg, it decodes the message into the listed fields. Returns TRUE if OK, or FALSE if invalid message. If scc is 0, 1, or 2, then pscc, chan, and vmac are returned. Otherwise scc is 3 (invalid scc), and pscc, order, ordq, and local are returned. scc SAT color code for new channel (if 0, 1, or 2) pscc present SAT color code of current channel order order type ordq order qualifier local local control field (when order is local control type) chan new voice channel number vmac new voice channel mobile attenuation code int ct_decode_fcc_msg(msg,scc,dcc,min,order,ordq,local,chan,vmac) byte *msg, **min; int *scc,*dcc,*order,*ordq,*local,*chan,*vmac; Given a pointer to a 10-byte Forward Control Channel message in msg, it decodes the message into the listed fields. Returns TRUE if OK, or FALSE if invalid message. If TRUE, always returns scc, dcc and min. If scc is 0, 1, or 2, then chan, and vmac are returned. Otherwise scc is 3 (invalid scc), and order, ordq, and local are returned. scc SAT color code for new channel (if 0, 1, or 2) dcc digital color coded field min returns a pointer to a string with the Mobile Id Number formatted as "(nnn) nnn-nnnn". The string is overwritten on each call. order order type ordq order qualifier local local control field (when order is local control type) chan voice channel number char *ct_decode_order(order,ordq) int order, ordq; Given an order and order qualification code (such as those returned from ct_decode_fvc_msg() and ct_decode_fcc_msg(), returns a pointer to a string describing the order. The string pointed is overwritten on each call. void ct_tel2min(telnum,min1,min2) char *telnum; unsigned long *min1, *min2; Given a phone number in "(nnn) nnn-nnnn" format, it is returned encoded as min1 and min2 as defined by the cellular specifications. word ct_gen_bch(bits,buf) int bits; unsigned char *buf; Generates a BCH error correcting code. Takes number of bits to generate a bch code for, and pointer to first byte of data buffer containing the data bits. Deposits 12-bit BCH code into buffer right after the given number of data bits.