
SComP - Scanndy Communications Protocol
=======================================

SComP is intended to allow data transfer to and from, as well as remote control
of, Panmobil (smart)Scanndy devices by exchanging messages between two endpoints.
SComP uses message ids to allow for matching request/response pairs and assures
data integrity through use of CRC-32 checksums. Its main use is to provide
reliable bidirectional communication over unreliable serial communication lines.
The SComP metadata is human readable and is composed of only ASCII characters,
to simplify debugging and transport over binary intransparent communication
lines. In the design, simplicity was given higher precedence than efficiency.


SComP Packet Structure
----------------------

Each SComP data packet is composed of three main parts:
* the fixed size (10 octets) packet header
* variable length (up to 65535 octets) payload data
* the fixed size (8 octets) packet trailer

ssssTnnnnRp....pCCCCCCCC
\__/|\__/|\____/\______/
  | |  | |    |       |
  | |  | |    |       8 hex digits CRC-32, covering header and payload
  | |  | |    |
  | |  | |    n octets arbitrary payload data, see below
  | |  | |
  | |  | one octet reserved for future use, set to '#' for the time being
  | |  |
  | |  length n of payload data (four hex digits)
  | |
  | type of packet flag: 'Q' = request, 'R' = response
  |
  four hex digits message ID (sequence numnber), used to match related request/response pairs

Message IDs
...........
The request generator should generate a new message id for each request. The
recommended implemention is a counter that is incremented for each generated
request, but this approach is not mandatory. The receiver shall not make any
assumptions about the algorithm generating the request message ids. The sole
purpose of the request message ID is to re-use it in the header of the
corresponding response packet.

CRC-32
......
The CRC-32 implementation shall use an initial value of 0xFFFFFFFF and a polynom
of 0xEDB88320. The result shall be finalized by XORing it with 0xFFFFFFFF.

Example:
........
(The spaces were added to improve readability, they are not part of the protocol!)
-> 0042 Q 000C # beep:200,200 742C823D
<- 0042 R 0007 # ok 538068BA


SComP Payload Structure
-----------------------

Though generally capable of carrying arbitrary binary payload data, SComP is mainly
intended to transfer text messages consisting of specific commands and accompanying
data to facilitate interaction with devices of the PANMOBIL SCANNDY family.

All commands are treated as case sensitive. Command and data shall be separated by
a colon (':'). If no data is appended, the colon may be dropped. In case a command
is defined to use more than one parameter, subsequent parameters

The generic response upon successful completion is simply 'ok', unless otherwise
noted. Unless otherwise noted the generic response upon failure is simply 'error',
usually followed by an error code and a plain text error message, each separated
by a colon (':').

The following commands are currently defined (the angle brackets denote parameters
and do not actually appear in the message):

------------------------------------------

beep:<f>,<d>				request Scanndy to beep for a duration of <d> ms at <f> Hz,
							both in decimal notaion

------------------------------------------

vibrate:<d>					request Scanndy to vibrate for a duration of <d> ms,
							in decimal notaion

------------------------------------------

print:<text>				request Scanndy to print a text string to the screen
							NOTE: the escape sequences '\r' and '\n' are interpreted as
							carriage return and carriage return plus line feed, respectively.

------------------------------------------

setcrsr:<x>,<y>				set cursor position, column and row coordinates in decimal notation

------------------------------------------

clrscr:all					clear whole screen
clrscr:client 				clear client area
clrscr:title 				clear title bar

------------------------------------------

keydata:<k>					unsolicited message, result of a proactive keypress on Scanndy
                            (contains a single printable character)

------------------------------------------

barscan:<t>					request Scanndy to initiate a barcode scan for t ms

bardata:<data> 				result of a barcode scan, <data> is presented as text string
							(sent as response to a barscan request or as unsolicited request
							upon user user action)
							NOTE: a failure to read any barcode data simply results in the response
							"bardata", without any actual data attached. No specific error response
							is generated.

------------------------------------------

rfidscan:tid[,<addr>,<len>]	request to scan an RFID TID, optionally addressed
rfidscan:epc[,<addr>,<len>]	request to scan RFID EPC data (UHF Gen2 only), optionally addressed
rfidscan:usr,<addr>,<len>	request to scan RFID user data

rfiddata:<data>				result of an RFID scan, 'data' is presented in hexadecimal notation
							(message is sent as response to a barscan request or as unsolicited
							request upon user user action)
							NOTE: a failure to read any RFID tag data simply results in the
							response "rfiddata", without any actual data attached. No specific
							error response is generated.

------------------------------------------

rfidwrite:usr,<addr>,<data>	request Scanndy to write RFID user data, <addr> in decimal notation,
							<data> in hexadecimal notation.

rfidwrite:epc[,<addr>],<data> request Scanndy to write EPC data (UHF Gen2 only)
							If <addr> is specified, the EPC length stored in the PC word will
							not be updated.

------------------------------------------

====================================================================================================================

TODO:
-----
textinput:<mode>,<len>		request interactive text input on Scanndy of specified mode (num|alnum) and max. length
textdata:<ddd>				result of requested interactive text input on Scanndy

setcfg:<section>:<item>=<v>	set configuration <item> in <section> to value <v>
getcfg:<section>:<item>		get configuration value of <item> in <section>

File transfer:
--------------
	-> putfile:<filename>
	<- send:<x>
	-> data:<data 1>
	<- send:<x> | repeat
	...
	-> ok
	<- ok


	-> getfile:<filename>
	<- data:<data 1>
	-> ok (| repeat)
	...
	<- data:<data n>
	-> ok
	<- ok

--------------
