Crate mavinspect

MAVInspect is a library for parsing MAVLink message definitions.

🇺🇦

Usage

Discover and parse MAVLink XML using Inspector:

use mavinspect::parser::Inspector;

// Instantiate inspector and load XML definitions from several locations
let inspector = Inspector::builder()
    .set_sources(&[
        "./message_definitions/standard",
        "./message_definitions/extra",
    ])
    .set_include(&["crazy_flight"])
    .build()
    .unwrap();
   
// Parse all XML definitions
let protocol = inspector.parse().unwrap();
   
// Get `CrazyFlight` custom dialect
let crazy_flight = protocol.get_dialect_by_canonical_name("crazy_flight").unwrap();

// Get `CRAZYFLIGHT_OUTCRY` message
let outcry_message = crazy_flight.get_message_by_name("CRAZYFLIGHT_OUTCRY").unwrap();
println!("\n`CRAZYFLIGHT_OUTCRY` message: {:#?}", outcry_message);

Here we obtain an instance of Protocol that contains a collection of dialects. Each Dialect contains MAVLink enums and messages as well as additional information (like version or dialect dependencies).

Dialects Naming

To avoid collision between similar dialect names like SomeDialect and some_dialect in libraries which use MAVInspect for code generation, we match dialect names up to lower_snake_case. This means that SomeDialect, SOME_DIALECT, and some_dialect will be considered the same, while somedialect will be considered as a different dialect. For example:

let inspector_builder = Inspector::builder()
    // this is the original dialect name as it appears in the XML file name
    .set_include(&["SomeDialect"])
    // and this is a canonical name
    .set_include(&["some_dialect"]);
// both rules will lead to the same result since names will be converted to `some_dialect` upon matching

See details in Dialect::canonical_name.

Filtering

It is possible to filter Protocol and a specific Dialect by messages, enums, commands, and MAVLink microservices. For example:

use mavinspect::protocol::{Filter, Microservices};

/* obtain protocol with `common` dialect */

// Filter
let filtered_protocol = protocol.filtered(
    &Filter::by_microservices(Microservices::HEARTBEAT | Microservices::MISSION)
    .with_messages(&["FILE_TRANSFER_PROTOCOL"])
    .with_enums(&["GIMBAL_DEVICE_CAP_FLAGS"])
    .with_commands(&["MAV_CMD_SET_*"])
);

Check Filter for details.

Cargo Features

• serde — add Serde support.
• unstable — unstable API features. These features can be changed at any moment and their usage in production environments is discouraged.

Protocol Specification API

MAVLink entities are defined in the protocol module. The root of the specification is Protocol struct that contains a collection of Dialect. The latter contains dialect metadata, messages and enums.

Most of the entities with complex validation rules and lots of parameters are using builder instead of direct instantiation (no constructors). We assume that library clients prefer to use XML definitions as a ground truth for their dialects and are not very interested in manual creation of Rust entities. However, this possibility remains open yet not encouraged.

All entities optionally support Serde and are thread-safe.

Errors

All errors are variants (or sub-variants) of Error. Fallible functions and methods return Result type.

Modules

• errors
  MAVInspect errors
• parser
  MAVLink parsing utilities.
• protocol
  MAVLink protocol entities.
• utils
  Common utils

Structs

• Inspector
  Discovers and parses MAVLink XML definitions.