### Install and Run mavlink2rest

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Install the service using Cargo and run it with different connection and server configurations. Examples include UDP, serial, and TCP connections.

```bash
cargo install mavlink2rest
```

```bash
# Run: listen for MAVLink on UDP 14550, serve REST on port 8088
mavlink2rest --connect udpin:0.0.0.0:14550 --server 0.0.0.0:8088 --mavlink 2
```

```bash
# Serial connection example (57600 baud)
mavlink2rest --connect serial:/dev/ttyUSB0:57600 --server 0.0.0.0:8088
```

```bash
# TCP client example
mavlink2rest --connect tcpout:192.168.1.10:5760 --server 0.0.0.0:8088
```

```bash
# Docker (default UDP 14550 → REST 8088)
docker run --rm --init -p 8088:8088 -p 14550:14550/udp --name mavlink2rest mavlink/mavlink2rest
```

```bash
# Docker with custom source port and PX4 initial heartbeat burst
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" \
  -e EXTRA_ARGS="--send-initial-heartbeats" \
  --name mavlink2rest mavlink/mavlink2rest
```

```bash
# Build Docker image locally for x86_64
docker build --build-arg TARGET_ARCH=x86_64-unknown-linux-musl -t mavlink/mavlink2rest .
```

--------------------------------

### Get ATTITUDE message structure example (JSON)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

The example JSON structure for an ATTITUDE message, showing all fields and their default values.

```json
{
    "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
    }
  }
```

--------------------------------

### Install mavlink2rest via Cargo

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Use this command to install the mavlink2rest tool if you have Cargo installed. Ensure you have Rust and Cargo set up.

```bash
cargo install mavlink2rest
```

--------------------------------

### Get COMMAND_LONG message structure example

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Use the helper endpoint to generate a JSON structure for MAVLink messages, which can then be populated and sent.

```json
{
    "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
    }
}
```

--------------------------------

### GET /info — Service Version

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Retrieve build metadata and the REST API version number for the mavlink2rest service.

```bash
curl http://0.0.0.0:8088/info
```

```json
# Expected output:
# {
#   "version": 0,
#   "service": {
#     "name": "mavlink2rest",
#     "version": "1.0.2",
#     "sha": "bd7667d",
#     "build_date": "2024-05-31T00:00:00Z",
#     "authors": "Patrick José Pereira <patrickelectric@gmail.com>"
#   }
# }
```

--------------------------------

### Get ATTITUDE message structure example (curl)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Fetches a template JSON structure for the ATTITUDE MAVLink message, useful for understanding its fields.

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

--------------------------------

### Example WebSocket MAVLink Messages

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Demonstrates the structure of MAVLink messages received over a WebSocket connection, including `RC_CHANNELS` and `RC_CHANNELS_RAW`.

```json
{
  "header": {
    "component_id": 1,
    "sequence": 98,
    "system_id": 1
  },
  "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"
  }
}
{
  "header": {
    "component_id": 1,
    "sequence": 98,
    "system_id": 1
  },
  "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"
  }
}
```

--------------------------------

### Get ATTITUDE message status example

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

This snippet shows the status structure for a MAVLink message, including timing and frequency information.

```json
"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"
  }
}
```

--------------------------------

### Get HEARTBEAT message structure example

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Use this endpoint to get a JSON structure for a specific MAVLink message, useful for message creation.

```json
{
  "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
  }
}
```

--------------------------------

### GET /info — Service Version

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Retrieves build metadata and the REST API version number of the mavlink2rest service.

```APIDOC
## GET /info — Service Version

### Description
Returns build metadata and REST API version number.

### Method
GET

### Endpoint
/info

### Response
#### Success Response (200)
- **version** (integer) - The API version number.
- **service** (object) - Information about the service.
  - **name** (string) - The name of the service.
  - **version** (string) - The version of the service.
  - **sha** (string) - The git commit SHA of the build.
  - **build_date** (string) - The date and time the service was built.
  - **authors** (string) - The author(s) of the service.

### Request Example
```bash
curl http://0.0.0.0:8088/info
```

### Response Example
```json
{
  "version": 0,
  "service": {
    "name": "mavlink2rest",
    "version": "1.0.2",
    "sha": "bd7667d",
    "build_date": "2024-05-31T00:00:00Z",
    "authors": "Patrick José Pereira <patrickelectric@gmail.com>"
  }
}
```
```

