Messages Format

Introduction

Messages Format and how to use them

For the message definitions see http://docs.paparazziuav.org/latest/paparazzi_messages.html

Types

Paparazzi "PPRZ" standard message for direct serial connection

Pprzlink v1.0

PPRZ-message: ABCxxxxxxxDE
byte:    |   value:
    0        PPRZ_STX (0x99)
    1        LENGTH (PPRZ_STX->PPRZ_CHECKSUM_B)
    2        SENDER_ID
    3        MSG_ID
    4..(N-2) MSG_PAYLOAD (messages.xml)
    N-1      PPRZ_CHECKSUM_A (sum[B->C])
    N        PPRZ_CHECKSUM_B (sum[ck_a])

Pprzlink v2.0

Note that there is currently no explicit way to recognize whether the protocol is v1.0 or 2.0 so it has to be known before the communication.

PPRZ-message: ABCxxxxxxxDE
    A PPRZ_STX (0x99)
    B LENGTH (A->E)
    C PPRZ_DATA
      0 SOURCE (~sender_ID)
      1 DESTINATION (can be a broadcast ID)
      2 CLASS/COMPONENT
        bits 0-3: 16 class ID available
        bits 4-7: 16 component ID available
      3 MSG_ID
      4 MSG_PAYLOAD
      . DATA (messages.xml)
    D PPRZ_CHECKSUM_A (sum[B->C])
    E PPRZ_CHECKSUM_B (sum[ck_a])

Secure Paparazzi (S-PPRZ) for serial and transparent modem communication

Secure Paparazzi link (pprzlink) uses symmetric key encryption with Chacha20 cipher.

s-pprzlink uses a formally verified cryptographic library HACL* developed by the Prosecco team at INRIA Paris in collaboration with Microsoft Research, as part of Project Everest.

Because certain data have to be send in plaintext (such as the message counter), s-pprzlink uses Authenticated Encryption with Associated Data (AEAD) algorithm to authenticate such data before use. Authentication means that any unauthorized change in data is detected upon decryption. Authentication is important because if we decide to send SENDER_ID or DESTINATION_ID in plaintext - so the receiver can decide whether to decrypt the message - we don't want it to be tampered with. s-pprzlink uses a modified Galois Embedded Crypto algorithm, refer there for more details about the algorithm itself.

The cryptographic overhead during regular communication is 20 bytes (4 bytes of the counter, 16 bytes of the authentication tag), plus the necessary key exchange at the beginning of communication.

S-Pprzlink v1.0

PPRZ-message: ABCxxxxxxxDE
byte:      |     value:
   0             PPRZ_STX (0x99)
   1             LENGTH (PPRZ_STX->PPRZ_CHECKSUM_B)
   2-5           COUNTER (4 bytes)
   6             encrypted SENDER_ID
   7             encrypted MSG_ID
   8..(N-16)     encrypted MSG_PAYLOAD (messages.xml)
   (N-15)..(N-2) TAG (16 bytes)
   N-1           PPRZ_CHECKSUM_A (sum[B->C])
   N             PPRZ_CHECKSUM_B (sum[ck_a])

S-Pprzlink v1.0

byte	Value	Type
0	PPRZ_STX (0x99)	Header
1	length N (PPRZ_STX->checksum B)	Header
2	sender ID	Authenticated data
3	counter LSB 1	Authenticated data
4	counter LSB 2	Authenticated data
5	counter LSB 3	Authenticated data
6	counter LSB 4	Authenticated data
7	message ID	Encrypted payload
8..(N-16)	(optional) message payload (0-234 bytes)	Encrypted payload
(N-15)..(N-2)	tag (16 bytes)	Authentication tag
N-1	checksum A	Header
N	checksum B	Header

S-Pprzlink v2.0

In this case we decrypt only packets with matching DESTINATION (or broadcast), to avoid decrypting unwanted data.

PPRZ-message: ABCxxxxxxxDE
    A PPRZ_STX (0x99)
    B LENGTH (A->E)
    C PPRZ_DATA
      0 SOURCE (~sender_ID)
      1 DESTINATION (can be a broadcast ID)
      2-5 COUNTER (4 bytes)
      // ciphertext start
      6 CLASS/COMPONENT
        bits 0-3: 16 class ID available
        bits 4-7: 16 component ID available
      7 MSG_ID
      8 MSG_PAYLOAD
      . DATA (messages.xml)
      // ciphertext end
      8-19 TAG (12 bytes)
    D PPRZ_CHECKSUM_A (sum[B->C])
    E PPRZ_CHECKSUM_B (sum[ck_a])

XBee API format

XBee-message: ABCDxxxxxxxE
    A XBEE_START (0x7E)
    B LENGTH_MSB (D->D)
    C LENGTH_LSB
    D XBEE_PAYLOAD
      0 XBEE_TX16 (0x01) / XBEE_RX16 (0x81)
      1 FRAME_ID (0)     / SRC_ID_MSB
      2 DEST_ID_MSB      / SRC_ID_LSB
      3 DEST_ID_LSB      / XBEE_RSSI
      4 TX16_OPTIONS (0) / RX16_OPTIONS
      5 PPRZ_DATA
        0 SENDER_ID
        1 MSG_ID
        2 MSG_PAYLOAD
        . DATA (messages.xml)
    E XBEE_CHECKSUM (sum[D->D])

   ID is AC_ID for aircraft, 0x100 for ground station

Telemetry storage format for data logger

TLM-message: ABCDEFGHxxxxxxxI
    A PPRZ_STX (0x99)
    B LENGTH (H->H)
    C SOURCE (0=uart0, 1=uart1, 2=i2c0, ...)
    D TIMESTAMP_LSB (100 microsecond raster)
    E TIMESTAMP
    F TIMESTAMP
    G TIMESTAMP_MSB
    H PPRZ_DATA
      0 SENDER_ID
      1 MSG_ID
      2 MSG_PAYLOAD
      . DATA (messages.xml)
    I CHECKSUM (sum[B->H])