The Unsorted BBS Collection/thegreatunsorted.tar/thegreatunsorted/texts/cell_nfo/ctlib.txt

Text File | 1994-06-20 | 18KB | 631 lines

        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 [phone]]

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.