Crate mavlink_dialects

Crate mavlink_dialects 

Source
Expand description

🇺🇦 repository crates.io docs.rs issues

MAVLink messages bindings based on MAVInspect.

This library is a part of MAVSpec code-generation toolchain and is intended to use alongside with it. However, nothing prevents you from using this crate independently.

Since MAVSpec is I/O agnostic, it and does not provide any abstractions for transferring MAVLink messages. If you want to communicate with MAVLink devices, use Mavio for embedded devices and simple tasks or Maviola for advanced I/O in std environments (for ground control stations, communication layers, and so on).

§Usage

use dialect::enums::{MavAutopilot, MavModeFlag, MavState};
use dialect::messages::Heartbeat;
use dialect::Minimal as DialectMessage;
use mavlink_dialects::dialects::minimal as dialect;
use mavlink_dialects::spec::*;

let message = Heartbeat {
    autopilot: MavAutopilot::Armazila,
    base_mode: MavModeFlag::HIL_ENABLED,
    system_status: MavState::Active,
    ..Default::default()
};

// Check that this message indeed supports `MAVLink 1`.
assert_eq!(message.min_supported_mavlink_version(), MavLinkVersion::V1);

// Encode to MAVLink payload.
let payload = message.encode(MavLinkVersion::V2).unwrap();
assert_eq!(payload.version(), MavLinkVersion::V2);
assert_eq!(payload.id(), message.id());

// Decode from MAVLink payload, now without .
let dialect_message = DialectMessage::decode(&payload).unwrap();
match dialect_message {
    DialectMessage::Heartbeat(msg) => {
        assert_eq!(msg.id(), Heartbeat::ID);
    }
    _ => panic!("Unexpected dialect message: {:?}", dialect_message),
}

§Features

This library provides MAVLink abstractions to work with MAVLink messages and dialects.

It also provides a set of additional tools to work with MAVLink microservices. Basic microservices support involves generation of sub-dialects which include only required entities. For some microservices, like mission, additional utilities are provided.

§Dialects

Standard MAVLink dialect can be bundled with MAVSpec. This can be enabled by the corresponding dlct-<name> feature flags.

  • minimal — minimal dialect required to expose your presence to other MAVLink devices.
  • standard — a superset of minimal dialect, that expected to be used by almost all flight stack.
  • common — minimum viable dialect with most of the features, a building block for other future-rich dialects.
  • ardupilotmega — feature-full dialect used by ArduPilot. In most cases this dialect is the go-to choice if you want to recognize almost all MAVLink messages used by existing flight stacks.
  • all — meta-dialect which includes all other standard dialects including those which were created for testing purposes. It is guaranteed that namespaces of the dialects in all family do not collide.
  • Other dialects from MAVLink XML definitions: asluav, avssuas, csairlink, cubepilot, development, icarous, matrixpilot, paparazzi, ualberta, uavionix. These do not include python_array_test and test dialects which should be either generated manually or as a part of all meta-dialect.

§Default Dialect

When standard MAVLink dialects are used and at least dlct-minimal Cargo feature is enabled, this library exposes default_dialect and DefaultDialect entities that allow to access the most feature-rich enabled MAVLink dialect.

§Microservices

MAVSpec allows to generate additional structures tailored for MAVLink microservices. Each microservice is a subdialect with only those messages and enums which are necessary. To generate microservice subdialects use msrv-* feature flags.

At the moment, microservices are only generated for the default_dialect and, if enabled, are available at default_dialect::microservices and as microservices module of the corresponding default dialect.

We do not recommend to enable microservices for libraries that perform generic MAVLink operations as, if not used properly, this may increase compilation time and binary size.

§Fingerprints

MAVSpec may skip code re-generation if dialects haven’t changed. It uses 64-bit CRC fingerprint to monitor changes. Set fingerprints feature flag to enable this behavior.

This feature is useful for reducing build time during development and CI runs. Make sure that your releases are clean and do not depend on fingerprints.

§Caveats

The API is straightforward and generally stable, however, incorrect use of certain features may lead to issues during deployment and development.

§Binary Size

For small applications that use only a small subset of messages, avoid using dialect enums as they contain all message variants. Instead, decode messages directly from frames:

