User Tools

Site Tools


projects:crazyflie:firmware:comm_protocol

This is an old revision of the document!


Overview

CRTP is the protocol used to communicate with Crazyflie. Is originally stands for Crazy RealTime Protocol. The protocol permits to communicate independently with the copter subsystem and would have the capability to handle packet priorities.

CRTP is implemented in 3 layers:

  • CRTP Link is responsible for transferring the packets between the copter and the PC. It will typically handles packet size and error detection.
  • CRTP Packet handling delivers the packet to the right subsystem in the copter and in the PC control software.
  • Application/ports represents the subsystems that sends and receives messages.

Implemented link drivers:

Link
UART Uart link, mainly used in early development
USB To be implemented USB link.
radio 2.4 GHz NordicSemi Radio link

Current port allocation:

Port Target Used for
0 Console Read console text that is printed to the console on the Crazyflie using consoleprintf
2 Parameters Get/set parameters from the Crazyflie. Parameters are defined using a macro in the Crazyflie source-code
3 Commander Sending control set-points for the roll/pitch/yaw/thrust regulators
5 Log Set up log blocks with variables that will be sent back to the Crazyflie at a specified period. Log variables are defined using a macro in the Crazyflie source-code
14 Client-side debugging Debugging the UI and exists only in the Crazyflie Python API and not in the Crazyflie itself.
15 Link layer Used to control and query the communication link

Communication

Packet structure

A CRTP packet consists of a 8bit header followed by 0-31 bytes of data.

  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
|     Port      |  Res. | Chan. | 
+---+---+---+---+---+---+---+---+
|            DATA 0             |
+---+---+---+---+---+---+---+---+
:   :   :   :   :   :   :   :   :
+---+---+---+---+---+---+---+---+
|            DATA 30            |
+---+---+---+---+---+---+---+---+

+--------+--------+--------+--------+--------+--....--+--------+
|  0xAA  |  0xAA  | Header | Length | Data0  | Packet | CRC32  |
+--------+--------+--------+--------+--------+--....--+--------+
Field Byte Bit Description
Header 0 0-1 The destination channel
0 2-3 Reserved for transport layer
0 4-7 The destination port
Data 1-31 The data in the packet

A port maps to a major function in the Crazyflie that is normally implemented as a separate task. When a CRTP packet is received in the Crazyflie the packet is routed according to the port. The channel can be seen as a sub-set for the port where and can be used to further define commands for the receiving function but no routing will be done using the channel.

Physical layers

Below is the structures for the packages both for the wired serial interface and for the wireless interface. The limitation for the length of the data is set so that it will fit inside one packet for the wireless transmission.

2.4 GHz NordicSemi Radio

The wireless interface will add additional header data like CRC when sending the packet and therefore the packet sent to the wireless interface is only a CRTP packet.

USB port

TODO

Serial port

  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
|             0xAA              |
+---+---+---+---+---+---+---+---+
|             0xAA              |
+---+---+---+---+---+---+---+---+
|      Port     |  Res  | Chan. |
+---+---+---+---+---+---+---+---+
|         Packet length         |
+---+---+---+---+---+---+---+---+
|            DATA 0             |
+---+---+---+---+---+---+---+---+
:   :   :   :   :   :   :   :   :
+---+---+---+---+---+---+---+---+
|            DATA 30            |
+---+---+---+---+---+---+---+---+
|            Cksum              |
+---+---+---+---+---+---+---+---+

+--------+--------+--------+--------+--------+--....--+--------+
|  0xAA  |  0xAA  | Header | Length | Data0  | Packet | Cksum  |
+--------+--------+--------+--------+--------+--....--+--------+
Field Byte Bit Description
Start 0-1 0-2 Start token for synchronization (0xAAAA)
Header 2 0-1 The destination channel
2 2-3 Reserved for the link layer
2 4-7 The destination port
Size 3 Number of data byte
Data 4-.. The data in the packet
Cksum 4+size Checksum. Sum of all the bytes, excluding Start, modulo 256.

