home *** CD-ROM | disk | FTP | other *** search
- 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.
-