StarTalk V0.2
-------------

***** WARNING *****

StarTalk is beta software, and is not covered by anything resembling a
warranty.  It has only been tested on my phone, and attempts to
implement an undocumented protocol for talking to your phone.  There
is every possibility that StarTalk will completely blow away the
settings and phonebook in your phone, although as far as I know it
does not do that.  If you have data stored in your phone that you
don't have elsewhere, or that you would be unhappy if it were
destroyed, I would not even think of using StarTalk without backing up
your phone first.

Now back to our regularly scheduled README.

StarTalk is a tool for letting your Linux machine talk to a Motorola
StarTac PCS phone.  It currently basically lets you dump your
addressbook and write a new addressbook to your phone.  It aspires to
let you read and set all options in your phone, and to be easily
integrated into a package designed to synchronize phonebooks.

This release of StarTalk is more written as a demo program than
anything else.  It will write your phonebook to a text file and read
specially formatted text files in to write them to the phone.  It also
has a simplistic test mode, which will send a couple packets that I
haven't had time to analyze, and print the results, for future
figuring out.  When run in debug level 3 or higher, it will include
full packet dumps to and from the phone, which have proven useful in
figuring out how the protocol works, and in decoding the information
in the packets.

You can combine the reading and writing phonebook text files with some
straightforward Perl scripting to synchronize your phone addressbook
with another addressbook -- just read in both books, decide what needs
to be changed to make them synchronized, and write out a text file
which will cause StarTalk to make the changes.  Then run st to write
this text file to your phone.

This program has only been tested under Linux kernel 2.2.13.  It will
probably need to be changed slightly to run on other platforms,
because I haven't been particularly careful to make it portable.  It
has also only been tested with my phone, which is running software
6308.  I don't know how the software versions work on these phones,
but that's what the menus on my phone report as the software version.

I have written up a brief summary of the parts of the protocol that I
have figured out in the file called PROTOCOL, which should be in the
same directory as this file.  I have also included a file called
INTERCEPTTY, which describes how I observed the packets travelling
to and from and my StarTac phone.

StarTac is a trademark of Motorola, and PCS is probably a trademark of
Sprint or somebody.  StarTalk is copyright (c) 2000 by Scott Gifford,
and is distributed under the GNU Public License.  For more details
about StarTalk's license, see the file COPYING in this directory.

The Cable
---------

The cable I use to connect my phone to my computer is the Data
Connectivity Kit.  One end of the phone connects into the bottom of
the phone, and the other end is a 9-pin female serial connector that
plugs into the back of my computer.

The cable is sold by itself as a Motorola SYN7464 or SYN7465B Data
TrueSync Connectivity Cable, or as part of the Motorola 98193 CDMA
Data Connectivity Kit with Truesync Software.  Searching for these on
the Internet, I was able to easily find several places which sell
them.

This cable says it is compatible with the following phones:

    Motorola Talkabout/ T8160/ T8167/ T8367/ 
    Timeport/ P8367/ P8160/ P8167/ P8767*/ 
    V8060/ V8062/ V8160/ V8162/ 
    Startac/ Star-Tac/ St7760/ ST7762/ ST7860/ ST7860W/ ST7867/ ST7867W/
    ST7868/ ST7868W

    * The P8767 apparently requires a firmware upgrade from the dealer to
      work with this cable and software.

I suspect that this software will work with any of these phones, but
I've only tried it on my own.  If StarTalk works for you, please check
the Web page, and if your phone model is not listed there, email me
with the model number so I can add it as confirmed working.

I've gotten numerous requests for information on how to make your own
cable.  I haven't been able to find any information about this; if you
have some please send it my way.  From what others have told me, I
understand that the cable contains a microchip, and doesn't simply
connect pins on the phone to pins on the serial port, so it is more
difficult than it seems like it should be.

Compiling
---------

Just type make.  There's no configure script, no nuthin'.  I may add
one later on if it proves necessary, but I don't have access to any
other machines that I can plug my phone into, so right now this isn't
a particularly portable program.

Configuring
-----------

