-
Notifications
You must be signed in to change notification settings - Fork 0
API Documentation
This page is intended for the developers of the communication protocol that will enable our interfacing microcontrollers to speak to our computers (both onboard and shoreside).
It describes the message structure to be followed and defines an exhaustive set of commands that are used to communicate between devices. Further, each command has an inherent payload structure for each direction of data transfer which is also described here.
Development of this page is being discussed in this issue.
The protocol is used to provide a consistent method by which serial communication is sent/received on the boat. It begins and ends with a standard header and footer and contains a payload of varying size dependent upon the function of the message (command) being sent.
The protocol assumes the computer (onboard or shoreside) is issuing a request to the microcontroller. In this way, the computer is able to control the flow and rate of information transfer. The structure of a message is as follows:
| Start Indicator | Command Number | Payload | CRC16 (MSB) | CRC16 (LSB) |
|---|---|---|---|---|
| 0xAA | 0x00 to 0xFF | Varying Size | 0x00 to 0xFF | 0x00 to 0xFF |
Each message begins with the same byte, always 0xAA.
The type of message being sent is indicated by the command number. Each microcontroller has a block of commands reserved exclusively for it. This provides further consistency and a means of easily adding commands.
| Block Start | Block End | Microcontroller |
|---|---|---|
| 0x00 | 0x0F | Wireless Communications |
| 0x10 | 0x1F | Propulsion |
| 0x20 | 0x2F | Navigation |
| 0x30 | 0x3F | |
| 0x40 | 0x4F | |
| 0x50 | 0x5F | |
| 0x60 | 0x6F | |
| 0x70 | 0x7F | |
| 0x80 | 0x8F | |
| 0x90 | 0x9F | |
| 0xA0 | 0xAF | |
| 0xB0 | 0xBF | |
| 0xC0 | 0xCF | |
| 0xD0 | 0xDF | |
| 0xE0 | 0xEF | |
| 0xF0 | 0xFF |
The payload of each message is dependent upon the command issued. However, each command has a specific payload length associated with both the request and the response message.
The CRC16 (a 16-bit Cyclic Redundancy Check) is a method by which the validity of a serial message can be verified. It is a mathematical equation applied to the entire message (except the CRC itself) by the sender and is then verified by the receiver. If there is a discrepancy then it is known that the message is corrupted.