Ports

Logging

The purpose of the logging is to be able to log variables that are available in the copter during runtime. The available variables are listed using a TOC that can be read from the copter. A logging block can then be registered consisting of there variables and the data will be sent periodically via CRTP to a receiver.

Table of content access

This channel is used to access the loggable variables table of content.

Messages

Each message uses an additional command byte that is followed by 0 to 31 bytes of data depending of the command. For every command byte there's a difference in usage depending on if the message is sent from the Crazyflie to a Computer or the other way around.

The logging variables are sequentially requested by the receiver until the end. When the last loggable variable is reached it has the ID 0 'Last TOC element'. The reset command permits to reset the TOC pointers so that the next sent TOC element will be the first one. The Get CRC commands also returns the number of loggable variables.

The CRC32 is a hash of the copter's loggable variable TOC. The aim of having this is to be able to cache data on the receiver end and to quickly check the validity of it when connecting.

The following messages are sent from the Client to the Crazyflie:

Request for Byte Description
TOC item 0 0x00 to identify the command
1 The index of the TOC item to request. This is optional, if the index is omitted the first item of the TOC will be returned
TOC CRC and count 0 Request the TOC CRC and item count

The following messages are sent from the Crazyflie to the Client:

Reply for Byte Description
TOC item 0 0x00 to identify the command
1 The ID of the next variable to fetch. If ID == 0xFF no more items are available.
2 Variable ID
3 Type (ref to variable type?)
4-n Null terminated string containing group name
n-m Null terminated string containing variable name
TOC CRC and count 0 0x01 to identify the command
1 Number of total variables in TOC
2-5 CRC32 value of the TOC (of what exacly? group/names?)
Usage

Example of checking the CRC of a TOC to determine if the TOC needs to be refreshed.

   Computer                 Crazyflie
   --------                 ---------
Get TOC CRC32      --->
                   <---     TOC CRC32
[Compare CRC]                   

Example of downloading TOC contents from Crazyflie.

   Computer                 Crazyflie
   --------                 ---------
Request for TOC item --->  
with ID omitted
                     <---  First TOC element (including ID of next element)
Request for TOC item --->
                     <--- Requested TOC element (including ID of next element)
                     ....
                     ....
Request for TOC item --->
                     <--- Requested TOC element (no more items, return next index 0xFF)
[Fetch complete]                   

Log settings access

This channel is used to access the log settings to add/remove/append/start/stop logging. Once a logging block is added to the settings the data it is set to log will periodically be pushed from the Crazyflie to the Client.

Messages

The following messages are sent from the Client to the Crazyflie:

Request for Byte Description
Adding a new log 0 0x00 for identifying the command to add a logging block
1 Desired block id
2 Period in 10th of ms
3-31 Variables to log
Append to log 0 0x01 for identifying the command to append logging variables to an existing block
1 Block ID
2-31 Variables to log
Delete a log 0 0x02 to identify the command for delete an existing block
1 Block ID
Enable a log 0 0x03 to identify the command for enabling logging data from an existing block
1 Block ID
Disable a log 0 0x04 to identify the command for disablling logging data from an existing block
1 Block ID

The response for all of the above messages is sent from the Crazyflie to the Client:

Byte Description
0 The command byte that was sent
1 The ID of the log block that the command operated on
2 Return status for the command. If != 0 see list of return codes
Variable format

The following format is used to identify a variable that is to be logged from the Crazyflie

Log Type Description
1 uint8_t
2 uint16_t
3 uint32_t
4 int8_t
5 int16_t
6 int32_t
7 float32
8 float16
Storage Type Description
0 Variable in TOC
1 Memory address pointing to uint8_t
2 Memory address pointing to uint16_t
3 Memory address pointing to uint32_t
4 Memory address pointing to int8_t
5 Memory address pointing to int16_t
6 Memory address pointing to int32_t
7 Memory address pointing to float32
  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
