Communication protocol

What can it do?
Request settings and configuration of drone, ground station and camera
Change settings for all kinds of applications
Request & send firmware/hardware version
Easily to be extended to send any command to ground station or drone. Like shell commands
The communication protocol is implemented by the communication module. It is designed to send single messages that do not need high update rates. That way it is not necessary to map an RC channel to the desired function. RC switches are updated about 60 times/second and thus create a lot of interference.
This protocol is based on JSON which can be transported using the DroneBridge Raw protocol (Groundstation <--> Drone) or any standard network protocol like UDP/TCP (wifi mode or USB tethering)
Structure
 JSON
CRC32
 UTF-8
4 bytes
Defined Messages
Parameter Request
Request all possible settings parameters that can be changed via a settings request. This does not request the parameter values.
{ "destination": 1, 
  "type": "settingsparamreq",
  "request": "db",
  "id": 1234,
  "parameters": [ "COMMON", "GROUND", "AIR" ]
}
Parameter Response
Return all settings parameters within the requested sections.
​
{ "destination": 4,
  "type": "settingsparamres",
  "response": "db",
  "origin": "drone",
  "id": 1234,
  "parameters": {
    "COMMON": [
      "parameter_name1",
      "parameter_name2"
    ],
    "GROUND": [
      "parameter_name1",
      "parameter_name2"]
      ,
    "AIR": [
      "parameter_name1",
      "parameter_name2"
    ]
  }
}
Settings Request
 Request of specific sections and keys of the config file. Destination can be 1, 2, 5
{ "destination": 1, 
  "type": "settingsrequest",
  "request": "db",
  "id": 1234,
  "settings": {
    "COMMON": ["communication_id", "rc_proto"],
    "GROUND": ["datarate", "en_control", "wifi_ap_if"],
    "AIR": ["datarate", "keyframerate"]
  }
}
Settings Response
{
  "destination": 4,
  "type": "settingsresponse",
  "response": "db",
  "origin": "drone",
  "id": 1234,
  "settings": {
    "COMMON": {
      "name1": "value1",
      "name2": "value2"
    },
    "GROUND": {
      "name3": "value3",
      "name4": "value4"
    },
    "AIR": {
      "name5": "value5",
      "name6": "value6"
    }
  }
}
Settings Change Request
 Change specific settings of the specified sections. Destination can be 1, 2 or 5
{
  "destination": 2,
  "type": "settingschange",
  "change": "db",
  "id": 4321,
  "settings": {
    "COMMON": {
      "freq": "2472",
      "communication_id": "202"
    },
    "GROUND": {
      "joy_interface": "0",
      "wifi_ap_if": "internal"
    },
    "AIR": {
      "en_plugin": "Y",
      "video_bitrate": "auto"
    }
  }
}
Settings Change Success Message
On successful settings change.
{ "destination": 4, 
  "type": "settingssuccess",
  "origin": "drone",
  "id": 4321
}
System Identification Request
{ "destination": 1, 
  "type": "system_ident_req",
  "id": 4321
}
System Identification Response
{ "destination": 4,
  "type": "system_ident_rsp",
  "origin": "groundstation",
  "HID": 0,
  "FID": "1.6.1",
  "id": 4321
}
"Calibrate" RC/Joystick
This is no real calibration. "jscal" is told to use the full range for each axis provided by the HID (eg -127 to 127). By default the system may only use values from -125 to 125 and adds a dead zone. As the user needs to calibrate his RC locally it is not necessary to do it all over again on the ground station. We just make sure the fully range is used.
{ "destination": 1,
  "type": "adjustrc",
  "device": "/dev/input/js0",
  "id": 4321
}
Ping Request
{ "destination": 2, 
  "type": "pingrequest",
  "id": 4321
}
Ping Response
{ "destination": 4, 
  "type": "pingresponse",
  "origin": "drone",
  "id": 4321
}
Error Response
{ "destination": 4, 
  "type": "error",
  "origin": "groundstation",
  "message": "Some kind of error message",
  "id": 4321
}
ACK Response
Universal acknowledgement message. May be returned by any kind of request/change message.
{ "destination": 4, 
  "type": "ack",
  "id": 4321
}
Fields
JSON Key
Description
Possible values
 destination
What device is supposed to process the message
1: ground station only
2: ground station & UAV
3: GoPro
4: App/GCS
5: UAV only
 request
 What application settings are requested?
db: DroneBridge
 response
 What application settings are included
​
db: DroneBridge
 id
Random 4 digit ID to identify request and response
0000-9999
 origin
The origin/sender of the message
drone
ground station
 change
What application settings shall be changed
​
db: DroneBridge
 settings
JSON Object with all settings inside. Same keys as inside config file
​
 HID
 Hardware ID
0: DroneBridge for RPi, 
1: DroneBridge for ESP32 (WiFi mode)
 FID
 Firmware version
Software version number of the release
CRC32
 CRC32 of the entire JSON as implemented by the Python package binascii
 binascii.crc32('my payload JSON')
Sequence Diagramms
Settings request & response between app, ground station & UAS
Adding a custom message to the communication module
The communication module can transport messages of all kind. If a known message is received it does something. What it does is totally up to the users implementation. Often a user wants to send some sort of trigger to the UAV or ground station. Back in the days it was common to use one of the RC channels to trigger all sorts of actions. This is not very efficient since the RC sends all channels about 100 times/second even if you do not need that high update rates for your action. A simple camera ON/OFF switch would be an example.
 So let's say you want to change some setting of a camera connected to your AirPi. To do that you need to execute a command like mycam -- shuterspeed 500 on the AirPi. What you do to implement this into DroneBridge is the following:
1.Define a custom message that follows the specification of the communication protocol. Just like the new adjustrc message. You can put as many parameters in there as you need. Your message could look like this: 
{ "destination": 5,
  "type": "mycamshutter",
  "speed": 500,
  "id": 4321
}
The parameters destination, type and id are mandatory.
2.Make the communication module aware of the new message & write the code that should be executed. Add an if-clause that runs if your defined message-type is received​
3.Generate a return message to let the user know your message was received. Eg. it is as simple as calling rtrn_message = new_ack_message()​
That's it! Now just send your newly defined message via UDP to the communication module and let it do the rest. Here is an example on how to generate the entire communication message including the CRC32 at the end from a json. This will return the pure bytes of the message that now can be sent to the communication module (UDP: Port 1605) of the ground station.
With just a few lines of code, a user can implement any custom functionality with ease. No need to waste or flood the carrier with RC channels. No need to generate huge amounts of traffic.

Developer Guide - Previous

Raw protocol

Next - Developer Guide

Status messages

Last modified 2yr ago

Copy link

On this page

What can it do?

Structure

Defined Messages

Parameter Request

Parameter Response

Settings Request

Settings Response

Settings Change Request

Settings Change Success Message

System Identification Request

System Identification Response

"Calibrate" RC/Joystick

Ping Request

Ping Response

Error Response

ACK Response

Fields

CRC32

Sequence Diagramms

Adding a custom message to the communication module