MAVInspect

Rust library for parsing MAVLink XML definitions.

🇺🇦

This library is a building block for other MAVLink-related tools (code generators, telemetry collectors, IO, etc.). We intentionally moved everything which is not related to protocol inspection to other Mavka project.

This project respects semantic versioning. As allowed by specification, breaking changes may be introduced in minor releases until version 1.0.0 is reached. However, we will keep unstable features under the unstable feature flag whenever possible.

Install

Install MAVSpec with cargo:

cargo add mavinspect

Usage

Parse standard and custom XML definitions from ./message_definitions:

use mavinspect::parser::Inspector;

fn main() {
    // Instantiate inspector and load list of XML definitions
    let inspector = Inspector::builder()
        .set_sources(&[
            "./message_definitions/standard",
            "./message_definitions/extra",
        ])
        .build()
        .unwrap();
    
    // Parse all XML definitions
    let protocol = inspector.parse().unwrap();
    
    // Get `minimal` dialect
    let minimal = protocol.dialects().get("minimal").unwrap();
    
    // Get `HEARTBEAT` message
    let heartbeat = minimal.get_message_by_name("HEARTBEAT").unwrap();
    println!("\n`HEARTBEAT` message: {:#?}", heartbeat);
}

See examples and API documentation for advanced usage.

Dialects Naming

To avoid collision between similar dialect names like SomeDialect and some_dialect in libraries which use MAVInspect for code generation, we match 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.

Examples

• parser — parse XML definitions.

  cargo run --example parser --features=serde
  

Roadmap

API is considered relatively stable but certain advanced features are yet to be developed. However, most of these features are nice to have, rather than something necessary to consider this library complete.

Milestone v1 contains features considered necessary to reach stable version 1.0.0.

There are several experimental features which may or may be released. Most of them are related to the gRPC milestone.

Propositions and pull-requests are welcomed.

Other MAVLink Tools

First of all, there is an official MAVLink client for Rust worth mentioning: rust-mavlink. One of the reasons behind writing this library was the desire to decouple parser and code generator into the separate projects.

I was personally inspired by gomavlib library for MAVLink (Go). I like the way it is written, and its source code helped me in several cases when official MAVLink documentation wasn't clear enough.

If you want to autogenerate language bindings and prefer Python, you might be interested in the official mavgen code-generation tool. If you are looking for a router for MAVLink messages, then we suggest mavp2p. If you want a solution that supports MAVLink microservices, then it worth checking MAVSDK that uses gRPC API.

MAVLink is almost 15 years old, but the ecosystem around this protocol is still dynamic and developing. Some projects are stable and robust, while others are nice and feature-rich but incomplete.

License

Here we simply comply with the suggested dual licensing according to Rust API Guidelines (C-PERMISSIVE).

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.