crazyflie-link 0.5.0

Crazyflie link
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

#![allow(clippy::single_component_path_imports)]

//! # Crazyflie Link
//!
//! This Crate implement the Crazyflie radio link connection using Crazyradio.
//! It allows to scan for Crazyflies and to open a safe bidirectional radio connection using a Crazyradio.
//!
//! The entry point to this Crate is the [LinkContext], it keeps track of Crazyradio dongles
//! and provides functions to open a link [Connection].
//!
//! A connection can then be used to send and receive packet with the Crazyflie.
//!
//! Example:
//!
//! ``` no_run
//! # use std::error::Error;
//! # async fn test() -> Result<(), Box<dyn Error>> {
//! // Create a link Context
//! let context = crazyflie_link::LinkContext::new();
//!
//! // Scan for Crazyflies
//! let cf_found = context.scan([0xe7; 5]).await?;
//!
//! if let Some(uri) = cf_found.first() {
//!     let connection = context.open_link(uri).await?;
//!     let packet = connection.recv_packet().await?;
//!     println!("Packet received: {:?}", packet);
//! }
//! # Ok(())
//! # }
//! ```
//! 
//! ## Link URI format
//! 
//! The link URI format is as follows:
//! 
//! ``` text
//! radio://<radio_nth>/<channel>/[datarate]/[address]?[options=value&options=value...]
//! ```
//! 
//! - `radio_nth` is the index of the Crazyradio to use (0 for the first, 1 for the second, etc.)
//! - `channel` is the radio channel to use (0-125)
//! - `datarate` is the datarate to use (optional, default is 2M, possible values are 250K, 1M, 2M)
//! - `address` is the radio address to use (optional, default is e7e7e7e7e7, 5 bytes in hex)
//! - `options` are additional options:
//!   - safelink: Disable safelink packet loss protection (optional, default is 1, 0 to disable)
//!   - ackfilter: Enable ACK filtering, if disable, empty ack packet will be send as null packet downstream (optional, default is 0, 1 to enable)
//!   - timeout: Set the receive timeout in milliseconds (optional, default is 1000)
//! 
//! **Note**: Crazyradio 2.0 only support channels 0-100, and datarates 1M and 2M.
//!
//! ## Cargo features
//!
//! - **packet_capture** - Enable packet capture via Unix socket (Unix only)
//!
//! ## Packet Capture
//!
//! When the `packet_capture` feature is enabled, CRTP packets can be captured and sent
//! to an external application for analysis. Call [`capture::init()`] at startup to
//! connect to the capture socket.
//!
//! The capture uses a Unix socket at `/tmp/crazyflie-capture.sock`. To view packets in
//! Wireshark, use the extcap plugin from <https://github.com/evoggy/wireshark-crazyflie>.
//!
//! ### Capture Format
//!
//! Each captured packet is sent with a 41-byte header followed by the CRTP packet data:
//!
//! | Offset | Size | Field       | Description                              |
//! |--------|------|-------------|------------------------------------------|
//! | 0      | 1    | link_type   | 1 = Radio, 2 = USB                       |
//! | 1      | 1    | direction   | 0 = TX (to Crazyflie), 1 = RX (from CF)  |
//! | 2      | 12   | address     | Radio address (5 bytes) or empty for USB |
//! | 14     | 1    | channel     | Radio channel (0 for USB)                |
//! | 15     | 16   | serial      | Radio/device serial number               |
//! | 31     | 8    | timestamp   | Microseconds since Unix epoch (LE)       |
//! | 39     | 2    | length      | CRTP packet length (LE)                  |
//! | 41     | N    | data        | CRTP packet (header + payload)           |

#[macro_use]
extern crate bitflags;

mod connection;
mod context;
mod crazyflie_usb_connection;
mod crazyradio_connection;
pub mod error;
mod packet;

#[cfg(feature = "packet_capture")]
pub mod capture;

pub(crate) use crazyradio;

pub use connection::{Connection, ConnectionStatus, ConnectionTrait, PlatformAck, RadioLinkStatistics};
pub use context::LinkContext;
pub use error::Error;
pub use packet::Packet;
pub use crazyradio::SharedCrazyradio;