--------------------------------

### Run mavlink2rest with Docker (Default Settings)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

This command starts the mavlink2rest service using Docker with default network and server configurations. It maps the necessary ports for MAVLink and REST communication.

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

--------------------------------

### Get service information (JSON)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

The JSON response containing version, name, SHA, build date, and authors of the mavlink2rest service.

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

--------------------------------

### Get service information (curl)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Retrieves metadata about the mavlink2rest service, including its version and build details.

```sh
curl --request GET http://0.0.0.0:8088/info
```

--------------------------------

### Get all MAVLink messages (curl)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

This command retrieves all MAVLink messages. The output can be very large; a link to a gist is provided for convenience.

```sh
curl --request GET http://0.0.0.0:8088/v1/mavlink
```

--------------------------------

### Get time of last ATTITUDE message (JSON)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

The direct output for the last update time of an ATTITUDE message.

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

--------------------------------

### GET /v1/mavlink — Retrieve All Received Messages

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Retrieves the entire in-memory message store as a nested JSON tree.

```APIDOC
## GET /v1/mavlink — Retrieve All Received Messages

### Description
Returns the entire in-memory message store as a nested JSON tree indexed by `vehicles → system_id → components → component_id → messages → MESSAGE_NAME`.

### Method
GET

### Endpoint
/v1/mavlink

### Parameters
#### Path Parameters
- **system_id** (integer) - Required - The system ID of the vehicle.
- **component_id** (integer) - Required - The component ID of the vehicle.
- **MESSAGE_NAME** (string) - Required - The name of the MAVLink message to retrieve.

### Request Example
```bash
# Dump all received messages (can be large)
curl http://0.0.0.0:8088/v1/mavlink

# Navigate to a specific vehicle's component message list
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages

# Retrieve a single message with its status block
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE

# Drill into a single field value
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE/message/roll
```

### Response
#### Success Response (200)
- **message** (object) - The MAVLink message payload.
  - **type** (string) - The type of the MAVLink message.
  - **time_boot_ms** (integer) - Timestamp in milliseconds since system boot.
  - **roll** (number) - Roll angle in radians.
  - **pitch** (number) - Pitch angle in radians.
  - **yaw** (number) - Yaw angle in radians.
  - **rollspeed** (number) - Roll angular speed in radians per second.
  - **pitchspeed** (number) - Pitch angular speed in radians per second.
  - **yawspeed** (number) - Yaw angular speed in radians per second.
- **status** (object) - Status information about the message reception.
  - **time** (object) - Time-related statistics.
    - **counter** (integer) - Number of times this message has been received.
    - **first_update** (string) - Timestamp of the first reception.
    - **last_update** (string) - Timestamp of the last reception.
    - **frequency** (number) - Average reception frequency in Hz.

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

--------------------------------

### Get ATTITUDE message data (JSON)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

The JSON output for the ATTITUDE message includes detailed flight data and status information.

```json
{
  "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"
    }
  }
}
```

--------------------------------

### Send MAVLink Command: Set Flight Mode

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Sends a COMMAND_LONG message to set the vehicle's flight mode. This example demonstrates setting the mode to STABILIZE using MAV_CMD_DO_SET_MODE.

```bash
curl -X 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": 0.0, \
      "param2": 0.0, "param3": 0.0, "param4": 0.0, \
      "param5": 0.0, "param6": 0.0, "param7": 0.0, \
      "command": { "type": "MAV_CMD_DO_SET_MODE" }, \
      "target_system": 1, "target_component": 1, "confirmation": 0 \
    } \
  }'
