Zipplet's Stuff

MISE (Microcontroller Serial) protocol, 1.0
-------------------------------------------

Copyright (c) Michael Nixon (Zipplet) 2009.

web: http://www.zipplet.co.uk/, http://www.zipplet.org/
email: zipplet@zipplet.co.uk

1. Introduction
---------------

MISE is a packet-oriented communication protocol that is designed to be easy to
implement with a low memory/CPU footprint. It is designed to be used between
microcontrollers (e.g. PIC) and a host, usually a computer. The recommended
implementation runs over RS232 or USB via a converter IC.

Note: Device refers to the microcontroller, host refers to the computer.
Note: MISE is used for the main application. For bootloaders, please see the
MICROSE protocol.

MISE uses the concept of packets. All communication between the host and device
occurs as packets. No out-of-band communication is supported. No error detection
or correction is performed but could be added in a later revision of the
protocol.

2. Packet format
----------------

+--------+----------+--------+-------------------------------------------------+
| Offset | Type     | Length | Description                                     |
+--------+----------+--------+-------------------------------------------------+
|      0 | Byte     | 1      | Packet synchronisation marker 0. $FF            |
|      1 | Byte     | 1      | Packet synchronisation marker 1. $FF            |
|      2 | Byte     | 1      | Command class                                   |
|      3 | Byte     | 1      | Command subclass                                |
|      4 | Byte*4   | 4      | Mandatory parameter bytes                       |
|      5 | Byte     | 1      | Payload size <psize>                            |
|      6 | Array    | psize  | Payload data                                    |
+--------+----------+--------+-------------------------------------------------+

All packets start with 2 synchronisation markers - both a single byte - $FF.
This marker allows the host and device to resynchronise if the cable is pulled
out and then re-inserted while either end is currently transmitting a packet.
This works because there is a special rule required when $FF is to be
transmitted at any other time.

When transmitting, if you need to transmit $FF at any time you must transmit
$FF followed by $00. This may increase the length of the packet header if any
fields are $FF. This can also increase the payload data size that is transmitted
on the wire for the same reason. For example, if the payload is 250 bytes equal
to $FF, then 500 bytes must be transmitted ($FF+$00 250 times). The payload size
field reflects the decoded size not the transmitted size.

This does not increase RAM usage as you can use a simple toggle register to
decode this format. Efficiency is reduced slightly but the benefit is that it
is *always* possible to resynchronise the stream. There are more efficient ways
to achieve this but they need much more overhead.

Payload size can be 0 for no payload, up to 255 as the maximum size in a single
packet. Devices may not support large payloads (due to RAM constraints). Hosts
must support payloads of 255 bytes. All devices must support a minimum payload
size of 16 bytes. Until you know that the device supports a bigger payload size
(MISE_RC_GETDEVICEID) you must not send a larger payload.

3. Resynchronisation
--------------------

One feature of MISE is the way it can automatically resynchronise interrupted
streams without misinterpreting data. This is easy to implement if your receive
function works somewhat like this:

 - STATE = waiting for a new packet
 - ReceiveLoop:
 - Read a byte into <temp>
 - If the byte <> $FF, store it into <temp2> and goto ReceiveLoop
 - <temp> = $FF at this point
 - If <temp2> is $FF, set STATE = receiving a packet otherwise...
 - ...set <temp2> to $FF and goto ReceiveLoop

This pseudocode will ignore everything until it receives 2 $FF's in a row -
this is vastly simplified and your state machine will be much more complex.
See http://www.zipplet.co.uk/ later for example implementations.

4. Protocol violations
----------------------

If your receive loop detects out-of-band transmission (synchronisation issue)
or a protocol violation ($FF followed by something other than $00 or $FF) you
are allowed to send a protocol violation error packet, but you do not have to.
See below for the list of reserved command class/subclass combinations used
for protocol messages.

5. Reserved command class
-------------------------

The command class $00 is reserved for low level protocol communications and
errors. Please implement the commands you want to, but don't implement them
differently to this specification or your device/host will be incompatible.

6. Reserved command list
------------------------

All of these commands have the class as $00.
Format is: $<subclass>, constant_name - friendly name

--------------------------------------------------------------------------------
$00, MISE_RC_PROTOCOLERROR - Protocol error report to other endpoint
Parameters: Byte 0 = error type
Error types:
  - $00: Out-of-band data (synchronisation error)
  - $01: Invalid $FF sequence (got something other than $FF+$FF or $FF+$00)
  - $02: Payload too large (use MISE_RC_GETDEVICEID)

--------------------------------------------------------------------------------
$01, MISE_RC_PING - Ping - verify responsiveness of the endpoint
Paramaters: Data to send back as a response
Ping is useful to determine if the other endpoint implements MISE, and that it
is responding to commands. It should be the first command used when establishing
communications.

--------------------------------------------------------------------------------
$02, MISE_RC_PONG - Pong (ping response)
Parameters: Data originally sent to this endpoint via MISE_RC_PING

--------------------------------------------------------------------------------
$03, MISE_RC_GETPROTOCOLVERSION - Get version of MISE protocol supported
Parameters: None

--------------------------------------------------------------------------------
$04, MISE_RC_PROTOCOLVERSION - Response to MISE_RC_GETPROTOCOLVERSION
Parameters: Bytes 0-3 = protocol major,minor,year(0-99),month(1-12)
Sent by an endpoint in response to MISE_RC_GETPROTOCOLVERSION
Current version is 1.0 with a varying date.

--------------------------------------------------------------------------------
$05, MISE_RC_GETDEVICEID - Get endpoint device ID and max payload size
Parameters: none
This is usually sent from the host to a device.
This must be implemented by the host and device.
This should NOT be send by a device until the host has sent this command to
the device and obtained a response. Otherwise, the host does not know if it can
send a long identification string or not (max payload size).

--------------------------------------------------------------------------------
$06, MISE_RC_DEVICEID - Device ID response
Parameters: Bytes 0-2 = user defined ID information. Byte 3 = max payload size
Payload: Device friendly name as a string
This must be implemented by the host and device.
Hosts always send a max payload size of 255. For devices, 16-255.

--------------------------------------------------------------------------------
$07, MISE_RC_BOOTLOADER - Enter bootloader mode
Parameters: None
This command is implemented by the device. Upon receiving this command the
device will enter bootloader mode. Usually the bootloader will use the MICROSE
protocol and a hello packet will be sent by the bootloader, so the host will
know that the device has entered bootloader mode.