root/plugins/moto-sync/README

INTRODUCTION

This is a VERY EXPERIMENTAL plugin for syncing with Motorola phones 
using the AT command set. It supports syncing phonebook and calendar 
entries (ie. the contact and event object types). It will most likely
mess up the data on your phone and any other members of the sync group,
due to the limited data that can be stored on the phone, so use with caution
and make backups! See BACKUP/TESTING below.


SUPPORTED HARDWARE

Known working models:
 * L7 SLVR
 * V3i RAZR
 * V557

Possibly working, but only lightly tested:
 * V3x RAZR (tested reading only)
 * V635 (tested reading only)

Untested, but might be working with recent changes:
 * K1 KRZR (extended calendar suppport, ticket #425)
 * V3xx RAZR (extended calendar suppport, ticket #425)
 * V3c (doesn't like AT+MODE=0, ticket #505)
 * V3 RAZR (tickets #599, #555, #504)

Models known not to work:
 * V600 (shorter contact entries, ticket #504)
 * A780 (doesn't seem to respond to AT commands, except with ERROR)

If your phone isn't listed above, or if your results differ, please let 
me know how it works for you, by emailing andrewb AT cse DOT unsw DOT 
edu DOT au.


REQUIREMENTS

 * OpenSync 0.31 or later with the python bindings and python-module plugin
 * Python 2.4 or newer
 * The python-dateutil library (at least version 1.1),
   from http://labix.org/python-dateutil
 * Optionally, the pybluez library (at least version 0.9)
   from http://org.csail.mit.edu/pybluez/


INSTALLATION

cp motosync.py $PREFIX/lib/opensync/python-plugins
cp moto-sync $PREFIX/share/opensync/defaults


CONFIGURATION

For now, there is only one configuration option to moto-sync: the device 
string to communicate with the phone. This is specified in a small XML 
file, the contents of which should look like:
        <config><device>your device string here</device></config>

There are two options for specifying the device string:
 1. If your phone is connected by bluetooth, and you have the pybluez 
    package installed (see REQUIREMENTS above), you can use its MAC 
    address (eg. 00:11:22:33:44:55) as the device string.

 2. Otherwise, you have to specify the full path to a device node on the 
    local file system that can be used to communicate with the phone.
    Devices you're likely to use in this case are:
  * /dev/ttyACM0 for a USB modem connection (or whatever other device the
    phone shows up on, see dmesg). Note that the phone has to be in the
    "Data/Fax connection" mode, not mounted as a USB storage device.
  * /dev/rfcomm0 which is the first bluetooth channel. You need to setup 
    that channel to bind with your phone, by doing something like:
         rfcomm bind rfcomm0 00:11:22:33:44:55 1


BACKUP/TESTING

Before doing anything, it is probably a good idea to backup the data 
from your phone. You can use the mototool script to do this, and to 
delete entries on the phone. Run 'mototool --help' for details, or, for 
the impatient, try:
    mototool -d (device string) -f myphone.backup --backup

The best way to get started testing this plugin is in a sync group 
with file-sync. To configure and use this, do:
        msynctool --addgroup moto-file
        msynctool --addmember moto-file moto-sync
        msynctool --addmember moto-file file-sync
        msynctool --configure moto-file 1 # configure moto-sync, as above
        msynctool --configure moto-file 2 # configure file-sync, set the path(s)
        msynctool --discover moto-file 1
        msynctool --discover moto-file 2
        msynctool --sync moto-file # cross your fingers!


LIMITATIONS AND KNOWN PROBLEMS

Unfortunately the functionality offered by the phone is extremely 
limited. I'd love to know how well it works with SyncML, especially for 
complex calendar events, but I'm guessing the answer is "not very". The 
phone books and calendar work in basically the same way:
 * entries are stored in memory "positions"
 * there are AT commands to read and write the data at a certain position

This means that if an event changes position (which you can do for the 
phone book, for example if you want to change speed dial numbers) we 
don't have any way of detecting that it's the same event. Similarly, if 
an entry is deleted and a new one created in its place, we can't 
distinguish that from a (large) change to the original entry.

For the phone book, each entry has a name, number, contact type 
(home/work/mobile/email address etc.), nickname, address, category 
number, birthday, and some other fields for things like ringer ID that 
we don't handle very well yet. A contact with multiple phone numbers is 
actually just multiple entries in the phone book, so when we read 
entries we have to merge any with the same name into a single contact, 
and split them up again on write. This leads to all sorts of problems in 
maintaining consistent UIDs for a contact, when our only real handle on 
which entry is which is the positions it occupies.

For the calendar, each event has a name, date/time, duration, alarm 
date/time, repeat type, and list of exceptions. The repeat type in 
particular is very limited, and unless you have a recent-model phone 
with extended calendar support, many recurring events can't be 
represented on the phone. At the moment the plugin detects this and 
just refuses to write them. A better solution would be to split them up 
into multiple events, but this will confuse OpenSync when we sync up 
again.


TODO

 * Better error/exception handling
 * See all the FIXMEs in the code
 * Do something with "mailing list" entries in the phonebook
 * Add support for reading/writing the SIM phonebook
 * Improve support for other hardware