tk3-mikrokopter - Openrobots

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).

Table 1. Message format
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).

Table 2. Special characters
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).

Table 3. Integer encoding
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.

Table 4. ID query message
Bytes	1	1	1
	`^`	`?`	`$`

Table 5. ID reply message
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).

Table 6. Timestamp message
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).

Table 7. Startup message
Bytes	1	1	1
	`^`	`g`	`$`

Motor stop

This message stops the motor.

Table 8. Stop message
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.

Table 9. PWM message
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.

Table 10. PWM array message
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.

Table 11. Velocity message
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.

Table 12. Velocity array message
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.

Table 13. Velocity query message
Bytes	1	1	1
	`^`	`s`	`$`

Table 14. Velocity query reply
Bytes	1	1	1 (bit field)	2 (signed int)	1
	`^`	`S`	`emergency (bit 7) servo (bit 6) spinning (bit 5) starting (bit 4) motor id (bits 0 to 3)`	`half rotational period (µs)`	`$`

Current query

This message queries the instantaneous current consumption. The reply contains the value in miliampers.

Table 15. Current query message
Bytes	1	1	1
	`^`	`a`	`$`

Table 16. Current query reply
Bytes	1	1	1 (bit field)	2 (unsigned int)	1
	`^`	`A`	`emergency (bit 7) servo (bit 6) spinning (bit 5) starting (bit 4) motor id (bits 0 to 3)`	`current (mA)`	`$`

Motor data query

This message ask for important values from the motor to be sent periodically.

Table 17. Motor data query
Bytes	1	1	4 (unsigned int)	1
	`^`	`m`	`period (µs)`	`$`

Table 18. Motor data
Bytes	1	1	1	1 (bit field)	2 (signed int)	2 (unsigned int)	2 (unsigned int)	1
	`^`	`M`	`sequence #`	`emergency (bit 7) servo (bit 6) spinning (bit 5) starting (bit 4) motor id (bits 0 to 3)`	`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.

Table 19. Sensor data message
Bytes	1	1	1
	`^`	`d`	`$`

Table 20. Sensor data reply
Bytes	1	1	1 (bit field)	2 (unsigned int)	2 (unsigned int)	2 (unsigned int)	2 (unsigned int)	1
	`^`	`D`	`emergency (bit 7) servo (bit 6) spinning (bit 5) starting (bit 4) motor id (bits 0 to 3)`	`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.

Table 21. Velocity controller message
Bytes	1	1	1
	`^`	`k`	`$`

Table 22. Velocity controller reply
Bytes	1	1	1 (bit field)	2 (unsigned int)	2 (signed int)	2 (signed int)	2 (signed int)	1
	`^`	`K`	`emergency (bit 7) servo (bit 6) spinning (bit 5) starting (bit 4) motor id (bits 0 to 3)`	`target velocity (µs)`	`bias`	`gain`	`error`	`$`

Battery level query

This message ask for periodic battery level.

Table 23. Battery level query message
Bytes	1	1	4 (unsigned int)	1
	`^`	`b`	`period (µs)`	`$`

Table 24. Battery level data
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.

Table 25. Beep
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.

Table 26. ID query message
Bytes	1	1	1
	`^`	`?`	`$`

Table 27. ID reply message
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).

Table 28. Startup message
Bytes	1	1	1
	`^`	`g`	`$`

It is also possible to start only one motor by specifying its id.

Table 29. Individual startup message
Bytes	1	1	1 (unsigned int)	1
	`^`	`g`	`motor id`	`$`

Motors stop

This message stops all motors.

Table 30. Stop message
Bytes	1	1	1
	`^`	`x`	`$`

It is also possible to stop only one motor by specifying its id.

Table 31. Individual stop message
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.

Table 32. PWM array message
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.

Table 33. Velocity control message
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.

Table 34. Gyroscope calibration message
Bytes	1	1	1	1 (unsigned int)	1
	`^`	`z`	`g`	`time (s)`	`$`

Table 35. Gyroscope calibration report
Bytes	1	1	1
	`^`	`Z`	`$`

IMU query

This message ask for periodic IMU data.

Table 36. IMU query message
Bytes	1	1	4 (unsigned int)	1
	`^`	`i`	`period (µs)`	`$`

Table 37. IMU data
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.

Table 38. Battery level query message
Bytes	1	1	4 (unsigned int)	1
	`^`	`b`	`period (µs)`	`$`

Table 39. Battery level data
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.

Table 40. Motor data message
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.

Table 41. Beep
Bytes	1	1	2 (unsigned int)	1
	`^`	`~`	`frequency (Hz)`	`$`

Project

General

Profile

Aerial Robotics Testbed » telekyb3 » tk3-mikrokopter

Indexes

Communication protocol

Message format

Brushless controller messages

ID

Clock timestamp

Motor startup

Motor stop

PWM duty cycle

Velocity control

Velocity query

Current query

Motor data query

Sensor data query

Velocity controller data query

Battery level query

Beep

Flight controller messages

ID

Motors startup

Motors stop

PWM duty cycle

Velocity control

Gyroscope calibration

IMU query

Battery level query

Motor data query

Beep