StarTalk V0.4
-------------

***** 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 kernels 2.2.13 and 2.4.9.
It may 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-2002 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.

Testing
-------

To let you (and me!) make sure StarTalk works, a small test script
is included.  The test script does not support command-line options
to startalk, so the device /dev/pcsphone must exist and point to the
serial device that the StarTAC phone is connected to (see the section
Configuring).

To just try the phonebook reading tests, run:

    ./runtest

To run the reading and writing tests (which will destroy entry #99 in your
phonebook if anything fails), run:

    ./runtest -overwrite

If you need to pass options to startalk to get it to work (like -p
/path/to/serial/port), or if you'd like extra debugging information (like
-d 4), you can ask for options to be passed to each startalk invocation
by setting the environment variable TESTOPTS.  So, for example, to run
all tests using /dev/ttyS0 with debug level 4, do

    TESTOPTS="-p /dev/ttyS0 -d 4" ./test -overwrite


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
	-s: Read/write settings instead of phonebook
	-t: Test the phone and StarTalk
	-T: Set default timeout (in seconds) for communication with the phone.
	    Default is 10; use -1 for no timeout.
	-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'
	-e: Display empty phonebook entries
	-p: Specify the tty/device to be used to talk to the phone.
	    Default is '/dev/pcsphone'.
	-i: Specify init string sent to phone
	    Default is 'AT S7=45 S0=0 L1 V1 X4 &c1 E1 Q0'.
	-v: Verbose mode (same as -d 1)
	-d: Debug level
	    1: Verbose
	    2: Downright noisy
	    3: Full packet dumps
	    4: Tediously report on the inner workings of StarTalk.
	-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.

email - The email address of the phonebook entry.  Only supported on
  new-format phonebooks.

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.

Mailing List
------------

If you have trouble with StarTalk, or have ideas about its future
development, try joining the StarTalk mailing list.  Send a mail
message to majordomo@suspectclass.com with a line in the body saying:

    subscribe startalk

to join, and send mail to startalk@suspectclass.com to post your message.
Only subscribed users are allowed to post.


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/


Credits
-------
Thanks to:

   Jason White <jdwhite@jdwhite.org> for his help with testing and
   debugging the new-style phonebooks and email addresses.

   Jeffrey C. Honig <jch@eng.bsdi.com> for his help and his code to
   support special characters in phone numbers and to make StarTalk
   simpler and faster.

   Gilbert Raymond <gilbert@lucent.com> contributed ideas and code for
   supporting special characters in phone numbers, and feedback on the
   documentation.

   David Kirk <david@flinthomes.net> contributed an old Verizon 7867W
   phone, which will let me continue support for the newer-firmware
   phones.  Thanks David!


Consulting
----------

If you'd like to use StarTalk in your company, get support for
StarTalk, or sponsor a new feature you would like, please consider
hiring me as a consultant.  For more information, see:

    http://www.suspectclass.com/~sgifford/consulting/


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