Technical Reference Manual
Psion Link Protocol
In its simplest form data is sent over the link using the 'link layer', an error correcting protocol which uses data packets. Each packet has the following format (in hex):
The first three bytes are always 16 10 02.
The next byte, <CHAN>, is the channel number. It is not used and must always equal 1. It is compared to the value stored at $2173, which is set to 1 when the comms link is loaded and not changed afterwards. It may be that some other communications devices use a different channel number.
The next byte, <TYPE>, contains the type of packet in the top 5 bits, and also a sequence number in the bottom 3 bits. The sequence number is a number that each data packet has to make sure that they are not mixed up. Since the sequence number increases with each new data packet, missing packets can be detected.
There are 4 types of packet:
The bytes 10 03 follow the data to signal the end of the packet.
The <CRC> is a 16-bit checksum for all the bytes between the header 16 10 02 and the footer 10 03. See below.
To make sure that sending the bytes 10 03 in the data will not prematurely end the packet, an escape mechanism is used. Every 10 byte in the data (or chan/type bytes) will be sent twice over the link. The receiving end then replaces each 10 10 by a single 10, and will not end the packet if it is followed by a 03. The extra 10 is not used in generating the CRC however.
The maximum length of a packet is 260 bytes.
Explaining CRC theory is beyond this manual. However CRCs can be computed by knowing the following values:
CRC(01)=C1C0 CRC(10)=01CC CRC(02)=81C1 CRC(20)=01D8 CRC(04)=01C3 CRC(40)=01F0 CRC(08)=01C6 CRC(80)=01A0
The CRC of any single byte can be computed by EOR-ing the values above together for each set bit in the byte. If ChCl is the CRC for a sequence of one or more bytes, then the CRC of that sequence followed by a byte B will be CRC(B eor Ch) eor (Cl*0100).
For example, let's calculate CRC(01 10):
CRC(01) = C1C0. CRC(01 10) = CRC(10 eor C1) eor C000 = CRC(D1) eor C000 = CRC(80) eor CRC(40) eor CRC(10) eor CRC(01) eor C000 = 01A0 eor 01F0 eor 01CC eor C1C0 eor C000 = 005C
When CL is running on the PC, it continuously sends out Link Request packets. When the Psion is ready to start communicating it first starts up a link session in the following manner:
After that the link is considered to be active and working, and the sequence numbers are reset.
Specifically, the packets involved are:
Link Request: 16 10 02 01 10 10 10 03 00 5C Acknowledge: 16 10 02 01 00 10 03 01 90
If in step 3 a disconnect request is received, it should contain an error byte as data. Receiving a data packet will cause the Psion to return a data acknowledgement, and then it also considers the link to be active.
The start-up sequence above is performed before every data transfer. It can also be called specifically by using the XLCON: command, or calling rs$licon in machine code.
When sending a sequence of data packets, each packet is numbered 1,2,..,6,7,0,1,... etc. After each packet is sent, a reply is expected. What happens next depends on the type of reply:
A single packet can be sent using the XLPUT:(a$) command, or RS$liput in machine code.
When receiving a sequence of data packets, each packet should numbered 1,2,..,6,7,0,1,... etc. After each packet is received, a reply is expected. When the Psion is waiting for a data packet, what happens depends on the type of packet it receives:
A single packet can be received using the XLGET$: command, or RS$liput in machine code.
Note that the sequence numbers used when receiving packets are independent from those used when sending packets.
When the link session is finished, the link should be deactivated. This is done by calling the XLDIS: command, or RS$lidis in machine code. This will send a disconnect packet, and close the link session. The disconnect packet has no data when sent from the Psion, but those sent by CL will contain a single byte which is the error number.
The link layer is simply an error correcting protocol for sending small snippets of data. Built on top of this is a protocol for sending and receiving files, file access commands etc.
The Psion Series 3 and 5 first have an NCP protocol layer above the link layer. NCP is a method of sending data over different channels. This is not implemented on the series II, though there seems to be a simple channel byte in every packet which is not used at all.
The file protocol layer generally works like this:
It now remains to be explained what overlays there are, what commands they accept and what data they return.
This overlay handles all remote file access (i.e. XFOPEN, XFCLOSE etc). There are five types of data packet that the Psion sends to CL/FILE. The data packet starts with a byte between 00 and 04 to indicate the call type and is followed by the parameters.
For example, suppose we run the following short program:
TEST: XFOPEN:("HOMER.TXT",1,1) XFPUT$:("Doh"+CHR$(33)) XFCLOSE:
then the following list is the complete exchange between the Psion and the PC, assuming no errors occur:
Start link layer session: PC: Link Request: 16 10 02 01 10(10)10 03 00 5C Ps: Link Request: 16 10 02 01 10(10)10 03 00 5C PC: Acknowledge: 16 10 02 01 00 10 03 01 90 Then the FILE overlay is loaded: Ps: FILE overlay: 16 10 02 01 19 46 49 4C 45 10 03 2D BE PC: Acknowledge: 16 10 02 01 01 10 03 C0 50 Reply: PC: No Data: 16 10 02 01 19 10 03 C0 5A Ps: Acknowledge: 16 10 02 01 01 10 03 C0 50 File is opened: Ps: Open command: 16 10 02 01 1A 00 01 01 48 4F 4D 45 52 2E 54 58 54 10 03 39 8B H O M E R . T X T PC: Acknowledge: 16 10 02 01 02 10 03 80 51 Reply: PC: No Data: 16 10 02 01 1A 10 03 80 5B Ps: Acknowledge: 16 10 02 01 02 10 03 80 51 Send data: Ps: Data Doh!: 16 10 02 01 1B 02 44 6F 68 21 10 03 A1 DE D o h ! PC: Acknowledge: 16 10 02 01 03 10 03 41 91 Reply: PC: No Data: 16 10 02 01 1B 10 03 41 9B Ps: Acknowledge: 16 10 02 01 03 10 03 41 91 End signal: Ps: End packet: 16 10 02 01 1C 01 10 03 98 C0 PC: Acknowledge: 16 10 02 01 04 10 03 00 53 Reply: PC: No Data: 16 10 02 01 1C 10 03 00 59 Ps: Acknowledge: 16 10 02 01 04 10 03 00 53 End link layer session: Ps: disconnect: 16 10 02 01 08 10 03 00 56
This is the most commonly used one. It handles all standard file transfer. There are four types of data packet that the Psion sends to FTRAN. The data packet starts with a byte between 00 and 03 to indicate the call type and is followed by the parameters.
The commands available are:
When sending/receiving ODB files, each record is sent in a separate packet. No data is returned after the recv command.
When sending/receiving block files, the data is split in a separate packets, generally about FE bytes long. The data returned after the recv command is the length of the block in the file, followed by the Psion file type (between 82 and 8F).
When sending/receiving OPL files, the data is split in a separate packets just like block files. The line ends are indicated by zero bytes, and it is FTRAN that translates it to/from CR/LF when writing to disk. The data returned after the recv command is the length of the block in the file, the Psion file type (81 - although the file is stuctured like an OB3), followed by 0000 and the length of the OPL part of the procedure block file. Note that using file type 83 works fine if used with the COMMS menu, but produces pack corruption when used with the OPL XTRECV: command.
This overlay handles the loading of BOOT code, and the XMLOAD: command. After the BOOT overlay is loaded, it expects to be sent a data packet containing the name of the boot file to load. The reply packet contains the length of the code.
The Psion then sends a packet containing the address to load the code. In reply the first data packet contains the first part of the code, ready to be stored in memory. When the Psion next sends a packet containing just a zero byte, the next code packet is sent. This is repeated as often as necessary.
When the end of the code has been reached, a disconnect packet with a zero error is returned by CL/BOOT.
Note that fixing up the relocatable addresses in the code is done by CL/BOOT.
Instead of using the BOOT option in the menu, the XMLOAD: command can be used. XMLOAD:(addr%,len%,name$) loads the boot code from remote file name$ to address addr%, but rejects it if the code exceeds length Len%.
This overlay exits the CL program completely (by stuffing q and y in the keyboard buffer of the PC). It has no other functions. It can therefore be used by using the following sequence of commands:
XLCON: XLPUT:("EXIT") XLDIS:
These overlays are used by the spreadsheet program. When you choose the FILE/IMPORT or FILE/EXPORT menu options, the Psion requests the PLANM overlay which returns the file type menu, and the Psion disconnects again. The file type menu returned is 19h bytes long and is as follows:
03 "WKS" 0001 03 "WK1" 0002 03 "WR1" 0003 03 "DIF" 0004 00
It is in the correct format for the MN$DISP (SWI 50h) system service.
The PLAN overlay handles the transfer and conversion of the spreadsheet files. To export a file, the Psion first sends it a packet of which the first byte is between 81h and 84h depending on the file type chosen, and the rest contains the file name. The spreadsheet data follows; first a packet containing the dimensions of the sheet, then a packet for each non-empty cell, and finally a packet containing just FE. The reply that PLAN gives each time is a packet containing 00, except that the FE is answered with FE 00.
A cell is encoded in this format:
If a cell contains a formula and its result then one packet contains the formula, and the cell is resent in the next packet but this time containing just the value.
For example, here are the packets sent to PLAN to export a simple sheet:
84 54 45 53 54 Export TEST in DIF format. 02 04 Columns A-B, Rows 1-4 used. 01 00 22 43 4F 4C 31 B1, contains "COL1" 00 01 22 52 4F 57 31 A2, contains "ROW1" 01 01 87 31 B2, contains 1 00 02 22 52 4F 57 32 A4, contains "ROW2" 01 02 87 35 B3, contains 5 01 03 87 3D 42 32 2B 42 33 B4, contains =B2+B3 (formula) 01 03 87 36 B4, contains 6 (value) FE End of sheet
Import is very similar. First the Psion sends CL/PLAN a packet of which the first byte is between 01 and 04 depending on the file type chosen, and the rest contains the file name. It just returns 00. Then the Psion sends a 00 and PLAN returns the first non-empty cell, in the same format as before. This is repeated until PLAN sends FE00, signifying the end of the sheet.