This file describes the protocol that is currently in use between the sun and the psion
The first section defines the data transfer protocol, the second desctibes the messages that are passed between the two programs
Low Level Data Transfer Protocol
All messages from the sun to the psion are composed of the character $ followed by two bytes representing the remaining length of the message in hex, followed by the number of bytes, followed by another two bytes in hex representing the checksum of the text lastly a carriage return is sent.
e.g. $02cs$D6
means a two byte message with the message composed of the characters cs and a checksum of DS
The psion responds with the letter R implying that the checksum was not correct or the letter O implying that the data was transfered correctly. If the checksum is incorrect then the same data stream is resent untill it is correctly recieved
The psion sends data to the sun using the same base protocol
The checksum is computed by taking the lowest 8 bits of the sum of the ascii characters in the datastream. It does not include the length information of the checksum information. In the example above the checksum is calculated on the letters cs
File transfer level binary checksumms
This adds an additional checksumming on the binary data being transfered using the same routine. the first two bytes sent from the transfer routines in file transfers only contain the checksum of the binary data sent the rest of the protocol is the same. On reciept of a packet it is decoded and the binary checksum is calculated. if it is good the letter G is sent other wise the letter B is used to request anothe transfer. NOTE when sending from the psion these will be prefixed with the letter X. Also note that the conversion from binary is assumed to have worked OK. we are just checking for single character transpositions which seem to occur sometimes
Checksum
It should be noted that the checksum used is somewhat simple, perhaps in the future a more advanced mechanism will be used as the current version does not handle sequencing corrections. I've noticed that sometines this does cause problems.
The psion has to send newline sequences for some reason but the sun can safely ignore these
Synchronisation
The sun waits untill it recieves an XONLINE message before completing the rest os it's sequence.
Due to the speed difference between the sun and psion the psion needs to send a ready to recieve character (>). This is transmitted without any checksums and is also partialy used to resync the sun if things get out of order.
The following section describes the messages transfered
Readers should be aware that the idiot level protocol used means that the current path on the psion is set (using the sp command) and that other commands operate on this preset path.
All the commands to the psion are a two letter command code, sometimes followed by a space and then parameters. Any reply is listed here. For historical reasons all message from the psion are prefixed with an X > is used to indicate a message sent to the psion < is used to indicate the return if a ? is listed this means that the reply may vary (e.g. error / success codes)
Note not all of the commands in the suncom program are used by the current version of the psion program
Command: dc (disconnect), This issues a shutdown commend to the suncom process on the psion
Response sequence
< XDISCONNECTED - the psion has recognised the request and is shutting down
Command: vn (version number), This requests the psion to return it's version number (This is compiled into the suncom image file and is generated by sccs) The version number is offten used to check that the suncom program supports a particular function
Response sequence
< Xnn.nn - where nn.nn is the SCCS version (SCCS version number of type nn.nn.nn.nn are also posible)
Command: ft (File type), This requests the type of the file set in the current path
Response sequence
?< XBADPATH - if the current path cannot be examined
?< XDIR and or XTEXT and or XHIDDEN and or XSYSTEM and or XVOLUME - one or more will be returned
Command: sz (file size), this returns the size of the file set in the current path in bytes
Response sequence
< Xnumber - where number is the number of bytes in the file indicated in the current path
Command: rw (read write status), this indicates if the file set in the current path is read only or read write
Response sequence
?< XBADPATH - if the current path cannot be examined
?< XRW or XRO - XRW if the file indicated in the current path is read write, XRO if it is read only
Command: sp path (set path), this sets the internal path on the psion to be the given path
Response sequence
?< XBADPARAM - if there is no path component
< XOK - indicated the current path has been set
Command: rp (remove path), this attempts to remove the file or directory specified in the current path
Response sequence
?< XBADRF - if the remove has failed (for whatever reason)
< XOK - indicates the file or directory indicated by the current path has been removed
Command: ti (time), this returns the files last modification time (in seconds from Jan 1970 as per the standard unix time standard) be aware that this is a large number and needs to fit into a long
Response sequence
?< XBADPATH - if the file indicated by the current path cannot be examined
< Xnumber - where number is the age of the file in seconds from midnight 1/1/1970, the same as unix. This is going to be a large number
Command: lp (list path), this lists the files matched by the current path (wild cards allowed in the filename component)
Response sequence
< XSTARTLIST - indicates list information is about to follow
?< XBADPATH - if the current path does not match anything
< repeated Xname - where name is the return value from the directory or whatever
< XENDLIST - indicating the end of list data
Command: ep (exists path), this indicates if the current path exists in the psion filesystem
Response sequence
< XYES or XNO - XYES if the current path points to a file or directory, XNO if it does not
Command: gf (get file), this instructs the psion to recieve the current path from the sun. This will use the selected transfer mechanism and use it. Currently this only the binary format works correctly (described here). If filechecksumming is in use (see fc) there may be retries once the data line has been decoded if there is an error in the binary data chksum
Response sequence
< XSTARTGET - indicated that the recieve sequence is about to start
< XBADOPEN or XGOODOPEN - XBADOPEN indicates that the file cannot be opened for writting, aborts the sequence. XGOODOPEN indicates that the file open succeded
> data stream - the data stream is comprised of two ascii bytes representing each binary byte. When the psion recieves the file the data is transfered in a sort of hex format. Regrade the letter A as zero and the letter P as 15, the binary value is composed of taking the first character, converting it into a number multiplying by 16 and then adding the converted value of the second byte, this the letter C is transmited as ED (in ascii this calculates as 'E' - 'A' = 4, 'D' - 'A' = 3, thus (4*16)+3 = 67 the ascii value of the character C) This could cause problems on machines that do not unserstand ASCII of use a different character sequence
> XE - used to inducate the end of the data stream
< XBADGET or XENDGET - XBADGET if the file cant be closed (never been seen yet) or XENDGET indicating that the file has been closed correctly
Command: pf (put file), this instructs the psion to transfer the current path to the sun. This will check on the currently selected transfer mechanism and use it. Currently only the binary format works correctly (described here). If filechecksumming is in use (see fc) there may be retries once the data line has been decoded if there is an error in the binary data chksum
Response sequence
< XSTARTPUT - indicates that the transmit sequence is about to start
< XBADOPEN or XGOODOPEN - XBADOPEN if the file cannot be opened (it's a directory or alike), XGOODOPEN if it was succesfully opened for reading
< data stream - repeated lines containing pairs of ascii charecters representing a single binary data value. Each pair is actualy the HEX representation, thus 'C' is 43 and the binary number 237 is ED
< XE - indicates the data stream is completed
< XBADPUT or XENDPUT - XBADPUT if the file does not close correctly or there was an error reading the file. XENDPUT if the transmision went OK
Command: md (make directory), this instructs the psion to try to make a directory based on the current path
Response sequence
< XBADMKDIR or XOK - XBADMKDIR if the make curectory call failed, XOK if it succeded
Command: vb (verbose toggle), this switched between verbose and quiet mode. in verbose mode messages are displayed on the psion indicating the command and where relevant path being used
Response sequence
< XOK - command has been done
Command: ds (dump strings), return some internal strings
Response sequence
< XSTART - indicating the start of a data sequence
< Xdata - one or more lines containing internal data
< XEND - indicating the end of the data sequence
Command: tm (transfer binary), selects the binary transfer mode
Response sequence
< XOK - command has been done
Command: tx (transfer xmodem), selects the xmodem protocols for transfering files, this should not be used as the xmodem code has bugs
Response sequence
< XOK - command has been done
Command: iv (is verbose), indicate if the verbode mode is operational
Response sequence
< XYES or XNO - XYES if verbose mode is active otherwise XNO
Command: ia (is ascii), old command retained for compatibility, indicates if ascii transfer mode is being used
Response sequence
< XYES or XNO - XYES if the ascii mode is in use otherwise XNO
Command: ix (is xmodem), indicate if the transfer mode is xmodem
Response sequence
< XYES or XNO - XYES if the xmodem mode is in use otherwise XNO
Command: sc (screen toggle), toggle psion screen updates on and off
Response sequence
< XOK - command has been done
Command: is (is screen), indicate if screen updates are occuring (Turning of updates significantly speeds up things like backup chich do a lot of commands and this a lot of screen updates without doing a lot of data file transfers)
Response sequence
< XYES of XNO - XYES if the screen is being updated, XNO otherwise
Command: sl (set sent line counter), reset the sent line counter on the psion display
Response sequence
< XOK - command has been done
Command: rl (set recieved line counter), reset the recieved line counter on the psion display
Response sequence
< XOK - command has been done
Command: ol (online), indicate is the suncom process is running, ised as a sort of ping command occasionaly
Response sequence
< XONLINE - indicates the program is running
Command: dt text (display text), display the text in the psion status window
Response sequence
Command: wy (write yes), set the file indicated in the current path to be read write
Response sequence
< XBADPATH or XOK or XBADSET - XBADPATH if the file indicated by the current path does not exist, XBADSET if there was an error setting the path to be read write and XOK if the command succeend
Command: wn (write no), set the file indicated in the current path to be read only
Response sequence
< XBADPATH or XOK or XBADSET - XBADPATH if the file indicated by the current path does not exist, XBADSET if there was an error setting the path to be read only and XOK if the command succeend
Command: cs (chechsum), calculate the checksum on the file indicated in the current path
Response sequence
< XSTARTSUM - indicated that checksum information is about to follow
< XGOODOPEN or XBADOPEN - XGOODOPEN if the file indicated by the current path was opened succesfully for read, XBADOPEN otherwise
?< XBADSUM - there was an error on doing the checksum operation
< Xnumber - where number indicates the checksum
< XENDSUM - indicated the end of the checksum operation
Command: cd (change directory), set the default directory to be the current path
Response sequence
< XBADRCD or XOK - XBADRCD is for some reason the operation failes (posibly the current path does not exist or is not a directory), XOK is the operation succeeds
Command: pp (print path), return the current directory (like the unix pwd command)
Response sequence
< Xpath - where path is the current working directory
Command: tf length (truncate file), set the length of the file indicated by the current path to be length bytes long (This is a potentialy very dangerous command and should be used carefully
Response sequence
?< XBADPARAM or XBADOPEN or XBADSETEOF or XBADCLOSE or XOK - XBADPARAM if the length parameter wes not found, XBADOPEN if the file indicated by current path could not be opened, XBADSETEOF if an error occured in the operation (possibly seting the EOF beyond the actual file end) XBADCLOSE if there was an error in closing the file and XOK if all went well
Command: sd (start debugging), if the debugging code is compiled into the suncom application start logging of debugging information to the file indicated in the current path
Response sequence
< XBADOPEN or XGOODOPEN - XBADOPEN if the file indicate in the current path could not be opened for writting, XGOODOPEN if it was
Command: ed (end debugging), if the debugging code is compiled into the suncom application end the logging of debugging information
Response sequence
< XBADCLOSE or XGOODCLOSE - XBADCLOSE if there was an error closing the file, XGOODCLOSE if the file closed succesfully
Command: fc (file binary checksums), TUrns on / off the binary level checksumming which occurs during the file transfer