```

--------------------------------

### Python WebSocket Client for MAVLink

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

An asynchronous Python client using aiohttp to connect to the MAVLink WebSocket endpoint. It can stream messages with optional filtering and handles connection errors. This script requires the aiohttp library to be installed.

```python
# Python async WebSocket client (requires aiohttp)
import asyncio
import aiohttp

async def stream_mavlink(url: str, msg_filter: str = ".*") -> None:
    async with aiohttp.ClientSession() as session:
        ws = await session.ws_connect(
            f"{url}/v1/ws/mavlink?filter={msg_filter}",
            autoclose=False, autoping=False
        )
        async for msg in ws:
            if msg.type == aiohttp.WSMsgType.TEXT:
                print(msg.data.strip())
            elif msg.type == aiohttp.WSMsgType.ERROR:
                print(f"Error: {ws.exception()}")
                break
            elif msg.type in (aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSED):
                await ws.close()
                break

# Stream only ATTITUDE messages
asyncio.run(stream_mavlink("http://0.0.0.0:8088", msg_filter="ATTITUDE"))

# CLI usage of bundled example client
python examples/websocket_client.py --url http://0.0.0.0:8088 --filter "ATTITUDE"
python examples/websocket_client.py --url http://blueos.local:6040 --filter "RC_.*"
```

--------------------------------

### Get ATTITUDE message data (curl)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Retrieves the ATTITUDE message data for a specific vehicle and component. Requires the vehicle ID and component ID.

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

--------------------------------

### Stream Filtered MAVLink Messages via WebSocket

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Opens a WebSocket connection to stream only RC channel-related MAVLink messages. The `filter=RC_.*` regex limits the stream to messages starting with 'RC_'.

```bash
websocat "ws://0.0.0.0:8088/v1/ws/mavlink?filter=RC_.*"
```

--------------------------------

### GET /v1/mavlink — Retrieve All Received Messages

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Access the in-memory MAVLink message store via a nested JSON tree. Supports navigating to specific vehicles, components, messages, or individual field values.

```bash
# Dump all received messages (can be large)
curl http://0.0.0.0:8088/v1/mavlink
```

```bash
# Navigate to a specific vehicle's component message list
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages
```

```bash
# Retrieve a single message with its status block
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE
```

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

```bash
# Drill into a single field value
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE/message/roll
```

```json
# 0.02339238114655018
```

--------------------------------

### Access Web UI and API Documentation

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Instructions for accessing the mavlink2rest web interface, interactive Swagger UI, raw OpenAPI JSON specification, and an LLM-friendly API description using curl and open commands.

```bash
# Open the built-in web dashboard in a browser
open http://0.0.0.0:8088/

# Open interactive Swagger UI
open http://0.0.0.0:8088/docs

# Fetch the raw OpenAPI JSON spec
curl http://0.0.0.0:8088/docs.json

# LLM-friendly plain-text API description
curl http://0.0.0.0:8088/v1/llm
```

--------------------------------

### Mavlink2rest Command Line Help

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Displays the available command-line options and flags for configuring mavlink2rest. This includes settings for MAVLink connection, component ID, MAVLink version, and the REST server address.

```text
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]
```

--------------------------------

### Initialize Vue App and Fetch Data

Source: https://github.com/mavlink/mavlink2rest/blob/master/src/html/index.html

This snippet initializes a Vue.js application, fetches service information, and sets up a recurring data request. It binds 'this' context for callbacks.

```javascript
/*global Vue*/
const app = Vue.createApp({
  mounted() {
    this.requestData()
    fetch('info').then( function (response) {
      response.json().then((info) => this.info = info)
    }.bind(this),
    )
  },
  methods: {
    sort_dict (dict) {
      return Object.keys(dict).sort().reduce((tempDict, key) => (tempDict[key] = dict[key], tempDict), {});
    },
    formatAuthors (authors) {
      const formatted = authors.split(':').map((author) => {
        console.log(`author: ${author}`)
        const { groups: { name }, } = /(?<name>.*) <.*>/gm.exec(author)
        return name
      })
      return formatted.join(', ')
    },
    formatLastTime (lastMessage) {
      return ((Date.now() - Date.parse(lastMessage)) / 1000).toFixed(3)
    },
    async requestData () {
      setTimeout( function () {
        fetch('v1/mavlink').then( function (response) {
          response.json().then((data) => this.data = data)
        }.bind(this),
        )
        this.requestData()
      }.bind(this),
      500,
      )
    },
  },
  data() {
    return {
      data: undefined,
      info: undefined,
    }
  },
})

