Protocol

The protocol between the Python client and Arduino is a synchronous request
response based system. The client initiates all communication, one request
at a time.

Each request yields a response from the Arduino which must be consumed fully
before the next request can be sent.

Each request is packed into a structured binary envelope consisting of a
leading octet indicating the length of the message (excluding the leading
octet), followed by a single octet describing the command that is to be
executed by the Arduino, followed by 0 up to and including 62 bytes of
command-specific payload data:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |     Length    |    Command    |              Data             |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


1. Command Messages

The following commands are defined:


1.1 Read

Command byte: 'r' (0x72 / ASCII 114)
Data: 16 bit address in network byte order. Since the AT28C256 has only 15
address lines, only the 15 lower bits are used. The leading, MSB is unused.

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |        3      |       'r'     |0|      15 bit address         |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The response is a message containing the value at the specified address:

   0                   1
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |        1      |     value     |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+



1.2. Write

Command byte: 'w' (0x77 / ASCII 119)
Data: 3 bytes, broken down as follows: 2 bytes containing a 15 bit address
in network byte order, followed by one octet of data to be written to the
specified address.

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |        4      |       'w'     |0|      15 bit address         |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |      Data     |
  +-+-+-+-+-+-+-+-+

The response is an acknowledgement message to indicate the operation finished
and a new command can be sent. An acknowledgement message is defined as a
single 0-byte.


1.3. Dump

Command byte: 'd' (0x64 / ASCII 100)
Data: No payload following the command byte.

   0                   1
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |        1      |       'd'     |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The response is the raw contents of the entire EEPROM. This is returned as a
sequence of messages each starting with a length octet, followed by up to 63
bytes of raw payload data.

Each message is explicitly and synchronously acknowledged by the client using
a 0-byte acknowledgement message before the next message is sent.

The dump command returns exactly 32768 bytes of content at which point the
transmission is complete. The client does not respond with an acknowledgement
after the final message as no further communication will be initiated by the
circuit to warrant flow control.


1.4. Load

Command byte: 'l' (0x6C / ASCII 108)
Data: 2 bytes indicating the size of the upload that follows the request
message. Since the AT28C256 has only 15 address lines, only the lower 15 bits
are used. The leading, MSB is ignored.

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |        3      |       'l'     |0|       15 bit length         |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Directly following the command message is the stream of messages each starting
with a length octet, followed by up to 63 bytes of raw payload data.

Each message is explicitly and synchronously acknowledged by the Arduino using
a 0-byte acknowledgement message before the next message is sent. This includes
the initial command message which needs to be explicitly acknowledged before
the client can proceed to send payload messages.

The command is complete once the specified number of bytes have been received.
The Arduino acknowledges the final message with a 0-byte message.

Writing always begins at address 0.


1.5 Reset

Command byte: 'r' (0x72 / ASCII 114)
Data: No payload following the command byte.

   0                   1
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |        1      |       'r'     |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Immediately abort the pending operation and wait for a new command. No
acknowledgement is sent.


2.0 Flow Control

Since the Arduino's serial-over-usb port does not support hardware flow
control and has a limited 64-byte receive buffer, data is sent in discrete,
sequential segments that in most cases need to be explicitly acknowledged by
the peer before the next can be sent.

To prevent an overflow the receive buffer, the maximum segment size is 64
bytes; 1 length octet followed by at most 63 data bytes.