INTRODUCTION
------------

The StarTac phone connects to a standard serial port on a computer.
It initially speaks to the computer like a modem, and a special AT
command followed by a sequence of bytes puts the phone into "data
mode" (that's my terminology).  Once the phone is in data mode, it
communicates with the computer over a simple binary reply-response
protocol.

To see more detail of what StarTalk exchanges with the phone, run it
with the '-d3' switch, and everything sent to or received from the
phone will be dumped.  If you have another program that can talk to
your StarTac phone, see the file INTERCEPTTY for information on
dumping the data sent to and received from the phone.


PACKET FORMAT
-------------

All packets used for the exchange of data between the computer and the
phone, including the sequence of bytes that puts the phone into data
mode, have the same basic format.  It goes a little something like
this:

byte 0                             byte 5
+----------------------------------------+
| header                           | len |
+----------------------------------------+
| payload ...                            |
+----------------------------------------+
|                   ...                  |
+----------------------------------------+
| ... payload               | checksum   |
+----------------------------------------+


I have not completely deciphered the format of the header field.  It
is exactly 5 bytes.  It seems to always begin with the byte 0xAA,
followed by either 0XB0 or 0xB1, followed by 0x00, then either 0x02,
0x03, or 0x00, then 0x00.

In commands sent to the phone, StarTalk always uses a constant
sequence of bytes, which is (in hex) AA B0 00 02 00.  This seems to
work, although I don't understand exactly what it means.

Responses from the phone contain different values for the non-constant
part of the header.  So far, I have been able to do everything I need
to do without having to do anything with these values except skip over
them.

I have only tried this with my phone, so I'm not sure if these bytes
represent some kind of identifier, similar to an IP or MAC address, or
if this is just a string of bytes that indicates the beginning of the
message.

After the header, a single byte contains the length, in bytes, of the
payload.  Because only a single byte is used for length, the maximum
size of the payload is 255 bytes.

The payload itself contains either the command to the phone, or the
response from the phone.  It must be exactly the number of bytes
specified in the length byte.

Finally, the last two bytes of the packet are a 16-bit checksum of the
previous packet, sent in big-endian order (most significant byte
followed by least significant byte).  The checksum is a checksum in
the most literal sense of the word; it is calculated by a simple
addition of bytes 3 through the final byte of the payload -- that is,
the final two bytes of the header, the length byte, and the entire
payload.  It is not clear how an overflow is handled, where the
checksum is too large to fit in the 16 bits allotted to it, but this
can only happen if the packet is 254 or more bytes long, and this
could very easily just never happen.

As long as the packet is 253 bytes or fewer, and the maximum value of
each byte is 255, the maximum possible checksum is 65535 (255*253 is
the maximum value for the payload, plus 255 for the maximum value of
header byte 3, header byte 4 is always 0 so does not affect the
checksum, plus 255 for the maximum value of the length byte).

Here is a sample packet.  It happens to be the packet StarTalk would
send to the phone to request phonebook entry 1.

    0: AA B0 00 02 00 05 |       
    6: CF 01 01 00 01 00 |       
   12: D9                |  

Bytes 0-4 are the standard StarTalk request header.  Byte 5 is the
length of the payload, 5 bytes.  The following 5 bytes, bytes 6-10,
are the payload itself.  Bytes 11-12 are the checksum.

INITIALIZATION
--------------

The serial port must be opened at 19,200 bps for successful
communication with the phone to occur.

After opening the serial port, I do some a series of fairly random
things, including sending a break and taking down and back up the flow
control lines.  This fixes a problem I had before where the phone
could not talk to startalk until I talked to it once with minicom.  I
solved this by tracing minicom, and having startalk do pretty much
everything it did.  Probably this is overkill, and I will try to track
down the useless parts in a future release and remove them.

When we first begin communicating with the phone, it will talk to the
computer as a modem, responding to standard AT commands.  I always
begin talking to the phone by sending "AT\r\n", then waiting to make
sure I receive "OK\r\n" in response.

