Maviola

A high-level MAVLink communication library written in Rust.

MAVLink is a lightweight open protocol for communicating between drones, onboard components and ground control stations. It is used by such autopilots like PX4 or ArduPilot. MAVLink has simple and compact serialization model. The basic abstraction is message which can be sent through a link (UDP, TCP, UNIX socket, UART, whatever) and deserialized into a struct with fields of primitive types or arrays of primitive types. Such fields can be additionally restricted by enum variants, annotated with metadata like units of measurements, default or invalid values.

There are several MAVLink dialects. Official dialect definitions are XML files that can be found in the MAVlink repository. Based on message abstractions, MAVLink defines so-called microservices that specify how clients should respond on a particular message under certain conditions or how they should initiate a particular action.

Maviola provides abstractions such as communication nodes, networks, or devices and implements stateful features of MAVLink protocol: sequencing, message signing, automatic heartbeats, and so on. The key features are:

Synchronous and asynchronous API. The latter is based on Tokio.
Both MAVLink 1 and MAVLink 2 protocol versions are supported, it is also possible to have protocol-agnostic channels that support both versions.
Maviola supports all standard MAVLink dialects, controlled by corresponding cargo features.
Additional custom dialects can be generated by MAVSpec.

This library is based on Mavio, a low-level library with no-std support. If you are looking for a solution for embedded devices, then Mavio probably would be a better option.

Usage

📖 If you want to learn how to use Maviola, start from reading Maviola Playbook. The following section is just a brief introduction.

This library provides both synchronous and asynchronous API. The synchronous API can be enabled by sync feature flag. The asynchronous API is based on Tokio, and can be enabled by async feature flag. The differences between synchronous and asynchronous APIs are minimal, so you can easily switch between them, if necessary. It is also possible to use both synchronous and asynchronous APIs in different parts of your project.

Synchronous API

Install:

cargo add maviola --features sync

Create a synchronous TCP server that represents a particular MAVLink device:

use maviola::prelude::*;
use maviola::sync::prelude::*;

pub fn main() -> Result<()> {
    // Create a synchronous MAVLink node 
    // with MAVLink 2 protocol version
    let server = Node::sync::<V2>()
        .id(MavLinkId::new(17, 42))                     // Set device system and component IDs
        .connection(TcpServer::new("127.0.0.1:5600")?)  // Define connection settings
        .build()?;

    // Handle node events
    for event in server.events() {
        match event {
            // Handle a new peer
            Event::NewPeer(peer) => println!("new peer: {peer:?}"),
            // Handle a peer that becomes inactive
            Event::PeerLost(peer) => {
                println!("peer offline: {peer:?}");
                // Exit when all peers are disconnected
                if !server.has_peers() {
                    break;
                }
            }
            // Handle incoming MAVLink frame
            Event::Frame(frame, callback) => if server.validate_frame(&frame).is_ok() {
                // Handle heartbeat message
                if let Ok(Minimal::Heartbeat(msg)) = frame.decode::<Minimal>() {
                    // Respond with the same heartbeat message to all clients,
                    // except the one that sent this message
                    callback.respond_others(&server.next_frame(&msg)?)?;
                }
            }
            Event::Invalid(frame, err, callback) => {
                /* Handle invalid frame */
            }
        }
    }
}

Asynchronous API

Install:

cargo add maviola --features async

Create an asynchronous TCP server that represents a particular MAVLink device:

use maviola::prelude::*;
use maviola::asnc::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Create an asynchronous MAVLink node
    // with MAVLink 2 protocol version
    let server = Node::asnc::<V2>()
        .id(MavLinkId::new(17, 42))             // Set device system and component IDs
        .connection(
            TcpServer::new("127.0.0.1:5600")?   // Define connection settings
        )
        .build().await?;

    // Subscribe to a stream of node events
    let mut events = server.events().unwrap();
    // Handle node events
    while let Some(event) = events.next().await {
        match event {
            // Handle a new peer
            Event::NewPeer(peer) => println!("new peer: {peer:?}"),
            // Handle a peer that becomes inactive
            Event::PeerLost(peer) => {
                println!("peer offline: {peer:?}");
                // Exit when all peers are disconnected
                if !server.has_peers().await {
                    break;
                }
            }
            // Handle incoming MAVLink frame
            Event::Frame(frame, callback) => if server.validate_frame(&frame).is_ok() {
                // Handle heartbeat message
                if let Ok(Minimal::Heartbeat(msg)) = frame.decode::<Minimal>() {
                    // Respond with the same heartbeat message to all clients,
                    // except the one that sent this message
                    callback.respond_others(&server.next_frame(&msg)?)?;
                }
            }
            Event::Invalid(frame, err, callback) => {
                /* Handle invalid frame */
            }
        }
    }
    Ok(())
}

Examples

Basic examples can be found here.

API Stability

Although this library has suspiciously small version number, the most parts of the API are considered stable. All parts of the API that are still under consideration are hidden under the unstable Cargo feature flag.

There are few exceptions, namely the Device entity. We are considering to enrich its API in the near future and can't guarantee that this operation won't require breaking the existing API.

Basically, the project reached the state, when our intuition and our engineering experience tells us that further development will be mostly related to adding new functionality, not amending the existing one. The current plan is to create a proper roadmap, so other people won't have to rely on our vaguely expressed gut feeling.

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.

maviola 0.1.0