|    Log type   | Storage type  |
+---+---+---+---+---+---+---+---+
|        Variable ID            |
+---+---+---+---+---+---+---+---+
  7   6   5   4   3   2   1   0
+---+---+---+---+---+---+---+---+
|    Log type   | Storage type  |
+---+---+---+---+---+---+---+---+
|        Mem Address 0          |
+---+---+---+---+---+---+---+---+
|        Mem Address 1          |
+---+---+---+---+---+---+---+---+
|        Mem Address 2          |
+---+---+---+---+---+---+---+---+
|        Mem Address 3          |
+---+---+---+---+---+---+---+---+
List of return codes
Error Description
0x00 No error
0x01 Block not found
0x02 Block already created, needs delete
0xFF Generic error
Usage

Adding a new log block to the settings:

   Computer                 Crazyflie
   --------                 ---------
Add log packet     --->
                   <---     Log packet added ok
[DONE]

Packet structure:
Computer -> CF : 0x[5,1] 0x00 0x01 0x0A 0x02 0x55
CF -> Computer : 0x[5,1] 0x00 0x55 0x00                   

Deleting an existing log block from the settings:

   Computer                 Crazyflie
   --------                 ---------
Delete log packet  --->
                   <---     Log packet deleted ok
[DONE]                   

Packet structure:
Computer -> CF : 0x[5,1] 0x02 0x55
CF -> Computer : 0x[5,1] 0x02 0x55 0x00

Log data access

Logging data is sent back to the copter as raw data with only the block id. This means that the lookup of what data is for what variable has to be done on the computer side.

Adding a log block logging variable ID 0x55 at 100ms interval and of type uint16:
Computer -> CF : 0x[5,1] 0x00 0x01 0x0A 0x02 0x55
CF -> Computer : 0x[5,1] 0x00 0x55 0x00

Receiving a log block logging variable (value 0xBABE):
CF -> Computer : 0x[5,2] 0x55 0xBA 0xBE

Parameters

The parameters system aims at making accessible all the gettable and settable parameters of the copter. In the copter a table of parameters is hold and can be retrieved. In this table every parameter name is associated with an ID and a group name. Three ID are used to acces the TOC and the paramareters:

Port Function
(0,9,0) TOC access
(0,9,1) Parameter read
(0,9,2) Parameter write

TOC access

This ports permits to access the parameters table of content. The first byte of the message is a message ID, three messages ID are defined:

Message ID Meaning in upstream packets Meaning in downstream packets
0 Reset TOC pointer Last TOC element
1 Get next TOC element TOC element
3 Get TOC CRC32 TOC CRC32

The upstream ID are commands and are sent alone. The downstream have the following formats:

Bytes     1       1          1    Null terminated strings
        +---+------------+------+----------+--------------+
        | 0 |            |      |          |              |
        +---+  Param ID  | Type |  Group   |     Name     |
        | 1 |            |      |          |              |
        +---+------------+------+---+------+--------------+
        | 3 | Num. Param |  CRC32   |
        +---+------------+----------+
Bytes     1       1           4

The parameters are sequentially requested by the PC until the end. When the last parameter is reached it has the ID 0 'Last TOC element'. The reset command permits to reset the TOC pointers so that the next sent TOC element will be the first one. The Get CRC commands also returns the number of parameters.

The CRC32 is a hash of the copter TOC. This is aim at implementing caching of the TOC in the PC Utils to avoid fetching the full TOC each time the copter is connected.

Parameter read

TODO

Parameter write

TODO

Fight control

TODO

3:15:0 Echo (profiling)
3:15:1 Source (profiling)
3:15:2 Sink (profiling)
3:15:3 NULL packet
projects/crazyflie/firmware/comm_protocol.1364908441.txt.gz · Last modified: 2015-07-15 16:30 (external edit)