Pre beta fixups

esp-radio/src/lib.rs

@@ -6,27 +6,31 @@
 //!
 //! This documentation is built for the
 #![doc = concat!("**", chip_pretty!(), "**")]
-//! . Please ensure you are reading the correct [documentation](https://docs.espressif.com/projects/rust/esp-radio/latest/) for your target
+//! . Please ensure you are reading the correct [documentation] for your target
 //! device.
 //!
-//! ## Usage
+//! ## Overview
 //!
-//! ### Importing
+//! esp-radio provides Wi-Fi, Bluetooth Low Energy (BLE), ESP-NOW and IEEE
+//! 802.15.4 drivers for Espressif microcontrollers. It builds on top of
+//! [esp-hal] and the vendor binary blobs to provide wireless connectivity in a
+//! `no_std` environment.
 //!
-//! Enabling the `unstable` feature on `esp-radio` requires you to also enable
-//! the `unstable` feature on `esp-hal` in the final binary crate.
-//!
-//! Ensure that the right features are enabled for your chip. See [Examples](https://github.com/esp-rs/esp-hal/tree/main/examples#examples) for more examples.
-//!
-//! You will also need a dynamic memory allocator, and a preemptive task scheduler in your
-//! application. For the dynamic allocator, we recommend using `esp-alloc`. For the task scheduler,
-//! the simplest option that is supported by us is `esp-rtos`, but you may use Ariel
-//! OS or other operating systems as well.
+//! Wi-Fi and BLE require a dynamic memory allocator and a preemptive task
+//! scheduler at runtime. We recommend [`esp-alloc`] and [`esp-rtos`] for this,
+//! though any allocator or RTOS (such as Ariel OS) that implements the required
+//! interfaces will work.
 #![cfg_attr(
     feature = "ieee802154",
-    doc = "<div class=\"warning\"><b>Hint:</b> The scheduler is not required for the 802.15.4.</div>"
+    doc = "<div class=\"warning\"><b>Hint:</b> The scheduler is not required for IEEE 802.15.4.</div>"
 )]
-#![doc = ""]
+//! Drivers that don't currently have a stable API are marked as `unstable` in
+//! the documentation. Enabling the `unstable` feature on `esp-radio` requires
+//! you to also enable the `unstable` feature on `esp-hal` in the final binary
+//! crate.
+//!
+//! ### Quick start
+//!
 //! ```rust, no_run
 #![doc = esp_hal::before_snippet!()]
 //! use esp_hal::interrupt::software::SoftwareInterruptControl;
@@ -46,7 +50,7 @@
     wifi_driver_supported,
     doc = r#"
 
