Opie Plugin for OpenSync README
===============================

This OpenSync plugin is intended to allow synchronisation with the Opie 
handheld environment (http://opie.handhelds.org). In theory it should also 
support some versions of Qtopia as found on the Sharp Zaurus, but no testing 
of this has been done.

This plugin is a work in progress but should be able to sync contacts, 
calendar events and todo list entries, minus a few fields, as well as support
for syncing notes. However, use is entirely at your own risk - back up your 
data on both sides first!

If you'd like to help, please try the plugin and send any questions, patches 
or corrections to the opensync users list 
(opensync-users@lists.sourceforge.net). Thanks!


Configuration Options
---------------------

hostname
  Hostname or IP address of the handheld device eg. 192.168.0.2

username
  User name to log into the device as (default root).

password
  Password to log into the device with (default Qtopia). Note that this is
  the synchronisation password and not the actual password for the user.
  Note: in current versions of Opie this password must begin with "Qtopia"
  or "rootme" and the two characters after that are ignored. This will be
  fixed in later versions.

device
  Device type being connected to:
    opie    - Opie or compatible OS (default)
    qtopia2 - Qtopia 2.0 or compatible OS (eg. Zaurus with original ROM)
              Note: Qtopia support has not been tested.

port
  TCP port on the device to use for file transfers. Default is 4242 (which
  Opie's built-in FTP server listens on).

conntype
  Connection type to use:
    ftp  - use FTP (default). Uses Opie's built-in FTP server to transfer
           data without encryption.
    scp  - use scp/ssh commands to transfer data securely. Note: this will 
           require you to set up key-based ssh authentication.

backupdir
  (Optional) If you want the files from your device backed up prior to every 
  sync, set this option to a directory to put the backups into. A directory 
  named using the current date and time will be created for each backup. 
  Files will also be written to this directory in the event that uploading to 
  the device fails.
  Note that old backups are not purged - you will need to do this yourself.

notestype
  Destination for notes on the device:
    basic       - Sync with .txt files in the user's home directory (default)
    opie-notes  - Sync with Opie-Notes


Additional options for debugging purposes only:

conntype
    none - don't connect, instead read/write files in the directory specified 
           by the localdir parameter (see below).

use_qcop
  Control the use of QCOP to notify the device of syncing:
    true  - enable QCOP (default)
    false - disable QCOP. You will likely want to set this if you use
            conntype = none.

localdir
  If conntype = none, you can use localdir to specify where the Opie data 
  files should be read from / written to. If not specified, the default is /tmp.


Troubleshooting
---------------

I see the error "Failed to log into server"

  Make sure you have set the security options properly on the Opie side - go
  to Settings->Security->Sync and set the "Accept sync from network" option to
  an appropriate value for your network setup. You should also check the
  username and password set in the configuration for the plugin. See the notes
  under the "password" option above.


Syncing freezes at a particular point

  An error may be occurring during the sync which is not being shown in the 
  output - please report this problem to the OpenSync mailing list 
  (opensync-users@lists.sourceforge.net). If you can, enable the OpenSync
  tracing feature and look through for any messages that include "ERROR".


Calendar events are several hours out

  Check that you have set the time zone correctly on the handheld - please see
  the documentation for your handheld OS (if you are using Familiar please
  see the Familiar release notes). Essentially you need to make sure that
  /etc/localtime is the correct timezone file for your locale, or a symlink
  that points to the correct file. At present the timezone must also match the
  timezone on the machine running OpenSync.


After syncing with KDEPIM, the KDE address book shows phone numbers as "Other"

  This is a problem with the KDE KAddressBook application - it does not know
  how to show the type for phone numbers that have more than one type tag (eg.
  both Work and Mobile). If you don't like this then please comment/vote on
  KDE bug #102466 (http://bugs.kde.org/show_bug.cgi?id=102466).


Todo alarms don't seem to synchronise properly when syncing with KDEPIM

  Opie's support for todos is not as comprehensive as KDEPIM's - most of the
  trouble comes from Opie not supporting a due time (only a due date). In the
  reverse direction, KDEPIM does not support specific date/time value for
  alarms on todos which Opie uses.


I am using the scp protocol and I keep getting "Permission denied" errors

  If you have not done so you need to set up SSH public key authentication
  between the device running Opie and the machine running OpenSync. There is
  no way for a password to be passed to scp so key-based authentication must
  be used.


Todo list
---------

Missing fields on contacts

  "Business web page", "Gender" and "Children" fields from the Opie side are
  not currently handled since OpenSync's internal XML format does not
  currently support them.

Timezone issues

  Having a different timezone selected on the Opie side than the other member
  of a sync group is not currently supported. There may also be other
  timezone-related issues.

Qtopia testing / support

  No testing has yet been done with Qtopia on Zaurus devices, only Opie 
  (version 1.2.0+).

Opie SQLite PIM backend support

  Only Opie's XML (default) backend is currently supported. Supporting the 
  SQLite backend will require adding support for querying the database 
  remotely in Opie so this is not a trivial task.