app.mount('#app')
```

--------------------------------

### Build mavlink2rest Docker Image Locally

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Use this command to build the Docker image for mavlink2rest locally. Specify the target architecture if needed.

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

--------------------------------

### Run mavlink2rest with Docker (Custom Settings)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

This command demonstrates how to run mavlink2rest with Docker while customizing MAVLink source and REST server ports using environment variables. It also maps the new MAVLink port.

```sh
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
```

--------------------------------

### CPU Usage: 1 Client, 100Hz

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage with one client requesting all mavlink messages at 100Hz. Note the increased usage per core.

```text
20% CPU usage (~5% each core)
```

--------------------------------

### CPU Usage: 1 Client, 10Hz

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage with one client requesting all mavlink messages at 10Hz.

```text
9% CPU usage
```

--------------------------------

### Get time of last ATTITUDE message (curl)

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

This command specifically retrieves the timestamp of the last received ATTITUDE message.

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

--------------------------------

### mavlink2rest CLI Flags Reference

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Reference for command-line flags to control runtime behavior, including connection types, MAVLink version, server addresses, and debug logging.

```bash
# Full flag reference
mavlink2rest --help
```

```bash
# USAGE:
#   mavlink2rest [FLAGS] [OPTIONS]
#
# FLAGS:
#   -h, --help                    Prints help information
#   -V, --version                 Prints version information
#   -v, --verbose                 Enable debug logging
#       --send-initial-heartbeats Burst 5 heartbeats at startup (required for PX4)
#
# OPTIONS:
#   -c, --connect <TYPE:<IP/SERIAL>:<PORT/BAUDRATE>>
#                                 MAVLink connection string [default: udpin:0.0.0.0:14550]
#       --mavlink <VERSION>       MAVLink wire version: 1 or 2 [default: 2]
#   -s, --server <IP:PORT>        REST server bind address [default: 0.0.0.0:8088]
#       --system-id <SYSTEM_ID>   This service's MAVLink system ID [default: 255]
#       --component-id <ID>       This service's MAVLink component ID [default: 0]
```

```bash
# Practical examples
mavlink2rest -v --connect udpin:0.0.0.0:14550 --server 127.0.0.1:8088 --mavlink 2 --system-id 255 --component-id 240
```

```bash
mavlink2rest --connect udpin:0.0.0.0:14550 --send-initial-heartbeats  # PX4 wake-up
```

--------------------------------

### CPU Usage: 20 WebSockets, No Filters

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage with 20 websocket connections and no message filtering. Demonstrates significant load distribution.

```text
48% CPU usage (20% @ 1 core, ~9% @ 3 cores)
```

--------------------------------

### Get MAVLink Data

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Retrieve MAVLink data in JSON format. This endpoint allows access to individual nested keys of MAVLink messages and their status.

```APIDOC
## GET /v1/mavlink

### Description
Retrieves all MAVLink data. The output is a large JSON object containing all available MAVLink messages and their details.

### Endpoint
`/v1/mavlink`

### Example
```sh
curl --request GET http://0.0.0.0:8088/v1/mavlink
```

## GET /v1/mavlink/vehicles/{vehicle_id}/components/{component_id}/messages/{message_name}

### Description
Retrieves a specific MAVLink message for a given vehicle and component.

### Endpoint
`/v1/mavlink/vehicles/{vehicle_id}/components/{component_id}/messages/{message_name}`

### Parameters
#### Path Parameters
- **vehicle_id** (integer) - Required - The ID of the vehicle.
- **component_id** (integer) - Required - The ID of the component.
- **message_name** (string) - Required - The name of the MAVLink message (e.g., ATTITUDE).

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

