xmavlink

# MAVLink Spec Alignment for 1.0

Review date: 2026-05-08

Primary references:

- MAVLink packet serialization: https://mavlink.io/en/guide/serialization.html
- MAVLink routing: https://mavlink.io/en/guide/routing.html
- MAVLink 2 overview: https://mavlink.io/en/guide/mavlink_2.html
- MAVLink 2 signing: https://mavlink.io/en/guide/message_signing.html
- MAVLink XML schema guide: https://mavlink.io/en/guide/xml_schema.html

## 1.0 Support Posture

XMAVLink's 1.0 compatibility target is MAVLink 2 first. MAVLink 1 remains
supported for basic frame parsing, packing, and routing while that support stays
cheap to maintain, but MAVLink 1-only work should not displace MAVLink 2
correctness. If a future gap requires significant MAVLink 1-specific
investment, prefer an explicit support reduction over slowing MAVLink 2 work.

Supported runtime scope:

- MAVLink 2 unsigned frames without incompatible flags.
- MAVLink 2 signed-frame boundary parsing and signature trailer
  representation. Configured inbound signed frames are authenticated before
  unpacking and routed with replay protection, and unsigned outbound MAVLink 2
  frames are signed on signing-enabled connections. Applications can configure
  timestamp load/save callbacks for local signing timestamp persistence. Inbound
  `SETUP_SIGNING` frames are delivered locally but not forwarded between MAVLink
  connections.
- MAVLink 1 frames for existing users and legacy links.
- Serial, `udpin`, `udpout`, and outbound TCP (`tcpout`) transports.
- Generated dialect modules from trusted MAVLink XML build inputs.

Known non-goals for 1.0 unless separately implemented:

- Automatic `SETUP_SIGNING` key provisioning.
- TCP server (`tcpin`) transport.
- Treating untrusted XML dialect files as safe input.
- Full `mavgen` feature parity for XML validation, WIP filtering, and every
  generated helper surface.

## Checklist

| Area | Status | Notes |
| --- | --- | --- |
| MAVLink 2 frame shape | Supported | Parses and emits the v2 header, 24-bit message id, payload, checksum, and compatible flags. Unsupported incompatible flags are discarded. |
| MAVLink 2 signing | Supported with provisioning caveat | Signed-frame boundaries and the 13-byte signature trailer are parsed and represented. Configured inbound signed frames are verified before unpacking and routed with per-connection replay checks. Unsigned MAVLink 2 inbound frames are rejected by default while signing is enabled unless explicitly accepted. Unsigned outbound MAVLink 2 frames are signed on signing-enabled connections with per-connection timestamp increments. Optional timestamp load/save callbacks let applications persist local signing timestamps. Inbound `SETUP_SIGNING` frames are local-only; XMAVLink does not automate key provisioning. See `MAVLINK2_SIGNING.md`. |
| MAVLink 2 payload truncation | Supported | Outbound payloads trim trailing zero bytes while preserving a non-empty all-zero payload's first byte; inbound v2 payloads are padded back to known dialect length before unpacking. |
| MAVLink 2 future extension bytes | Supported | Generated v2 unpack clauses now ignore trailing extension bytes that are unknown to the local dialect. This preserves extension-field forward compatibility. |
| MAVLink 2 extension CRC behavior | Supported | `CRC_EXTRA` generation excludes extension fields, matching the serialization guide. |
| MAVLink 2 extension field packing defaults | Supported | Omitted known extension fields are packed as zero-equivalent values for v2 messages while remaining omitted from v1 payloads. |
| MAVLink 1 frame shape | Supported | Existing parser/packer handles v1 framing, checksum, and 8-bit message ids. New MAVLink 1-only expansion is not a priority for 1.0. |
| CRC_EXTRA calculation | Supported | Field ordering is size-stable for base fields, arrays are ordered by element size, and extension fields are excluded. |
| Field ordering | Supported | Base fields are stably sorted by native type size; extension fields remain in XML declaration order. |
| Unknown message handling | Partial | Unknown known-shape frames are forwarded as broadcast when the message id is not present in the dialect. Unknown messages cannot expose target fields because the payload cannot be decoded. |
| Compatible flags | Supported | MAVLink 2 compatible flags are retained and otherwise ignored. |
| Incompatible flags | Supported | Unknown incompatible flags are discarded as required. Signing's known 13-byte trailer is consumed when present so stream boundaries stay aligned. |
| Routing unchanged packets | Supported with signing caveat | Forwarding generally uses the original raw frame bytes. Unsigned MAVLink 2 frames sent over signing-enabled connections are signed for that outbound link; already signed MAVLink 2 frames are forwarded unchanged. |
| Target inference | Supported | Generated metadata classifies broadcast, system, component, and system-component targets from `target_system` and `target_component` fields. |
| Route reset after reboot | Supported | Routing tracks `SYSTEM_TIME.time_boot_ms` per source system/component and clears learned routes for that system when the same source reports a lower boot time. |
| XML includes | Partial | Includes are recursive and deterministic, but missing include errors and duplicate handling are not yet aligned with `mavgen`. |
| Enum merging | Partial | Matching enum names are merged and sorted by value. Duplicate enum entries are not rejected yet. |
| Duplicate message ids | Unsupported validation | The parser/generator does not currently reject duplicate message ids across includes. |
| XML `bitmask="true"` | Supported | Enum-level bitmask declarations are parsed and used before heuristic bitmask detection. |
| XML identifiers and source generation safety | Partial | XML is treated as trusted build input. Identifier validation and safer escaping are tracked separately in #49. |
| Generated Common dialect | Supported within above scope | `lib/common.ex` is regenerated from `config/common.xml` and should be treated as build output. |

