docs: document most of esp-hosted driver

This commit is contained in:
Ulf Lilleengen 2023-12-20 10:09:05 +01:00
parent 52a801fdb7
commit abea4dde3d
3 changed files with 28 additions and 0 deletions

View File

@ -5,6 +5,7 @@ use heapless::String;
use crate::ioctl::Shared; use crate::ioctl::Shared;
use crate::proto::{self, CtrlMsg}; use crate::proto::{self, CtrlMsg};
/// Errors reported by control.
#[derive(Copy, Clone, PartialEq, Eq, Debug)] #[derive(Copy, Clone, PartialEq, Eq, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))] #[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Error { pub enum Error {
@ -13,30 +14,42 @@ pub enum Error {
Internal, Internal,
} }
/// Handle for managing the network and WiFI state.
pub struct Control<'a> { pub struct Control<'a> {
state_ch: ch::StateRunner<'a>, state_ch: ch::StateRunner<'a>,
shared: &'a Shared, shared: &'a Shared,
} }
/// WiFi mode.
#[allow(unused)] #[allow(unused)]
#[derive(Copy, Clone, PartialEq, Eq, Debug)] #[derive(Copy, Clone, PartialEq, Eq, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))] #[cfg_attr(feature = "defmt", derive(defmt::Format))]
enum WifiMode { enum WifiMode {
/// No mode.
None = 0, None = 0,
/// Client station.
Sta = 1, Sta = 1,
/// Access point mode.
Ap = 2, Ap = 2,
/// Repeater mode.
ApSta = 3, ApSta = 3,
} }
pub use proto::CtrlWifiSecProt as Security; pub use proto::CtrlWifiSecProt as Security;
/// WiFi status.
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))] #[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct Status { pub struct Status {
/// Service Set Identifier.
pub ssid: String<32>, pub ssid: String<32>,
/// Basic Service Set Identifier.
pub bssid: [u8; 6], pub bssid: [u8; 6],
/// Received Signal Strength Indicator.
pub rssi: i32, pub rssi: i32,
/// WiFi channel.
pub channel: u32, pub channel: u32,
/// Security mode.
pub security: Security, pub security: Security,
} }
@ -65,6 +78,7 @@ impl<'a> Control<'a> {
Self { state_ch, shared } Self { state_ch, shared }
} }
/// Initialize device.
pub async fn init(&mut self) -> Result<(), Error> { pub async fn init(&mut self) -> Result<(), Error> {
debug!("wait for init event..."); debug!("wait for init event...");
self.shared.init_wait().await; self.shared.init_wait().await;
@ -82,6 +96,7 @@ impl<'a> Control<'a> {
Ok(()) Ok(())
} }
/// Get the current status.
pub async fn get_status(&mut self) -> Result<Status, Error> { pub async fn get_status(&mut self) -> Result<Status, Error> {
let req = proto::CtrlMsgReqGetApConfig {}; let req = proto::CtrlMsgReqGetApConfig {};
ioctl!(self, ReqGetApConfig, RespGetApConfig, req, resp); ioctl!(self, ReqGetApConfig, RespGetApConfig, req, resp);
@ -95,6 +110,7 @@ impl<'a> Control<'a> {
}) })
} }
/// Connect to the network identified by ssid using the provided password.
pub async fn connect(&mut self, ssid: &str, password: &str) -> Result<(), Error> { pub async fn connect(&mut self, ssid: &str, password: &str) -> Result<(), Error> {
let req = proto::CtrlMsgReqConnectAp { let req = proto::CtrlMsgReqConnectAp {
ssid: unwrap!(String::try_from(ssid)), ssid: unwrap!(String::try_from(ssid)),
@ -108,6 +124,7 @@ impl<'a> Control<'a> {
Ok(()) Ok(())
} }
/// Disconnect from any currently connected network.
pub async fn disconnect(&mut self) -> Result<(), Error> { pub async fn disconnect(&mut self) -> Result<(), Error> {
let req = proto::CtrlMsgReqGetStatus {}; let req = proto::CtrlMsgReqGetStatus {};
ioctl!(self, ReqDisconnectAp, RespDisconnectAp, req, resp); ioctl!(self, ReqDisconnectAp, RespDisconnectAp, req, resp);

View File

@ -97,12 +97,14 @@ enum InterfaceType {
const MAX_SPI_BUFFER_SIZE: usize = 1600; const MAX_SPI_BUFFER_SIZE: usize = 1600;
const HEARTBEAT_MAX_GAP: Duration = Duration::from_secs(20); const HEARTBEAT_MAX_GAP: Duration = Duration::from_secs(20);
/// Shared driver state.
pub struct State { pub struct State {
shared: Shared, shared: Shared,
ch: ch::State<MTU, 4, 4>, ch: ch::State<MTU, 4, 4>,
} }
impl State { impl State {
/// Shared state for the
pub fn new() -> Self { pub fn new() -> Self {
Self { Self {
shared: Shared::new(), shared: Shared::new(),
@ -111,8 +113,13 @@ impl State {
} }
} }
/// Type alias for network driver.
pub type NetDriver<'a> = ch::Device<'a, MTU>; pub type NetDriver<'a> = ch::Device<'a, MTU>;
/// Create a new esp-hosted driver using the provided state, SPI peripheral and pins.
///
/// Returns a device handle for interfacing with embassy-net, a control handle for
/// interacting with the driver, and a runner for communicating with the WiFi device.
pub async fn new<'a, SPI, IN, OUT>( pub async fn new<'a, SPI, IN, OUT>(
state: &'a mut State, state: &'a mut State,
spi: SPI, spi: SPI,
@ -144,6 +151,7 @@ where
(device, Control::new(state_ch, &state.shared), runner) (device, Control::new(state_ch, &state.shared), runner)
} }
/// Runner for communicating with the WiFi device.
pub struct Runner<'a, SPI, IN, OUT> { pub struct Runner<'a, SPI, IN, OUT> {
ch: ch::Runner<'a, MTU>, ch: ch::Runner<'a, MTU>,
state_ch: ch::StateRunner<'a>, state_ch: ch::StateRunner<'a>,
@ -166,6 +174,7 @@ where
{ {
async fn init(&mut self) {} async fn init(&mut self) {}
/// Run the packet processing.
pub async fn run(mut self) -> ! { pub async fn run(mut self) -> ! {
debug!("resetting..."); debug!("resetting...");
self.reset.set_low().unwrap(); self.reset.set_low().unwrap();

View File

@ -1,3 +1,5 @@
#![allow(missing_docs)]
use heapless::{String, Vec}; use heapless::{String, Vec};
/// internal supporting structures for CtrlMsg /// internal supporting structures for CtrlMsg