Crate maviola

Source
Expand description

§Maviola

A high-level MAVLink communication library written in Rust.

🇺🇦 repository crates.io docs.rs issues

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.

This library is a part of Mavka toolchain. It is based on Mavio, a low-level MAVLink library, and compatible with MAVSpec MAVLink dialects generator.

§📖 Documentation

If you want to learn how to use Maviola, start from reading Maviola Playbook. This page contains only a brief introduction.

§Usage

Maviola provides both synchronous and asynchronous API. The synchronous API is available in sync module and can be enabled by sync feature flag. The asynchronous API is based on Tokio, it can be found in asnc module and is enabled by async feature flag.

Here is a simple example of a synchronous TCP server:

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

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

// Handle node events
for event in server.events() {
     match event {
         // Handle incoming MAVLink frame
         Event::Frame(frame, callback) => {
             // Handle heartbeat message
             if let Ok(DefaultDialect::Heartbeat(msg)) = frame.decode::<DefaultDialect>() {
                 // Respond with the same heartbeat message to all clients,
                 // except the one that sent this message
                 callback.broadcast(&server.next_frame(&msg)?)?;
             }
         }
         _ => {
             /* Handle other node events */
         }
     }
}

You can learn more about this example in Quickstart section that gets into details.

Also check Overview, Synchronous API, and Asynchronous API documentation sections for details on how to use different types of API.

§Features

Maviola is designed to hide most of its functionality under corresponding feature flags. If you need certain features, you have to explicitly opt-in.

§API Modes

These features are not mutually exclusive, you can use both synchronous and asynchronous API in different parts of the project.

§Unstable Features

Some parts of the API are still considered to be unstable and available only under the unstable feature flag. We mark unstable and experimental entities with ⍚ in documentation.

§Embedded Devices

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

Protocol entities reside in the protocol module.

§Dialects

Maviola packages standard MAVLink dialects under corresponding dlct-* feature flags in protocol::dialects. It is possible to define your own dialects with XML message definitions using MAVSpec or even create your ad-hoc dialects using pure Rust.

Check Dialects documentation section for details.

§Microservices

We utilise MAVSpec ability to generate MAVLink microservices as sub-dialects. Use msrv-* feature flags to enable specific microservices.

We also re-export additional microservice utils as protocol::microservices. You should enable the corresponding msrv-utils-* feature flag to access such functionality.

§Message Definitions

You may access metadata for MAVLink message definitions by enabling definitions feature flag. The metadata is available at protocol::definitions.

§Feature Flags

§Generic features

  • default — Default features (empty).
  • full — All stable features (no unsafe features). This should be used instead of –all-features for most of the production environments
  • unstable — Enables unstable API features.
  • unsafe — Unsafe features.

§MAVSpec tools

  • derive — Includes derive maros from MAVSpec
  • definitions — Includes MAVLink message definitions
  • metadata — Adds additional metadata to MAVLink entities.

§I/O

  • sync — Enables synchronous API.
  • async — Enables asynchromous API via Tokio.

§Serialization and reflection

These features enable serde and specta support.

  • serde — Enables serde support.
  • specta — Enables specta support.

§Dialects

Bundle standard MAVLink dialects as defined in XML message definitions generated by MAVSpec.

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

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

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

⚠️ 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

    These additional utils are packaged into protocol::microservices::mission microservice and can be alternatively accessed through protocol::microservices::utils::mission.

    ⚠️ Requires unstable feature to take effect.

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

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

§Test utils (⚠️ do not use at production ⚠️)

  • test_utils — Add testing utils that allow to run complex tests. Primarily used for documentation but can be utilized by other libraries as well.

Modules§

asnc
Maviola asynchronous I/O
core
Core MAVLink entities
docs
📖 Maviola Playbook
error
Maviola core errors
prelude
Maviola prelude
protocol
MAVLink protocol
sync
Maviola synchronous API