Palm OS Desktop HOWTO
 by David H. Silber [email protected]
 v1.0.0, 20 September 1998

 This HOWTO document explains how to use your Palm OS device with a
 Linux system.  Although HOWTO documents are targeted towards use with
 the Linux operating system, this one is not dependent on the version
 of unix used.
 ______________________________________________________________________

 Table of Contents


 1. Introduction

    1.1 This Document
    1.2 See Also
    1.3 Mailing List
    1.4 Mailing List Archives
    1.5 FTP Site

 2. General Information

    2.1 Hardware Installation

 3. Sharing Palm OS device Data with your Linux System

    3.1 The pilot-link software
       3.1.1 Installing the pilot-link software
       3.1.2 Using the pilot-link software
          3.1.2.1 pilot-xfer
          3.1.2.2 install-memo
          3.1.2.3 memos
          3.1.2.4 pilot-addresses
    3.2 MakeDoc
       3.2.1 Installing MakeDoc
       3.2.2 Using MakeDoc

 4. People

 5. A History of Palm OS devices.



 ______________________________________________________________________

 11..  IInnttrroodduuccttiioonn

 First there was the Pilot, then the PalmPilot, and now we have the
 Palm III from Palm Computing Devices.  IBM sells a rebadged version of
 the PalmPilot Professional, which they call the WorkPad.  What are
 these gadgets?  They are Personal Digital Assistants (PDAs), sometimes
 known as palm-top computers.  Sold as an electronic combination of
 address book, telephone directory and memo pad, they are actually
 general-purpose computers capable of running almost any kind of
 application.  The trick is to find Palm OS applications to fit your
 needs and to be able to share your data with your Linux system.  Palm
 OS devices incorporate software to synchronize their data with
 programs running on another computer.  Such software for use on a
 Windows 95 system is generally bundled with the device.  A MacOS
 version is also available.  If the foriegn computer is running some
 other operating system, you need to find third party software to work
 with your Palm OS device.  This document describes such software that
 is available for use on a Linux or unix system.


 11..11..  TThhiiss DDooccuummeenntt

 The latest version of this document can be read at
 http://www.orbits.com/Palm/PalmOS-HOWTO.html, and is part of the Linux
 Documentation Project (LDP).  This document superceedes the previous
 version, which was called the Pilot HOWTO.  See
 http://sunsite.unc.edu/LDP/ for further information about the LDP and
 other HOWTO documents.

 If you find anything in this document which needs to be corrected or
 better explained, please send me e-mail at the address above and
 specify which version of this document you are referring to.

 This document is Copyright (C) 1997 & 1998 by David H. Silber.  It is
 released under the copyright terms in the LDP HOWTO-INDEX document.


 11..22..  SSeeee AAllssoo

 The http://www.orbits.com/Palm/PalmDevelompent-HOWTO.html document
 describes how to use the gcc-based development system to write Palm OS
 applications.

 The http://www.orbits.com/Palm/PalmConduit-HOWTO.html document
 describes how to use the pilot-link libraries to write Linux-resident
 conduits for use with Palm OS devices.


 11..33..  MMaaiilliinngg LLiisstt

 The pilot-unix mailing list is maintained by Matthew Cravit pilot-
 [email protected].  Its mandate is:


      The pilot-unix mailing list is for discussion and idea-sharing for those
      interested in using the US Robotics Pilot PDAs with UNIX systems. This
      includes people who are interested in helping to develop tools to allow the
      Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot
      for Unix.




 For more information, including how to subscribe to the list, send
 mail containing the word ``INFO'' to pilot-unix-
 [email protected].  The subject line does not matter.


 11..44..  MMaaiilliinngg LLiisstt AArrcchhiivveess

 An archive of the pilot-unix mailing list can be found at
 http:///www.acm.rpi.edu/~albert/pilot/.  It is maintained by Chris
 Stevens [email protected].


 11..55..  FFTTPP SSiittee

 An FTP site containing an archive of Palm OS tools for use on unix
 systems is located at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/.  It is
 maintained by Jeff Dionne [email protected].






 22..  GGeenneerraall IInnffoorrmmaattiioonn

 22..11..  HHaarrddwwaarree IInnssttaallllaattiioonn

 Palm OS devices come with a ``cradle'' for exchanging data with the
 desktop computer.  This device is actually a serial cable with a
 custom holder for the Palm OS devices and an integrated `HotSync'
 button.  Plug your cradle into a spare serial port on your computer.
 When you run each of the stand-alone programs, you will need to place
 your Palm OS device in the cradle and push the `HotSync' button so the
 Palm OS device knows that it has to communicate.  If the Palm OS
 device happens to be off when the button is pushed, it will turn
 itself on.

 For convenience, create a device, /dev/pilot which will be an
 alternate name for the serial port to which your Palm OS device cradle
 is connected.  As the root user, enter the following at the shell
 prompt:


      ln /dev/cua0 /dev/pilot




 Replace cua0 with the name of the port to which you connected your
 Palm OS device's cradle.





 33..  SShhaarriinngg PPaallmm OOSS ddeevviiccee DDaattaa wwiitthh yyoouurr LLiinnuuxx SSyysstteemm

 33..11..  TThhee ppiilloott--lliinnkk ssooffttwwaarree

 The pilot-link suite of software tools allows you to download programs
 onto your Palm OS device, and transfer data for the Palm OS device's
 various built-in programs between the Linux system and the Palm OS
 device.  While these programs are not quite as seamless as the desktop
 software that comes with the Palm OS device, they do allow you to copy
 your data in both directions.  In general, each separate program in
 the pilot-link suite manages one type of data.



 33..11..11..  IInnssttaalllliinngg tthhee ppiilloott--lliinnkk ssooffttwwaarree

 The prepackaged versions will inevitably lag slightly behind the
 master distribution, but will be easier to install and not require
 configuration.  The master distribution might be a better choice in
 those rare occasions when you have been waiting for a particular
 feature or bug fix.

 You can get the _D_e_b_i_a_n _L_i_n_u_x (i386) port of _p_i_l_o_t_-_l_i_n_k version 0.8.7
 from ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-
 i386/otherosfs/pilot-link_0.8.7-2.deb.
 ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-
 i386/otherosfs/pilot-link_0.8.7-2.deb.  If this file does not exist,
 you will likely find a newer version located in the same directory.
 If all else fails, or if you want a more recent version than has been
 packaged for Debian, you can install the generic distribution, as
 detailed below.  Install this file in the normal manner and skip to
 _U_s_i_n_g _t_h_e _p_i_l_o_t_-_l_i_n_k _s_o_f_t_w_a_r_e.


 You can get the _R_e_d_H_a_t _L_i_n_u_x (i386) port of _p_i_l_o_t_-_l_i_n_k version 0.8.9
 from ftp://ftp.redhat.com/pub/contrib/i386/pilot-
 link-0.8.9-1.i386.rpm.  If this file does not exist, you will likely
 find a newer version located in the same directory.  If all else
 fails, or if you want a more recent version than has been packaged for
 RedHat, you can install the generic distribution, as detailed below.
 Install this file in the normal manner and skip to _U_s_i_n_g _t_h_e _p_i_l_o_t_-
 _l_i_n_k _s_o_f_t_w_a_r_e.

 For other versions of Linux or unix, or if you need the absolute
 latest version, download the version 0.9.0 of pilot-link from
 ftp://ryeham.ee.ryerson.ca/pub/PalmOS/pilot-link.0.9.0.tar.gz.  The
 version number is likely to change, but new versions should end up in
 the same location with a similar name.

 Once you have the software distribution, unpack it with:


      tar -xvzf pilot-link.0.9.0.tar.gz




 If your version of tar does not support the -z option, decompress the
 archive with gunzip, as follows:


      gunzip pilot-link.0.9.0.tar.gz | tar -xvf -




 This will create a directory (pilot-link.0.9.0) containing the source.

 Change your working directory to the source (pilot-link.0.9.0)
 directory.

 Run ./configure.  This will search through your system for information
 needed to compile the software.  configure will set things up to be
 installed in /usr/local by default.  If you want to change it, run
 ./configure --prefix=DIR, where DIR is replaced with the name of the
 directory to which the software will be installed.

 Run make.  This will compile the software.  The software will not be
 installed until later, so that you have a chance to try it out first.
 (If you are replacing an older version with a newer release, you may
 wish to check and make sure that no functionality that you need has
 been broken.  Generally, this is not a problem.)

 As the root user, run make install.  This will copy the software into
 directories under /usr/local (or wherever you specified with the
 --prefix option).  If you can not log in as root, you can install the
 software to some directory where you have write access.

 Don't forget to add any new directories of executables to your search
 path.


 33..11..22..  UUssiinngg tthhee ppiilloott--lliinnkk ssooffttwwaarree

 Most of the programs in the pilot-link suite are _c_o_n_d_u_i_t_s, that is
 they transfer data into or out of your Palm OS device.

 Each time you use of one of these programs, press the HotSync button
 on your Palm OS device's cradle.  This will initiate the Palm OS
 device side of the data transfer.  Note that not all of these programs
 prompt you to press the `HotSync' button, so you may have to remember
 to do it yourself.


 For more details, and other options to these programs, view the
 corresponding manual page.  There is an overview manual page under the
 name pilot-link.  For the pilot-xfer program, for example, type man
 pilot-xfer at your unix shell prompt.




 33..11..22..11..  ppiilloott--xxffeerr

 Possibly the most useful program in the pilot-link suite, pilot-xfer
 allows you to install programs on your Palm OS device, make a backup,
 and restore that backup.


 To install a program:


      pilot-xfer /dev/pilot -i program.prc




 To backup your Palm OS device:


      pilot-xfer /dev/pilot -b backup-directory




 This will copy all of the databases on your Palm OS device, (including
 programs?)  to a directory called ``backup-directory'', creating it if
 it does not already exist.

 To restore data to Palm OS device:


      pilot-xfer /dev/pilot -r backup-directory




 Generally, you will only need to do this if your Palm OS device loses
 power or if you have to do a hard reset.

 To list the programs on your Palm OS device:


      pilot-xfer /dev/pilot -l







 33..11..22..22..  iinnssttaallll--mmeemmoo

 Install a Linux file onto the Palm OS device as a memo.


 To install a memo into your (already existing) _p_r_o_j_e_c_t category:


      install-memo /dev/pilot -c project project.memo




 The name of the file will be inserted into the memo as its first line
 and will appear in the directory of memos on your Palm OS device.



 33..11..22..33..  mmeemmooss

 This program grabs each memo from the Palm OS device and prints it out
 in standard mailbox format.

 To view your memos:


      memos /dev/pilot











 33..11..22..44..  ppiilloott--aaddddrreesssseess

 pilot-addresses Transfer the address database to or from the Palm OS
 device.

 To write your address data to a Linux file from your Palm OS device:


      pilot-addresses /dev/pilot -w storage.file




 To read your address data from a Linux file onto your Palm OS device:


      pilot-addresses /dev/pilot -r storage.file










 33..22..  MMaakkeeDDoocc

 One short-coming of the Palm OS device's built-in memo program is that
 it does not deal well with large documents.  To compensate for this,
 Rick Bram <mailto:[email protected]> wrote _D_o_c, a document reader
 for the Palm OS device.  (See
 http://www.concentric.net/~rbram/doc.shtml).  Documents can be
 converted to the Doc format with MakeDoc, by Pat Beirne
 <mailto:[email protected]>.



 33..22..11..  IInnssttaalllliinngg MMaakkeeDDoocc

 MakeDoc can be downloaded from
 http://www.concentric.net/~rbram/makedoc7.cpp.  Compile it with your
 C++ compiler and install the resulting executable as ``makedoc'' in a
 directory in your search path.  There seems to be a small bug in
 makedoc (version 0.7a) in that it does not output a newline as the
 last character displayed to the user.  This does not seem to affect
 the resulting document file, but it is annoying.

 There is a new version out, but it requires Java.  Take a look at Pat
 Beirne's MakeDoc web page at
 http://cpu563.adsl.sympatico.ca/MakeDocJ.htm.



 33..22..22..  UUssiinngg MMaakkeeDDoocc

 Use MakeDoc as follows:


      makedoc data.txt data.prc "Data to display with Doc"




 This will create a file data.prc, which can be installed on your Palm
 OS device with pilot-xfer.  The text _"_D_a_t_a _t_o _d_i_s_p_l_a_y _w_i_t_h _D_o_c_" will
 be displayed in the directory of documents that _D_o_c manages.

 The syntax for MakeDoc is as follows:


      makedoc [-n] [-b] <text-file> <prc-file> <story-name>
      or
      makedoc -d [-b] <prc-file> <text-file>





    <<tteexxtt--ffiillee>>
       The file that you wish to convert.

    <<pprrcc--ffiillee>>
       The name of the resulting file.  (End the name with ``.prc''.)

    <<ssttoorryy--nnaammee>>
       The name you want displayed in the Doc or Jdoc directory of
       documents.

 There are also options to decode the resulting .prc file and manage
 various compression options.







 DD..  PPeeooppllee

 Kenneth Albanowski <mailto:[email protected]> Maintains the pilot-link
 suite of tools.

 Donnie Barnes <mailto:[email protected]> Packaged pilot-link suite as Red
 Hat RPM files.

 Rick Bram <mailto:[email protected]> Author of Doc.

 Matthew Cravit <mailto:[email protected]> List owner for
 the _p_i_l_o_t_-_u_n_i_x mailing list.

 Jeff Dionne <mailto:[email protected]> Original author of the
 pilot-link suite of tools.  Manages the FTP area for the UNIX Palm
 OS/Pilot development project.

 Mark W. Eichin <mailto:[email protected]> Ported pilot-link
 suite to Debian Linux.

 David H. Silber <mailto:[email protected]> Author of this document.

 Chris Stevens <mailto:[email protected]> Maintains the pilot-unix
 mailing list archives.


 EE..  AA HHiissttoorryy ooff PPaallmm OOSS ddeevviicceess..

 There are two versions of the Pilot.  They are the _1_0_0_0 and the _5_0_0_0
 and have 128k and 512k of RAM, respectively. They come with Palm OS
 1.0 in ROM.

 Then came two devices with the name _P_a_l_m_P_i_l_o_t.  They are the _P_a_l_m_P_i_l_o_t
 _P_e_r_s_o_n_a_l and the _P_a_l_m_P_i_l_o_t _P_r_o_f_e_s_s_i_o_n_a_l and have 512k and 1 Meg of
 RAM, respectively.  They also have a backlighting feature for the LCD
 panel and version 2.0 of the operating system.  The _P_r_o_f_e_s_s_i_o_n_a_l also
 comes with a TCP/IP stack and a few extra programs built-in.

 (IBM has released a rebadged version of the PalmPilot Professional,
 which they call a _W_o_r_k_P_a_d.)

 Now we have the Palm III, which has a redesigned case and an infrared
 port, not to mention the 2 Meg of RAM and Palm OS 3.0.

 It is possible to upgrade any Pilot by swapping out the memory card,
 which includes both RAM & ROM.  Of course, this doesn't get you
 backlighting for the original Pilot series.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.