16 releases (9 breaking)
0.10.0 | Nov 6, 2020 |
---|---|
0.8.0 | Jul 4, 2020 |
0.5.0 | Mar 23, 2020 |
0.2.0 | Nov 10, 2019 |
#139 in WebSocket
51 downloads per month
42KB
676 lines
Mavlink2Rest
mavlink2rest
creates a REST server that provides mavlink information from a mavlink source.
The current version supports the ardupilotmega dialect, that includes common, icarous and uavionix.
Install ⚡
- ⚙️ Cargo Install:
cargo install mavlink2rest
Downloads 📦
- 💻 Windows
- 🍎 MacOS
- 🐧 Linux
- 🍓 Raspberry
- ARMv6 binary, ARMv7 is also available under the project releases.
For others or different releases, check the releases menu.
Endpoints
Pages
- Main webpage:
GET /
- Provides information about mavlink2rest and available messages.
API
- MAVLink JSON:
-
GET /mavlink|/mavlink/*
. The output is a JSON that you get each nested key individually, E.g:- http://0.0.0.0:8088/mavlink/ATTITUDE
- http://0.0.0.0:8088/mavlink/ATTITUDE/roll
- http://0.0.0.0:8088/mavlink/ATTITUDE/message_information/time/last_message
- Any MAVLink message will contain a normal message definition, as described in
GET /helper/message/<MESSAGE_NAME>
, and a message_information structure defined as:"message_information": { "counter": 0, // Number of messages received "frequency": 10.0, // Frequency of the received message "time": { // ISO 8601 / RFC 3339 date & time format "first_message": "2020-03-28T12:47:52.315383-03:00", "last_message": "2020-03-28T14:16:21.417836-03:00" } }
- Any MAVLink message will contain a normal message definition, as described in
-
POST /mavlink
. Sends the message to a specific vehicle.- For more information about the MAVLink message definition: https://mavlink.io/en/guide/serialization.html
- header: Is the mavlink header definition with
system_id
,component_id
andsequence
. - message: A valid mavlink message, for more information check
GET /helper/message/<MESSAGE_NAME>
.- Check ARM/DISARM example.
-
GET /helper/message/MAVLINK_MESSAGE_NAME
: Helper endpoint to create JSON compatible MAVLink messages, whereMAVLINK_MESSAGE_NAME
is the mavlink message name. E.g:- http://0.0.0.0:8088/helper/message/COMMAND_LONG
{ "header": { "system_id": 255, "component_id": 0, "sequence": 0 }, "message": { "type": "COMMAND_LONG", "param1": 0.0, "param2": 0.0, "param3": 0.0, "param4": 0.0, "param5": 0.0, "param6": 0.0, "param7": 0.0, "command": { "type": "MAV_CMD_NAV_WAYPOINT" // Random value }, "target_system": 0, "target_component": 0, "confirmation": 0 } }
- http://0.0.0.0:8088/helper/message/COMMAND_LONG
-
Examples
Get all messages:
curl --request GET http://0.0.0.0:8088/mavlink\?pretty\=true
# The output is huge, you can get it here: https://gist.github.com/patrickelectric/26a407c4e7749cdaa58d06b52212cb1e
Get attitude:
curl --request GET http://0.0.0.0:8088/mavlink/ATTITUDE?pretty=true
{
"message_information": {
"counter": 46460,
"frequency": 7.966392517089844,
"time": {
"first_message": "2020-03-28T12:47:52.315383-03:00",
"last_message": "2020-03-28T14:25:04.905914-03:00"
}
},
"pitch": 0.004207547288388014,
"pitchspeed": 0.0010630330070853233,
"roll": 0.004168820567429066,
"rollspeed": 0.0009180732304230332,
"time_boot_ms": 6185568,
"type": "ATTITUDE",
"yaw": -1.5562472343444824,
"yawspeed": 0.0009576341835781932
}
Get time of last ATTITUDE message:
curl --request GET http://0.0.0.0:8088/mavlink/ATTITUDE/message_information/time/last_message?pretty=true
"2020-03-28T14:28:51.577853-03:00"
Get a message structure example:
curl --request GET http://0.0.0.0:8088/helper/message/ATTITUDE\?pretty\=true
{
"header": {
"system_id": 255,
"component_id": 0,
"sequence": 0
},
"message": {
"type": "ATTITUDE",
"time_boot_ms": 0,
"roll": 0.0,
"pitch": 0.0,
"yaw": 0.0,
"rollspeed": 0.0,
"pitchspeed": 0.0,
"yawspeed": 0.0
}
}
Request vehicle to be armed:
# ARM: param1 is 1.0
curl --request POST http://0.0.0.0:8088/mavlink -H "Content-Type: application/json" --data \
'{
"header": {
"system_id": 1,
"component_id": 1,
"sequence": 0
},
"message": {
"type":"COMMAND_LONG",
"param1":1.0,
"param2":0.0,"param3":0.0,"param4":0.0,"param5":0.0,"param6":0.0,"param7":0.0,
"command":{
"type":"MAV_CMD_COMPONENT_ARM_DISARM"
},
"target_system":0,
"target_component":0,
"confirmation":0
}
}'
Request vehicle to be disarmed:
# ARM: param1 is 0.0
curl --request POST http://0.0.0.0:8088/mavlink -H "Content-Type: application/json" --data \
'{
"header": {
"system_id": 1,
"component_id": 1,
"sequence": 0
},
"message": {
"type":"COMMAND_LONG",
"param1":0.0,
"param2":0.0,"param3":0.0,"param4":0.0,"param5":0.0,"param6":0.0,"param7":0.0,
"command":{
"type":"MAV_CMD_COMPONENT_ARM_DISARM"
},
"target_system":0,
"target_component":0,
"confirmation":0
}
}'
Note: For any invalid
GET
, you'll receive a 404 response with the error message. Note: The endpoints that allowGET
and provides a JSON output, also allow the usage of the query parameterpretty
with a boolean valuetrue
orfalse
, E.g: http://0.0.0.0:8088/helper/message/COMMAND_LONG?pretty=true
Websocket
It's also possible to connect multiple websockets with the following path /ws/mavlink
, the endpoint also accepts the query parameter filter
, the filter value should be a regex that matches MAVLink message names, E.g: /ws/mavlink?filter=.*
for all messages, /ws/mavlink?filter=RC_.*
will match RC_CHANNELS_RAW and RC_CHANNELS, resulting in the following output:
{ // First message
"chan10_raw": 0,
"chan11_raw": 0,
"chan12_raw": 0,
"chan13_raw": 0,
"chan14_raw": 0,
"chan15_raw": 0,
"chan16_raw": 0,
"chan17_raw": 0,
"chan18_raw": 0,
"chan1_raw": 1500,
"chan2_raw": 1500,
"chan3_raw": 1500,
"chan4_raw": 1500,
"chan5_raw": 1500,
"chan6_raw": 1500,
"chan7_raw": 1500,
"chan8_raw": 1500,
"chan9_raw": 0,
"chancount": 16,
"message_information": {
"counter": 3732,
"frequency": 4.0,
"time": {
"first_message": "2020-09-01T20:36:24.088099-03:00",
"last_message": "2020-09-01T20:51:57.278901-03:00"
}
},
"rssi": 0,
"time_boot_ms": 3122812,
"type": "RC_CHANNELS"
}
{ // Second message
"chan1_raw": 1500,
"chan2_raw": 1500,
"chan3_raw": 1500,
"chan4_raw": 1500,
"chan5_raw": 1500,
"chan6_raw": 1500,
"chan7_raw": 1500,
"chan8_raw": 1500,
"message_information": {
"counter": 3732,
"frequency": 4.0,
"time": {
"first_message": "2020-09-01T20:36:24.088310-03:00",
"last_message": "2020-09-01T20:51:57.279438-03:00"
}
},
"port": 0,
"rssi": 0,
"time_boot_ms": 3122812,
"type": "RC_CHANNELS_RAW"
}
For a demonstration, please check the example under the examples filder: websocket_client.py
Benchmark
The following benchmarks were extracted from a raspberry pi 3 connected to a pixhawk running ArduSub.
-
In idle.
6% CPU usage
-
1 client requesting all mavlink messages at 10Hz
9% CPU usage
-
1 client requesting all mavlink messages at 100Hz
20% CPU usage (~5% each core)
-
1 websocket with no filters
11% CPU usage
-
5 websockets with no filters
24% CPU usage (14% @ 1 core, ~3% @ 3 cores)
-
20 websockets with filter only for ATTITUDE message (receiving at 10Hz)
9% CPU usage
-
20 websockets with filter only for NAMED_VALUE_FLOAT message (receiving at 70Hz)
17% CPU usage (9% @ 1 core, ~2% @ 3 cores)
-
20 websockets with no filters
48% CPU usage (20% @ 1 core, ~9% @ 3 cores)
-
1 client requesting all mavlink messages 1000 times
60% CPU usage (~15% each core) Time taken for tests 3.7 seconds Total requests 1000 Successful requests 1000 Failed requests 0 Requests per second 273.60 [#/sec] Median time per request 3ms Average time per request 4ms
-
10 clients requesting all mavlink messages, 100 requests for each client.
140% CPU usage (~46% each core) Time taken for tests 1.4 seconds Total requests 1000 Successful requests 1000 Failed requests 0 Requests per second 733.14 [#/sec] Median time per request 13ms Average time per request 13ms Sample standard deviation 3ms
-
100 clients requesting all mavlink messages, 1000 requests for each client.
140% CPU usage (~46% each core) Time taken for tests 13.8 seconds Total requests 10000 Successful requests 10000 Failed requests 0 Requests per second 725.83 [#/sec] Median time per request 132ms Average time per request 137ms Sample standard deviation 54ms
Dependencies
~30MB
~614K SLoC