Adds an example to the Wifi module and cleans up some public type documentation

Author: jhodapp

esp32-wroom-rp/src/lib.rs

@@ -7,19 +7,19 @@
 //!
 //! It's intended to communicate with recent versions of most [Arduino-derived WiFiNINA firmwares](https://www.arduino.cc/reference/en/libraries/wifinina/)
 //! that run on an ESP32-WROOM-XX WiFi module. For example, Adafruit makes such WiFi hardware, referred to as the [Airlift](https://www.adafruit.com/product/4201), and maintains its [firmware](https://github.com/adafruit/nina-fw).
-//! 
+//!
 //! This driver is implemented on top of [embedded-hal](https://github.com/rust-embedded/embedded-hal/), which makes it platform-independent, but is currently only intended
 //! to be used with [rp2040-hal](https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal) for your application.
-//! 
+//!
 //! Please see the README.md for details on where to obtain and how to connect your RP2040-based device (e.g. Pico) to your ESP32-WROOM-XX WiFi board.
-//! 
+//!
 //! Once connected, note that all communication with the WiFi board occurs via a SPI bus. As the example below (and all examples under the directory `cross/`)
 //! show, you first need to create an `embedded_hal::spi::Spi` instance. See the [rp2040-hal documentation](https://docs.rs/rp2040-hal/0.6.0/rp2040_hal/spi/index.html) along
 //! with the datasheet for your device on what specific SPI ports are available to you.
-//! 
+//!
 //! You'll also need to reserve 4 important [GPIO pins](https://docs.rs/rp2040-hal/0.6.0/rp2040_hal/gpio/index.html) (3 output, 1 input) that are used to mediate communication between the two boards. The examples
 //! also demonstrate how to do this through instantiating an instance of `esp32_wroom_rp::gpio::EspControlPins`.
-//! 
+//!
 //! **NOTE:** This crate is still under active development. This API will remain volatile until 1.0.0.
 //!
 //! ## Usage
@@ -50,7 +50,7 @@
 //! use fugit::RateExtU32;
 //! use hal::clocks::Clock;
 //! use hal::pac;
-//! 
+//!
 //! use esp32_wroom_rp::gpio::EspControlPins;
 //! use esp32_wroom_rp::wifi::Wifi;
 //!
@@ -59,11 +59,11 @@
 //! #[link_section = ".boot2"]
 //! #[used]
 //! pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_W25Q080;
-//! 
+//!
 //! // External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
 //! // if your board has a different frequency
 //! const XTAL_FREQ_HZ: u32 = 12_000_000u32;
-//! 
+//!
 //! // Entry point to our bare-metal application.
 //! //
 //! // The `#[entry]` macro ensures the Cortex-M start-up code calls this function
@@ -138,11 +138,11 @@
 //!     loop {}
 //! }
 //! ```
-//! 
+//!
 //! ## More examples
-//! 
+//!
 //! Please refer to the `cross/` directory in this crate's source for examples that demonstrate how to use every part of its public API.
-//! 
+//!
 
 #![doc(html_root_url = "https://docs.rs/esp32-wroom-rp")]
 #![doc(issue_tracker_base_url = "https://github.com/Jim-Hodapp-Coaching/esp32-wroom-rp/issues")]

esp32-wroom-rp/src/network.rs

@@ -1,10 +1,5 @@
 //! Defines common network functions, types and error definitions.
 //!
-//! ## Usage
-//!
-//! ```no_run
-//! ```
-//!
 
 use defmt::{write, Format, Formatter};
 

esp32-wroom-rp/src/protocol.rs

@@ -1,10 +1,5 @@
 //! Defines functions, types and error definitions related to the WiFiNINA protocol communication specification.
 //!
-//! ## Usage
-//!
-//! ```no_run
-//! ```
-//!
 
 pub(crate) mod operation;
 

esp32-wroom-rp/src/spi.rs

@@ -1,4 +1,10 @@
-//! Serial Peripheral Interface (SPI) for Wifi
+//! Serial Peripheral Interface (SPI)
+//!
+//! Contains all SPI bus related structs, types and errors. Also responsible for
+//! implementing WifiNINA protocol communication over a selected SPI interface.
+//!
+//! Note: Currently everything in this file is private and considered internal to the crate.
+//!
 use core::convert::Infallible;
 
 use embedded_hal::blocking::delay::DelayMs;

esp32-wroom-rp/src/tcp_client.rs

@@ -39,7 +39,7 @@
 //!     );
 //! }
 //! ```
-//! 
+//!
 
 use embedded_hal::blocking::delay::DelayMs;
 use embedded_hal::blocking::spi::Transfer;

esp32-wroom-rp/src/wifi.rs

@@ -3,6 +3,52 @@
 //! ## Usage
 //!
 //! ```no_run
