8 releases
0.1.3 | Aug 9, 2024 |
---|---|
0.1.2 | Apr 8, 2024 |
0.1.1 | Mar 26, 2024 |
0.1.0-alpha1 | Dec 30, 2023 |
#7 in Robotics
37 downloads per month
600KB
9K
SLoC
Maviola
A high-level MAVLink communication library written in Rust.
Repositories
Currently, we use GitLab as the main project repository and GitHub as official mirror.
We accept issues and pull-requests only at GitLab but will do our best to keep GitHub discussions as alive as possible.
The mirror will always contain latest release tags and is kept up to date automatically.
Intro
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
andMAVLink 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.
Install
If you want to use synchronous API, you can install Maviola with:
cargo add maviola --features sync
And for asynchronous API:
cargo add maviola --features async
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. There is a corresponding
issue in the tracker.
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.
You can track v1 milestone dedicated to API stabilisation.
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.
Dependencies
~2β11MB
~124K SLoC