This program expects to talk to a TTY-style device at /dev/pcsphone.
I make this a symlink to the serial port that I plug my phone into (by
typing 'ln -s /dev/ttyS0 /dev/pcsphone').  You could also make an
actual device node for it, or you could just remember to always
specify the port with the '-p' option.

Usage
-----

Usage: ./startalk [-c] [-r|-w|-t] [-n entrynum(s)] [-v] [-d debuglevel] [-p phonetty]
        -c: Clear out phonebook entries.  USE WITH CARE!!
            When used with the -w option, will clear out all entries
            which are not in the file read in.
            When used with the -n option, will clear out the entries
            in the specified range.
        -r: Read entire phonebook from phone and dump to stdout
        -w: Read phonebook from stdin and write to phone
        -t: Write some test packets to phone, and read the results
        -n: Specify to perform the read, write, or clear on
            entries specified by n.
            You can use commas to specify multiple entry numbers, and can
            use the dash character to specify a range of numbers.
            For example, '-n 1-9,25-30,99'
        -p: Specify the tty/device to be used to talk to the phone
        -v: Verbose mode (same as -d 1)
        -d: Debug level
            1: Verbose
            2: Downright noisey
            3: Full packet dumps
        -h: Help (display this message)


File Format
-----------

The files that StarTalk reads and writes are (loosely) based on the
LDIF files used by LDAP servers.  They are basically individual
records seperated by blank lines.  Each record contains name/value
pairs seperated by a colon.  For example:

      position: 1
      name: Emergency!
      company: Police
      phone-office: 911

represents an addressbook entry in position 1 (the first speeddial
entry), with a name of "Emergency!", a company of "Police", and an
office telephone number of 911.  The values should be exactly what
should go to the phone -- both name and company should be 12
characters or less, and the phone number shouldn't contain any
non-numeric characters.  StarTalk tries to just ignore data that it
thinks is invalid, printing a warning message if it can.

Here's a description of all of the fields that StarTalk recognizes in
these files:

position - The position of this entry in the StarTac phonebook.

name - The first line of a description of an item in the phonebook.
  This is what is displayed while you are flipping through your
  phonebook on your phone.

company - The second line of a description of an item in the
  phonebook.  Once you have selected an item on the phone, the display
  flashes back and forth between name and company.  Some people use
  the 'name' field for the last name, and this field for the first
  name.

phone-* - phone number entries.  These appear in the order they are in
  your phonebook, and will be written in the order they appear in the
  file.  The word after the dash indicates which type of phone number
  it is, and will affect the icon displayed for that phone number.
  Valid words are 'office', 'home', 'pager', and 'mobile'.  There are
  two other types for fax machines and other, but they are not
  supported right now becuase I don't use them for anything.

Comment lines start with a '#'.  The # character can *ONLY* appear at
the beginning of a line, or else it will not be treated as a comment
character.

If the only attribute for a phonebook entry is the position number,
that is assumed to be a blank phonebook entry.  These entries will not
be generated when reading the phonebook unless specially requested,
and when writing the phonebook, they will remove the entry in the
given position.

The Future
----------

Here are the plans I've got for the future of StarTalk.  If you would
like to help with any of these, please email me and we'll coordinate.

  * Better portability

  * Support for more commands

  * L10N/I18N support

  * Turn most of StarTalk into a library, for easier integration with
    other programs.

  * Work on integrating StarTalk into popular PIM tools.

Related Projects
----------------

palm2star - Transfers entries from a Palm device to a StarTAC phone.
            http://cuspy.com/software/palm2star/

StarTAC AT Commands - http://ridge.trideja.com/wireless/atcommands/

StarTAC Software Revisions - http://ridge.trideja.com/wireless/swrev.html

StarTAC Hardware - These are for GSM phones, but they mention that the
                   other StarTAC phones are very similar.
                   http://www.tele-servizi.com/Janus/motpages.html
                   http://www.gsm-products.com/html/

jStarTalk - a Java version of StarTalk
            http://jStarTalk.MageNet.com

qcplink - like StarTalk for Qualcomm phones
          http://qcplink.sourceforge.net/

gnokii - like StarTalk for Nokia phones
         http://gnokii.org/

--
$Id: README,v 201.0 2002/02/14 09:29:14 sgifford Exp $
