$Id: README 3078 2007-12-12 07:50:04Z mark_ellis $

Contents of this document
-------------------------

	o Overview
	o License
	o How to get support
	o External requirements
	o Installation from CVS


Overview
--------

Synce-serial is part of the SynCE project:

  http://synce.sourceforge.net/

This module contains helper scripts for setting up a serial connection for use
with SynCE. They are basically wrappers around pppd:

	synce-serial-config  - Use this to select serial port and IP adresses
	synce-serial-start   - Use this to start connection
	synce-serial-abort   - Use this to abort a connection

Usage
-----

There are 3 ways to use these scripts.

1. From the command-line

   To use these scripts from the command-line, make sure "dccm" or
   "vdccm" is running to allow communication with your device.  Then
   plug in your PDA, and as root run:

       synce-serial-start /path/to/dev

   When you are done, run:

       synce-serial-abort /path/to/dev

   then remove the device.

   To reconnect, you will have to unplug the device and plug it in
   again; the PDA will only watch for a connection from a PC once when
   it is plugged in.

   If you always plug your PDA into the same port, you can save a
   default configuration by running:

       synce-serial-config /path/to/dev

   After that "synce-serial-start" and "synce-serial-abort" with no
   arguments will start and stop the connection you've configured.

   By default, an IP address will be selected for you, and the DNS
   configuration on the PDA will be set to your PC.  You can override
   this from both synce-serial-start and synce-serial-config by giving
   the IP addresses and DNS server on the command-line; run either
   program with the "--help" option for more information.


2. From udev

   Newer Linux kernels use "udev" to provide a framework for detecting
   devices when they are plugged in, and running the appropriate
   script. You can use this to automatically configure your PDA as
   soon as it's plugged in.

   Note that you'll still need to have "dccm" or "vdccm" running as
   your regular login account before plugging PDAs in, or else the
   connection will quickly fail.

   To activate the synce-serial scripts from your udev configuration,
   create a link to the "synce-udev.rules" file in your udev "rules.d"
   directory.  For example:

       cd /etc/udev/rules.d
       ln -s /usr/local/share/synce/synce-udev.rules 60-synce.rules

   Now run:

       udevcontrol reload_rules

   The devices should show up to dccm/vdccm a few seconds after they
   are plugged in, and remove themselves shortly after they are
   removed.

   If you run into trouble, try watching your logfiles to see what's
   happening.

2. From hotplug

   Older Linux kernels use "hotplug" to manage devices automatically
   when they are plugged in or removed.

   To configure synce-serial for hotplug of USB devices, first add a
   link to "synce.hotplug" to your "hotplug/usb" directory.  For
   example:

       cd /etc/hotplug/usb
       ln -s /usr/local/bin/synce-serial-hotplug synce

   Now make sure that hotplug knows which device IDs should be handled
   by synce.  There's a partial list in "synce.usermap", included with
   synce-serial.  To add this to your hotplug configuration, you can
   append it to your "usb.usermap" file:

       cd /etc/hotplug/
       cp usb.usermap usb.usermap.bak
       cat usb.usermap /usr/local/share/synce/synce.usermap >usb.usermap.new
       mv usb.usermap.new usb.usermap

   If you run into trouble, try watching your logfiles to see what's
   happening.


Multiple device support
-----------------------

Currently multiple device support for USB connections is limited to 120
devices due to the IP assignment mechanism.


License
-------

MIT License, see the file LICENSE for details.


How to get support
------------------

To increase the possibility of getting help, please read this document first:

  http://www.tuxedo.org/~esr/faqs/smart-questions.html

Information about the SynCE mailing lists are available here:

  http://sourceforge.net/mail/?group_id=30550

If your question has not been covered before, send it to the synce-devel
mailing list.


External requirements
---------------------

You need ppp to use this.


Installation from CVS
---------------------

o Make sure you have these versions of the GNU autotools:

    autoconf-2.53
    automake-1.6.1
    libtool-1.4.2

o Checkout "serial" as described on:

    http://sourceforge.net/cvs/?group_id=30550

o Generate scripts and things:

    ./bootstrap

o Configure:

    ./configure
 
  Use the --help parameter to view configuration options.

o Build:

    make

o Install:

    make install