Crate mavspec

Crate mavspec 

Source
Expand description

§MAVSpec

🇺🇦 repository crates.io docs.rs issues

Bindings and code-generation toolchain for MAVLink protocol based on MAVInspect.

This library is I/O agnostic 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).

MAVSpec is a part of Mavka toolchain

§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.

§Rust

All Rust-related bindings can be found in rust module.

This library is mostly focused on Rust bindings. At the moment, we support other languages using specta.

By default, this library pre-builds standard MAVLink dialects. However, when --no-default-features is set, then you should enable one of the dialects Cargo features as described below.

§Dialects

Standard MAVLink dialect can be bundled with MAVSpec. This can be enabled by the corresponding 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.

To bundle MAVLink entities for Rust, you should enable rust-dialects feature flag.

For example:

use mavspec::rust::dialects::common as dialect;
use dialect::{Common, messages::Heartbeat};

let message = Heartbeat {
    /* construct a message */
};

// Use message with dialect enum:
let dialect_message = Common::Heartbeat(message);

// Dialect message:
match dialect_message {
    Common::Heartbeat(msg) => {
        /* process heartbeat */
    }
    /* process other messages */
};

§Default dialect

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

The sequence of default dialects is the following (in the order of the increased completeness):

  • minimal — enabled by dlct-minimal feature flag
  • standard — enabled by dlct-standard feature flag
  • common — enabled by dlct-common feature flag
  • ardupilotmega — enabled by dlct-ardupilotmega feature flag
  • all — enabled by dlct-all feature flag

§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.

Microservices are generated only for a default dialect and available as rust::microservices. To generate microservice subdialects use the corresponding msrv-* feature flag.

MAVSpec also provides additional utils to work with MAVLink microservices. These tools can be enabled by msrv-utils-* feature flags and available in rust::microservices::utils module.

msrv-utils-* are considered unstable for now! Use unstable feature flag to enable them.

§Metadata

You may want to add additional metadata to MAVLink entities such as a name of enum or the list of its variants. In that case you may enable metadata feature flag.

use mavspec::rust::default_dialect::enums::MavCmd;

println!("Enum name: {}", MavCmd::name());

for entry in MavCmd::entries() {
  println!("Entry {:?} has a value {}", entry, entry.value());
}

§Message definitions

It is possible to bundle message definitions generated by MAVInspect into definitions module. This can be useful for ground control stations that require to present the user with the descriptions of MAVLink entities.

To enable definitions bundling use definitions feature flag.

For example:

 let protocol = mavspec::definitions::protocol();
 let mav_cmd = protocol
     .default_dialect()
     .unwrap()
     .get_enum_by_name("MAV_CMD")
     .unwrap();

 println!("MAV_CMD\n: {}", mav_cmd.description());

Message definitions available only with std feature enabled. Otherwise, this will cause build to fail.

§Generation

This library can generate custom dialects from XML definitions.

Check rust::gen for details.

§Fingerprints

MAVInspect 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.

Additionally, you may use microservices to reduce API surface you are interacting with.

§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.
  • definitions requires std feature to be enabled.

§Feature Flags

In most of the cases you will be interested in dialect features, msrv-*, msrv-utils-* 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.

    Unstable features will be marked with ⍚.

  • rust — Enable Rust core interfaces

  • specs — Enable all core interfaces

§Code generation

Features required for custom dialects generation.

  • rust_gen — Enable Rust code-generation tools
  • generators — Enable all generators
  • 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

These features control whether and how MAVLink message definitions generated by MAVInspect will be bundled.

⚠️ While being useful for ground control stations, the generated definitions is quite large and may bloat the size of the binary.

  • definitions — Bundles MAVLink message definitions.

    Message definitions will be generated only for bundled MAVLink dialects. Microservices will be ignored as they are just subsets of existing dialects.

§Dialects

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

Enabled dialects can be found under the rust::dialects module.

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.

To bundle Rust bindings for MAVLink dialects, enable rust-dialects. No Rust bindings will be generated otherwise.

The dialect selection will also control which dialect definitions will be bundled if definitions feature is enabled.

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

If enabled, microservices can be found in rust::microservices module.

These features will enable additional MAVLink utilities such as *.waypoints files support, mission planninc, etc.

If enabled, additional microservice tools can be found in rust::microservices::utils.

⚠️ All such features require unstable feature to be enabled in order to take effect.

  • msrv-utils-all — All MAVLink microservices utils

    ⚠️ Requires unstable feature to take effect.

  • msrv-utils-mission — Mission protocol utils

    If enabled, these microservice tools can be found in rust::microservices::utils::mission.

    ⚠️ Requires unstable feature to take effect.

§Technical features

These features should not be used directly.

  • cli — ⊛ Command-line utilities

    Turned on automatically when CLI tools are built.

  • 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.

  • msrv-utils — ⊛️ Enables MAVLink microservices extra utils

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

Modules§

definitions
MAVLink message definitions for MAVSpec.
rust
MAVSpec’s code generation toolchain for Rust