Communication protocol
Message format
Messages sent to and received from the microcontrollers are byte oriented streams. All messages start with a caret sign ^ (0x5e) and end with a dollar sign $ (0x24).
Bytes | 1 | n | 1 |
---|---|---|---|
^ |
n unsigned bytes |
$ |
An exclamation mark ! inside a message body indicates a transmission error and invalidates the whole message. The characters ^, $, ! and \ are special and must be escaped with a backslash \ followed by the two’s complement of the escaped character (they are thus encoded on two successive bytes).
Special character | Escaped version inside a message body |
---|---|
^ |
\ 0xa2 |
$ |
\ 0xdb |
! |
\ 0xde |
\ |
\ 0xa3 |
All messages may embed signed or unsigned integers. They are encoded on 1, 2 or 4 bytes (depending on the message format decribred later), in big-endian format (most significative byte first).
Bytes | 1 | 2 | 3 | 4 |
---|---|---|---|---|
8 bits integer |
n |
|||
16 bits integer |
n >> 8 |
n |
||
32 bits integer |
n >> 24 |
n >> 16 |
n >> 8 |
n |
Brushless controller messages
The brushless controller defines the following messages:
Clock timestamp
This message can be sent periodically to the controller so that is calibrates its internal oscillator. The message contains the local time on the sending machine, encoded in micro seconds (possibly wrapped around).
Bytes | 1 | 1 | 4 (unsigned int) | 1 |
---|---|---|---|---|
^ |
t |
local timestamp (µs) |
$ |
Motor startup
This message starts the motor at a very low speed (about 16Hz).
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
g |
$ |
Motor stop
This message stops the motor.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
x |
$ |
PWM duty cycle
This spins the motor at the given PWM duty cycle. The duty cycle is encoded as a 16 bit unsigned integer, but useful range is from 0 (0%) to 1023 (100%). The motor must be started for that message to be taken into account.
Bytes | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|
^ |
p |
pwm (0-1023) |
$ |
Velocity control
This spins the motor at a given velocity. The velocity is encoded as the rotational period in micro seconds (the inverse of the velocity), on a 16 bit unsigned integer.
Bytes | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|
^ |
v |
rotational period (µs) |
$ |
Velocity query
This message queries the current spinning velocity. The reply contains a bit field with the current spinning state, as well as the current rotational period in microseconds.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
s |
$ |
Bytes | 1 | 1 | 1 (bit field) | 2 (unsigned int) | 1 |
---|---|---|---|---|---|
^ |
S |
emergency (0x80) |
rotational period (µs) |
$ |
Current query
This message queries the instantaneous current consumption. The reply contains the value in miliampers.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
a |
$ |
Bytes | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|
^ |
A |
current (mA) |
$ |
Motor data query
This message queries important values from the motor.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
m |
$ |
Bytes | 1 | 1 | 4 (unsigned int) | 1 (bit field) | 2 (unsigned int) | 2 (unsigned int) | 2 (unsigned int) | 1 |
---|---|---|---|---|---|---|---|---|
^ |
M |
timestamp (µs) |
emergency (0x80) |
rotational period (µs) |
pwm (0-1023) |
peak current (mA) |
$ |
The timestamp is the internal time at which data where gathered. The peak current is the maximum current recorded since the last time this message was sent by the microcontroller.
Sensor data query
This message queries values from various on board sensors.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
d |
$ |
Bytes | 1 | 1 | 4 (unsigned int) | 2 (unsigned int) | 2 (unsigned int) | 2 (unsigned int) | 2 (unsigned int) | 1 |
---|---|---|---|---|---|---|---|---|
^ |
D |
timestamp (µs) |
battery level (mV) |
current (mA) |
microcontroller temperature (0.1 ⁰C) |
pcb temperature (0.1 ⁰C) |
$ |
The timestamp is the internal time at which data where gathered.
Velocity controller data query
This message queries values from the velocity controller.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
k |
$ |
Bytes | 1 | 1 | 4 (unsigned int) | 1 (bit field) | 2 (unsigned int) | 2 (signed int) | 2 (signed int) | 2 (signed int) | 1 |
---|---|---|---|---|---|---|---|---|---|
^ |
K |
timestamp (µs) |
emergency (0x80) |
target velocity (µs) |
bias |
gain |
error |
$ |
The timestamp is the internal time at which data where gathered.