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

This OpenSync plugin is intended to enable 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, todo list entries, and notes. Support for the new
synchronisation features in Opie 1.2.5 is included. 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 to the 
opensync users list (opensync-users@lists.sourceforge.net) - although please 
check the Troubleshooting section below before posting. Patches and 
corrections are also always welcome - these should be sent to the opensync 
development mailing list (opensync-devel@lists.sourceforge.net). Thanks!


Requirements
------------

 * A device running Opie 1.2.0 or later (however, the latest version
   available is recommended)
 * Connection: the plugin assumes you have a working network connection
   set up between the device and the machine you are running OpenSync on. 
   This could be ethernet over USB, PPP over serial, wifi, bluetooth etc. - 
   as long as an IP network is available the transport is not important.
 * The OpenSync xmlformat plugin (now split out from the core) is required.
 * libcurl, libxml2, glib-2.0
 * OpenSSH for scp connections (optional)


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

opie-sync now uses the new OpenSync configuration format, so basic settings
are similar to other plugins, but there are some important notes for each one
below.

Connection

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

  Port
    TCP port on the device to use for file transfers. Default is 4242 (which
    Opie's built-in FTP server listens on). See also the ConnType option 
    below. Normally this should not be changed.

Authentication

  Username
    User name to log into the device as (default is root, and this will
    almost always be the value here unless you are testing on a PC).

Advanced Options

  The "advanced options" specific to opie-sync are as follows:

  ClientType
    Client 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.

  ConnType
    Type of connection to use:
      ftp  - use FTP (default). Uses Opie's built-in FTP server to transfer
             data without encryption. For Opie 1.2.5 this is the only option.
      scp  - use scp/ssh commands to transfer data securely. Note: this will 
             require you to set up key-based ssh authentication. *** See
             Todo List below ***
  
  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.

Resources

  OpenSync 0.38+ supports configuration of multiple resources per plugin. 
  opie-sync does not use these for the contact, event or todo types (although
  they must be present for synchronisation to work). However, it will use
  resource definitions to determine the source of note entries (replacing the 
  notestype configuration option in previous versions). The default 
  configuration file sets up two resources:

    Basic text files - sync with .txt files in the user's home directory (default)
    Opie-Notes       - sync with Opie-Notes

  Only one of these note resources can be enabled at once.


Additional options (for debugging purposes only!):

  ConnType
    An additional value for this option exists:
      none - don't connect, instead read/write files in the directory 
             specified by the LocalDir option (see below).

  DisableQcop
    Control the use of QCOP to notify the device of syncing:
      0 - enable QCOP (default)
      1 - disable QCOP. You will likely want to set this if you set ConnType 
          to 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/empty, 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 set in the configuration for the plugin (should usually be "root").


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. *** See Todo list below ***


Todo list
---------

Secure syncing not supported on 1.2.5

  The new synchronisation method in Opie 1.2.5 does not support exchange of
  data using encryption.

Missing fields on contacts

  "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 1.x/2.x on Zaurus devices, only 
  Opie (version 1.2.0+). In addition Qtopia 4 is not supported (there is a
  separate Qtopia4 OpenSync plugin for the latter).