+//! let mut wifi = Wifi::init(spi, esp_pins, &mut delay).unwrap();
+//!
+//! let result = wifi.join(ssid, passphrase);
+//! defmt::info!("Join Result: {:?}", result);
+//!
+//! defmt::info!("Entering main loop");
+//!
+//! let mut sleep: u32 = 1500;
+//! loop {
+//!     match wifi.get_connection_status() {
+//!         Ok(status) => {
+//!             defmt::info!("Connection status: {:?}", status);
+//!             delay.delay_ms(sleep);
+//!
+//!             if status == ConnectionStatus::Connected {
+//!                 defmt::info!("Connected to network: {:?}", SSID);
+//!
+//!                 // The IPAddresses of two DNS servers to resolve hostnames with.
+//!                 // Note that failover from ip1 to ip2 is fully functional.
+//!                 let ip1: IpAddress = [9, 9, 9, 9];
+//!                 let ip2: IpAddress = [8, 8, 8, 8];
+//!                 let dns_result = wifi.set_dns(ip1, Some(ip2));
+//!
+//!                 defmt::info!("set_dns result: {:?}", dns_result);
+//!
+//!                 match wifi.resolve(hostname) {
+//!                     Ok(ip) => {
+//!                         defmt::info!("Server IP: {:?}", ip);
+//!                     }
+//!                     Err(e) => {
+//!                         defmt::error!("Failed to resolve hostname {}", hostname);
+//!                         defmt::error!("Err: {}", e);
+//!                     }
+//!                 }
+//!
+//!                 defmt::info!("Leaving network: {:?}", ssid);
+//!                 wifi.leave().ok();
+//!             } else if status == ConnectionStatus::Disconnected {
+//!                 sleep = 20000; // No need to loop as often after disconnecting
+//!             }
+//!         }
+//!         Err(e) => {
+//!             defmt::error!("Failed to get connection result: {:?}", e);
+//!         }
+//!     }
+//! }
 //! ```
 //!
 
@@ -98,7 +144,7 @@ impl Format for ConnectionStatus {
     }
 }
 
-/// Fundamental struct for controlling a connected ESP32-WROOM NINA firmware-based Wifi board.
+/// Base type for controlling an ESP32-WROOM NINA firmware-based WiFi board.
 #[derive(Debug)]
 pub struct Wifi<B, C> {
     pub(crate) protocol_handler: RefCell<NinaProtocolHandler<B, C>>,
@@ -109,8 +155,8 @@ where
     S: Transfer<u8>,
     C: EspControlInterface,
 {
-    /// Initializes the ESP32-WROOM Wifi device.
-    /// Calling this function puts the connected ESP32-WROOM device in a known good state to accept commands.
+    /// Initialize the ESP32-WROOM WiFi device.
+    /// Call this function to put the connected ESP32-WROOM device in a known good state to accept commands.
     pub fn init<D: DelayMs<u16>>(
         spi: S,
         esp32_control_pins: C,
@@ -128,42 +174,42 @@ where
         Ok(wifi)
     }
 
-    /// Retrieves the NINA firmware version contained on the connected ESP32-WROOM device (e.g. 1.7.4).
+    /// Retrieve the NINA firmware version contained on the connected ESP32-WROOM device (e.g. 1.7.4).
     pub fn firmware_version(&mut self) -> Result<FirmwareVersion, Error> {
         self.protocol_handler.borrow_mut().get_fw_version()
     }
 
-    /// Joins a WiFi network given an SSID and a Passphrase.
+    /// Join a WiFi network given an SSID and a Passphrase.
     pub fn join(&mut self, ssid: &str, passphrase: &str) -> Result<(), Error> {
         self.protocol_handler
             .borrow_mut()
             .set_passphrase(ssid, passphrase)
     }
 
-    /// Disconnects from a joined WiFi network.
+    /// Disconnect from a previously joined WiFi network.
     pub fn leave(&mut self) -> Result<(), Error> {
         self.protocol_handler.borrow_mut().disconnect()
     }
 
-    /// Retrieves the current WiFi network connection status.
+    /// Retrieve the current WiFi network [`ConnectionStatus`].
     pub fn get_connection_status(&mut self) -> Result<ConnectionStatus, Error> {
         self.protocol_handler.borrow_mut().get_conn_status()
     }
 
-    /// Sets 1 or 2 DNS servers that are used for network hostname resolution.
+    /// Set 1 or 2 DNS servers that are used for network hostname resolution.
     pub fn set_dns(&mut self, dns1: IpAddress, dns2: Option<IpAddress>) -> Result<(), Error> {
         self.protocol_handler
             .borrow_mut()
             .set_dns_config(dns1, dns2)
     }
 
-    /// Queries the DNS server(s) provided via [set_dns] for the associated IP address to the provided hostname.
+    /// Query the DNS server(s) provided via [`set_dns`] for the associated IP address to the provided hostname.
     pub fn resolve(&mut self, hostname: &str) -> Result<IpAddress, Error> {
         self.protocol_handler.borrow_mut().resolve(hostname)
     }
 
-    /// Provides a reference to the `Spi` bus instance typically used when cleaning up
-    /// an instance of `Wifi`.
+    /// Return a reference to the `Spi` bus instance typically used when cleaning up
+    /// an instance of [`Wifi`].
     pub fn destroy(self) -> S {
         self.protocol_handler.into_inner().bus.into_inner()
     }