Once we are sure we can communicate with the "modem mode" of the
phone, we can send a special AT command which will cause it to go into
"data mode", the mode we want it to be in to read and write the
phone's settings.  The command is "AT&F8\r\n", a standard AT command
which instructs the phone to go into factory default mode 8.  We will
receive "OK\r\n" in response to this, followed by the first packet of
data mode communication.

First, we will get a packet with contents that I don't understand.  We
then send a packet with single payload byte 0x1F.  We get another
packet from the phone, and send a packet with the single payload byte
0x96.  We get a response from the phone to this packet, and now the
phone is in data mode.  I have tried removing packets from the end of
this sequence, and the phone is not in a state where commands can be
sent to it afterwards, so this entire process seems to be necessary to
get the phone into data mode.  It is possible that this is some kind
of options negotiation, a simplistic authentication procedure, or
simply a procedure to be blindly followed.

After the phone is in data mode, we can send it any of the other
commands listed here.  In each case, a single request from the
computer will result in a single response from the phone.  I am not
aware of any circumstances in which the phone sends packets without
receiving a request to do so.

While the phone is in data mode, the screen goes blank, and it does
not respond to keypresses.  I'm not sure whether it will receive
incoming calls in data mode.  It remains in this state until the
command to return to normal state is sent, or until it is powered off
and back on.

Here is an example of what an initialization looks like:

--------Sent to Phone--------
    0: AA B0 00 02 00 01 |       
    6: 1F 00 22          |   "
