$Id: README,v 1.19 2001/08/12 03:36:44 thosch Rel $ IC35Link for Linux ================== IC35Link provides tools to communicate with the Siemens IC35 over a serial port. Contents Abstract Installation configure, make, install create configure script Usage of ic35sync Examples Restrictions Usage of ic35mgr Restrictions Files in the distribution Documents Miscellaneous Tools Sources in the src directory References Standard Disclaimer, Warnings, Copyright Abstract -------- The tools included in the IC35Link package are: - ic35sync synchronizes IC35 address, schedule, todo and memo data with Personal Information Management databases (PIMfiles). - ic35mgr The IC35 manager is for accessing IC35 MMCard(s), backup,restore the IC35 PIM-database and install applications on the IC35. CAVEAT: install applications on the IC35 is (as of version 1.17) not yet implemented. - vcaconv is a converter for PIMfiles in vCard,vCalendar and binary formats. it was mainly used during development. For non-developers the "imphandy" conversion might be useful to manage the phonebook of a mobile phone with the IC35: it converts vCards into the "HANDY" category for uploading them from this category on the IC35 to the phonebook of the mobile phone (after import or sync with IC35). - ic35log is for pretty-printing ic35sync, ic35mgr (and 'portmon') logfiles and useful mainly for developers. - ic35sync.txt describes the IC35 synchronization protocol (in german). - ic35mgr.txt describes the IC35 manager protocols (in german). All programs give help about usage if called with the short "-h" or the long "--help" option. Starting with version 1.17 the package is named "ic35link", because it provides more than just IC35 synchronization under GNU/Linux. Up to version 1.16 the package name was "ic35sync". Installation ------------ Unpack the archive ic35link-*.tar.gz (you appeareantly did that ;-). configure, make, install Do the usual ./configure make su # superuser login for install make install-strip # strip symbols and debugging info exit # superuser logout Installation is done to /usr/local/bin and /usr/local/share/ic35link by default, change that with 'configure --prefix=/some/other/path'. For details run 'configure --help' and see the file INSTALL. The 'configure' options of major interest are: --prefix=/opt install to /opt/bin/ instead of default /usr/local/bin/ --disable-logandcomsim compile without logging and simulated communication support --disable-warnings disable compile warnings --enable-ansi enable strict ANSI-C compilation --enable-pedantic enable pedantic compile warnings be warned to get several compile errors and/or warnings feel free to fix them (and send me the patches :-) * The programs are compiled with debugging info. Should you want to install them with that, use 'make install' instead of the 'make install-strip' above. * The programs and documents can be uninstalled with 'make uninstall'. * If you modify the vCard/vCalendar parser source vcc.y, you will need 'bison' version 1.25 or newer. Compilation with 'yacc' will not work and/or create a vcc.c producing 'parser stack overflow' errors. create configure script If you use an archive ic35link-*.tar.gz you should not need this. If you obtained ic35link from the public CVS repository you have to generate the configure script and Makefile.in with sh autogen.sh It will check for autoconf and automake, you'll have to install these packages if some of the checks fail. If all goes well it will automatically run './configure' with the options passed to autogen.sh and "--enable-maintainer-mode". The latter enables 'make maintainer-clean', which deletes everything not in the CVS repository, e.g. also the configure script. Setting the environment variable NOCONFIGURE to some non-empty value will prevent autogen.sh from running configure. Usage of ic35sync ----------------- ic35sync synchronizes IC35 address, schedule, todo and memo data with Personal Information Management databases (PIMfiles) mainly in vCard,vCalendar format. Get information about usage with: ic35sync --help ic35sync supports 4 modes of operation, given as command argument: - status reports IC35 status: firmware version, timestamp of last sync operation and total and modified number of records per IC35 file. No PIMfiles are accessed, contents of IC35 are not changed, thus good for an initial test. - export does export IC35 data to PIMfile(s), data in IC35 is not changed and no IC35 or PIM records will be deleted. The sychronisation stamp will not be written to IC35 and any changemarks on records in the IC35 remain intact. This is the initial operation to start using IC35 data also with Linux Personal Information Managers. It is also usable to backup all the IC35 data. Records from existing PIMfile(s) can afterwards be propagated to IC35 with an 'import' or 'sync' operation. - import does import data from PIMfile(s) into IC35, changes in PIMfile(s) reflect only the IC35 record numbers and status, no IC35 or PIM records will be deleted. The synchronisation stamp (current date and time) will be written to IC35 only if all IC35 records match with PIMfile, e.g. if the IC35 was empty before the import. This is the initial operation to start using Linux PIM databases also on IC35. it can be used also to restore data into IC35. Any records previously existing in IC35 can then be propagated into PIMfile(s) with an 'export' or 'sync' operation. - sync synchronizes changes in IC35 and PIMfile(s): records modified in IC35 will be updated to PIMfile(s), records deleted in IC35 will be deleted from PIMfile(s) and vice versa. If changes to the same record were made in both the IC35 and the PIMfile, the latter takes precedence, i.e. PIM overrides IC35. All record changemarks on IC35 will be cleared and the current date and time will be written to IC35 as synchronisation stamp, because after sync all IC35 records match with PIMfile(s). With the vCard/vCalendar format (default or option "--format vca") up to 3 PIMfile(s) can be specified on the ic35sync commandline: If 3 PIMfiles are specified, the first file is for Addresses, the second file is for Schedule and ToDo, the third file is for Memo. If 2 PIMfiles are specified, the first file is for Adresses and the second file for Schedule, ToDo and Memo. Korganizer and gnomecal will work with the second file only if there are not VMEMO-records in it, i.e. only if there is not any Memo note on the IC35! If 1 PIMfile is specified, this single file is used for all data from Adresses, Schedule, ToDo and Memo. Korganizer, gnomecal and and gnomecard cannot work with that single file! If no PIMfiles are specified, the default filenames are used, which are ic35.vcard for Adresses, ic35.vcal for Schedule and ToDo, and ic35.memo for Memo, the files are assumed in the current directory. Examples * GNOME addressbook and calendar IC35 syncstation connected at /dev/ttyS1, IC35 password is "secret" initial export from IC35: ic35sync -d /dev/ttyS1 -p secret export \ ~/.gnome/GnomeCard.gcrd ~/.gnome/user-cal.vcf ic35.memo synchronize changes in IC35 and addressbook,calendar: ic35sync -d /dev/ttyS1 -p secret sync \ ~/.gnome/GnomeCard.gcrd ~/.gnome/user-cal.vcf ic35.memo * KDE KOrganizer and GNOME addressbook initial import into IC35 at /dev/ic35, no IC35 password: ic35sync import ~/.gnome/GnomeCard.gcrd \ ~/.kde/share/apps/korganizer/calendar.vcs ic35.memo synchronize changes in IC35 and addressbook,KOrganizer: ic35sync sync ~/.gnome/GnomeCard.gcrd \ ~/.kde/share/apps/korganizer/calendar.vcs ic35.memo Restrictions * ic35sync yet has no options for resolving synchronize conflicts. If the same record is modified on both sides, the modification in the PIMfile takes precedence and overrides the changes on IC35. * ic35sync yet has a proprietary VMEMO format for memo records. The VMEMO format was invented by me following the vCard/vCalendar standard. Unfortunately there is no GUI software supporting it. Suggestions for the memo records are welcome. * ic35sync should be used with _existing_ vCalendar files, because Korganizer and gnomecal rely on their own file formats and do not work properly with vCalendar files _created_ by ic35sync. Korganizer uses newline characters as line separators and wants its own PRODID. gnomecal uses carriagereturn linefeed sequences as line separators and wants its own PRODID and VERSION. ic35sync does respect and not change the format of an existing vCalendar file to avoid confusing Korganizer/gnomecal. * ic35sync's sync operation is rather slow, because always all IC35 records are read to find the records, which were deleted from the PIMfile(s). This is needed, as Korganizer, gnomecal and gnomecard leave no traces (e.g. delete-flags) from deleted records. * gnomecal does not support VEVENT.DESCRIPTION but multiple lines in VEVENT.SUMMARY. ic35sync maps the first line of VEVENT.SUMMARY to/from the IC35 "Summary" field and all remaining lines to/from the IC35 "Notes" field. * gnomecal does not support VTODO.DTSTART. ic35sync maps the IC35 "Start" field to/from a line marked with "DTSTART:" in VTODO.DESCRIPTION. * gnomecard does not support the X-PILOTSTAT change mark. ic35sync regards VCARD records as changed if their with revised time VCARD.REV is newer than the date and time of the last sync. * korganizer does not support VTODO.CATEGORIES, VTODO.DTSTART and VTODO.DUE ic35sync maps the IC35 Category and the "Start" and "Due" fields to/from lines marked "CATEGORIES:", "DTSTART:" and "DUE:" in the VTODO.DESCRIPTION. * korganozer supports only VEVENT.DALARM, but not VEVENT.AALARM ic35sync maps IC35 "LED" and "Beep" alarms to/from VEVENT.DALARM. * the IC35 address fields "(Def.)" have no VCARD counterparts. ic35sync maps them to/from lines marked "(def1):" and "(def2):" in VCARD.NOTE. Usage of ic35mgr ---------------- The IC35 manager currently supports access of the IC35 MMCard(s) and backup,restore the IC35 internal PIM-database to/from a file. Get help about usage with ic35mgr --help and experiment (and please tell me about problems, suggestions and wanted features, e-mail address below). Restrictions * The ic35mgr MMCard access commands mmcget,mmcput,mmcdel accept the filepath in the IC35 native form (e.g. MMcard1\IC35\APP\REVERSI.APP) or more convenient with lowercase characters and slash separators (e.g. mmcard1/ic35/app/reversi.app). The filepath argument in the IC35 native form must be enclosed in single (') or double (") quotes to prevent the shell from eating the backslash (\) characters. * Reading a MMCard file with mmcget will set the timestamp of the local file to that of the MMCard file. Even when only reading a MMCard file, the IC35 will set the MMCard file's timestamp to the current date and time. * Installing application programs on the IC35 is planned, but not yet implemented. If someone (from Siemens) would provide me with the specification of the installation protocol would ease this a lot. Files in the Distribution ------------------------- Documents README sic! you're reading this NEWS release information about IC35Link ChangeLog sic! details about what was changed TODO sic! what remains to be done and whish list COPYING GNU GENERAL PUBLIC LICENSE AUTHORS who has written IC35Link THANKS who has contributed to IC35Link doc/ic35sync.txt description of IC35sync protocol, yet only (?) german doc/ic35mgr.txt description of IC35manager protocol, yet only (?) german Miscellaneous INSTALL generic installation instructions for 'configure' autogen.sh generates configure and Makefile.in etc. config.h configuration header created by configure config.h.in input for configure to create config.h, created by autoheader configure configuration script, created by autoconf configure.in input for autoconf to create configure Makefile makes 'make' make it ;-) created by configure Makefile.in input for configure to create Makefile, created by automake Makefile.am input for automake to create Makefile.in Tools src/ic35log.sh make logfiles of IC35 communications more readable. supported are logfiles created by "portmon" (from www.sysinternals.com) and the logfiles from ic35sync and ic35mgr (of course ;-). Sources in the src directory ic35sync.c IC35 synchronize PersonalInformationManagement (PIM) data ic35mgr.c IC35 manager: access MMCard, backup,restore database dataio.c dataio.h PIM data import to / export from IC35 database records datatxt.c support for text output IC35 record databin.c support for binary IC35 record format (PIM)files datavca.c support for vCard,vCalendar format PIMfiles vcutil.h vcutil.c utilities for vCard,vCalendar ic35frec.h ic35frec.c IC35 record access and file descriptions syntrans.c syntrans.h IC35 synchronize transactions: connect, disconnect open, close, read, write IC35 database file synproto.c synproto.h IC35 synchronize protocol mgrtrans.c mgrtrans.h IC35 manager transactions: connect, disconnect MMCard status, directory, file access mgrproto.c mgrproto.h IC35 manager protocol genproto.c genproto.h general IC35 protocol support comio.c comio.h basic serial communication with IC35 util.c util.h utilities: logging, errors, messages vcc.h export header for vCard,vCalendar API vcc.y parser for vCard-,vCalendar-files vobject.h vobject.c API for vCard,vCalendar VObject port.h compilation environment for vCard,vCalendar API vcaconv.c vCard,vCalendar conversion, e.g. to/from binary IC35 data References ---------- The vCard,vCalendar API sources were taken from gnome-pim-1.2.0, and fixed a bit to reduce compile warnings. Sources for vCard,vCalendar API: - Gnome-PIM gnome-pim-1.2.0.tar.gz from ftp://ftp.gnome.org/pub/GNOME/stable/sources/gnome-pim/ - KPilot kpilot_3.1.10-1.0.tar.gz (based on KPilot 3.1b9) from ftp://kde.tdyc.com/pub/kde/debian/dists/potato/contrib/source/ see also http://www.slac.com/pilone/kpilot_home/index.html - versit consortium's SDK for Windows DLLs from http://www.imc.org/pdi/sdkdllsr.zip The autogen.sh script was taken from gnome-pim-1.3.2 and fixed a bit to fit the needs of ic35link. Standard Disclaimer, Warnings, Copyright ---------------------------------------- THIS SOFTWARE HAS BUGS (as any software has ;-). Use it at your own risk. I take no responsibility for any data loss or damage, etc. done by this software, i.e. should your IC35 crash or explode while using ic35sync or ic35mgr, sorry. Besides my home machine this software was successfully used with: - KDE-1.1.2 Korganizer v1.1.1 - Gnome-1.2 gnomecard,gnomecal from gnome-pim-1.2.0 - IC35 Firmware V1.28 - IC35 Firmware V1.38 (thanks Thomas Lichtenberg) - Debian-2.2r2 kernel 2.0.36 gcc-2.95.2 Pentium-I/133MHz /dev/ttyS3 - Debian-2.2r2 kernel-2.2.13 gcc-2.95.2 Pentium-III/400MHz /dev/ttyS1 - SuSE-7.2 (thanks Karl Stroetmann) - SuSE-7.0 kernel-2.2.16 gcc-2.95.2-98 AMD-K5/100MHz /dev/ttyS1 - SuSE-7.0 kernel-2.2.16 gcc-2.95.2-98 Pentium-III/450MHz /dev/ttyS0 - SuSE-6.0 kernel-2.0.36 gcc-2.7.2.3-5 BAYCOM Notebook Pentium-I/166MHz - Mandrake-7.2 AMD-Duron/750MHz /dev/ttyS1 (thanks Malte Schmidt) - Mandrake-8.0 gcc-2.96 (thanks Christian Theile) That being said, I _really_ want comments regarding this software as well as suggestions and bug reports. t.schulz@d2mail.de Thomas Schulz 2000-12-25 Geibelstrasse 57 D-22303 Hamburg Germany Copyright (C) 2000,2001 Thomas Schulz This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program in the file COPYING; if not, write to the Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA