MAVLink

MAVLink (Micro Air Vehicle Link) is a lightweight, binary messaging protocol designed for reliable communication between vehicles, onboard components, and ground control systems. It is widely used in the UAV, robotics, and autonomous systems ecosystem due to its efficiency, extensibility, and well-defined message schemas.

In MAPS Messaging, MAVLink support focuses on ingesting and normalising MAVLink traffic so it can be routed, transformed, stored, and analysed alongside other protocols.

Current status
MAVLink support is inbound only. MAPS can receive MAVLink frames, track remote endpoints, decode payloads, and publish them internally. Outbound MAVLink frame generation and transmission are not yet implemented.

Features

Dynamic loading of MAVLink dialects
common dialect supported out of the box
MAVLink v1 and v2 frame handling
Topic naming based on remote endpoint, MAVLink header fields, and message name
Optional decoding of incoming MAVLink payloads into JSON for downstream processing
Global and per-source message filtering
Known source registry using systemId and componentId
Optional raw frame forwarding to other MAVLink UDP endpoints
Duplicate suppression window
Dead-letter namespace for rejected frames

Quick Start

- name: "Mavlink Interface"
  url: udp://0.0.0.0:14440/
  protocol: mavlink
  auth: usernamePassword

Configuration

Fields below map to MavlinkConfigDTO. MAVLink is typically connectionless over UDP, so “session” controls are implemented as MAPS-level tracking and expiry for observed remote endpoints.

Field	Type	Default	Description
`fullyQualifiedPathToDialectXml`	string	`""`	Fully qualified path to the MAVLink dialect XML file. If not set, the built-in common dialect is used.
`idleSessionTimeout`	long (s)	`600`	Idle timeout for a tracked remote endpoint session. If no frames are seen for this duration, the session may be expired.
`maximumSessionExpiry`	int (s)	`86400`	Upper bound on how long a session may be retained, even if intermittently active.
`advertiseInterval`	int (s)	`30`	Interval at which MAVLink heartbeat or advertise messages are emitted by the protocol layer where applicable.
`maxInFlightEvents`	int	`1`	Maximum number of in-flight MAVLink events per session before backpressure is applied.
`topicNameTemplate`	string	`"/{remoteSocket}/{systemId}/{componentId}/{messageName}"`	Topic template used when publishing decoded MAVLink messages into MAPS.
`statusTopicNameTemplate`	string	`"/{remoteSocket}/{systemId}/{componentId}/{messageName}/status"`	Topic template used when publishing MAVLink status events, such as sequence monitoring issues.
`parseToJson`	boolean	`true`	If `true`, MAPS decodes MAVLink messages into JSON. If `false`, raw binary frames are published.
`forwardUrls`	string	`""`	Comma-separated list of UDP endpoints to forward received MAVLink frames to.
`forwardRawFrames`	boolean	`true`	If forwarding is enabled, forward raw MAVLink frames instead of decoded messages.
`forwardRejectedRawFrames`	boolean	`false`	If `true`, frames rejected by filtering can still be forwarded as raw MAVLink frames.
`dropIfTargetEqualsSource`	boolean	`true`	Prevent forwarding a MAVLink packet back to its source address and port.
`dedupWindowMillis`	int (ms)	`0`	Duplicate suppression window. Matching packets received within this window are dropped. `0` disables duplicate detection.
`acceptedMessageIds`	`list<int>`	`[]`	Global allow-list of MAVLink message IDs. If empty, all IDs are accepted unless rejected.
`rejectedMessageIds`	`list<int>`	`[]`	Global reject-list of MAVLink message IDs. Applied after the allow-list.
`knownSources`	`list<MavlinkKnownSourceDTO>`	`[]`	Registry of known MAVLink sources identified by `systemId` and `componentId`.
`rejectUnknownSources`	boolean	`false`	If `true`, frames from sources not listed in `knownSources` are rejected.
`rejectedFrameNamespace`	string	`"/protocol/mavlink/dlq"`	Namespace used when publishing rejected MAVLink frames.
`includeRejectedFrameMetadata`	boolean	`true`	Include metadata such as source address, IDs, and rejection reason with rejected frame events.

Example with topic templating, source filtering, and forwarding

- name: "Mavlink Interface"
  url: udp://0.0.0.0:14440/
  protocol: mavlink
  auth: usernamePassword
  selectorThreadCount: "{processors}/2"
  idleSessionTimeout: 300
  maximumSessionExpiry: 86400
  advertiseInterval: 15
  maxInFlightEvents: 8
  topicNameTemplate: "/mavlink/{remoteSocket}/{systemId}/{componentId}/{messageName}"
  statusTopicNameTemplate: "/mavlink/{remoteSocket}/{systemId}/{componentId}/{messageName}/status"
  parseToJson: true
  rejectUnknownSources: false
  dedupWindowMillis: 250
  forwardUrls: "udp://192.168.1.50:14550/,udp://192.168.1.51:14550/"
  forwardRawFrames: true
  forwardRejectedRawFrames: false
  dropIfTargetEqualsSource: true
  acceptedMessageIds:
    - 0
    - 33
  rejectedMessageIds:
    - 253

Topic Template Tokens

The topicNameTemplate and statusTopicNameTemplate support token replacement.

Token	Description
`{remoteSocket}`	Remote endpoint identifier, typically `ip:port`
`{systemId}`	MAVLink system ID
`{systemName}`	Friendly source name from `knownSources`, when matched
`{componentId}`	MAVLink component ID
`{messageName}`	Decoded MAVLink message name from the active dialect
`{messageId}`	MAVLink message ID

