Implement Exclusive use of SharedCrazyradio and add WeakSharedCrazyradio (#5)

* Implement Exclusive use of SharedCrazyradio and add WeakSharedCrazyradio

In order to handle multiple connection to radios and to be able to close the USB radio
once all connections are dropped,  the LinkContext was using Arc<SharedCrazyradio> and Weak<SharedCrazyradio>.

This was not how the SharedCrazyradio was intended to be used, it was internded to be cloned to share the radio,
not access by multiple unmutable references.

This commit makes the SharedCrazyradio type encode this requirement by taking &mut self to most methods.
It also adds a WeakSharedCrazyradio to handle the USB device management.

The Crate version is bumped up since this is a breaking change.

* Fix tests and example for new API

* Run Cargo-fmt

Author: ataffanel

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "crazyradio"
-version = "0.3.1"
+version = "0.4.0"
 authors = ["Arnaud Taffanel <arnaud@taffanel.org>"]
 edition = "2018"
 description = "Crazyradio USB dongle driver"

examples/async_broadcast.rs

@@ -3,14 +3,18 @@ use crazyradio::{Channel, Crazyradio, SharedCrazyradio};
 #[tokio::main]
 async fn main() -> Result<(), crazyradio::Error> {
     let radio = Crazyradio::open_first_async().await?;
-    let cr = SharedCrazyradio::new(radio);
+    let mut cr = SharedCrazyradio::new(radio);
 
     let channel = Channel::from_number(78).unwrap();
     let address = [0xff, 0xe7, 0xe7, 0xe7, 0xe7];
-    let payload = [0x8f, 0x07, 0x00, 0x00, 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x40, 0x40];
+    let payload = [
+        0x8f, 0x07, 0x00, 0x00, 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x40,
+        0x40,
+    ];
 
     // send a takeoff command via broadcast
-    cr.send_packet_no_ack_async(channel, address, payload.to_vec()).await?;
+    cr.send_packet_no_ack_async(channel, address, payload.to_vec())
+        .await?;
 
     Ok(())
 }

examples/async_scan.rs

@@ -3,7 +3,7 @@ use crazyradio::{Channel, Crazyradio, SharedCrazyradio};
 #[tokio::main]
 async fn main() -> Result<(), crazyradio::Error> {
     let radio = Crazyradio::open_first_async().await?;
-    let cr = SharedCrazyradio::new(radio);
+    let mut cr = SharedCrazyradio::new(radio);
 
     println!("Scanning channels from 0 to 125 ...");
     let result = cr

examples/bandwidth_test.rs

@@ -18,8 +18,8 @@ fn main() -> Result<(), crazyradio::Error> {
     let crtp_channel = 0;
     let header = ((crtp_port & 0x0F) << 4) | (crtp_channel & 0x0F);
     let payload_size = 28;
-    let packet = vec![header as u8; payload_size+1]; // +1 for header byte
-    
+    let packet = vec![header as u8; payload_size + 1]; // +1 for header byte
+
     let mut n_ack = 0;
     let mut n_syslink = 0;
     let start = Instant::now();
@@ -30,7 +30,7 @@ fn main() -> Result<(), crazyradio::Error> {
         if ack.received {
             n_ack += 1;
 
-            if ack_data.len() > 2 && ack_data[0]&0xFC == 0xF0 {
+            if ack_data.len() > 2 && ack_data[0] & 0xFC == 0xF0 {
                 n_syslink += 1;
             }
         }
@@ -44,8 +44,15 @@ fn main() -> Result<(), crazyradio::Error> {
 
     println!("Sent {} packets in {:.2} seconds", N_PACKETS, seconds);
     println!("Throughput: {:.2} packets/second", pps);
-    println!("Packet success rate: {:.2}%", (n_ack as f64 / N_PACKETS as f64) * 100.0);
-    println!("Syslink packet rate: {:.2}% ({} pk/s)", (n_syslink as f64 / N_PACKETS as f64) * 100.0, (n_syslink as f64 / seconds));
+    println!(
+        "Packet success rate: {:.2}%",
+        (n_ack as f64 / N_PACKETS as f64) * 100.0
+    );
+    println!(
+        "Syslink packet rate: {:.2}% ({} pk/s)",
+        (n_syslink as f64 / N_PACKETS as f64) * 100.0,
+        (n_syslink as f64 / seconds)
+    );
 
     Ok(())
 }

examples/broadcast.rs

@@ -9,7 +9,10 @@ fn main() -> Result<(), crazyradio::Error> {
     cr.set_ack_enable(false)?;
 
     // send a takeoff command via broadcast
-    cr.send_packet_no_ack(&[0x8f, 0x07, 0x00, 0x00, 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x40, 0x40])?;
+    cr.send_packet_no_ack(&[
+        0x8f, 0x07, 0x00, 0x00, 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x40,
+        0x40,
+    ])?;
 
     Ok(())
 }

examples/stress_setup.rs

@@ -1,5 +1,5 @@
 use crazyradio::{Channel, Crazyradio};
-use indicatif::{ProgressBar, HumanCount};
+use indicatif::{HumanCount, ProgressBar};
 
 fn main() -> Result<(), crazyradio::Error> {
     let mut cr = Crazyradio::open_first()?;
@@ -15,7 +15,7 @@ fn main() -> Result<(), crazyradio::Error> {
 
     let mut i = 0;
     loop {
-        i+=1;
+        i += 1;
         for j in 0..100usize {
             // cr.set_channel(Channel::from_number(0)?)?;
             // cr.set_ack_enable(j.is_multiple_of(2))?;
@@ -29,7 +29,6 @@ fn main() -> Result<(), crazyradio::Error> {
                 let mut ack_data = [0u8; 32];
                 cr.send_packet(&[0xff], &mut ack_data)?;
             }
-            
         }
         pb.set_message(format!("Iterations: {} ({} loops)", i, HumanCount(i * 100)));
         pb.tick();

src/lib.rs

@@ -10,10 +10,12 @@
 //!  - **async** enables async function to create a [Crazyradio] object and use the [SharedCrazyradio]
 //!  - **serde** emables [serde](https://crates.io/crates/serde) serialization/deserialization of the [Channel] struct
 
+#![deny(missing_docs)]
+
 #[cfg(feature = "shared_radio")]
 mod shared_radio;
 #[cfg(feature = "shared_radio")]
-pub use crate::shared_radio::SharedCrazyradio;
+pub use crate::shared_radio::{SharedCrazyradio, WeakSharedCrazyradio};
 
 use core::time::Duration;
 #[cfg(feature = "serde_support")]
@@ -451,15 +453,15 @@ impl Crazyradio {
     }
 
     /// Set inline-settings USB protocol mode
-    /// 
+    ///
     /// When this mode is enabled, setting channel, datarate, address and
     /// ack_enable will become cached operations, and these settings
     /// will be sent as header to the data over USB. This increases performance
     /// when communicating with more than one PRX.
-    /// 
+    ///
     /// This mode, if available, is activated by default when creating the Crazyradio
     /// object.
-    /// 
+    ///
     /// This mode is only available with Crazyradio 2.0+
     pub fn set_inline_mode(&mut self, inline_mode_enable: bool) -> Result<()> {
         let setting = inline_mode_enable.then_some(1).unwrap_or(0);
@@ -478,8 +480,12 @@ impl Crazyradio {
     }
 
     /// Set packet loss simulation.
-    /// 
-    pub fn set_packet_loss_simulation(&mut self, packet_loss_percent: u8, ack_loss_percent: u8) -> Result<()> {
+    ///
+    pub fn set_packet_loss_simulation(
+        &mut self,
+        packet_loss_percent: u8,
+        ack_loss_percent: u8,
+    ) -> Result<()> {
         if self.device_desciptor.device_version() < rusb::Version::from_bcd(0x0500) {
             return Err(Error::DongleVersionNotSupported);
         }
@@ -511,7 +517,6 @@ impl Crazyradio {
     ///                be truncated. The length of the ack payload is returned
     ///                in Ack::length.
     pub fn send_packet(&mut self, data: &[u8], ack_data: &mut [u8]) -> Result<Ack> {
-
         if self.inline_mode {
             self.send_inline(data, Some(ack_data))
         } else {
@@ -538,7 +543,6 @@ impl Crazyradio {
                 length: received - 1,
             })
         }
-        
     }
 
     /// Send a data packet without caring for Ack (for broadcast communication).
@@ -558,7 +562,7 @@ impl Crazyradio {
     }
 
     fn send_inline(&mut self, data: &[u8], ack_data: Option<&mut [u8]>) -> Result<Ack> {
-        const OUT_HEADER_LENGTH: usize=8;
+        const OUT_HEADER_LENGTH: usize = 8;
         const IN_HEADER_LENGTH: usize = 2;
 
         const OUT_FIELD2_ACK_ENABLE: u8 = 0x10;
@@ -582,21 +586,24 @@ impl Crazyradio {
         command.extend_from_slice(&data);
 
         let mut answer = [0u8; 64];
-        self.device_handle.write_bulk(0x01, &command, Duration::from_secs(1))?;
-        self.device_handle.read_bulk(0x81, &mut answer, Duration::from_secs(1))?;
+        self.device_handle
+            .write_bulk(0x01, &command, Duration::from_secs(1))?;
+        self.device_handle
+            .read_bulk(0x81, &mut answer, Duration::from_secs(1))?;
 
         // Decode answer
         let payload_length = (answer[0] as usize) - 2;
         if let Some(ack_data) = ack_data {
-            ack_data[0..payload_length].copy_from_slice(&answer[IN_HEADER_LENGTH..(IN_HEADER_LENGTH+payload_length)]);
+            ack_data[0..payload_length]
+                .copy_from_slice(&answer[IN_HEADER_LENGTH..(IN_HEADER_LENGTH + payload_length)]);
         }
 
         Ok(Ack {
-                received: answer[1] & IN_HEADER_ACK_RECEIVED != 0,
-                power_detector: answer[1] & IN_HEADER_POWER_DETECTOR != 0,
-                retry: ((answer[1] & IN_HEADER_RETRY_MASK) >> IN_HEADER_RETRY_SHIFT) as usize,
-                length: payload_length,
-            })
+            received: answer[1] & IN_HEADER_ACK_RECEIVED != 0,
+            power_detector: answer[1] & IN_HEADER_POWER_DETECTOR != 0,
+            retry: ((answer[1] & IN_HEADER_RETRY_MASK) >> IN_HEADER_RETRY_SHIFT) as usize,
+            length: payload_length,
+        })
     }
 }
 
@@ -611,7 +618,6 @@ impl Crazyradio {
 #[cfg(feature = "async")]
 #[cfg_attr(docsrs, doc(cfg(feature = "async")))]
 impl Crazyradio {
-
     /// Async vesion of [Crazyradio::open_first()]
     pub async fn open_first_async() -> Result<Self> {
         let (tx, rx) = flume::bounded(0);
@@ -651,14 +657,19 @@ impl Crazyradio {
     }
 }
 
+/// Errors returned by Crazyradio functions
 #[derive(thiserror::Error, Debug, Clone)]
 pub enum Error {
-    #[error("Usb Error: {0}:?")]
+    /// USB error returned by the underlying rusb library
+    #[error("Usb Error: {0:?}")]
     UsbError(rusb::Error),
+    /// Crazyradio not found
     #[error("Crazyradio not found")]
     NotFound,
+    /// Invalid argument passed to function
     #[error("Invalid arguments")]
     InvalidArgument,
+    /// Crazyradio version not supported
     #[error("Crazyradio version not supported")]
     DongleVersionNotSupported,
 }
@@ -701,6 +712,9 @@ impl<'de> Deserialize<'de> for Channel {
 }
 
 impl Channel {
+    /// Create a Channel from its number (0-125)
+    ///
+    /// Returns an Error::InvalidArgument if the channel number is out of range
     pub fn from_number(channel: u8) -> Result<Self> {
         if channel < 126 {
             Ok(Channel(channel))
@@ -719,16 +733,23 @@ impl From<Channel> for u8 {
 /// Radio datarate
 #[derive(Copy, Clone, PartialEq)]
 pub enum Datarate {
+    /// 250 kbps
     Dr250K = 0,
+    /// 1 Mbps
     Dr1M = 1,
+    /// 2 Mbps
     Dr2M = 2,
 }
 
 /// Radio power
 pub enum Power {
+    /// -18 dBm
     Pm18dBm = 0,
+    /// -12 dBm
     Pm12dBm = 1,
+    /// -6 dBm
     Pm6dBm = 2,
+    /// 0 dBm
     P0dBm = 3,
 }