home *** CD-ROM | disk | FTP | other *** search
/ PC World 1999 August / PCWorld_1999-08_cd.bin / doc / HOWTO / PalmOS-HOWTO < prev    next >
Text File  |  1998-09-23  |  15KB  |  529 lines
  1.   Palm OS Desktop HOWTO
  2.   by David H. Silber palm@orbits.com
  3.   v1.0.0, 20 September 1998
  4.  
  5.   This HOWTO document explains how to use your Palm OS device with a
  6.   Linux system.  Although HOWTO documents are targeted towards use with
  7.   the Linux operating system, this one is not dependent on the version
  8.   of unix used.
  9.   ______________________________________________________________________
  10.  
  11.   Table of Contents
  12.  
  13.  
  14.   1. Introduction
  15.  
  16.      1.1 This Document
  17.      1.2 See Also
  18.      1.3 Mailing List
  19.      1.4 Mailing List Archives
  20.      1.5 FTP Site
  21.  
  22.   2. General Information
  23.  
  24.      2.1 Hardware Installation
  25.  
  26.   3. Sharing Palm OS device Data with your Linux System
  27.  
  28.      3.1 The pilot-link software
  29.         3.1.1 Installing the pilot-link software
  30.         3.1.2 Using the pilot-link software
  31.            3.1.2.1 pilot-xfer
  32.            3.1.2.2 install-memo
  33.            3.1.2.3 memos
  34.            3.1.2.4 pilot-addresses
  35.      3.2 MakeDoc
  36.         3.2.1 Installing MakeDoc
  37.         3.2.2 Using MakeDoc
  38.  
  39.   4. People
  40.  
  41.   5. A History of Palm OS devices.
  42.  
  43.  
  44.  
  45.   ______________________________________________________________________
  46.  
  47.   1.  Introduction
  48.  
  49.   First there was the Pilot, then the PalmPilot, and now we have the
  50.   Palm III from Palm Computing Devices.  IBM sells a rebadged version of
  51.   the PalmPilot Professional, which they call the WorkPad.  What are
  52.   these gadgets?  They are Personal Digital Assistants (PDAs), sometimes
  53.   known as palm-top computers.  Sold as an electronic combination of
  54.   address book, telephone directory and memo pad, they are actually
  55.   general-purpose computers capable of running almost any kind of
  56.   application.  The trick is to find Palm OS applications to fit your
  57.   needs and to be able to share your data with your Linux system.  Palm
  58.   OS devices incorporate software to synchronize their data with
  59.   programs running on another computer.  Such software for use on a
  60.   Windows 95 system is generally bundled with the device.  A MacOS
  61.   version is also available.  If the foriegn computer is running some
  62.   other operating system, you need to find third party software to work
  63.   with your Palm OS device.  This document describes such software that
  64.   is available for use on a Linux or unix system.
  65.  
  66.  
  67.   1.1.  This Document
  68.  
  69.   The latest version of this document can be read at
  70.   http://www.orbits.com/Palm/PalmOS-HOWTO.html, and is part of the Linux
  71.   Documentation Project (LDP).  This document superceedes the previous
  72.   version, which was called the Pilot HOWTO.  See
  73.   http://sunsite.unc.edu/LDP/ for further information about the LDP and
  74.   other HOWTO documents.
  75.  
  76.   If you find anything in this document which needs to be corrected or
  77.   better explained, please send me e-mail at the address above and
  78.   specify which version of this document you are referring to.
  79.  
  80.   This document is Copyright ⌐ 1997 & 1998 by David H. Silber.  It is
  81.   released under the copyright terms in the LDP HOWTO-INDEX document.
  82.  
  83.  
  84.   1.2.  See Also
  85.  
  86.   The http://www.orbits.com/Palm/PalmDevelompent-HOWTO.html document
  87.   describes how to use the gcc-based development system to write Palm OS
  88.   applications.
  89.  
  90.   The http://www.orbits.com/Palm/PalmConduit-HOWTO.html document
  91.   describes how to use the pilot-link libraries to write Linux-resident
  92.   conduits for use with Palm OS devices.
  93.  
  94.  
  95.   1.3.  Mailing List
  96.  
  97.   The pilot-unix mailing list is maintained by Matthew Cravit pilot-
  98.   unix-owner@lists.best.com.  Its mandate is:
  99.  
  100.  
  101.        The pilot-unix mailing list is for discussion and idea-sharing for those
  102.        interested in using the US Robotics Pilot PDAs with UNIX systems. This
  103.        includes people who are interested in helping to develop tools to allow the
  104.        Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot
  105.        for Unix.
  106.  
  107.  
  108.  
  109.  
  110.   For more information, including how to subscribe to the list, send
  111.   mail containing the word ``INFO'' to pilot-unix-
  112.   request@lists.best.com.  The subject line does not matter.
  113.  
  114.  
  115.   1.4.  Mailing List Archives
  116.  
  117.   An archive of the pilot-unix mailing list can be found at
  118.   http:///www.acm.rpi.edu/~albert/pilot/.  It is maintained by Chris
  119.   Stevens albert@acm.rpi.edu.
  120.  
  121.  
  122.   1.5.  FTP Site
  123.  
  124.   An FTP site containing an archive of Palm OS tools for use on unix
  125.   systems is located at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/.  It is
  126.   maintained by Jeff Dionne jeff@ryeham.ee.ryerson.ca.
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.   2.  General Information
  134.  
  135.   2.1.  Hardware Installation
  136.  
  137.   Palm OS devices come with a ``cradle'' for exchanging data with the
  138.   desktop computer.  This device is actually a serial cable with a
  139.   custom holder for the Palm OS devices and an integrated `HotSync'
  140.   button.  Plug your cradle into a spare serial port on your computer.
  141.   When you run each of the stand-alone programs, you will need to place
  142.   your Palm OS device in the cradle and push the `HotSync' button so the
  143.   Palm OS device knows that it has to communicate.  If the Palm OS
  144.   device happens to be off when the button is pushed, it will turn
  145.   itself on.
  146.  
  147.   For convenience, create a device, /dev/pilot which will be an
  148.   alternate name for the serial port to which your Palm OS device cradle
  149.   is connected.  As the root user, enter the following at the shell
  150.   prompt:
  151.  
  152.  
  153.        ln /dev/cua0 /dev/pilot
  154.  
  155.  
  156.  
  157.  
  158.   Replace cua0 with the name of the port to which you connected your
  159.   Palm OS device's cradle.
  160.  
  161.  
  162.  
  163.  
  164.  
  165.   3.  Sharing Palm OS device Data with your Linux System
  166.  
  167.   3.1.  The pilot-link software
  168.  
  169.   The pilot-link suite of software tools allows you to download programs
  170.   onto your Palm OS device, and transfer data for the Palm OS device's
  171.   various built-in programs between the Linux system and the Palm OS
  172.   device.  While these programs are not quite as seamless as the desktop
  173.   software that comes with the Palm OS device, they do allow you to copy
  174.   your data in both directions.  In general, each separate program in
  175.   the pilot-link suite manages one type of data.
  176.  
  177.  
  178.  
  179.   3.1.1.  Installing the pilot-link software
  180.  
  181.   The prepackaged versions will inevitably lag slightly behind the
  182.   master distribution, but will be easier to install and not require
  183.   configuration.  The master distribution might be a better choice in
  184.   those rare occasions when you have been waiting for a particular
  185.   feature or bug fix.
  186.  
  187.   You can get the Debian Linux (i386) port of pilot-link version 0.8.7
  188.   from ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-
  189.   i386/otherosfs/pilot-link_0.8.7-2.deb.
  190.   ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-
  191.   i386/otherosfs/pilot-link_0.8.7-2.deb.  If this file does not exist,
  192.   you will likely find a newer version located in the same directory.
  193.   If all else fails, or if you want a more recent version than has been
  194.   packaged for Debian, you can install the generic distribution, as
  195.   detailed below.  Install this file in the normal manner and skip to
  196.   Using the pilot-link software.
  197.  
  198.  
  199.   You can get the RedHat Linux (i386) port of pilot-link version 0.8.9
  200.   from ftp://ftp.redhat.com/pub/contrib/i386/pilot-
  201.   link-0.8.9-1.i386.rpm.  If this file does not exist, you will likely
  202.   find a newer version located in the same directory.  If all else
  203.   fails, or if you want a more recent version than has been packaged for
  204.   RedHat, you can install the generic distribution, as detailed below.
  205.   Install this file in the normal manner and skip to Using the pilot-
  206.   link software.
  207.  
  208.   For other versions of Linux or unix, or if you need the absolute
  209.   latest version, download the version 0.9.0 of pilot-link from
  210.   ftp://ryeham.ee.ryerson.ca/pub/PalmOS/pilot-link.0.9.0.tar.gz.  The
  211.   version number is likely to change, but new versions should end up in
  212.   the same location with a similar name.
  213.  
  214.   Once you have the software distribution, unpack it with:
  215.  
  216.  
  217.        tar -xvzf pilot-link.0.9.0.tar.gz
  218.  
  219.  
  220.  
  221.  
  222.   If your version of tar does not support the -z option, decompress the
  223.   archive with gunzip, as follows:
  224.  
  225.  
  226.        gunzip pilot-link.0.9.0.tar.gz | tar -xvf -
  227.  
  228.  
  229.  
  230.  
  231.   This will create a directory (pilot-link.0.9.0) containing the source.
  232.  
  233.   Change your working directory to the source (pilot-link.0.9.0)
  234.   directory.
  235.  
  236.   Run ./configure.  This will search through your system for information
  237.   needed to compile the software.  configure will set things up to be
  238.   installed in /usr/local by default.  If you want to change it, run
  239.   ./configure --prefix=DIR, where DIR is replaced with the name of the
  240.   directory to which the software will be installed.
  241.  
  242.   Run make.  This will compile the software.  The software will not be
  243.   installed until later, so that you have a chance to try it out first.
  244.   (If you are replacing an older version with a newer release, you may
  245.   wish to check and make sure that no functionality that you need has
  246.   been broken.  Generally, this is not a problem.)
  247.  
  248.   As the root user, run make install.  This will copy the software into
  249.   directories under /usr/local (or wherever you specified with the
  250.   --prefix option).  If you can not log in as root, you can install the
  251.   software to some directory where you have write access.
  252.  
  253.   Don't forget to add any new directories of executables to your search
  254.   path.
  255.  
  256.  
  257.   3.1.2.  Using the pilot-link software
  258.  
  259.   Most of the programs in the pilot-link suite are conduits, that is
  260.   they transfer data into or out of your Palm OS device.
  261.  
  262.   Each time you use of one of these programs, press the HotSync button
  263.   on your Palm OS device's cradle.  This will initiate the Palm OS
  264.   device side of the data transfer.  Note that not all of these programs
  265.   prompt you to press the `HotSync' button, so you may have to remember
  266.   to do it yourself.
  267.  
  268.  
  269.   For more details, and other options to these programs, view the
  270.   corresponding manual page.  There is an overview manual page under the
  271.   name pilot-link.  For the pilot-xfer program, for example, type man
  272.   pilot-xfer at your unix shell prompt.
  273.  
  274.  
  275.  
  276.  
  277.   3.1.2.1.  pilot-xfer
  278.  
  279.   Possibly the most useful program in the pilot-link suite, pilot-xfer
  280.   allows you to install programs on your Palm OS device, make a backup,
  281.   and restore that backup.
  282.  
  283.  
  284.   To install a program:
  285.  
  286.  
  287.        pilot-xfer /dev/pilot -i program.prc
  288.  
  289.  
  290.  
  291.  
  292.   To backup your Palm OS device:
  293.  
  294.  
  295.        pilot-xfer /dev/pilot -b backup-directory
  296.  
  297.  
  298.  
  299.  
  300.   This will copy all of the databases on your Palm OS device, (including
  301.   programs?)  to a directory called ``backup-directory'', creating it if
  302.   it does not already exist.
  303.  
  304.   To restore data to Palm OS device:
  305.  
  306.  
  307.        pilot-xfer /dev/pilot -r backup-directory
  308.  
  309.  
  310.  
  311.  
  312.   Generally, you will only need to do this if your Palm OS device loses
  313.   power or if you have to do a hard reset.
  314.  
  315.   To list the programs on your Palm OS device:
  316.  
  317.  
  318.        pilot-xfer /dev/pilot -l
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.   3.1.2.2.  install-memo
  327.  
  328.   Install a Linux file onto the Palm OS device as a memo.
  329.  
  330.  
  331.   To install a memo into your (already existing) project category:
  332.  
  333.  
  334.        install-memo /dev/pilot -c project project.memo
  335.  
  336.  
  337.  
  338.  
  339.   The name of the file will be inserted into the memo as its first line
  340.   and will appear in the directory of memos on your Palm OS device.
  341.  
  342.  
  343.  
  344.   3.1.2.3.  memos
  345.  
  346.   This program grabs each memo from the Palm OS device and prints it out
  347.   in standard mailbox format.
  348.  
  349.   To view your memos:
  350.  
  351.  
  352.        memos /dev/pilot
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.   3.1.2.4.  pilot-addresses
  365.  
  366.   pilot-addresses Transfer the address database to or from the Palm OS
  367.   device.
  368.  
  369.   To write your address data to a Linux file from your Palm OS device:
  370.  
  371.  
  372.        pilot-addresses /dev/pilot -w storage.file
  373.  
  374.  
  375.  
  376.  
  377.   To read your address data from a Linux file onto your Palm OS device:
  378.  
  379.  
  380.        pilot-addresses /dev/pilot -r storage.file
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.   3.2.  MakeDoc
  392.  
  393.   One short-coming of the Palm OS device's built-in memo program is that
  394.   it does not deal well with large documents.  To compensate for this,
  395.   Rick Bram <mailto:rbram@concentric.net> wrote Doc, a document reader
  396.   for the Palm OS device.  (See
  397.   http://www.concentric.net/~rbram/doc.shtml).  Documents can be
  398.   converted to the Doc format with MakeDoc, by Pat Beirne
  399.   <mailto:pat.beirne@sympatico.ca>.
  400.  
  401.  
  402.  
  403.   3.2.1.  Installing MakeDoc
  404.  
  405.   MakeDoc can be downloaded from
  406.   http://www.concentric.net/~rbram/makedoc7.cpp.  Compile it with your
  407.   C++ compiler and install the resulting executable as ``makedoc'' in a
  408.   directory in your search path.  There seems to be a small bug in
  409.   makedoc (version 0.7a) in that it does not output a newline as the
  410.   last character displayed to the user.  This does not seem to affect
  411.   the resulting document file, but it is annoying.
  412.  
  413.   There is a new version out, but it requires Java.  Take a look at Pat
  414.   Beirne's MakeDoc web page at
  415.   http://cpu563.adsl.sympatico.ca/MakeDocJ.htm.
  416.  
  417.  
  418.  
  419.   3.2.2.  Using MakeDoc
  420.  
  421.   Use MakeDoc as follows:
  422.  
  423.  
  424.        makedoc data.txt data.prc "Data to display with Doc"
  425.  
  426.  
  427.  
  428.  
  429.   This will create a file data.prc, which can be installed on your Palm
  430.   OS device with pilot-xfer.  The text "Data to display with Doc" will
  431.   be displayed in the directory of documents that Doc manages.
  432.  
  433.   The syntax for MakeDoc is as follows:
  434.  
  435.  
  436.        makedoc [-n] [-b] <text-file> <prc-file> <story-name>
  437.        or
  438.        makedoc -d [-b] <prc-file> <text-file>
  439.  
  440.  
  441.  
  442.  
  443.  
  444.      <text-file>
  445.         The file that you wish to convert.
  446.  
  447.      <prc-file>
  448.         The name of the resulting file.  (End the name with ``.prc''.)
  449.  
  450.      <story-name>
  451.         The name you want displayed in the Doc or Jdoc directory of
  452.         documents.
  453.  
  454.   There are also options to decode the resulting .prc file and manage
  455.   various compression options.
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.   D.  People
  464.  
  465.   Kenneth Albanowski <mailto:kjahds@kjahds.com> Maintains the pilot-link
  466.   suite of tools.
  467.  
  468.   Donnie Barnes <mailto:djb@redhat.com> Packaged pilot-link suite as Red
  469.   Hat RPM files.
  470.  
  471.   Rick Bram <mailto:rbram@concentric.net> Author of Doc.
  472.  
  473.   Matthew Cravit <mailto:pilot-unix-owner@lists.best.com> List owner for
  474.   the pilot-unix mailing list.
  475.  
  476.   Jeff Dionne <mailto:jeff@ryeham.ee.ryerson.ca> Original author of the
  477.   pilot-link suite of tools.  Manages the FTP area for the UNIX Palm
  478.   OS/Pilot development project.
  479.  
  480.   Mark W. Eichin <mailto:eichen@kitten.gen.ma.us> Ported pilot-link
  481.   suite to Debian Linux.
  482.  
  483.   David H. Silber <mailto:pilot@orbits.com> Author of this document.
  484.  
  485.   Chris Stevens <mailto:albert@acm.rpi.edu> Maintains the pilot-unix
  486.   mailing list archives.
  487.  
  488.  
  489.   E.  A History of Palm OS devices.
  490.  
  491.   There are two versions of the Pilot.  They are the 1000 and the 5000
  492.   and have 128k and 512k of RAM, respectively. They come with Palm OS
  493.   1.0 in ROM.
  494.  
  495.   Then came two devices with the name PalmPilot.  They are the PalmPilot
  496.   Personal and the PalmPilot Professional and have 512k and 1 Meg of
  497.   RAM, respectively.  They also have a backlighting feature for the LCD
  498.   panel and version 2.0 of the operating system.  The Professional also
  499.   comes with a TCP/IP stack and a few extra programs built-in.
  500.  
  501.   (IBM has released a rebadged version of the PalmPilot Professional,
  502.   which they call a WorkPad.)
  503.  
  504.   Now we have the Palm III, which has a redesigned case and an infrared
  505.   port, not to mention the 2 Meg of RAM and Palm OS 3.0.
  506.  
  507.   It is possible to upgrade any Pilot by swapping out the memory card,
  508.   which includes both RAM & ROM.  Of course, this doesn't get you
  509.   backlighting for the original Pilot series.
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.