-
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.
Request Message:
- Payload Size: 1 byte (null)
Response Message:
- Payload Size: 1 byte
Request Message:
- Payload Size: 14 Bytes
- See Qik 2s12v10 User Guide -> Configuration Parameters for more details
| Byte | Description | Valid Range |
|---|---|---|
| 13 (MSB) | MSB of Set Indicator Word | 0b00000000 to 0b00001111 |
| 12 | LSB of Set Indicator Word | 0b00000000 to 0b11111111 |
| 11 | Device ID | 0 to 127 |
| 10 | PWM Parameter | 0 to 5 |
| 9 | Shut Down Motors on Error | 0 to 7 |
| 8 | Serial Timeout | 0 to 127 |
| 7 | Motor M0 Acceleration | 0 to 127 |
| 6 | Motor M1 Acceleration | 0 to 127 |
| 5 | Motor M0 Brake Duration | 0 to 127 |
| 4 | Motor M1 Brake Duration | 0 to 127 |
| 3 | Motor M0 Current Limit / 2 | 0 to 127 |
| 2 | Motor M1 Current Limit / 2 | 0 to 127 |
| 1 | Motor M0 Current Limit Response | 0 to 127 |
| 0 (LSB) | Motor M1 Current Limit Response | 0 to 127 |
Response Message:
- Payload Size: 13 Bytes
- The reponse contains the configuration as it was just set. This is used to confirm the correct change was made to the parameters
- See Qik 2s12v10 User Guide -> Configuration Parameters for more details
| Byte | Description | Valid Range |
|---|---|---|
| 12 | Reserved for Expansion | 0 |
| 11 | Device ID | 0 to 127 |
| 10 | PWM Parameter | 0 to 5 |
| 9 | Shut Down Motors on Error | 0 to 7 |
| 8 | Serial Timeout | 0 to 127 |
| 7 | Motor M0 Acceleration | 0 to 127 |
| 6 | Motor M1 Acceleration | 0 to 127 |
| 5 | Motor M0 Brake Duration | 0 to 127 |
| 4 | Motor M1 Brake Duration | 0 to 127 |
| 3 | Motor M0 Current Limit / 2 | 0 to 127 |
| 2 | Motor M1 Current Limit / 2 | 0 to 127 |
| 1 | Motor M0 Current Limit Response | 0 to 127 |
| 0 (LSB) | Motor M1 Current Limit Response | 0 to 127 |
Request Message:
- Payload Size: 1 byte (null)
- This command reads the configuration of the motor controller without modifying any of the settings
Response Message:
- Payload Size: 13 bytes
- See Qik 2s12v10 User Guide -> Configuration Parameters for more details
| Byte | Description | Valid Range |
|---|---|---|
| 12 | Reserved for Expansion | 0 |
| 11 | Device ID | 0 to 127 |
| 10 | PWM Parameter | 0 to 5 |
| 9 | Shut Down Motors on Error | 0 to 7 |
| 8 | Serial Timeout | 0 to 127 |
| 7 | Motor M0 Acceleration | 0 to 127 |
| 6 | Motor M1 Acceleration | 0 to 127 |
| 5 | Motor M0 Brake Duration | 0 to 127 |
| 4 | Motor M1 Brake Duration | 0 to 127 |
| 3 | Motor M0 Current Limit / 2 | 0 to 127 |
| 2 | Motor M1 Current Limit / 2 | 0 to 127 |
| 1 | Motor M0 Current Limit Response | 0 to 127 |
| 0 (LSB) | Motor M1 Current Limit Response | 0 to 127 |
Request Message:
- Payload Size: 9 bytes
- Used to set the speed of both motors simultaneously
Request 0x13 – Set Motor Speeds
| Byte | Description | Valid Range |
|---|---|---|
| 8 (MSB) | Reserved for Expansion | 0 |
| 7 | M0 Speed (MSB) | Integer -100 to 100 |
| 6 | M0 Speed | Integer -100 to 100 |
| 5 | M0 Speed | Integer -100 to 100 |
| 4 | M0 Speed (LSB) | Integer -100 to 100 |
| 3 | M1 Speed (MSB) | Integer -100 to 100 |
| 2 | M1 Speed | Integer -100 to 100 |
| 1 | M1 Speed | Integer -100 to 100 |
| 0 | M1 Speed (LSB) | Integer -100 to 100 |
Response Message:
- The response from the microcontroller to a set motor speed is to reply with the new motor speed to confirm the set was successful
- Payload Size: 9 bytes