home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / comms / x_sun_psio / code / protocol < prev    next >
Encoding:
Text File  |  1995-05-23  |  13.5 KB  |  184 lines

  1. This file describes the protocol that is currently in use between the sun and the psion
  2. The first section defines the data transfer protocol, the second desctibes the messages that are passed between the two programs
  3.  
  4. Low Level Data Transfer Protocol
  5. 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.
  6. e.g.  $02cs$D6
  7. means a two byte message with the message composed of the characters cs and a checksum of DS
  8. 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
  9. The psion sends data to the sun using the same base protocol
  10. 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
  11. File transfer level binary checksumms
  12. 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
  13. Checksum
  14. 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.
  15. The psion has to send newline sequences for some reason but the sun can safely ignore these
  16. Synchronisation
  17. The sun waits untill it recieves an XONLINE message before completing the rest os it's sequence.
  18. 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.
  19. The following section describes the messages transfered
  20. 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.
  21. 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)
  22. Note not all of the commands in the suncom program are used by the current version of the psion program
  23.  
  24. Command:  dc (disconnect), This issues a shutdown commend to the suncom process on the psion
  25. Response sequence
  26. < XDISCONNECTED - the psion has recognised the request and is shutting down
  27.  
  28. 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
  29. Response sequence
  30. < Xnn.nn - where nn.nn is the SCCS version (SCCS version number of type nn.nn.nn.nn are also posible)
  31.  
  32. Command:  ft (File type), This requests the type of the file set in the current path
  33. Response sequence
  34. ?< XBADPATH - if the current path cannot be examined
  35. ?< XDIR and or XTEXT and or XHIDDEN and or XSYSTEM and or XVOLUME - one or more will be returned
  36.  
  37. Command:  sz (file size), this returns the size of the file set in the current path in bytes
  38. Response sequence
  39. < Xnumber - where number is the number of bytes in the file indicated in the current path
  40.  
  41. Command:  rw (read write status), this indicates if the file set in the current path is read only or read write
  42. Response sequence
  43. ?< XBADPATH - if the current path cannot be examined
  44. ?< XRW or XRO - XRW if the file indicated in the current path is read write, XRO if it is read only
  45.  
  46. Command:  sp path (set path), this sets the internal path on the psion to be the given path
  47. Response sequence
  48. ?< XBADPARAM - if there is no path component
  49. < XOK - indicated the current path has been set
  50.  
  51. Command: rp (remove path), this attempts to remove the file or directory specified in the current path
  52. Response sequence
  53. ?< XBADRF - if the remove has failed (for whatever reason)
  54. < XOK - indicates the file or directory indicated by the current path has been removed
  55.  
  56. 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
  57. Response sequence
  58. ?< XBADPATH - if the file indicated by the current path cannot be examined
  59. < 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
  60.  
  61. Command: lp (list path), this lists the files matched by the current path (wild cards allowed in the filename component)
  62. Response sequence
  63. < XSTARTLIST - indicates list information is about to follow
  64. ?< XBADPATH - if the current path does not match anything
  65. < repeated Xname - where name is the return value from the directory or whatever
  66. < XENDLIST - indicating the end of list data
  67.  
  68. Command:  ep (exists path), this indicates if the current path exists in the psion filesystem
  69. Response sequence
  70. < XYES or XNO - XYES if the current path points to a file or directory, XNO if it does not
  71.  
  72. 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
  73. Response sequence
  74. < XSTARTGET - indicated that the recieve sequence is about to start
  75. < XBADOPEN or XGOODOPEN - XBADOPEN indicates that the file cannot be opened for writting, aborts the sequence. XGOODOPEN indicates that the file open succeded
  76. > 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
  77. > XE - used to inducate the end of the data stream
  78. < XBADGET or XENDGET - XBADGET if the file cant be closed (never been seen yet) or XENDGET indicating that the file has been closed correctly
  79.  
  80. 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
  81. Response sequence
  82. < XSTARTPUT - indicates that the transmit sequence is about to start
  83. < XBADOPEN or XGOODOPEN - XBADOPEN if the file cannot be opened (it's a directory or alike), XGOODOPEN if it was succesfully opened for reading
  84. < 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
  85. < XE - indicates the data stream is completed
  86. < 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
  87.  
  88.  
  89. Command:  md (make directory), this instructs the psion to try to make a directory based on the current path
  90. Response sequence
  91. < XBADMKDIR or XOK - XBADMKDIR if the make curectory call failed, XOK if it succeded
  92.  
  93. 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
  94. Response sequence
  95. < XOK - command has been done
  96.  
  97. Command:  ds (dump strings), return some internal strings
  98. Response sequence
  99. < XSTART - indicating the start of a data sequence
  100. < Xdata - one or more lines containing internal data
  101. < XEND - indicating the end of the data sequence
  102.  
  103. Command:  tm (transfer binary), selects the binary transfer mode
  104. Response sequence
  105. < XOK - command has been done
  106.  
  107. Command:  tx (transfer xmodem), selects the xmodem protocols for transfering files, this should not be used as the xmodem code has bugs
  108. Response sequence
  109. < XOK - command has been done
  110.  
  111. Command:  iv (is verbose), indicate if the verbode mode is operational
  112. Response sequence
  113. < XYES or XNO - XYES if verbose mode is active otherwise XNO
  114.  
  115. Command:  ia (is ascii), old command retained for compatibility, indicates if ascii transfer mode is being used
  116. Response sequence
  117. < XYES or XNO - XYES if the ascii mode is in use otherwise XNO
  118.  
  119. Command:  ix (is xmodem), indicate if the transfer mode is xmodem
  120. Response sequence
  121. < XYES or XNO - XYES if the xmodem mode is in use otherwise XNO
  122.  
  123. Command:  sc (screen toggle), toggle psion screen updates on and off
  124. Response sequence
  125. < XOK - command has been done
  126.  
  127. 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)
  128. Response sequence
  129. < XYES of XNO - XYES if the screen is being updated, XNO otherwise
  130.  
  131. Command:  sl (set sent line counter), reset the sent line counter on the psion display
  132. Response sequence
  133. < XOK - command has been done
  134.  
  135. Command:  rl (set recieved line counter), reset the recieved line counter on the psion display
  136. Response sequence
  137. < XOK - command has been done
  138.  
  139. Command:  ol (online), indicate is the suncom process is running, ised as a sort of ping command occasionaly
  140. Response sequence
  141. < XONLINE - indicates the program is running
  142. Command:  dt text (display text), display the text in the psion status window
  143. Response sequence
  144.  
  145. Command:  wy (write yes), set the file indicated in the current path to be read write
  146. Response sequence
  147. < 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
  148.  
  149. Command:  wn (write no), set the file indicated in the current path to be read only
  150. Response sequence
  151. < 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
  152.  
  153. Command:  cs (chechsum), calculate the checksum on the file indicated in the current path
  154. Response sequence
  155. < XSTARTSUM - indicated that checksum information is about to follow
  156. < XGOODOPEN or XBADOPEN - XGOODOPEN if the file indicated by the current path was opened succesfully for read, XBADOPEN otherwise
  157. ?< XBADSUM - there was an error on doing the checksum operation
  158. < Xnumber - where number indicates the checksum
  159. < XENDSUM - indicated the end of the checksum operation
  160.  
  161. Command:  cd (change directory), set the default directory to be the current path
  162. Response sequence
  163. < 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
  164.  
  165. Command:  pp (print path), return the current directory (like the unix pwd command)
  166. Response sequence
  167. < Xpath - where path is the current working directory
  168.  
  169. 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
  170. Response sequence
  171. ?< 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
  172.  
  173. 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
  174. Response sequence
  175. < XBADOPEN or XGOODOPEN - XBADOPEN if the file indicate in the current path could not be opened for writting, XGOODOPEN if it was
  176.  
  177. Command:  ed (end debugging), if the debugging code is compiled into the suncom application end the logging of debugging information
  178. Response sequence
  179. < XBADCLOSE or XGOODCLOSE - XBADCLOSE if there was an error closing the file, XGOODCLOSE if the file closed succesfully
  180.  
  181. Command: fc (file binary checksums), TUrns on / off the binary level checksumming which occurs during the file transfer
  182. Response sequence
  183. < XOK
  184.