updated sync howto

1 files changed, 305 insertions, 36 deletions

diff --git a/bin/kdepim/korganizer/howtoSYNC.txt b/bin/kdepim/korganizer/howtoSYNC.txt
index e73709b..ad765d3 100644
--- a/bin/kdepim/korganizer/howtoSYNC.txt
+++ b/bin/kdepim/korganizer/howtoSYNC.txt
@@ -1,137 +1,176 @@
-NOTE:
+WARNING:
 YOU MAY GET UNEXSPECTED (I.E. WRONG) SYNCHRONIZATION RESULTS, 
 IF YOU CHANGE AN EVENT ON THE FIRST DEVICE AND SYNC IMMEDIATELY FROM
 THE OTHER DEVICE WITH THIS DEVICE, IF THE CLOCKS OF THE TWO DEVICES
 HAVE TOO MUCH DIFFERENCE.
 
+In other words: Please make shure, that the clocks of the devices 
+you want to sync have only a difference of some seconds!
+
 
 CONTENT:
 
 0) How syncing works
 1) Qick overview of settings
 2) Sync settings in sync dialog
 3) Syncing background
 4) Sync preferences
+5) Details about sync profile kinds
 
 *************************************************************************
 0) How syncing works
 *************************************************************************
 
-In KO/Pi you can synchronize ( sync ) your calendar 
-with another calendar, by syncing  your (local) calendar with a 
-(remote) file. This remote file may on your local filesystem
+Note:
+The recommended and easiest way to syncronize two devices where 
+KO/Pi or KA/Pi is installed, is the profile kind "Pi-Sync".
+Details about that in 5) b).
+
+In KDE-Pim/Pi you can synchronize ( sync ) your calendar/addressbook 
+with another calendar/addressbook , by syncing  your 
+(local) calendar/addressbook  with a (remote) file. 
+This remote file may on your local filesystem
 or on another (remote) device.
-If it is on another device, you have to specify a 
-command line download/upload command ( like scp, ftp, ...) to 
-a) download the remote file to your local machine to a temp file
-b) sync with this temp file
-c) upload the synced file to the remote device
 
-You should create for every device, to sync with, a sync profile.
+If you want to sync with another remote device, 
+you have two create a sync profile.
+You have two choices for choosing the profil kind:
+I)  You have to choose profile kind "Remote file" and to specify a 
+    command line download/upload command ( like scp, ftp, ...) to 
+    a) download the remote file to your local machine to a temp file
+    b) sync with this temp file
+    c) upload the synced file to the remote device
+II) If you want to sync with a device, where KO/Pi( or KA/Pi ) is
+    installed, you can easily get the remote file via network 
+    with the build in file transfer feature:
+    Choose profile kind "Pi-Sync" and
+    a) Start KO/Pi or KA/Pi on remote device and
+       enable "Pi-Sync" on remote device with password and port.
+    b) Specify password, port and IP address in your profile.
+
+
+You can sync with your mobile phone as well.
+Everything is explained in more details below.
 
 NOTE:
-Before syncing, it is recommended to close 
-a running KO/Pi on the remote device.
-(Note: KO/Pi running on Zaurus with 
+If you do not use profile kind "Pi-Sync",
+it is recommended to close 
+a running KO/Pi ( or KA/Pi) on the remote device.
+(Note: KO/Pi( or KA/Pi) running on Zaurus with 
 FastLoad enabled will never be closed!)
 After syncing with a running KO/Pi on the remote device,
 a "save" on the remote device will tell you that it needs to merge (sync).
 After merging (just a syncing with the changed file) 
 you will get the new data showing in remote KO/Pi. 
 
 *************************************************************************
 1) Qick overview of settings
 *************************************************************************
 
-a) Open sync settings dialog
+a) Open sync settings dialog (Menu Synchronize - Configure...)
 b) Give your device a unique name.
    (unique in the set of all devices you want to sync with).
    If you have already configured another devive and created 
    there a sync profile to sync with this device, give your device
