PSION link
==========

This distribution is for transferring files between a PSION organiser and a Unix machine, via a serial cable. The code has been used successfully on a PC running linux and a PSION 5, but it ought to work with other flavours of unix and the PSION series 3 machines also.

Quick start
===========

1.  Compile the code 

Take a quick look at "defaults.h" - sensible values are supplied in the file. (System admin people should know that a unix socket number should be allocated here.)
Solaris users will need to uncomment a line in the top level Makefile (just search for the word "Solaris").

type: make

2.  Run the test 

NB. this test creates and deletes a file called "C:\ptest". If you already have such a file on the PSION, it will be deleted if you run the test!

type: make test

3.  Now, if you look at the screen output, the basic command syntax should be fairly obvious!

4. Install the files

type: make install

NB. This will put the "ncp" and "rfsv" executables into /usr/local/bin/. You shouldn't have to run "ncp" by hand.

5. Try the 'ftp like' interface by just issuing the command 'rfsv'

Change history
==============

1.7 -> 1.8 (*) Control-D now does something sensible in rfsv
           (*) mput and mget now accept unix filename wildcards '*' and '?'
           (*) annoying description of file property flags has been moved elsewhere
               - type '??' in rfsv to see their meaning
           (*) 'defaults.h' has changed to support the S5 by default
           (*) Compiles with gcc 2.95

1.6 -> 1.7 (*) Psion 5 long filenames! (you must specify which psion machine
               you have in defaults.h)

1.5 -> 1.6 (*) Now recognises the local unix directory from which rfsv was launched
           (*) lcd commands are checked for valid directories
           (*) "!" runs a UNIX command in ftp mode
           (*) Bug fixed - psion files were not being closed after operations where
                           invalid UNIX filenames were supplied

1.4 -> 1.5 (*) Changes to "directory defaults" code
           (*) In ftp mode, "cd" takes you back to the default directory

1.3 -> 1.4 (*) rfsv now starts ncp automatically.
           (*) Compiles with sparcworks compiler.

1.2 -> 1.3 (*) Ftp like interface added. Just execute "rfsv"
           (*) Bug fix to receiving the VALID packet terminator sequence 0x10 0x10 0x10 0x03
               - this caused a problem when transferring some binary files from the psion.

1.0 -> 1.2 (*) Some bug fixes and changes to Makefiles

In the pipeline (V. long term I'm afraid)
=========================================

(*) Backup command. This recursively copies all psion files to unix. Will be intelligent enough to ignore files with unchanged timestamps on subsequent backups.

(*) Sync utility. Will be useful if, like me, you use the psion to edit source code while commuting(or whatever!). This utility will look at how file timestamps within a whole directory have changed since the last 'sync'. For each file: if it has been updated on unix, then it copies this to the psion; if updated on the psion, then it is copied to unix. If both a unix and psion file have been updated, then the psion file is copied to unix with a ".merge" suffix (to aviod this, use 'sync' before and after performing any file edits on unix).

More detailed explanation of code
=================================

There are two executables: a daemon process; and a file manipulation tool. Descriptions follow:

"rfsv" command (remote file service - a psion protocol)
------------------------------------------------------- 

This code is the user interface for transferring and manipulating psion files. A socket number should be supplied that matches the required "ncp daemon" process (see below).

Syntax: rfsv -s (socket number) (command) (command parameters)

Commands and parameters:

  ftp (or no parameters) - enter interactive "ftp - like" mode
  dir (psion file) - NB. end directory names with a "/" to see the whole contents 
  mkdir (psion directory) 
  del (psion file) 
  read (psion file) (unix file) 
  write (unix file) (psion file) 

"ncp" daemon (Network Control Protocol - a psion protocol) 
----------------------------------------------------------

This code manages all communication with the psion. It allows several simultaneous channels of communication, so that you can still access the psion while transferring a large file. One daemon is needed for each psion connected to your computer. Also, a unix tcp/ip socket number is required, and the daemon listens on this for communication requests.

Syntax: ncp -s (socket number) -d (device) -b (baud rate)
NB. This is started automaticall with "default device" and "default baud rate" by the "rfsv" command - unless you start it first!


Credits
=======

1. Thanks to Olaf Flebbe (o.flebbe@science-computing.de) for his document describing the communication protocol. This code would not have been written without his document. Website http://www.fortunecity.de/wolkenkratzer/trumpet/84/

2. Thanks to Alexander Thoukydides, who cracked the EPOC32 communication code. His Acorn Psion transport protocol implementation handles long filenames, and this enabled me to implement something here. His web site is at http://homepages.tcp.co.uk/~thouky/tcfp.html

3. Thanks to Rudolf Koenig (rfkoenig@immd4.informatik.uni-erlangen.de) for supplying the low level serial interface code (from his p3nfs code)

4. Thanks to Nils Faerber ( web site http://www.si.unix-ag.org/~nils/ ), who told me about Alexander Thoukydides' code.

5. Thanks to Pete Bentley, and anyone else who has mailed me bug fixes.

6. Also thanks to my wife Rach, and son Alex for allowing me some "time off" to write this.

If you have any queries/ suggestions please e-mail me, Phil Proudman, at phil@proudman51.freeserve.co.uk - but please browse the FAQ first.

FAQ
===
Q: I can't get it to work
A: Check the following:
      Are settings in defaults.h correct
      Serial connection configured to correct baud rate on psion

Q: Which compiler do you use?
A: I use gcc 2.95. If you port the code to another compiler/ OS, then please e-mail me the changes.