-----Received from Phone-----
    0: AA B0 00 03 00 02 |       
    6: 7B 11 00 91       | {   
--------Sent to Phone--------
    0: AA B0 00 02 00 01 |       
    6: 96 00 99          |    
-----Received from Phone-----
    0: AA B1 00 00 00 01 |       
    6: AC 00 AD          |    


RESTORING TO NORMAL STATE
-------------------------

To restore the phone to a state where you can use it as a regular
phone, send a packet with a payload consisting of the single byte
0x3F.  You should not expect a response to this packet.

Here is an example of the packet which restores the phone to its
normal state:

--------Sent to Phone--------
    0: AA B0 00 02 00 01 |       
    6: 3F 00 42          | ? B



PHONEBOOK COMMANDS
------------------

The commands to read and write phonebook entries both use a common
packet format to represent the phonebook entry itself.  This entry is
sent, along with other data, as part of the response from a phone
number read request, or as part of the request to write a phonebook
entry.

There are at least two different formats that a phonebook entry can
have, depending on the firmware or software version of your phone.
Which version is in use can be determined by reading a single entry and
looking at the size.

An older-format phonebook entry looks like this:

        +----+----+----+----+----+----+
byte 0  | Entry name line 1           |
        +----+----+----+----+----+----+
byte 6  | (cont)                      |
        +----+----+----+----+----+----+
byte 12 | Entry name line 2           |
        +----+----+----+----+----+----+
byte 18 | (cont)                      |
        +----+----+----+----+----+----+
byte 24 |0x00|0x00|NumTypes | Phone...|
        +----+----+----+----+----+----+
byte 30 | number 1                    |
        +----+----+----+----+----+----+
byte 36 | (cont)                      |
        +----+----+----+----+----+----+
byte 42 | (cont)  | Phone number 2    |
        +----+----+----+----+----+----+
byte 48 | (cont)                      |
        +----+----+----+----+----+----+
byte 54 | (cont)                      |
        +----+----+----+----+----+----+
byte 60 | Phone number 3              |
        +----+----+----+----+----+----+
byte 66 | (cont)                      |
        +----+----+----+----+----+----+
byte 72 |                   | Phone...|
        +----+----+----+----+----+----+
byte 78 | number 4                    |
        +----+----+----+----+----+----+
byte 84 | (cont)                      |
        +----+----+----+----+----+----+
byte 90 | (cont)  |
        +----+----+

The newer format looks identical, except that instead of two 0 bytes starting
at byte 24, there are 52.  To decode a newer format entry, just add 50 to
all offsets greater than 24.  The remainder of this description will only
refer to the old format entries.
        
The entire 92 bytes will be sent, regardless of the number of actual
phone numbers contained in the phonebook entry.

Bytes 0-11 contain the first line of the phonebook entry.  This is
simple ASCII text, and can contain mixed case and some symbols.  I
have not investigated the full character set of the StarTac phone, but
all of the characters I have tried to use have shown up as expected.
Any unused characters at the end of this line are sent as the ASCII
space character, 0x20, to pad it to exactly 12 characters.

Bytes 12-23 contain the second line of the phonebook entry.  As in the
first line, this is ASCII text, and is padded with spaces to make it
exactly 12 characters.

Bytes 24 and 25 appear to always contain 0s.

Bytes 26 and 27 are a 16-bit value which indicates which of the four
phone numbers are set for this entry, and what type of number they
are.  The type of entry determines which icon is displayed for the
phone number when viewing the addressbook.  The first 4 bits of this
16-bit value give a value between 0 and 15 for the type of the first
phone number.  The next 4 bits give the type of the second phone
number, the next 4 bits (the first 4 bits of byte 27) give the type of
the third phone number, and the final 4 bits give the type of the
fourth phone number.

The values of the phonebook type are as follows:

 0: No phone number
 1: Office phone number
 2: Home phone number
 3: Mobile phone number
 4: Pager phone number
 5: Fax phone number
 6: Unknown (question mark) number.

If all four phone numbers are not used, the unused numbers should have
a type of 0 -- No phone number.

The remaining bytes are 4 16-byte buffers (bytes 28-43, bytes 44-59,
bytes 60-75, and bytes 76-91) contain the phone numbers for this
entry.  The phone numbers are encoded with each 4 bits representing
one digit.  Digits 1-9 are indicated by the 4-bit sequence
representing those digits, the digit 0 is indicated by the 4-bit
sequence for 10, and the number is terminated by the 4-bit sequence
for 0.  For example, the number "01234" would be encoded as

+----+----+----+----+----+----+
|0xa1     |0x23     |0x40     | (in hex)
+----+----+----+----+----+----+
|1010 0001|0010 0011|0100 0000| (in binary)
+----+----+----+----+----+----+

After the terminating 4-bit sequence, the remaining bits in the
16-byte buffer should all be 0's.

For an example of a phonebook entry, see the example for 'Reading a
phonebook entry', starting at byte 6, or the example for 'Writing a
phonebook entry', starting at byte 11.


Reading a phonebook entry
--

To read a single phonebook entry, send a request packet to the phone
with a payload that begins with the bytes 0xCF 0x01 0x01 0x00,
followed by a byte containing the number of the entry to be retrieved.

In response, you will receive a packet that has the requested
phonebook entry in its payload.  The payload will have the 6 header
bytes 0xAA 0xB1 0x00 0x00 0x00 0x5C, followed by the phonebook entry
you requested.

Here is an example of a request for phonebook entry 99, followed by
the response.  The phonebook entry looks like this:

	position: 99
	name: TEST2
	company: 
	phone-fax: 2468
	phone-qmark: 3579

and the request and response look like this:

--------Sent to Phone--------
    0: AA B0 00 02 00 05 |       
    6: CF 01 01 00 63 01 |     c 
   12: 3B                | ;
Sending checksum 315 (0x013B)
-----Received from Phone-----
    0: AA B1 00 00 00 5C |      \
    6: 54 45 53 54 32 00 | TEST2 
   12: 00 00 00 00 00 00 |       
   18: 00 00 00 00 00 00 |       
   24: 00 00 00 00 00 00 |       
   30: 00 00 56 00 24 68 |   V $h
   36: 00 00 00 00 00 00 |       
   42: 00 00 00 00 00 00 |       
   48: 00 00 35 79 00 00 |   5y  
   54: 00 00 00 00 00 00 |       
   60: 00 00 00 00 00 00 |       
   66: 00 00 00 00 00 00 |       
   72: 00 00 00 00 00 00 |       
   78: 00 00 00 00 00 00 |       
   84: 00 00 00 00 00 00 |       
   90: 00 00 00 00 00 00 |       
   96: 00 00 03 5E       |    ^


Writing a phonebook entry
--

To write a single phonebook entry, send a request to the phone with a
payload that begins with the bytes 0xCF 0x01 0x02 0x00, followed by a
byte containing the number of the entry to be written, followed by the
phonebook entry to write in that position.

You will receive a packet in response, the contents of which are not
currently understood.

Here is an example of writing phonebook entry 99.  Entry 99 looks like
this:

	position: 99
	name: TEST2
	company: 
	phone-fax: 2468
	phone-qmark: 3579

and the request and response to the phone look like this:

--------Sent to Phone--------
    0: AA B0 00 02 00 61 |      a
    6: CF 01 02 00 63 54 |     cT
   12: 45 53 54 32 00 00 | EST2  
   18: 00 00 00 00 00 00 |       
   24: 00 00 00 00 00 00 |       
   30: 00 00 00 00 00 00 |       
   36: 00 56 00 24 68 00 |  V $h 
   42: 00 00 00 00 00 00 |       
   48: 00 00 00 00 00 00 |       
   54: 00 35 79 00 00 00 |  5y   
   60: 00 00 00 00 00 00 |       
   66: 00 00 00 00 00 00 |       
   72: 00 00 00 00 00 00 |       
   78: 00 00 00 00 00 00 |       
   84: 00 00 00 00 00 00 |       
   90: 00 00 00 00 00 00 |       
   96: 00 00 00 00 00 00 |       
  102: 00 04 9A          |    
Sending checksum 1178 (0x049A)
-----Received from Phone-----
    0: AA B1 00 00 00 01 |       
    6: AC 00 AD          |    


Removing a phonebook entry
--

Removing a phonebook entry uses the same command as writing a
phonebook entry, but all bytes of the phonebook entry are 0's.

Here is an example of clearing phonebook entry 99:

--------Sent to Phone--------
    0: AA B0 00 02 00 61 |      a
    6: CF 01 02 00 63 00 |     c 
   12: 00 00 00 00 00 00 |       
   18: 00 00 00 00 00 00 |       
   24: 00 00 00 00 00 00 |       
   30: 00 00 00 00 00 00 |       
   36: 00 00 00 00 00 00 |       
   42: 00 00 00 00 00 00 |       
   48: 00 00 00 00 00 00 |       
   54: 00 00 00 00 00 00 |       
   60: 00 00 00 00 00 00 |       
   66: 00 00 00 00 00 00 |       
   72: 00 00 00 00 00 00 |       
   78: 00 00 00 00 00 00 |       
   84: 00 00 00 00 00 00 |       
   90: 00 00 00 00 00 00 |       
   96: 00 00 00 00 00 00 |       
  102: 00 01 98          |    
Sending checksum 408 (0x0198)
-----Received from Phone-----
    0: AA B1 00 00 00 01 |       
    6: AC 00 AD          |    


SETTINGS COMMANDS
-----------------

Settings are managed by reading and writing several buffers which
contain the settings.  These buffers are sent and received as the
payload of a command.  A setting can be contained in a single bit, an
entire byte, or multiple bytes.

Here are the buffers that contain settings, or seem to contain
settings.

The SuperSettings Buffer
------------------------

This buffer contains most of the settings for the phone (about 32
different settings).

[ more to follow ]


--
$Id: PROTOCOL,v 400.1 2002/07/25 08:43:16 sgifford Exp $