-   the same name as this sync profile! The same name is important!
+   the same name as this sync profile! The same name is important, 
+   because it makes it possible to sync first A->B 
+   (A local device, that performs the sync, B remote device) 
+   and then B->A. Such that the B->A sync knows about the 
+   already performed A->B sync.
+   That means: It is unimportant if you sync A->B or B->A,
+   the devices A and B will be synced properly. 
 c) Create a new sync profile and give it a unique name.
    (unique in the set of all sync profiles on this device).
    If you want to sync with a device, where KO/Pi is already installed
    and which has a given unique device name, use this device name as
-   your profile name.
+   your profile name ( refer to b) ).
 d) Coose the profile kind of your syncing method:
       (i) Local file or
-     (ii) Remote file
-c) If you did choose (i), 
-      specify the file name you want to sync with.
-   If you did choose (ii), 
-      specify the system (command line) 
-      download/upload command of the remote file.
-d) Choose the other profile options.
-   Detailed explanation in 2.) 
-e) Close sync dialog with OK.
-f) Sync.
+     (ii) Pi-Sync or
+    (iii) Remote file or
+   (iiii) Mobile Phone.
+   Detailed explanation in 5) 
+e) Choose the other profile options.
+   Detailed explanation in 2) 
+f) Close sync dialog with OK.
+g) Sync.
 
 NOTE:
 AFTER SYNCING THERE ARE "SYNC EVENTS" CREATED 
 (OR UPDATED, IF IT ALREADY EXITS) FOR EACH SYNC PROFILE.
 YOU MAY NOT DELETE OR CHANGE THESE EVENTS. 
 
 *************************************************************************
 2) Sync settings in sync dialog
 *************************************************************************
 
 a) Local device name:
    -> 1) b)
 b) Profile:
    -> 1) c)
 c) Include in multiple sync:
    In the Synchronize menu, there is a multiple sync menu entry.
    If you choose this menu entry, all user defined profiles with this
    'Include in multiple sync' option enabled will be  synced 
    one after another. And this twice. This will take some time.
    After that sync, on all devices should be the same data.
 d) Ask for preferences before sync:
    Check this to be asked for sync settings before each sync.
 e) Sync preferences:
    Choose here your sync preferences.
    Details -> 4)
 f) Show summary after sync:
    Check this to get a small summary dialog after sync 
    about number of added/changed/deleted events on local/remote.
-g) Write back existing entries only:
-   Check this to update the remote calendar only.
-   I.e. no event/todo from yor local calendar is added to the
-   remote calendar. You may use this option to 
-   sync against some kind of "public calendar" without 
-   writing back your personal data.
-h) Write back file:
-   Check this to update the local calendar only.
+g) Write back synced data:
+   Uncheck this to update the local calendar only.
    I.e. your local calendar is synced with the remote calendar
    but nothing on the remote calendar is changed.
-i) Profile kind:
-   -> 1) d)
+   If you uncheck "Write back synced data", the settings
+   under h) and i) are ignored, of course.
+h) --Write back (on remote) existing entries only:
+   Check this to update the remote data only.
+   I.e. no data from yor local calendar/addressbook is added to the
+   remote device. You may use this option to 
+   sync against some kind of "public calendar/addressbook" without 
+   writing back your personal data.
+i) --Write back (calendar) entries in future only:
+   Check this to write back only calendar entries in future.
+   (Useful when syncing with mobile phones.)
+   You can specify the date range in weeks with
+   ---- Max. weeks in future.
+   Note: The date range starts always 7 days before the actual date!
+   I.e. the calendar events of the last week are written back always.
+j) Profile kind:
+   Details -> 5)
 
 *************************************************************************
 3) Syncing background
 *************************************************************************
 