This will help compiler to throw away unnecessary pieces of code.

§Unstable Features

Certain features are considered unstable and available only when unstable feature flag is enabled. Unstable features are marked with ⍚ and are may be changed in futures versions.

§Incompatible Features

  • Specta requires std feature to be enabled.

§Feature Flags

In most of the cases you will be interested in dlct-* and msrv-* feature families, and alloc / std target specification. However, a more fine-grained control may be required.

§Generic features

  • default — Default features (nothing is enabled)

  • alloc — Enable alloc support

  • std — Enable standard library support

  • metadata — Add additional metadata to MAVLink entities.

  • unstable — ⚠️ Enables unstable API features.

    Certain features won’t take effect without this flag

§Code generation

Features required for dialects generation.

  • fingerprints — Use protocol CRC-fingerprints to avoid re-generating files

§Serialization and reflection

These features enable serde and specta support.

  • serde — Enable serde support
  • specta — Enable specta support

§Dialects

These features control which MAVLink dialects will be considered by MAVSpec.

To enable standard MAVLink dialects as defined in XML message definitions, use dlct-* feature family.

In case you want to patch mavlink-message-definitions, you might be interested in enabling extra-dialects feature.

  • dlct-ardupilotmega — Include ardupilotmega dialect

  • dlct-asluav — Include ASLUAV dialect

  • dlct-avssuas — Include AVSSUAS dialect

  • dlct-common — Include common dialect

  • dlct-cs_air_link — Include csAirLink dialect

  • dlct-cubepilot — Include cubepilot dialect

  • dlct-development — Include development dialect

  • dlct-icarous — Include icarous dialect

  • dlct-matrixpilot — Include matrixpilot dialect

  • dlct-minimal — Include minimal dialect

  • dlct-paparazzi — Include paparazzi dialect

  • dlct-standard — Include standard dialect

  • dlct-ualberta — Include ualberta dialect

  • dlct-uavionix — Include uAvionix dialect

  • dlct-all — Include all meta-dialect

  • extra-dialects — Enables extra dialects

    Downstream crates can patch mavlink-message-definitions adding extra MAVLink dialects.

  • test-dialects — Enables test dialects

    These dialects are useful for checking various test cases.

These features will control generation of MAVLink microservice-specific bindings.

  • msrv-all — Support for all MavLink microservices
  • msrv-heartbeat — Heartbeat protocol support
  • msrv-mission — Mission microservice support
  • msrv-parameter — Parameter protocol support
  • msrv-parameter-ext — Extended parameter protocol support
  • msrv-command — Command protocol support
  • msrv-manual-control — Manual control protocol support
  • msrv-camera — Camera protocol v2 support
  • msrv-gimbal-v1 — Gimbal protocol v1 support
  • msrv-gimbal-v2 — Gimbal protocol v2 support
  • msrv-arm-auth — Arm authorization protocol support
  • msrv-image-transmission — Image transmission protocol support
  • msrv-ftp — File transfer protocol support
  • msrv-landing-target — Landing target protocol support
  • msrv-ping — Ping protocol support
  • msrv-path-planning — Path planning protocol support
  • msrv-battery — Battery protocol support
  • msrv-terrain — Terrain protocol support
  • msrv-tunnel — Tunnel protocol support
  • msrv-open-drone-id — Open Drone ID protocol support
  • msrv-high-latency — High latency protocol support
  • msrv-component-metadata — Component metadata protocol support
  • msrv-payload — Payload protocol support
  • msrv-traffic-management — Traffic management protocol support
  • msrv-events-interface — Events interface protocol support
  • msrv-time-sync — Time synchronization protocol support

§Technical features

These features should not be used directly.

  • msrv — ⊛ Enable MAVLink microservices support

    Do not use directly as this feature does not give access to any specific functionality by itself. Instead, use one of msrv-* features.

Modules§

default_dialect
Default standard MAVLink dialect module.
derive
mavspec MAVSpec Rust Procedural Macros
dialects
Autogenerated MAVLink dialects
rust
Rust bindings specifications left for compatibility with MAVSpec.
spec
mavspec

Enums§

DefaultDialect
Default standard MAVLink dialect. Enum containing all messages within all dialect.