## GET /v1/mavlink/vehicles/{vehicle_id}/components/{component_id}/messages/{message_name}/status/time/last_update

### Description
Retrieves the timestamp of the last update for a specific MAVLink message.

### Endpoint
`/v1/mavlink/vehicles/{vehicle_id}/components/{component_id}/messages/{message_name}/status/time/last_update`

### Parameters
#### Path Parameters
- **vehicle_id** (integer) - Required - The ID of the vehicle.
- **component_id** (integer) - Required - The ID of the component.
- **message_name** (string) - Required - The name of the MAVLink message (e.g., ATTITUDE).

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

--------------------------------

### Retrieve Last Update Timestamp

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Use this endpoint to get the last update timestamp for a specific MAVLink message. Ensure the vehicle, component, and message names are correct.

```bash
curl http://0.0.0.0:8088/v1/mavlink/vehicles/1/components/1/messages/ATTITUDE/status/time/last_update
```

--------------------------------

### Performance Test: 10 Clients, 100 Requests Each

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Performance metrics for 10 clients, each making 100 requests for all mavlink messages. Shows increased throughput and latency.

```text
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
```

--------------------------------

### Performance Test: 100 Clients, 1000 Requests Each

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Performance metrics for 100 clients, each making 1000 requests for all mavlink messages. Highlights high throughput and increased latency/deviation.

```text
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
```

--------------------------------

### CPU Usage: Idle

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage when the system is idle.

```text
6% CPU usage
```

--------------------------------

### Compile rust-mavlink with Features

Source: https://github.com/mavlink/mavlink2rest/blob/master/HOWTO-change-mavlink-msg.md

Compile the rust-mavlink library locally, enabling specific features like 'ardupilotmega' and 'emit-extensions' to support custom message sets.

```sh
cargo install --path . --features="ardupilotmega emit-extensions"
```

--------------------------------

### CPU Usage: 20 WebSockets, NAMED_VALUE_FLOAT Filter, 70Hz

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage with 20 websockets, filtering for NAMED_VALUE_FLOAT messages, and receiving at 70Hz. Shows load distribution.

```text
17% CPU usage (9% @ 1 core, ~2% @ 3 cores)
```

--------------------------------

### CPU Usage: 5 WebSockets, No Filters

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage with five websocket connections and no message filtering. Shows distributed load across cores.

```text
24% CPU usage (14% @ 1 core, ~3% @ 3 cores)
```

--------------------------------

### Performance Test: 1 Client, 1000 Requests

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Performance metrics for a single client making 1000 requests for all mavlink messages. Includes detailed request statistics.

```text
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
```

--------------------------------

### JavaScript WebSocket Connection and Message Handling

Source: https://github.com/mavlink/mavlink2rest/blob/master/src/html/watcher.html

This snippet sets up a WebSocket connection to the Mavlink2Rest API. It parses URL parameters to filter messages and defines handlers for connection events and incoming data. Use this to stream and process Mavlink data in real-time.

```javascript
const path = window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/'))
const WSAPI = `ws://${window.location.host}${path}`

