Communication protocol
Embedded into raw protocol. Used to send single messages to drone or ground station. Used to change settings. Implemented into communication module.
- 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)
JSON | CRC32 |
UTF-8 | 4 bytes |
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" ]
}
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"
]
}
}
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"]
}
}
{
"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"
}
}
}
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"
}
}
}
On successful settings change.
{ "destination": 4,
"type": "settingssuccess",
"origin": "drone",
"id": 4321
}
{ "destination": 1,
"type": "system_ident_req",
"id": 4321
}
{ "destination": 4,
"type": "system_ident_rsp",
"origin": "groundstation",
"HID": 0,
"FID": "1.6.1",
"id": 4321
}
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
}
{ "destination": 2,
"type": "pingrequest",
"id": 4321
}
{ "destination": 4,
"type": "pingresponse",
"origin": "drone",
"id": 4321
}
{ "destination": 4,
"type": "error",
"origin": "groundstation",
"message": "Some kind of error message",
"id": 4321
}
Universal acknowledgement message. May be returned by any kind of request/change message.
{ "destination": 4,
"type": "ack",
"id": 4321
}
JSON Key | Description | Possible values |
destination | What device is supposed to process the message |
|
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 |
|
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 |
|
FID | Firmware version | Software version number of the release |
CRC32 of the entire JSON as implemented by the Python package
binasciibinascii.crc32('my payload JSON')
Settings request & response between app, ground station & UAS
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.
Last modified 3yr ago