Documentation and housekeeping for esp-ieee802154 (#1730)

* Derive more traits on public types

* Document cargo features

* Minor documentation updates, remove an unused struct field

esp-ieee802154/Cargo.toml

@@ -16,19 +16,19 @@ bench = false
 test  = false
 
 [dependencies]
-byte             = "0.2.7"
+byte              = "0.2.7"
-critical-section = "1.1.2"
+critical-section  = "1.1.2"
-esp-hal          = { version = "0.18.0", path = "../esp-hal" }
+document-features = "0.2.8"
-esp-wifi-sys     = { git = "https://github.com/esp-rs/esp-wifi", rev = "2ceb4b3" }
+esp-hal           = { version = "0.18.0", path = "../esp-hal" }
-heapless         = "0.8.0"
+esp-wifi-sys      = { git = "https://github.com/esp-rs/esp-wifi", rev = "2ceb4b3" }
-ieee802154       = "0.6.1"
+heapless          = "0.8.0"
-log              = "0.4.21"
+ieee802154        = "0.6.1"
-vcell            = "0.1.3"
+log               = "0.4.21"
+vcell             = "0.1.3"
 
 [features]
-default = []
 esp32c6 = ["esp-hal/esp32c6", "esp-wifi-sys/esp32c6"]
 esp32h2 = ["esp-hal/esp32h2", "esp-wifi-sys/esp32h2"]
 
-## Output logging from the phy blobs. Requires nightly
+## Output logging from the PHY blobs. Requires nightly.
 binary-logs = []

esp-ieee802154/src/frame.rs

@@ -11,7 +11,7 @@ const FRAME_VERSION_OFFSET: usize = 2;
 const FRAME_VERSION_MASK: u8 = 0x30;
 
 /// IEEE 802.15.4 MAC frame
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Frame {
     /// Header
     pub header: Header,
@@ -24,7 +24,7 @@ pub struct Frame {
 }
 
 /// IEEE 802.15.4 MAC frame which has been received
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ReceivedFrame {
     /// Frame
     pub frame: Frame,

esp-ieee802154/src/lib.rs

@@ -1,12 +1,19 @@
-//! Low-level [IEEE 802.15.4] driver for the ESP32-C6 and ESP32-H2
+//! Low-level [IEEE 802.15.4] driver for the ESP32-C6 and ESP32-H2.
 //!
 //! Implements the PHY/MAC layers of the IEEE 802.15.4 protocol stack, and
 //! supports sending and receiving of raw frames.
 //!
+//! This library is intended to be used to implement support for higher-level
+//! communication protocols, for example [esp-openthread].
+//!
 //! [IEEE 802.15.4]: https://en.wikipedia.org/wiki/IEEE_802.15.4
-
+//! [esp-openthread]: https://github.com/esp-rs/esp-openthread
-#![no_std]
+//!
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 #![cfg_attr(feature = "binary-logs", feature(c_variadic))]
+#![no_std]
 
 use core::{cell::RefCell, marker::PhantomData};
 
@@ -33,13 +40,8 @@ mod hal;
 mod pib;
 mod raw;
 
-#[no_mangle]
-extern "C" fn rtc_clk_xtal_freq_get() -> i32 {
-    0
-}
-
 /// IEEE 802.15.4 errors
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Error {
     /// The requested data is bigger than available range, and/or the offset is
     /// invalid
@@ -58,7 +60,7 @@ impl From<byte::Error> for Error {
 }
 
 /// IEEE 802.15.4 driver configuration
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Config {
     pub auto_ack_tx: bool,
     pub auto_ack_rx: bool,
@@ -101,7 +103,6 @@ pub struct Ieee802154<'a> {
     _align: u32,
     transmit_buffer: [u8; FRAME_SIZE],
     _phantom1: PhantomData<&'a ()>,
-    //_phantom2:PhantomData< &'b ()>,
 }
 
 impl<'a> Ieee802154<'a> {
@@ -113,7 +114,6 @@ impl<'a> Ieee802154<'a> {
             _align: 0,
             transmit_buffer: [0u8; FRAME_SIZE],
             _phantom1: PhantomData,
-            //_phantom2: PhantomData,
         }
     }
 
@@ -221,6 +221,7 @@ impl<'a> Ieee802154<'a> {
         Ok(())
     }
 
+    /// Set the transmit done callback function.
     pub fn set_tx_done_callback(&mut self, callback: &'a mut (dyn FnMut() + Send)) {
         critical_section::with(|cs| {
             let mut tx_done_callback = TX_DONE_CALLBACK.borrow_ref_mut(cs);
@@ -228,6 +229,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Clear the transmit done callback function.
     pub fn clear_tx_done_callback(&mut self) {
         critical_section::with(|cs| {
             let mut tx_done_callback = TX_DONE_CALLBACK.borrow_ref_mut(cs);
@@ -235,6 +237,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Set the receive available callback function.
     pub fn set_rx_available_callback(&mut self, callback: &'a mut (dyn FnMut() + Send)) {
         critical_section::with(|cs| {
             let mut rx_available_callback = RX_AVAILABLE_CALLBACK.borrow_ref_mut(cs);
@@ -242,6 +245,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Clear the receive available callback function.
     pub fn clear_rx_available_callback(&mut self) {
         critical_section::with(|cs| {
             let mut rx_available_callback = RX_AVAILABLE_CALLBACK.borrow_ref_mut(cs);
@@ -249,6 +253,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Set the transmit done callback function.
     pub fn set_tx_done_callback_fn(&mut self, callback: fn()) {
         critical_section::with(|cs| {
             let mut tx_done_callback_fn = TX_DONE_CALLBACK_FN.borrow_ref_mut(cs);
@@ -256,6 +261,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Clear the transmit done callback function.
     pub fn clear_tx_done_callback_fn(&mut self) {
         critical_section::with(|cs| {
             let mut tx_done_callback_fn = TX_DONE_CALLBACK_FN.borrow_ref_mut(cs);
@@ -263,6 +269,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Set the receive available callback function.
     pub fn set_rx_available_callback_fn(&mut self, callback: fn()) {
         critical_section::with(|cs| {
             let mut rx_available_callback_fn = RX_AVAILABLE_CALLBACK_FN.borrow_ref_mut(cs);
@@ -270,6 +277,7 @@ impl<'a> Ieee802154<'a> {
         });
     }
 
+    /// Clear the receive available callback function.
     pub fn clear_rx_available_callback_fn(&mut self) {
         critical_section::with(|cs| {
             let mut rx_available_callback_fn = RX_AVAILABLE_CALLBACK_FN.borrow_ref_mut(cs);
@@ -287,6 +295,11 @@ impl<'a> Drop for Ieee802154<'a> {
     }
 }
 
+/// Convert from RSSI (Received Signal Strength Indicator) to LQI (Link Quality
+/// Indication)
+///
+/// RSSI is a measure of incoherent (raw) RF power in a channel. LQI is a
+/// cumulative value used in multi-hop networks to assess the cost of a link.
 pub fn rssi_to_lqi(rssi: i8) -> u8 {
     if rssi < -80 {
         0
@@ -349,3 +362,8 @@ fn rx_available() {
         }
     });
 }
+
+#[no_mangle]
+extern "C" fn rtc_clk_xtal_freq_get() -> i32 {
+    0
+}

esp-ieee802154/src/pib.rs

@@ -28,7 +28,7 @@ const IEEE802154_MULTIPAN_MAX: usize = 4;
 static PIB: Mutex<RefCell<Option<Pib>>> = Mutex::new(RefCell::new(None));
 
 /// Frame pending mode
-#[derive(Debug, Default, Clone, Copy, PartialEq)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub enum PendingMode {
     /// Frame pending bit always set to 1 in the ack to Data Request
     #[default]
@@ -44,7 +44,7 @@ pub enum PendingMode {
 }
 
 /// CCA mode
-#[derive(Debug, Default, Clone, Copy)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub enum CcaMode {
     /// Carrier only
     #[default]

esp-ieee802154/src/raw.rs

@@ -63,7 +63,7 @@ enum Ieee802154TxRxScene {
 }
 
 /// A raw payload received on some channel
-#[derive(Debug)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct RawReceived {
     /// Payload
     pub data: [u8; FRAME_SIZE],