+The same mentioned for calendars is valid for addressbooks as well.
+
 Synchronizing calendars ( i.e. files ) means, 
 to merge two calendars in a useful way.
 If the two calendars are completely different, 
 there is no problem, the resulting calendar contains 
 all data from the local and from the remote calendar.
 
 Problems will occur, if you have edited items 
 from the local calendar on the remote machine. 
 Then it could be, that items are in conflict. 
 Two items are "in conflict", if they have the 
 same unique ID (which get an item at time of 
 creation and owns it until it is deleted )
 and they both are modified after the last 
 synchronization.
 
 At first sync of two calendars there is no item deleted. 
 If the calendars are synced before and there is an item, 
 which is not edited after the last sync and is only 
 available in one calendar, then this item is deleted 
 in this calendar.
 
 But when was the last synchronization between two calendars?
 
 To know that, KO/Pi creates at first syncing 
@@ -174,24 +213,254 @@ SYNC PREFERENCES:
   "Ask for every entry" 
   is chosen automatically, 
   if this is selected.
 
  -Take newest entry on conflict:
   This takes the newest entry on conflict. 
   May be the most useful syncing mode.
 
  -Ask for every entry on conflict:
   Pops up an event viewer dialog and 
   shows the two conflicting entries there. 
   The user can chose, which entry he would like to take.
   The button for the newest entry 
   is automatically set as default button.
   The color for the newest entry is green.
 
  -Force: Take local entry always:
   Even if the calendars are already synced
   there is no item deleted on local. 
 
  -Force: Take remote entry always:
   Analogous to  
   "Force: Take local entry always"
 
