Addresses all current compile warnings and missing documentation warnings.

Author: jhodapp

cross/get_fw_version/src/main.rs

@@ -82,9 +82,9 @@ fn main() -> ! {
     defmt::info!("ESP32-WROOM-RP get NINA firmware version example");
 
     // These are implicitly used by the spi driver if they are in the correct mode
-    let spi_miso = pins.gpio16.into_mode::<hal::gpio::FunctionSpi>();
-    let spi_sclk = pins.gpio18.into_mode::<hal::gpio::FunctionSpi>();
-    let spi_mosi = pins.gpio19.into_mode::<hal::gpio::FunctionSpi>();
+    let _spi_miso = pins.gpio16.into_mode::<hal::gpio::FunctionSpi>();
+    let _spi_sclk = pins.gpio18.into_mode::<hal::gpio::FunctionSpi>();
+    let _spi_mosi = pins.gpio19.into_mode::<hal::gpio::FunctionSpi>();
 
     let spi = hal::Spi::<_, _, 8>::new(pac.SPI0);
 

cross/join/src/main.rs

@@ -24,14 +24,12 @@ use panic_probe as _;
 // Alias for our HAL crate
 use rp2040_hal as hal;
 
+use embedded_hal::spi::MODE_0;
 use embedded_time::fixed_point::FixedPoint;
 use embedded_time::rate::Extensions;
 use hal::clocks::Clock;
 use hal::pac;
 
-use embedded_hal::spi::MODE_0;
-use embedded_hal::blocking::delay::DelayMs;
-
 /// The linker will place this boot block at the start of our program image. We
 /// need this to help the ROM bootloader get our code up and running.
 #[link_section = ".boot2"]
@@ -87,9 +85,9 @@ fn main() -> ! {
     defmt::info!("ESP32-WROOM-RP join/leave WiFi network");
 
     // These are implicitly used by the spi driver if they are in the correct mode
-    let spi_miso = pins.gpio16.into_mode::<hal::gpio::FunctionSpi>();
-    let spi_sclk = pins.gpio18.into_mode::<hal::gpio::FunctionSpi>();
-    let spi_mosi = pins.gpio19.into_mode::<hal::gpio::FunctionSpi>();
+    let _spi_miso = pins.gpio16.into_mode::<hal::gpio::FunctionSpi>();
+    let _spi_sclk = pins.gpio18.into_mode::<hal::gpio::FunctionSpi>();
+    let _spi_mosi = pins.gpio19.into_mode::<hal::gpio::FunctionSpi>();
 
     let spi = hal::Spi::<_, _, 8>::new(pac.SPI0);
 

esp32-wroom-rp/src/gpio.rs

@@ -33,38 +33,59 @@
 use embedded_hal::blocking::delay::DelayMs;
 use embedded_hal::digital::v2::{InputPin, OutputPin};
 
+#[allow(dead_code)]
 #[derive(Clone, Copy, Debug)]
-pub enum IOError {
+enum IOError {
     Pin,
 }
 
+/// Provides an internal pin interface that abstracts the extra control lines that
+/// are separate from a data bus (e.g. SPI/I2C).
+/// 
+/// Not meant to be used outside of the crate.
 pub trait EspControlInterface {
+    /// Initializes all controls pins to set ready communication with the NINA firmware.
     fn init(&mut self);
 
+    /// Resets communication with the NINA firmware.
     fn reset<D: DelayMs<u16>>(&mut self, delay: &mut D);
 
+    /// Tells the NINA firmware we're about to send it a protocol command.
     fn esp_select(&mut self);
 
+    /// Tells the NINA firmware we're done sending it a protocol command.
     fn esp_deselect(&mut self);
 
+    /// Is the NINA firmware ready to send it a protocol command?
     fn get_esp_ready(&self) -> bool;
 
+    /// Is the NINA firmware ready to receive more commands? Also referred to as BUSY.
     fn get_esp_ack(&self) -> bool;
 
+    /// Blocking waits for the NINA firmware to be ready to send it a protocol command.
     fn wait_for_esp_ready(&self);
 
+    /// Blocking waits for the NINA firmware to acknowledge it's ready to receive more commands.
     fn wait_for_esp_ack(&self);
 
+    /// Blocking waits for the NINA firmware to be ready to send it a protocol command.
     fn wait_for_esp_select(&mut self);
 }
 
 /// A structured representation of all GPIO pins that control a ESP32-WROOM NINA firmware-based
 /// device outside of commands sent over the SPI/I²C bus. Pass a single instance of this struct
 /// into `Wifi::init()`.
 pub struct EspControlPins<CS: OutputPin, GPIO0: OutputPin, RESETN: OutputPin, ACK: InputPin> {
+    /// Chip select pin to let the NINA firmware know we're going to send it a command over
+    /// the SPI bus.
     pub cs: CS,
+    /// Puts the ESP32 WiFi target into bootloading mode. Or if acting as a server, provides
+    /// a status line for when data is ready to be read.
     pub gpio0: GPIO0,
+    /// Places the ESP32 WiFi target into reset mode. Useful for when the target gets into
+    /// a stuck state.
     pub resetn: RESETN,
+    /// Is the ESP32 WiFi target busy?
     pub ack: ACK,
 }
 
@@ -134,13 +155,9 @@ mod gpio_tests {
     use embedded_hal_mock::pin::{
         Mock as PinMock, State as PinState, Transaction as PinTransaction,
     };
-    use embedded_hal_mock::MockError;
-    use std::io::ErrorKind;
 
     #[test]
     fn gpio_init_sets_correct_state() {
-        let err = MockError::Io(ErrorKind::NotConnected);
-
         let cs_expectations = [PinTransaction::set(PinState::High)];
 
         let gpio0_expectations = [PinTransaction::set(PinState::High)];

esp32-wroom-rp/src/lib.rs

@@ -98,10 +98,12 @@ use embedded_hal::blocking::delay::DelayMs;
 
 const ARRAY_LENGTH_PLACEHOLDER: usize = 8;
 
+/// Highest level error types for this crate.
 #[derive(Debug)]
 pub enum Error {
-    // Placeholder variants
+    /// SPI/I2C related communications error with the ESP32 WiFi target
     Bus,
+    /// Timeout in communicating with the ESP32 WiFi target
     TimeOut,
 }
 

esp32-wroom-rp/src/protocol.rs

@@ -98,7 +98,7 @@ impl NinaParam for NinaByteParam {
 
     fn from_bytes(bytes: &[u8]) -> Self {
         let mut data_as_bytes: Vec<u8, 1> = Vec::new();
-        data_as_bytes.extend_from_slice(bytes);
+        data_as_bytes.extend_from_slice(bytes).ok().unwrap();
         Self {
             length: data_as_bytes.len() as u8,
             data: data_as_bytes,
@@ -131,7 +131,7 @@ impl NinaParam for NinaWordParam {
 
     fn from_bytes(bytes: &[u8]) -> Self {
         let mut data_as_bytes: Vec<u8, 2> = Vec::new();
-        data_as_bytes.extend_from_slice(bytes);
+        data_as_bytes.extend_from_slice(bytes).ok().unwrap();
         Self {
             length: data_as_bytes.len() as u8,
             data: data_as_bytes,
@@ -164,7 +164,7 @@ impl NinaParam for NinaSmallArrayParam {
 
     fn from_bytes(bytes: &[u8]) -> Self {
         let mut data_as_bytes: Vec<u8, MAX_NINA_PARAM_LENGTH> = Vec::new();
-        data_as_bytes.extend_from_slice(bytes);
+        data_as_bytes.extend_from_slice(bytes).ok().unwrap();
         Self {
             length: data_as_bytes.len() as u8,
             data: data_as_bytes,
@@ -197,7 +197,7 @@ impl NinaParam for NinaLargeArrayParam {
 
     fn from_bytes(bytes: &[u8]) -> Self {
         let mut data_as_bytes: Vec<u8, MAX_NINA_PARAM_LENGTH> = Vec::new();
-        data_as_bytes.extend_from_slice(bytes);
+        data_as_bytes.extend_from_slice(bytes).ok().unwrap();
         Self {
             length: data_as_bytes.len() as u16,
             data: data_as_bytes,

esp32-wroom-rp/src/protocol/operation.rs

@@ -30,15 +30,15 @@ impl<P> Operation<P> {
     // builds up an internal byte stream representing one Nina command
     // on the data bus.
     pub fn param(mut self, param: P) -> Self {
-        self.params.push(param);
+        self.params.push(param).ok().unwrap();
         self
     }
 
     // Used for denoting an Operation where no params are provided.
     //
     // Sets `has_params` to `false`
     pub fn with_no_params(mut self, no_param: P) -> Self {
-        self.params.push(no_param);
+        self.params.push(no_param).ok().unwrap();
         self.has_params = false;
         self
     }

esp32-wroom-rp/src/spi.rs

@@ -23,6 +23,7 @@ enum ControlByte {
     Error = 0xEFu8,
 }
 
+/// Fundamental struct for controlling a connected ESP32-WROOM NINA firmware-based Wifi board.
 #[derive(Debug, Default)]
 pub struct Wifi<B, C> {
     common: WifiCommon<NinaProtocolHandler<B, C>>,
@@ -68,6 +69,10 @@ where
         self.common.leave()
     }
 
+    /// Retrieves the current WiFi network connection status.
+    /// 
+    /// NOTE: A future version will provide a enumerated type instead of the raw integer values
+    /// from the NINA firmware.
     pub fn get_connection_status(&mut self) -> Result<u8, Error> {
         self.common.get_connection_status()
     }
@@ -93,7 +98,7 @@ where
         let operation =
             Operation::new(NinaCommand::GetFwVersion, 1).with_no_params(NinaNoParams::new(""));
 
-        self.execute(&operation);
+        self.execute(&operation).ok().unwrap();
 
         let result = self.receive(&operation)?;
 
@@ -105,17 +110,17 @@ where
             .param(NinaSmallArrayParam::new(ssid))
             .param(NinaSmallArrayParam::new(passphrase));
 
-        self.execute(&operation);
+        self.execute(&operation).ok().unwrap();
 
-        self.receive(&operation);
+        self.receive(&operation).ok().unwrap();
         Ok(())
     }
 
     fn get_conn_status(&mut self) -> Result<u8, self::Error> {
         let operation =
             Operation::new(NinaCommand::GetConnStatus, 1).with_no_params(NinaNoParams::new(""));
 
-        self.execute(&operation);
+        self.execute(&operation).ok().unwrap();
 
         let result = self.receive(&operation)?;
 
@@ -126,9 +131,9 @@ where
         let dummy_param = NinaByteParam::from_bytes(&[ControlByte::Dummy as u8]);
         let operation = Operation::new(NinaCommand::Disconnect, 1).param(dummy_param);
 
-        self.execute(&operation);
+        self.execute(&operation).ok().unwrap();
 
-        self.receive(&operation);
+        self.receive(&operation).ok().unwrap();
 
         Ok(())
     }
@@ -143,16 +148,16 @@ where
         let mut param_size: u16 = 0;
         self.control_pins.wait_for_esp_select();
 
-        self.send_cmd(&operation.command, operation.params.len() as u8);
+        self.send_cmd(&operation.command, operation.params.len() as u8).ok().unwrap();
 
         // Only send params if they are present
         if operation.has_params {
             operation.params.iter().for_each(|param| {
-                self.send_param(param);
+                self.send_param(param).ok().unwrap();
                 param_size += param.length();
             });
 
-            self.send_end_cmd();
+            self.send_end_cmd().ok().unwrap();
 
             // This is to make sure we align correctly
             // 4 (start byte, command byte, reply byte, end byte) + the sum of all param lengths
@@ -320,6 +325,7 @@ where
     }
 }
 
+#[allow(dead_code)]
 /// Error which occurred during a SPI transaction with a target ESP32 device
 #[derive(Clone, Copy, Debug)]
 pub enum SPIError<SPIE, IOE> {

host-tests/tests/spi.rs

@@ -1,4 +1,2 @@
-use std::{thread, time::Duration};
-
 #[test]
 fn do_something_with_spi_succeeds() {}