mavlink2rest is a tool that offers a RESTful API over the MAVLink protocol, facilitating seamless communication between unmanned systems and web applications. The tool supports the ArduPilotMega dialect, iCAROUS, and UAVionix, making it an ideal solution for developers who want to build custom interfaces for unmanned systems.

The current version supports the ardupilotmega dialect, that includes common, icarous and uavionix.

Grab it

Downloads :package:

Latest builds:

• :computer: Windows
• :apple: MacOS
• :penguin: Linux
• :strawberry: Raspberry
  • ARMv6 binary, ARMv7 is also available under the project releases.

For others or different releases, check the releases menu.

Install :zap:

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

• :gear: 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:
      --component-id <COMPONENT_ID>
          Sets the component ID for this service, for more information, check:
          https://mavlink.io/en/messages/common.html#MAV_COMPONENT [default: 0]
  -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]  [possible values: 1, 2]

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

      --system-id <SYSTEM_ID>                Sets system ID for this service. [default: 255]

Using Docker with mavlink2rest

You can also use the mavlink2rest with docker, the following command will start the service with the default settings:

docker run --rm --init -p 8088:8088 -p 14550:14550/udp --name mavlink2rest mavlink/mavlink2rest

The Dockerfile defines several environment variables that you can override at runtime:

MAVLINK_SRC: The MAVLink source connection string. Default is udpin:127.0.0.1:14550. SERVER_PORT: The IP and port for the REST server. Default is 0.0.0.0:8088. EXTRA_ARGS: Any additional command line arguments you want to pass to mavlink2rest. To customize these settings, use the -e flag with docker run:

docker run --rm --init\
    -p 8088:8088 \
    -p 14551:14551/udp \
    -e MAVLINK_SRC="udpin:0.0.0.0:14551" \
    -e SERVER_PORT="0.0.0.0:8088" \
    --name mavlink2rest mavlink/mavlink2rest

to build the docker image locally, you can use the following command:

docker build --build-arg TARGET_ARCH=x86_64-unknown-linux-musl -t mavlink/mavlink2rest .

Endpoints

Pages

• Main webpage: GET /
  • Provides information about mavlink2rest and available messages.
• Swagger: GET /docs
  • Provides information about mavlink2rest endpoints for the REST API.

API

• MAVLink JSON:

  • GET /v1/mavlink|/v1/mavlink/*. The output is a JSON that you get each nested key individually, E.g:

    • http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE
    • http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE/message/roll
    • http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE/status/time/last_update

  • Any MAVLink message will contain a normal message definition, as described in GET /v1/helper/mavlink?name=<MESSAGE_NAME>..

    • http://0.0.0.0:8088/v1/helper/mavlink?name=HEARTBEAT

      {
        "header": {
          "system_id": 255,
          "component_id": 0,
          "sequence": 0
        },
        "message": {
          "type": "HEARTBEAT",
          "custom_mode": 0,
          "mavtype": {
            "type": "MAV_TYPE_GENERIC"
          },
          "autopilot": {
            "type": "MAV_AUTOPILOT_GENERIC"
          },
          "base_mode": "MAV_MODE_FLAG_SAFETY_ARMED",
          "system_status": {
            "type": "MAV_STATE_UNINIT"
          },
          "mavlink_version": 3
        }
      }
      

      :sunglasses: This is really handy when creating messages.

  • ... and a status structure defined as:

    "status": {
      "time": {
        "counter": 2981,
        "first_update": "2024-05-31T11:59:44.313941926-03:00",
        "frequency": 10.037036895751953,
        "last_update": "2024-05-31T12:04:42.214212884-03:00"
      }
    }
    

  • POST /v1/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 /v1/helper/mavlink?name=<MESSAGE_NAME>.
      • Check ARM/DISARM example.

  • GET /v1/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/v1/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/v1/mavlink
# The output is huge, you can get it here: [https://gist.github.com/patrickelectric/26a407c4e7749cdaa58d06b52212cb1e](https://gist.github.com/patrickelectric/26a407c4e7749cdaa58d06b52212cb1e)

Get attitude:

curl --request GET http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE

{
  "message": {
    "pitch": 0.11506611853837967,
    "pitchspeed": 0.00003909762017428875,
    "roll": 0.02339238114655018,
    "rollspeed": 0.00035849903360940516,
    "time_boot_ms": 87110407,
    "type": "ATTITUDE",
    "yaw": -2.4364013671875,
    "yawspeed": 0.000020137056708335876
  },
  "status": {
    "time": {
      "counter": 22750,
      "first_update": "2024-05-31T11:59:44.313941926-03:00",
      "frequency": 5.495169162750244,
      "last_update": "2024-05-31T13:08:45.196118069-03:00"
    }
  }
}

Get time of last ATTITUDE message:

curl --request GET http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE/status/time/last_update

"2026-03-29T07:14:29.700718126-03:00"

Get a message structure example:

curl --request GET "http://0.0.0.0:8088/v1/helper/mavlink?name=ATTITUDE"

{
  "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/v1/mavlink -H "Content-Type: application/json" --data \
'{
  "header": {
    "system_id": 255,
    "component_id": 240,
    "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": {