+*************************************************************************
+5) Details about sync profile kinds
+*************************************************************************
+
+a) Local file
+   Please specify a local file you want to sync with.
+
+b) Pi-Sync (direct Kx/Pi to Kx/Pi sync)
+   We mention here only KO/Pi, but the same is valid for KA/Pi.
+   If you want to sync with a device, where KO/Pi is
+   installed, you can easily get the remote file via network 
+   with the build in file transfer feature "Pi-Sync":
+   You have first to enable file transfer on the remote device:
+   - Start KO/Pi on the remote device.
+   - Choose Menu Synchronize-Enable Pi-Sync.
+   - Choose a port number, where KO/Pi should listen for 
+     file sending requests. Valid port numbers are numbers
+     between 1 and 65565. Do not specify port numbers, that are
+     used by other applications. A port number between 9000 and 9999
+     is most likely not used by another application.
+     The default port number is 9197 for KO/Pi.
+     If you specify a port number, which is already in use,
+     you will get an error message when closing this dialog.
+   - Choose a password.
+   - Click OK.
+     Now KO/Pi will send the calendar data via the network, 
+     if some other device is sending a "please send calendar"
+     request on the given port using the given password.
+     If you want to be sure, nobody can access your calendar
+     data, simply disable the file transfer feature on the 
+     remote device after the syncing is done by choosing:
+     Menu Synchronize-Disable Pi-Sync.
+    
+   On your local device, create a new profile and choose
+   profile kind "Pi-Sync".
+   Fill in the needed values:
+   - Password for remote access:
+     The password you specified on the remote device.
+   - Remote IP address:
+     The IP address of the remote device.
+   - Remote port number:
+     The port number you specified on the remote device.
+   
+   Now you can syncronize your local device easily with your 
+   remote device. This works well for all platforms KO/Pi is 
+   running on, e.g. syncing a KO/Pi on Zaurus with KO/Pi on Windows
+   is now very easy.  
+
+c) Remote file
+   Syncing with the profile kind "Remote file" is performed in three steps:
+   i) download the remote file to your local machine to a temp file
+   ii) sync with this temp file
+   iii) upload the synced file to the remote device
+
+   The down-/uploading if i) and iii) is done via a command line command.
+   Please specify the download/upload command ( like scp, ftp, ...) and the
+   file name of the temp file in the corresponding fields.  
+
+d) Mobile device (cell phone)
+   We mention here only KO/Pi, but the same is valid for KA/Pi.
+   Note:
+   It is only possible to sync a mobile phone with one particular device
+   running KO/Pi. If you want to be able to write data of more than one device
+   to the mobile phone (e.g. from your Zaurus and from your Windows Laptop)
+   do not sync with the mobile phone at all, but use the 
+   "Export to phone" functionality from the different devices.
+   Using "Export to phone" makes it not possible to get back data from the
+   phone, if it was changed there, of course.
+   If you sync with the phone, do not use "Export to phone" from any device.
+   (And do not sync, as mentioned above, from any other device with that phone). 
+   It would delete the needed information for syncing with that phone!
+
+   We are using Gammu (Version: 0.98.9) ( http://freshmeat.net/projects/gammu/ ) 
+   for accessing the phones. 
+   Note: You cannot use the original Gammu for syncing KDE-Pim/Pi, because 
+   we have modified the original version to make it useable for syncing!
+   Gammu allows access to many phones in many ways (Irda, Bluetooth, serial,...).
+   The recommended phone access using Gammu with KDE-Pim/Pi is Irda (infrared).
+   Bluetooth access is disabled on the Zaurus, but may work on Windows.
+   Please look at the Gammu homepage and documentation about more details 
+   configuring Gammu how to access your phone.
+   If you have problems accessing your phone, start KO/Pi from the konsole
+   and you will get a more detailed output what went wrong.
+   About Gammu from the Gammu homepage:
+       Gammu (formerly known as MyGnokii2) is a cellular 
+       manager for various mobile phones/modems. 
+       It supports the Nokia 2100, 3100, 32xx, 33xx, 
+       3410, 35xx, 51xx, 5210, 5510, 61xx, 62xx,
+       63xx, 6510, 6610, 6800, 71xx, 7210, 7250, 
+       7250i, 82xx, 83xx, 8910, 9110, 9210 
+       and compatible and AT devices (Siemens, Alcatel, 
+       Falcom, WaveCom, IPAQ, Samsung, SE, and others) 
+       over cables/infrared/BlueTooth.
+   
+   Here is an example what to specify to access a Nokia 6310i via infrared:
+   On Linux (Zaurus):
+     I/O device: /dev/ircomm
+     Connection: irda
+     Model: <leave empty>
+   
+   On Windows:
+     I/O device: <ignored - i.e. leave empty>
+     Connection: irda
+     Model: <leave empty>
+
+   Here is the overview from the Gammu documentation, 
+   how to specify the connection settings  for
+     I/O device: 
+     Connection: 
+     Model:
+ 
+   Note: The documentation uses the term "port", 
+         where we use the term "I/O device".
+   Note: You do not have to create/change the gammurc configuration file.
+         That will do KO/Pi for you.  
+   Note: For a known model, leave "Model:" always empty, 
+         such that Gammu can auto detect the model.
+
+# This is a sample ~/.gammurc file.
+# In Unix/Linux  copy it into your home directory and name it .gammurc
+#                or into /etc and name it gammurc
+# In Win32       copy it into directory with Gammu.exe and name gammurc
+# More about parameters later
+# -----------------------------------------------------------------------------
+
+[gammu]
+
+port = com8:
+#model = 6110
+connection = fbusblue
+#synchronizetime = yes
+#logfile = gammulog
+#logformat = textall
+#use_locking = yes
+#gammuloc = locfile
+#startinfo = yes
+#gammucoding = utf8
+
+[gammu1]
+
+port = com8:
+#model = 6110
+connection = fbusblue
+#synchronizetime = yes
+#logfile = gammulog
+#logformat = textall
+#use_locking = yes
+#gammuloc = locfile
+#startinfo = yes
+#gammucoding = utf8
+
+# -----------------------------------------------------------------------------
+# Now info about "Connection" parameter and connected with it port type
+# (more about port types later)
+# -----------------------------------------------------------------------------
+# "Connection" parameter | Port type | More details
+# -----------------------|-----------|-----------------------------------------
+# "fbus"                 | serial    | Nokia FBUS2
+# "fbusirda"/"infrared"  | serial    | Nokia FBUS2 over direct infrared device
+# "fbusdlr3"/"dlr3"      | serial    | Nokia FBUS2 with DLR3 cable
+# "fbusdku5"             | dku5      | Nokia FBUS2 with DKU5 cable. WIN32 ONLY
+# "fbuspl2303"           | usb       | Nokia FBUS2 with USB cable based on
+#                        |           | PL2303 chip.
+# "fbusblue"             | serial    | Nokia FBUS2 over Bluetooth serial device
+# "phonetblue"           | serial    | Nokia PHONET FBUS over Bluetooth serial
+#                        |           | device
+# "mrouterblue"          | serial    |
+# "mbus"                 | serial    | Nokia MBUS2
+# "at19200"/"at115200"/..| serial    | AT commands.8 bits, None parity, 1 stop
+#                        |           | bit, no flow control
+# -----------------------|-----------|-----------------------------------------
+# "irdaphonet"/"irda"    | irda      | Nokia PHONET FBUS over socket infrared
+# "irdaat"               | irda      | AT commands with socket infrared
+# "irdaobex"             | irda      | OBEX over socket infrared. MODEL "obex"
+# -----------------------|-----------|-----------------------------------------
+# "bluephonet"           | BT        | Nokia PHONET FBUS with Bluetooth stack
+# "bluefbus"/"dlr3blue"  | BT        | Nokia FBUS2 with Bluetooth stack
+# "blueat"/"atblue"      | BT        | AT commands with Bluetooth stack
+# "blueobex"             | BT        | OBEX with Bluetooth. MODEL "obex"
+#
+# Now more about port types and connected with it "Port" parameter
+# -----------------------------------------------------------------------------
+# Port type | "Port" parameter in Windows/DOS | "Port" parameter in Linux/Unix
+# ----------|---------------------------------|--------------------------------
+# serial    | "com*:"                         | "/dev/ttyS*"
+#           | (example "com1:")               | (example "/dev/ttyS1")
+#           |                                 | or "/dev/tts/**" (with DevFS)
+# ----------|---------------------------------|--------------------------------
+# irda      | ignored (can be empty)          | "/dev/ircomm*"
+# ----------|---------------------------------|--------------------------------
+# BT        |                 Bluetooth device address
+#           |                 (example "")
+# ----------|---------------------------------|--------------------------------
+# dku5      | ignored (can be empty)          | connection with it not possible
+# ----------|---------------------------------|--------------------------------
+# usb       | connection with it not possible | "/dev/ttyUSB*"
+#
+# Other config parameters
+# -----------------------------------------------------------------------------
+# Parameter name  | Description
+# ----------------|------------------------------------------------------------
+# Model           | use only, when Gammu doesn't recognize your phone model.
+#                 | Put it here. Example values: "6110", "6150", "6210", "8210"
+# SynchronizeTime | if you want to set time from computer to phone during
+#                 | starting connection. Do not rather use this option when
+#                 | when to reset phone during connection (in some phones need
+#                 | to set time again after restart)
+# GammuLoc        | name of localisation file
+# StartInfo       | this option allow to set, that you want (setting "yes")
+#                 | to see message on the phone screen or phone should enable
+#                 | light for a moment during starting connection. Phone
+#                 | WON'T beep during starting connection with this option.
+# GammuCoding     | forces using specified codepage (in win32 - for example
+#                 | "1250" will force CP1250) or UTF8 (in Linux - "utf8")
+# ----------------|------------------------------------------------------------
+# Logfile         | Use, when want to have logfile from communication.
+# Logformat       | What debug info and format should be used:
+#                 |   "nothing" - no debug level (default)
+#                 |   "text"    - transmission dump in text format
+#                 |   "textall" - all possible info in text format
+#                 |   "errors"  - errors in text format
+#                 |   "binary"  - transmission dump in binary format
+# ----------------|------------------------------------------------------------
+# Use_Locking     | under Unix/Linux use "yes", if want to lock used device
+#                 | to prevent using it by other applications. In win32 ignored
+
+   
+   
+   
+   
\ No newline at end of file