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 is interactive, and walks you through the process. To run the interactive test script, type "./test", or just "make check". The more automated testing tool is runtest. To run just the reading tests, execute runtest with no options: ./runtest To run all tests, including tests which attempt to overwrite entry #99 in your phonebook, use the "-overwrite" flag: ./runtest -overwrite To run a specific test or tests, give their name or the path to them on the command-line: ./runtest 00 01 test.d/1* 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, run: 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 for his help with testing and debugging the new-style phonebooks and email addresses. Jeffrey C. Honig for his help and his code to support special characters in phone numbers and to make StarTalk simpler and faster. Gilbert Raymond contributed ideas and code for supporting special characters in phone numbers, and feedback on the documentation. David Kirk 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.1.1 2002/07/25 10:14:39 sgifford Exp $