const app = Vue.createApp({
  mounted() {
    const parameters = new URLSearchParams(location.search);
    this.path = parameters.get("path") ?? ''
    this.connectWebsocket()
  },
  methods: {
    connectWebsocket() {
      this.socket = new WebSocket(`${WSAPI}/v1/ws/mavlink");

      const path = this.path.split('/')
      path.shift() // Remove mavlink string
      path.shift() // Remove vehicle string
      let vehicleId = path.shift()
      vehicleId = vehicleId ? parseInt(vehicleId) : undefined
      path.shift() // Remove components string
      let componentId = path.shift()
      componentId = componentId ? parseInt(componentId) : undefined
      path.shift() // Remove messages string
      this.messageName = path.shift()

      if (this.messageName) {
        this.socket.onopen = (e) => {
          console.log("\n[open] Websocket connection established");
          fetch(this.path)
            .then((response) => {
              if (!response.ok) {
                console.error(`HTTP error ${response.status}`);
              }
              response.json()
                .then((data) => {
                  delete data.status
                  this.setMessage(data.message)
                })
                .catch((error) => {
                  console.error('Error transforming data to json:', error);
                });
            })
            .catch((error) => {
              console.error('Error fetching data:', error);
            });
        };
      }

      this.socket.onmessage = (event) => {
        let jsonData = JSON.parse(event.data);

        if (vehicleId !== undefined && jsonData.header.system_id !== vehicleId) {
          return
        }
        if (componentId !== undefined && jsonData.header.component_id !== componentId) {
          return
        }
        if (this.messageName !== undefined && jsonData.message.type !== this.messageName) {
          return
        }

        jsonData = path.reduce((a, b)=> a[b], jsonData)

        if (typeof jsonData === 'object' && ('header' in jsonData && 'message' in jsonData)) {
          this.setMessage(jsonData.message)
        } else {
          this.setMessage(jsonData)
        }
        this.time = new Date()
      };

      this.socket.onclose = (event) => {
        if (event.wasClean) {
          console.log(
            `\n[close] Websocket connection closed cleanly, code=${event.code} reason=${event.reason}`
          );
        } else {
          // e.g. server process killed or network down
          // event.code is usually 1006 in this case
          console.log("\n[close] Websocket connection died");
        }
        setTimeout(this.connectWebsocket, 4000);
      };

      this.socket.onerror = (error) => {
        console.log(`\n[error] Websocket error: ${error.message}`);
      };
    },
    setMessage(jsonData) {
      const jsonString = JSON.stringify(jsonData, null, 2);
      const jsonCode = document.getElementById("json-data");
      jsonCode.innerHTML = jsonString;
      hljs.highlightBlock(jsonCode);
    }
  },
  data() {
    return {
      messageName: '',
      path: '',
      socket: undefined,
      time: new Date()
    };
  },
});

app.mount("#app");
```

--------------------------------

### Checkout rust-mavlink Version

Source: https://github.com/mavlink/mavlink2rest/blob/master/HOWTO-change-mavlink-msg.md

Navigate into the rust-mavlink directory and checkout a specific version. This is crucial for aligning with the version specified in mavlink2rest's Cargo.toml.

```sh
cd rust-mavlink/
git checkout 0.10.2
```

--------------------------------

### Clone rust-mavlink Repository

Source: https://github.com/mavlink/mavlink2rest/blob/master/HOWTO-change-mavlink-msg.md

Clone the rust-mavlink repository, ensuring submodules are also fetched.

```sh
git clone git@github.com:mavlink/rust-mavlink.git --recursive
```

--------------------------------

### Send MAVLink Commands via WebSocket

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Demonstrates sending a MAVLink COMMAND_LONG message (e.g., ARM command) over a WebSocket connection using Python and aiohttp. The script connects to the endpoint, sends the command as a JSON string, and prints the acknowledgement.

```python
import asyncio
import json
import aiohttp

ARM_MESSAGE = {
    "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": {"type": "MAV_CMD_COMPONENT_ARM_DISARM"},
        "target_system": 1, "target_component": 1, "confirmation": 1
    }
}

async def send_via_websocket():
    async with aiohttp.ClientSession() as session:
        ws = await session.ws_connect(
            "ws://0.0.0.0:8088/v1/ws/mavlink?filter=.*",
            autoclose=False, autoping=False
        )
        # Send ARM command through the WebSocket
        await ws.send_str(json.dumps(ARM_MESSAGE))
        # Read the result acknowledgement
        reply = await ws.receive()
        print("Send result:", reply.data)
        await ws.close()

asyncio.run(send_via_websocket())
```

--------------------------------

### Stream All MAVLink Messages via WebSocket

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Opens a WebSocket connection to stream all incoming MAVLink messages in real time. The `filter=.*` regex ensures all messages are captured.

```bash
websocat "ws://0.0.0.0:8088/v1/ws/mavlink?filter=.*"
```

--------------------------------

### Compile mavlink2rest

Source: https://github.com/mavlink/mavlink2rest/blob/master/HOWTO-change-mavlink-msg.md

Compile the mavlink2rest project after updating its dependency on the local rust-mavlink library.

```sh
cargo install --path .
```

--------------------------------

### Clone mavlink2rest Repository

Source: https://github.com/mavlink/mavlink2rest/blob/master/HOWTO-change-mavlink-msg.md

Clone the mavlink2rest repository, ensuring submodules are also fetched.

```sh
git clone https://github.com/khancyr/mavlink2rest --recursive
```

--------------------------------

### CPU Usage: 1 WebSocket, No Filters

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

CPU usage with a single websocket connection and no message filtering.

```text
11% CPU usage
```

--------------------------------

### Service Information

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Provides information about the mavlink2rest service, including its version and build details.

```APIDOC
## GET /info

### Description
Retrieves information about the mavlink2rest service, such as its version, build date, and author.

### Endpoint
`/info`

### Example
```sh
curl --request GET http://0.0.0.0:8088/info
```

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

--------------------------------

### Update MAVLink Message Set (Custom Dialects)

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Steps to update the MAVLink message set by cloning, modifying message definitions in `rust-mavlink`, compiling it with custom features, and then configuring `mavlink2rest` to use the local `rust-mavlink` path.

```bash
# 1. Clone rust-mavlink with submodules
git clone git@github.com:mavlink/rust-mavlink.git --recursive
cd rust-mavlink
git checkout 0.10.2   # match version in mavlink2rest Cargo.toml

# 2. Edit message definitions
vim mavlink/message_definitions/v1.0/ardupilotmega.xml

# 3. Compile rust-mavlink with the target dialect
cargo install --path . --features="ardupilotmega emit-extensions"

# 4. Clone mavlink2rest and point Cargo.toml to local rust-mavlink
git clone https://github.com/mavlink/mavlink2rest --recursive
cd mavlink2rest
```

```toml
# In mavlink2rest/Cargo.toml – replace the registry dependency:
# Before:
mavlink = { version = "0.16.1", features = ["ardupilotmega", "emit-extensions"] }
# After:
mavlink = { path = "/path/to/rust-mavlink", features = ["ardupilotmega", "emit-extensions"] }
```

```bash
# 5. Build mavlink2rest with the updated message set
cargo install --path .
```

--------------------------------

### Arm Vehicle using REST API

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

Send a COMMAND_LONG message to arm the vehicle. Ensure `param1` is set to 1.0 for arming.

```sh
# 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": { \
      "type": "MAV_CMD_COMPONENT_ARM_DISARM" \
    }, \
    "target_system": 1, \
    "target_component": 1, \
    "confirmation": 1 \
  } \
}'
```

--------------------------------

### Helper Endpoint for MAVLink Messages

Source: https://github.com/mavlink/mavlink2rest/blob/master/README.md

A helper endpoint to generate JSON structures for MAVLink messages, useful for creating messages to be sent via the API.

```APIDOC
## GET /v1/helper/mavlink?name=<MESSAGE_NAME>

### Description
This endpoint generates a JSON structure for a specified MAVLink message name. It's useful for understanding the expected format and for creating message payloads.

### Endpoint
`/v1/helper/mavlink`

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the MAVLink message (e.g., HEARTBEAT, ATTITUDE, COMMAND_LONG).

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

### Response Example
```json
{
  "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
  }
}
```
```

--------------------------------

### Generate MAVLink Message Template

Source: https://context7.com/mavlink/mavlink2rest/llms.txt

Obtain a zero-valued JSON template for any MAVLink message by providing its name. This is essential for constructing valid POST request bodies.

```bash
curl "http://0.0.0.0:8088/v1/helper/mavlink?name=COMMAND_LONG"
```

```bash
curl "http://0.0.0.0:8088/v1/helper/mavlink?name=ATTITUDE"
```

```bash
curl "http://0.0.0.0:8088/v1/helper/mavlink?name=DOES_NOT_EXIST"
```