Example default topic:

/192.168.1.50:14550/1/1/HEARTBEAT

Example using a custom template:

/mavlink/192.168.1.50:14550/1/1/HEARTBEAT

Dialects

MAPS can load MAVLink dialect definitions dynamically.

The common MAVLink dialect is used by default.
Additional dialects can be provided using fullyQualifiedPathToDialectXml.
Dialect selection affects message decoding and the resolved messageName.

Known Sources

knownSources allows you to define expected MAVLink entities and attach metadata and filtering rules to them.

Each source is identified by the pair:

systemId
componentId

This is useful for:

assigning a stable friendly name to a source
identifying vehicle class
restricting allowed messages for a specific source
rejecting unknown endpoints when rejectUnknownSources is enabled

Known source fields

Field	Type	Default	Description
`name`	string	`""`	Friendly source name.
`description`	string	`""`	Optional human-readable description.
`systemId`	int	none	MAVLink system ID. Valid range is `1` to `255`.
`componentId`	int	none	MAVLink component ID. Valid range is `0` to `255`.
`vehicleClass`	enum	none	Logical vehicle type: `UAV`, `USV`, `UGV`, `UUV`, or `GCS`.
`acceptedMessageIds`	`list<int>`	`[]`	Per-source allow-list of MAVLink message IDs.
`rejectedMessageIds`	`list<int>`	`[]`	Per-source reject-list of MAVLink message IDs.

Vehicle classes

Value	Meaning
`UAV`	Air vehicle
`USV`	Surface vehicle
`UGV`	Ground vehicle
`UUV`	Underwater vehicle
`GCS`	Ground control station

Example known source registry

- name: "Mavlink Interface"
  url: udp://0.0.0.0:14440/
  protocol: mavlink
  auth: usernamePassword
  selectorThreadCount: "{processors}/2"

  knownSources:
    - name: "ground_control"
      vehicleClass: GCS
      description: "Ground control station"
      systemId: 255
      componentId: 190
      acceptedMessageIds:
        - 0

    - name: "uav_1"
      description: "UAV Quadrotor 1 — NW Narva forest patrol"
      vehicleClass: UAV
      systemId: 1
      componentId: 1

    - name: "uav_1_private_50"
      vehicleClass: UAV
      description: "UAV Quadrotor 1 private MAVLink component 50"
      systemId: 1
      componentId: 50

    - name: "uav_1_private_51"
      vehicleClass: UAV
      description: "UAV Quadrotor 1 private MAVLink component 51"
      systemId: 1
      componentId: 51

    - name: "uav_1_private_52"
      vehicleClass: UAV
      description: "UAV Quadrotor 1 private MAVLink component 52"
      systemId: 1
      componentId: 52

    - name: "uav_1_private_53"
      vehicleClass: UAV
      description: "UAV Quadrotor 1 private MAVLink component 53"
      systemId: 1
      componentId: 53

    - name: "uav_1_aux_115"
      vehicleClass: UAV
      description: "UAV Quadrotor 1 auxiliary MAVLink component 115"
      systemId: 1
      componentId: 115

    - name: "uav_1_companion"
      vehicleClass: UAV
      description: "UAV Quadrotor 1 onboard companion computer"
      systemId: 1
      componentId: 191

    - name: "uav_2"
      vehicleClass: UAV
      description: "UAV Quadrotor 2 — SW Narva forest patrol"
      systemId: 2
      componentId: 1

    - name: "usv_1"
      vehicleClass: USV
      description: "USV Surface Boat 1 — N Narva Bay patrol"
      systemId: 3
      componentId: 1

    - name: "usv_2"
      vehicleClass: USV
      description: "USV Surface Boat 2 — S Narva Bay patrol"
      systemId: 4
      componentId: 1

    - name: "ugv_1"
      vehicleClass: UGV
      description: "UGV Ground Rover 1 — S border patrol"
      systemId: 5
      componentId: 1

    - name: "ugv_2"
      vehicleClass: UGV
      description: "UGV Ground Rover 2 — S border patrol"
      systemId: 6
      componentId: 1

Filtering Behaviour

Filtering is applied in two layers:

Global filtering

acceptedMessageIds limits all inbound MAVLink traffic to a known set of message IDs
rejectedMessageIds excludes specific message IDs after allow-list checks

Per-source filtering

Each knownSources entry can also define:

acceptedMessageIds
rejectedMessageIds

This allows one source to accept a narrower or different set of messages than another.

Rejected Frames

When a frame is rejected because of source or message filtering:

it may be published under rejectedFrameNamespace
metadata can be included when includeRejectedFrameMetadata is enabled
raw rejected frames can still be forwarded when forwardRejectedRawFrames is enabled

This makes it possible to inspect or audit rejected traffic without accepting it into the normal processing path.

Forwarding

If forwardUrls is configured, MAPS can forward received MAVLink traffic to one or more UDP endpoints.

Typical use cases:

feeding a ground control station
mirroring traffic to another MAVLink consumer
passing through traffic that MAPS does not handle locally

When forwarding is enabled:

forwardRawFrames controls whether raw frames are forwarded
dropIfTargetEqualsSource prevents reflection back to the sender
forwardRejectedRawFrames allows rejected traffic to still be mirrored onward

Features​

Quick Start​

Configuration​

Example with topic templating, source filtering, and forwarding​

Topic Template Tokens​

Dialects​

Known Sources​

Known source fields​

Vehicle classes​

Example known source registry​

Filtering Behaviour​

Global filtering​

Per-source filtering​

Rejected Frames​

Forwarding​