Protocol Proposal

Welcome to the hoverboard-firmware-hack wiki!

Protocol description and operation:

Proposed change to protocol: from:

0x02
len 1-255
(cmd)
data - 0 to 254 bytes
CS - (0 - (sum of all bytes from len onwards)

to: 'machine' Protocol consist of:

0x02 - StartOfMessage ('SOM')
CI - byte continuity counter 
len - byte length 1-255 ******* Note: len is cmd+(numbytes) - NOT INCLUDING SOM, CI, CS
(cmd)
data - 0 to 254 bytes
CS - (0 - (sum of all bytes from CI onwards/or CRC - the STM32 has a hw CRC module)

Notes:

• CI Will increment for 'true' each message sent, but not for ACK or NACK.

• ACK and NACK will carry the CI of the message being acknowledged.

• messages controller->hoverboard will generally have base command 0-0x7f

• messages hoverboard->controller will generally have base command 0x80-0xff

• not hard rules; just guidance in cmd number creation.

• All messages except ACK/NACK will be responded to with ACK or NACK.

Sending:

• If an end sends a message, it should not send another until an ACK has been received or all retries sent.
• If an end receives a NACK, it should resend the last message with the same CI, up to 2 retries.
• If an end does not receive an ACK response within (TIMEOUT1), it should resend the last message with the same CI, up to 2 retries.

Receiving:

• if a message is received with the same CI as the last received message, ACK will be sent, but the message discarded.

• if an ACK is received which contains the same CI as the last ACK, the ACK will be ignored.

• if an ACK is received which contains a CI different to the last sent message, the ACK will be ignored. (?? implications??)

• In receive, if in a message (SOM has been received) and the time since the last character exceeds (TIMEOUT2), the incomming message should be discarded, and a NACK should be sent with the CI of the message in progress or zero if no CI received yet.

• sending messages and receiving messages are independent - e.g. if expecting an ACK, and a new message is received, the ACK should still be expected.

• normally, characters received BETWEEN messages which are not SOM should be treated as ASCII commands.

• implement a mode where non SOM characters between messages cause (TIMEOUT2) to be started, resulting in a NACK with CI of last received message + 1.

Timeouts:

• TIMEOUT1 - generally 500ms, but configurable through the protocol/flash?.
• TIMEOUT2 - generally 100ms, but configurable through the protocol/flash?. (normally, in a protocol like this, an inter-character timeout would be ~10 character times, but this is impractical in higher level implementations, like raw TCP-to-serial, so we're being a bit more relaxed to ease implementation).

Notes on failure modes:

Lost character:

• This would result in TIMEOUT2, and a NACK.
• if the CI is lost, the NACK may carry an incorrect CI.
• if the length was lost, then TIMEOUT2 may be triggered
• if the length was substituted for a smaller number, it would be _possible _for the receiver to think it had started a second message?

Corrupted character: (all message characters received)

• This would result in a fast NACK.
• if the corruption was the CI, the NACK may carry an incorrect CI.
• if the corruption was in the count, then TIMEOUT2 may be triggered.
• if the corruption made count short, it would be _possible _for the receiver to think it had started a second message?

Q:

is this too complex?

• It requires storage of the last message sent, and state at each end.
• It requires timeout implementations at both ends
• The same code should work at both ends (ok, so I'll have to convert to JS).
• Will it put others off from using it?
• are there race conditions which could result in a snowball message effect? Do we need to add Flush? Is flush practical in other environments (e.g. my linux/usb serial).
• should we 'bite the bullet' and use something mature like MODBUS?

comments moved into an issue - so that we get email notifications...