forked from jichu4n/pilot-link
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
414 lines (315 loc) · 16 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
pilot-link -- Palm Handheld Glue - http://www.pilot-link.org
The code and other related files in this distribution are licensed under the
GNU General Public License or "GPL", and the GNU Lesser Public License, or
"LGPL". See http://www.fsf.org/copyleft/lesser.html for a copy of the LGPL.
We will only accept changes into pilot-link if they comply with the proper
licensing. There are many companies using pilot-link in their core products
and are complying with the license. There are also others companies who don't
believe that adhering to the licensing is that important, and violate the
license instead. Please do not be one of these companies.
This code is under active development. If you would like to contribute to the
project, you can contact me, David A. Desrosiers, via email by sending an
email to [email protected].
We can also be reached on Internet Relay Chat, "irc", at irc.pilot-link.org
in the channel #pilot-link. I go by the name "setuid" there, and there are a
dozen or more helpful users and other developers that hang out there on a
regular basis.
From the main pilot-link website, you will find many links to helpful
documents, HOWTOs, complementary projects that use pilot-link, and other
resources to help you get the best use out of your Palm device on your
platform of choice; Linux, BSD or Mac OS X.
Main website........: http://www.pilot-link.org/
HOWTO Documents.....: http://howto.pilot-link.org/
Code documentation..: http://doxygen.pilot-link.org/
Reporting bugs......: http://bugs.pilot-link.org/
Mailing lists.......: http://lists.pilot-link.org/
We also have several mailing list that you can join. There are mailing lists
for development-specific talk, general talk, announcements and commits. On
the mailing list webpage, you will have the ability to subscribe and read the
past lists archives and posts from thousands of other users.
The architecture of pilot-link
------------------------------
There are several core parts of pilot-link:
the libraries
-------------
pilot-link communicates with Palm handhelds using several methods and
functions specific to these devices. In order to facilitate these
communications, the functions are stored in a library, which other
applications can link to and gain access to those functions. J-Pilot
is one example of an application that does exactly this.
The core pilot-link libraries are in the 'libpisock' and 'libpisync'
subdirectories of the project tree.
The standard library for pilot-link is written in the C language, and
is very easy to understand and extend if you need to do so.
the conduits
------------
In pilot-link, there is also the notion of "conduits", that can be
used to communicate directly with your Palm handheld. These
"conduits" are the actual applications that you run directly. These
are the "userspace" programs.
These "conduits" are found in the 'src' subdirectory of the project
tree.
the language bindings
---------------------
Along with the powerful libraries and conduits, pilot-link also
provides the ability to communicate with your Palm handheld using
your favorite language of choice. Currently, pilot-link includes
language "bindings" in Perl, Python, Java, and Tcl. This means you
can use those languages, instead of C directly, to talk to your Palm
handheld device and communicate with it.
Want to write a Java application that uses pilot-link's libraries?
Simple! Just use the Java bindings.
Want to talk to your Palm device using Perl code? Simply use the Perl
bindings.
Our hope is that more bindings will be added in the future, such as
Ruby or Objective C.
the tests
---------
In order to make sure the code in pilot-link does what it should, we
also include quite a bit of regression tests to check to make sure
each function we use is operating properly. These tests will check
each of these functions and report any errors or success as they are
run.
Building the project
--------------------
pilot-link is developed primarily on Debian GNU/Linux and FreeBSD. It
is expected to build cleanly on any POSIX-compliant platform. Some
users have reported success building it under Cygwin on Windows. It
will also build cleanly under Apple OSX, if you have the proper
development environment installed and configured on your machine.
Each of these will be explained in detail below.
Building pilot-link on Linux/Unix systems
-----------------------------------------
PLEASE READ THIS CAREFULLY! The worst thing you can do is the
overly-common misuse of "configure, make, make install" to build and
install pilot-link. There are so many customizations you can make to
pilot-link, that you should almost never build pilot-link without
options. Please make sure you use the --help option to "./configure"
to make sure you're enabling all of the options you wish to use.
If you have downloaded this code from the website, or as a tarball,
simply unpack the tarball and run "./configure" in the top-level
directory with your specific arguments. "./configure --help" will
describe all of them.
If you want to install in some place other than the default location of
/usr/local, pass configure an argument such as:
$ ./configure --prefix=/home/fred/pilot
If configure ran successfully, you should run 'make' to build the
software.
$ make
After the source builds, feel free to play around in the 'src'
subdirectory, CAREFULLY. 'dlpsh' and 'pilot-xfer' are probably the
most useful programs for you, and also the safest to use
non-destructively.
Once you have determined that pilot-link works and suits your needs
by testing with these programs, switch to the super user, typically
"root", to install the conduits, libraries, docs, and headers
required for proper operation and development of pilot-link.
$ su - root
If you wish to include root's environment when you install (STRONGLY
recommended), be sure to pass the '-' option when you su to root, as
above.
AFTER you test that the code works properly, run 'make install' to
install the code into your specified prefix, or the default of
/usr/local will be used.
# make install
If you are using a CVS version of pilot-link, you will have to run
'sh ./autogen.sh' instead, from the top-level directory, which will
create and bootstrap the "./configure" script for you.
You will also need to have your development environment set up, which
will require such tools as automake, autoconf, libtool, some system
headers, and others to be properly installed and configured on your
machine first. If you are running a current Linux or Unix system,
these common tools are probably packaged for you.
Building pilot-link on OS/2
---------------------------
pilot-link on OS/2 only supports serial devices. USB is unsupported
at this time. We would like volunteers to help us out porting
pilot-link to work with USB on that platform. If you are skilled and
interested in helping, please contact me directly. I can't seem to
get the OS to run correctly on any hardware I have, so I need some
help there.
The steps are fairly straightforward.
Run the os2configure.cmd script in the top-level directory.
Run make -f Makefile.os2
Play around, CAREFULLY. pilot-xfer is probably the most useful
program for you, and also the safest of all to use non-destructively.
Also dlpsh is a good app to use to poke around in your Palm device.
Run 'make install' if you you have tested thoroughly and are sure
pilot-link works well for you.
Note on pilot-debug: This program is a work-in-progress, and requires
Tcl 7.5 (or greater) and optionally Tk 4.1 (or greater) and/or
Readline 2.0. You'll need to modify Makefile to to use Readline 2.0,
and if your Tcl or Tk aren't in standard places, you'll need to
wiggle configure or the Makefile. You must have installed pilot-link
or else run pilot-debug in the pilot-link source directory if you
want the fancy images for the Remote UI window.
Building pilot-link on Apple OSX/Darwin
---------------------------------------
To build pilot-link on Apple OSX ("Darwin") systems, you will need to
make sure you have some development tools installed first. These can
all be found in the "Fink" package repository hosted on SourceForge.
http://fink.sourceforge.net/
Download and install the latest Fink from there onto your OSX system.
These will install into the $PREFIX of /sw on your machine. To gain
access to the binaries it places in /sw/bin, export the proper
/sw/bin path to the BEGINNING of your $PATH environment variable. Do
NOT put it at the end:
Correct method (for bash)
-------------------------
export PATH=/sw/bin:$PATH
Incorrect method (for bash)
---------------------------
export PATH=$PATH:/sw/bin
The reason we need it at the beginning, is so that we can make sure
the GNU tools that Fink uses, are chosen first, and not the OSX tools
which may carry the same name (libtool is one example).
Now that you have Fink installed, and the $PATH exported properly,
execute the following command (as root):
# fink selfupdate
This will update your newly-installed Fink to the latest version
available for download. In many cases, the latest version for
download may not be the latest version available. 'selfupdate'
ensures that it is.
From there, you will need to install some GNU tools. Please install
the following packages, using the 'fink install <packagename>'
syntax:
automake
autoconf
libtool
libtool-shlibs
m4
readline
readline-shlibs
make
When these are installed, you can then unpack pilot-link, and run the
./configure found inside with your custom arguments and parameters.
REMEMBER: It is almost always incorrect to run ./configure without
passing it any parameters. Please use './configure --help' first to
see descriptions of the parameters you will need to use to customize
pilot-link for your needs.
After running ./configure, you should then be able to build it with
the 'make' command. If it builds clean, PLEASE remember to test it
first. The syntax to test pilot-link on OSX for USB devices is as
follows:
<pilot-link-command> -p usb: [arguments..]
One example of this is as follows:
pilot-xfer --port usb: --list
This should list the record and resource databases found on your Palm
handheld device.
Building pilot-link on Cygwin under Windows
-------------------------------------------
FIXME: Unsupported at this time, but may run under Cygwin talking to
COM1 through the Cygwin virtual serial port bridging.
Some usage notes about pilot-link
---------------------------------
read-ical and sync-ical will only run if you have ical-2.x installed
and in the path.
sync-plan is a full syncronization program, though it has some
interesting quirks and requirements. You must running netplan from
plan-1.6.1 (probably available at
<http://www.in-berlin.de/User/bitrot>). Future or later versions may
work, but I cannot gaurantee this. Sync-plan does _not_ check the
Palm's user name, so be very careful not to sync two Palms to the
same Plan database. This will not work in a useful manner, at the
moment. Sync-plan leaves a file, that has a name starting with
"pilothash", in the current directory. This file must be present for
all future syncs between that plan database and that Palm.
As sync-plan is a work in progress, please contact me with any
problems.
The default connection rate is 9600 baud. You are welcome to try
higher baud rates (19200, 38400, or 57600) by setting the PILOTRATE
environment variable, but various machines have various limitations.
(Be careful about 38400 on a Linux box if you've been using setserial
to change the multiplier.)
pilot-mail (which requires a Palm with the new Mail application, as
well as sendmail and/or a POP3 server) is still in the experimental
stage. Run with an argument of '-H' for help. While I don't expect
it to lose data, (and by default mail is kept on both sides, not
deleted) I can not and will not guarantee that you won't. Please back
up your UNIX mailbox and Palm mailbox (via pilot-xfer) before
experimenting.
If you wish, you may easily change the default settings (pop host,
password, etc.) for pilot-mail by editing the top of pilot-mail.c, as
well as by setting the environment variables indicated in its help.
Scott Grosch's "validate" program is included, and can be made via
'make validate', but it may not be of use to anyone but Scott.
Debugging notes
---------------
Please see doc/README.debugging for more detailed information
describing how to debug pilot-link's core protocols and interfaces.
Debugging pilot-link will allow us to make pilot-link work better on
new devices and with new applications.
USB Notes
---------
Please see doc/README.usb for more detailed information on
configuring your system to use USB-enabled Palm handheld devices
using the standard Linux "visor" kernel module.
If you would like to try the new libusb code, please see
doc/README.libusb for details on how to get that working properly.
FreeBSD Notes
-------------
Please see doc/README.freebsd for more detailed information on
setting up pilot-link to work with FreeBSD systems. In FreeBSD, you
may have to set your ACLOCAL_FLAGS="-I /usr/local/share/aclocal/"
before running autogen.sh.
To use libusb, install the libusb port first and run configure. You
will need to set LDFLAGS, CFLAGS and CPPFLAGS to let configure find
the library, though. Something like this:
$ ACLOCAL_FLAGS="-I /usr/local/share/aclocal/"
$ LDFLAGS="-L/usr/local/lib"
$ CFLAGS="-I/usr/local/include"
$ CPPFLAGS="-I/usr/local/include"
$ export ACLOCAL_FLAGS LDFLAGS CFLAGS CPPFLAGS
Embedding information
---------------------
As of 0.5.0, the headers in pilot-link have been rearranged slightly
so that it should be easier and more reliable to use the libpisock.a
library in external applications.
If you want to use the pilot-link portability layer (configured via
autoconf), then include pi-source.h. Otherwise, do not touch this
file, as it sets up a mildly complex environment.
For all normal operations, simply include the obvious files (pi-file
for pdb and .prc file access, pi-dlp for DLP sync functions, etc.).
pi-macros contains the portable byte-access routines.
Reporting Bugs
--------------
Any bugs you find with pilot-link can be easily reported in the
online bug-tracking system found at http://bugs.pilot-link.org. From
there, any issues reported can be updated, audited, commented on, and
resolved. You can also attach files and patches any other relevant
items to each bug report, to help our team solve the issues or add
the features you report.
PLEASE NOTE
-----------
Please check the existing bugs in the system FIRST
before reporting your bug. There may be an identical
report from another user that matches your bug. If
you find one that is similar, please add your notes
and details to that existing report. Please try to be
as specific as possible.
If your bug is unique, and does not appear in the system, please fill
out a new bug report and remember to be as detailed as possible when
filling it out. Make sure to include your operating system, version
of pilot-link, Palm handheld type and the PalmOS version running on
the device, and any steps required to reproduce the bug.
With this information, the developers can be well-informed with the
information they'll need to help try to track down and fix your bug.
License notes
-------------
The utility programs, otherwise known collectively as "conduits"
(pilot-xfer, dlpsh, sync-plan, etc.) are licensed for use under the
GPL. For more information, please see the file COPYING included in
this source tree.
The libraries (libpisock, libpisync, libpisock++, and libcc) and the
language bindings (Perl, Python, Java, and Tcl) are licensed for use
under the LGPL. For more information, please see COPYING.LIB included
in this source tree.
All contained source is the copyright of its author(s). Please see
the copyright notices in the individual files for more information on
their individual copyrights.
---------------------
Happy Hacking,
The pilot-link Team
---------------------
pilot-link was originally written by Kenneth Albanowski <[email protected]>
and others.