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:
ID
This message queries the controller for it’s version, and motor id.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
? |
$ |
Bytes | 1 | 1 | 1 (unsigned int) | n>4 (string) | 1 |
---|---|---|---|---|---|
^ |
? |
motor id |
mkblX.Y |
$ |
X.Y represent the software version running on board.
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 signed integer, but useful range is from -1023 (-100%) to 1023 (100%). Negative values mean spinning in the reverse direction. The motor must be started for that message to be taken into account.
Bytes | 1 | 1 | 2 (signed int) | 1 |
---|---|---|---|---|
^ |
p |
pwm (-1023 .. 1023) |
$ |
Alternatively, an array can be broadcasted to all controllers. Each controller will take the i th value of the message where i is the motor id.
Bytes | 1 | 1 | 2 (signed int) | … | 2 (signed int) | 1 |
---|---|---|---|---|---|---|
^ |
q |
pwm (-1023 … 1023) |
… |
pwm (-1023 … 1023) |
$ |
Velocity control
This spins the motor at a given velocity. The velocity is encoded as the half of the desired rotational period in micro seconds (the inverse of the velocity), on a 16 bit signed integer. Negative values mean spinning in the reverse direction.
Bytes | 1 | 1 | 2 (signed int) | 1 |
---|---|---|---|---|
^ |
v |
half rotational period (µs) |
$ |
Alternatively, an array can be broadcasted to all controllers. Each controller will take the i th value of the message where i is the motor id.
Bytes | 1 | 1 | 2 (signed int) | … | 2 (signed int) | 1 |
---|---|---|---|---|---|---|
^ |
w |
half rotational period for motor 1 (µs) |
… |
half rotational period for motor motor n (µ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 half rotational period in microseconds.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
s |
$ |
Bytes | 1 | 1 | 1 (bit field) | 2 (signed int) | 1 |
---|---|---|---|---|---|
^ |
S |
emergency (bit 7) |
half 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 | 1 (bit field) | 2 (unsigned int) | 1 |
---|---|---|---|---|---|
^ |
A |
emergency (bit 7) |
current (mA) |
$ |
Motor data query
This message ask for important values from the motor to be sent periodically.
Bytes | 1 | 1 | 4 (unsigned int) | 1 |
---|---|---|---|---|
^ |
m |
period (µs) |
$ |
Bytes | 1 | 1 | 1 | 1 (bit field) | 2 (signed int) | 2 (unsigned int) | 2 (unsigned int) | 1 |
---|---|---|---|---|---|---|---|---|
^ |
M |
sequence # |
emergency (bit 7) |
half rotational period (µs) |
pwm (0-1023) |
peak current (mA) |
$ |
The peak current is the maximum current recorded since the last time this message was sent by the microcontroller.
The sequence number increments for each sent message.
Sensor data query
This message queries values from various on board sensors.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
d |
$ |
Bytes | 1 | 1 | 1 (bit field) | 2 (unsigned int) | 2 (unsigned int) | 2 (unsigned int) | 2 (unsigned int) | 1 |
---|---|---|---|---|---|---|---|---|
^ |
D |
emergency (bit 7) |
battery level (mV) |
current (mA) |
microcontroller temperature (0.1 ⁰C) |
pcb temperature (0.1 ⁰C) |
$ |
Velocity controller data query
This message queries values from the velocity controller.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
k |
$ |
Bytes | 1 | 1 | 1 (bit field) | 2 (unsigned int) | 2 (signed int) | 2 (signed int) | 2 (signed int) | 1 |
---|---|---|---|---|---|---|---|---|
^ |
K |
emergency (bit 7) |
target velocity (µs) |
bias |
gain |
error |
$ |
Battery level query
This message ask for periodic battery level.
Bytes | 1 | 1 | 4 (unsigned int) | 1 |
---|---|---|---|---|
^ |
b |
period (µs) |
$ |
Bytes | 1 | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|---|
^ |
B |
sequence # |
battery level (mV) |
$ |
The sequence number increments for each sent message.
Beep
This message plays a given sound tone with the motor, when it is stopped.
Bytes | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|
^ |
~ |
frequency (Hz) |
$ |
Flight controller messages
The flight controller defines the following messages:
ID
This message queries the controller for it’s version, and motor id.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
? |
$ |
Bytes | 1 | 1 | n>4 (string) | 1 |
---|---|---|---|---|
^ |
? |
mkflX.Y |
$ |
X.Y represent the software version running on board.
Motors startup
This message starts all motors at a very low speed (about 16Hz).
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
g |
$ |
It is also possible to start only one motor by specifying its id.
Bytes | 1 | 1 | 1 (unsigned int) | 1 |
---|---|---|---|---|
^ |
g |
motor id |
$ |
Motors stop
This message stops all motors.
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
x |
$ |
It is also possible to stop only one motor by specifying its id.
Bytes | 1 | 1 | 1 (unsigned int) | 1 |
---|---|---|---|---|
^ |
x |
motor id |
$ |
PWM duty cycle
This spins motors at the given PWM duty cycle. The duty cycle is encoded as a 16 bit signed integer, but useful range is from -1023 (-100%) to 1023 (100%). Negative values mean spinning in the reverse direction. Each motor takes the i th value of the message where i is the motor id.
Bytes | 1 | 1 | 2 (signed int) | … | 2 (signed int) | 1 |
---|---|---|---|---|---|---|
^ |
q |
pwm (-1023 … 1023) |
… |
pwm (-1023 … 1023) |
$ |
Velocity control
This spins motors at a given velocity. The velocity is encoded as an array of half rotational period in micro seconds (the inverse of the velocity), on a 16 bit signed integer. Negative values mean spinning in the reverse direction. Each motor takes the i th value of the message where i is the motor id.
Bytes | 1 | 1 | 2 (signed int) | … | 2 (unsigned int) | 1 |
---|---|---|---|---|---|---|
^ |
w |
half rotational period for motor 1 (µs) |
… |
half rotational period for motor motor n (µs) |
$ |
Gyroscope calibration
This message runs a calibration procedure for the gyroscopes, for the given amount of time. The board should be still while this procedure runs. There flight controller reports when the procedure is done.
Bytes | 1 | 1 | 1 | 1 (unsigned int) | 1 |
---|---|---|---|---|---|
^ |
z |
g |
time (s) |
$ |
Bytes | 1 | 1 | 1 |
---|---|---|---|
^ |
Z |
$ |
IMU query
This message ask for periodic IMU data.
Bytes | 1 | 1 | 4 (unsigned int) | 1 |
---|---|---|---|---|
^ |
i |
period (µs) |
$ |
Bytes | 1 | 1 | 1 | 2 (signed int) | 2 (signed int) | 2 (signed int) | 2 (signed int) | 2 (signed int) | 2 (signed int) | 1 |
---|---|---|---|---|---|---|---|---|---|---|
^ |
I |
sequence # |
linear acceleration X (mm/s²) |
linear acceleration Y (mm/s²) |
linear acceleration Z (mm/s²) |
angular velocity X (mrad/s) |
angular velocity Y (mrad/s) |
angular velocity Z (mrad/s) |
$ |
The sequence number increments for each sent message.
Battery level query
This message ask for periodic battery level.
Bytes | 1 | 1 | 4 (unsigned int) | 1 |
---|---|---|---|---|
^ |
b |
period (µs) |
$ |
Bytes | 1 | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|---|
^ |
B |
sequence # |
battery level (mV) |
$ |
The sequence number increments for each sent message.
Motor data query
This message queries important values from each connected motor.
Bytes | 1 | 1 | 4 (unsigned int) | 1 |
---|---|---|---|---|
^ |
m |
period (µs) |
$ |
There is one reply per connected motor, in the same format as the brushless controller message (see Motor data).
Beep
This message plays a given sound tone with the motors, when they are stopped.
Bytes | 1 | 1 | 2 (unsigned int) | 1 |
---|---|---|---|---|
^ |
~ |
frequency (Hz) |
$ |