-if let Ok(controller) = esp_radio::wifi::new(
+if let Ok(controller) = esp_radio::wifi::WifiController::new(
     peripherals.WIFI,
     Default::default(),
 ) {}
@@ -72,26 +76,52 @@ if let Ok(controller) = BleConnector::new(peripherals.BT, Default::default()) {}
 #![doc = concat!(r#"features = [""#, chip!(), r#""]"#)]
 //! ```
 //! 
-//! ### Optimization Level
+//! ## Examples
+//!
+//! We have a number of [examples] in the esp-hal repository. We use
+//! an [xtask] to automate the building, running, and testing of code and
+//! examples within esp-hal.
+//!
+//! Invoke the following command in the root of the esp-hal repository to get
+//! started:
+//! ```bash
+//! cargo xtask help
+//! ```
+//! 
+//! We have a [book] that explains the full esp-hal ecosystem
+//! and how to get started, and a [training] that covers some common
+//! scenarios with examples.
 //!
-//! It is necessary to build with optimization level 2 or 3 since otherwise, it
-//! might not even be able to connect or advertise.
+//! ## Optimization level
 //!
-//! To make it work also for your debug builds add this to your `Cargo.toml`
+//! The radio blobs require optimization level 2 or 3 to function correctly.
+//! Without it, Wi-Fi may fail to connect and BLE may fail to advertise.
+//!
+//! To apply this only to esp-radio in debug builds, add to your `Cargo.toml`:
 //! ```toml
 //! [profile.dev.package.esp-radio]
 //! opt-level = 3
 //! ```
-//! ## Globally disable logging
+//! 
+//! ## Disabling logging
+//!
+//! `esp-radio` contains trace-level logging statements that may impact
+//! performance. To disable them, use the `log` crate's compile-time
+//! [filters](https://docs.rs/log/latest/log/#compile-time-filters) and set
+//! `release_max_level_off`.
 //!
-//! `esp-radio` contains a lot of trace-level logging statements.
-//! For maximum performance you might want to disable logging via
-//! a feature flag of the `log` crate. See [documentation](https://docs.rs/log/0.4.19/log/#compile-time-filters).
-//! You should set it to `release_max_level_off`.
+//! [documentation]: https://docs.espressif.com/projects/rust/esp-radio/latest/
+//! [esp-hal]: https://docs.espressif.com/projects/rust/esp-hal/latest/
+//! [`esp-alloc`]: https://docs.espressif.com/projects/rust/esp-alloc/latest/
+//! [`esp-rtos`]: https://docs.espressif.com/projects/rust/esp-rtos/latest/
+//! [examples]: https://github.com/esp-rs/esp-hal/tree/main/examples
+//! [xtask]: https://github.com/matklad/cargo-xtask
+//! [book]: https://docs.espressif.com/projects/rust/book/
+//! [training]: https://docs.espressif.com/projects/rust/no_std-training/
 #![cfg_attr(
     multi_core,
     doc = concat!(
-        "### Running on the Second Core",
+        "## Running on the second core",
         "\n\n",
         "BLE and Wi-Fi can also be run on the second core.",
         "\n\n",

esp-radio/src/wifi/ap.rs

@@ -7,7 +7,7 @@ use procmacros::BuilderLite;
 
 #[cfg(feature = "unstable")]
 use super::CountryInfo;
-use super::{AuthenticationMethod, Protocols, SecondaryChannel, Ssid};
+use super::{AuthenticationMethod, DisconnectReason, Protocols, SecondaryChannel, Ssid};
 use crate::{WifiError, sys::include::wifi_ap_record_t};
 
 /// Information about a detected Wi-Fi access point.
@@ -53,8 +53,10 @@ pub struct AccessPointConfig {
     #[builder_lite(reference)]
     pub(crate) password: String,
     /// The maximum number of connections allowed on the access point.
+    #[builder_lite(unstable)]
     pub(crate) max_connections: u16,
     /// Dtim period of the access point (Range: 1 ~ 10).
+    #[builder_lite(unstable)]
     pub(crate) dtim_period: u8,
     /// Time to force deauth the station if the Soft-AccessPoint doesn't receive any data.
     #[builder_lite(unstable)]
@@ -149,6 +151,44 @@ impl defmt::Format for AccessPointConfig {
     }
 }
 
+/// Information about a station connected to the access point.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[non_exhaustive]
+pub struct ConnectedInfo {
+    /// The MAC address.
+    pub mac: [u8; 6],
+    /// The Association ID (AID) of the connected station.
+    pub aid: u16,
+    /// If this is a mesh child.
+    pub is_mesh_child: bool,
+}
+
+/// Information about a station disconnected from the access point.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[non_exhaustive]
+pub struct DisconnectedInfo {
+    /// The MAC address.
+    pub mac: [u8; 6],
+    /// The Association ID (AID) of the connected station.
+    pub aid: u16,
+    /// If this is a mesh child.
+    pub is_mesh_child: bool,
+    /// The disconnect reason.
+    pub reason: DisconnectReason,
+}
+
+/// Either the [ConnectedInfo] or [DisconnectedInfo].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum EventInfo {
+    /// Information about a station connected to the access point.
+    Connected(ConnectedInfo),
+    /// Information about a station disconnected from the access point.
+    Disconnected(DisconnectedInfo),
+}
+
 #[allow(non_upper_case_globals)]
 pub(crate) fn convert_ap_info(record: &wifi_ap_record_t) -> AccessPointInfo {
     let str_len = record

esp-radio/src/wifi/event.rs

@@ -1289,7 +1289,8 @@ pub fn enable_wifi_events(events: EnumSet<WifiEvent>) {
 /// - [WifiEvent::AccessPointStationDisconnected]
 /// - [WifiEvent::ScanDone]
 ///
-/// [crate::wifi::new] always enables these events, even if they were disabled beforehand.
+/// [crate::wifi::WifiController::new] always enables these events, even if they were disabled
+/// beforehand.
 #[instability::unstable]
 pub fn disable_wifi_events(events: EnumSet<WifiEvent>) {
     WIFI_EVENT_ENABLE_MASK.with(|mask| *mask &= !events);