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.

Grab it

Downloads 📦

Continuous builds:

💻 Windows
🍎 MacOS
🐧 Linux
🍓 Raspberry
- ARMv6 binary, ARMv7 is also available under the project releases.

For others or different releases, check the releases menu.

Install ⚡

If you prefer, you can install via cargo, if you don't know what it is, use the download section.

⚙️ Cargo Install: cargo install mavlink2rest

Help

Capabilities via the command line:

USAGE:
    mavlink2rest [FLAGS] [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Be verbose

OPTIONS:
    -c, --connect <TYPE:<IP/SERIAL>:<PORT/BAUDRATE>>
            Sets the mavlink connection string [default: udpin:0.0.0.0:14550]

        --mavlink <VERSION>
            Sets the mavlink version used to communicate [default: 2]

    -s, --server <IP:PORT>
            Sets the IP and port that the rest server will be provided [default: 0.0.0.0:8088]

Endpoints

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/mavlink?name=<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"
    }
}
```
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 and sequence.
- message: A valid mavlink message, for more information check GET /helper/mavlink?name=<MESSAGE_NAME>.
  - Check ARM/DISARM example.

GET /helper/mavlink?name=MAVLINK_MESSAGE_NAME: Helper endpoint to create JSON compatible MAVLink messages, where MAVLINK_MESSAGE_NAME is the mavlink message name. E.g:

http://0.0.0.0:8088//helper/mavlink?name=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
    }
}

Information:

GET /info, provides information about the service version.

http://0.0.0.0:8088/info

{
  "version": 0,
  "service": {
    "name": "mavlink2rest",
    "version": "0.10.0",
    "sha": "bd7667d",
    "build_date": "2021-03-03",
    "authors": "Author <email>"
  }
}

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/mavlink?name=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 allow GET and provides a JSON output, also allow the usage of the query parameter pretty with a boolean value true or false, E.g: http://0.0.0.0:8088/helper/mavlink?name=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

Williangalvani / mavlink2rest