## Changes Made In This Pass

- Generated MAVLink 2 unpackers now accept extra trailing bytes after all
  locally known fields and ignore them as future extension fields.
- Generated unpack specs now match the actual `unpack/3` runtime API and include
  an `unpack/3` fallback.
- Generated modules now compile for XML dialects with no enums or units.
- Enum-level `bitmask="true"` is parsed and reflected in generated field types,
  packing, and unpacking.
- Generated MAVLink 2 packers use zero-equivalent defaults for omitted known
  extension fields.
- MAVLink 2 signed frames now parse the 13-byte signature trailer into frame
  metadata.
- Low-level MAVLink 2 frame signing can set the signed incompatibility flag,
  recalculate checksum bytes, and append a generated signature trailer for an
  already packed frame.
- Low-level MAVLink 2 signing validation can verify signed frames and reject
  replayed or too-old timestamps.
- Inbound router and connection signing policy can verify signed MAVLink 2
  frames before unpacking, track replay state per connection, and reject
  unsigned MAVLink 2 frames by default while signing is enabled.
- Outbound router signing can sign unsigned MAVLink 2 frames on signing-enabled
  connections while leaving MAVLink 1 frames unsigned.
- Signing policy can load and save local signing timestamps through application
  callbacks, and rejects state-advancing frames when configured persistence
  fails.
- Inbound `SETUP_SIGNING` frames are delivered locally but not forwarded between
  MAVLink connections by generic routing.
- Learned routes are cleared for a remote system when the same
  system/component reports a lower `SYSTEM_TIME.time_boot_ms`, preventing stale
  targeted forwarding after reboot.
- Unsupported signed MAVLink 2 frames consume the 13-byte signature trailer when
  present, preventing TCP/serial stream buffers from treating signature bytes as
  a new frame prefix.
- MAVLink 2 packing now preserves a truly empty payload as length zero.
- Core MAVLink integer types were tightened for the signed 32-bit minimum and
  unsigned 64-bit zero value.

## Follow-Up Issues

- #53: Align XML parser/generator validation with `mavgen` for missing
  includes, duplicate message ids, duplicate enum entries, and reserved names.

These follow-ups should be prioritized by MAVLink 2 impact first. None of the
reviewed gaps require new MAVLink 1-only work before 1.0.