rpi_host/
lib.rs

1//! # rpi-host
2//!
3//! A library for controlling the Raspberry Pi 5 wireless interface, enabling easy switching
4//! between WiFi client mode and hotspot (access point) mode.
5//!
6//! ## Features
7//!
8//! - **Client Mode**: Connect to WiFi networks with SSID and optional password
9//! - **Hotspot Mode**: Create a WiFi access point for other devices to connect to
10//! - **Network Scanning**: Discover available WiFi networks with signal strength
11//! - **Internet Connectivity**: Validate internet access with multiple fallback targets
12//! - **Easy-to-use API**: High-level interface for common WiFi operations
13//!
14//! ## Requirements
15//!
16//! - Raspberry Pi with wireless interface (tested on Pi 5)
17//! - NetworkManager installed and running (default on Raspberry Pi OS Bookworm+)
18//! - Root/sudo permissions for WiFi operations
19//!
20//! ## Quick Start
21//!
22//! ### Connect to a WiFi Network
23//!
24//! ```no_run
25//! use rpi_host::WifiManager;
26//!
27//! fn main() -> Result<(), rpi_host::WifiError> {
28//!     let wifi = WifiManager::new()?;
29//!
30//!     // Connect to a network
31//!     wifi.connect("MyNetwork", Some("password123"))?;
32//!
33//!     // Check if we have internet
34//!     if wifi.has_internet()? {
35//!         println!("Connected to the internet!");
36//!     }
37//!
38//!     Ok(())
39//! }
40//! ```
41//!
42//! ### Create a Hotspot
43//!
44//! ```no_run
45//! use rpi_host::WifiManager;
46//!
47//! fn main() -> Result<(), rpi_host::WifiError> {
48//!     let wifi = WifiManager::new()?;
49//!
50//!     // Start a hotspot (password must be 8+ characters)
51//!     wifi.start_hotspot("Pi-Hotspot", Some("mypassword"))?;
52//!
53//!     // Check current mode
54//!     println!("Current mode: {}", wifi.get_mode()?);
55//!
56//!     Ok(())
57//! }
58//! ```
59//!
60//! ### Scan for Networks
61//!
62//! ```no_run
63//! use rpi_host::WifiManager;
64//!
65//! fn main() -> Result<(), rpi_host::WifiError> {
66//!     let wifi = WifiManager::new()?;
67//!
68//!     // Scan for available networks
69//!     for network in wifi.scan()? {
70//!         println!("{}: {}% signal, {}",
71//!             network.ssid,
72//!             network.signal_strength,
73//!             network.security
74//!         );
75//!     }
76//!
77//!     Ok(())
78//! }
79//! ```
80//!
81//! ### Advanced Hotspot Configuration
82//!
83//! ```no_run
84//! use rpi_host::{WifiManager, HotspotConfig, HotspotBand};
85//!
86//! fn main() -> Result<(), rpi_host::WifiError> {
87//!     let wifi = WifiManager::new()?;
88//!
89//!     // Create a 5GHz hotspot with custom settings
90//!     let config = HotspotConfig::new("My5GHotspot")
91//!         .with_password("securepassword")
92//!         .with_band(HotspotBand::A)  // 5GHz
93//!         .with_channel(36);
94//!
95//!     wifi.start_hotspot_with_config(config)?;
96//!
97//!     Ok(())
98//! }
99//! ```
100//!
101//! ## Switching Modes
102//!
103//! The library handles mode switching automatically. When you call `connect()` while
104//! in hotspot mode, it will stop the hotspot first. Similarly, `start_hotspot()` will
105//! disconnect from any current network.
106//!
107//! ```no_run
108//! use rpi_host::WifiManager;
109//!
110//! fn main() -> Result<(), rpi_host::WifiError> {
111//!     let wifi = WifiManager::new()?;
112//!
113//!     // Start in client mode
114//!     wifi.connect("HomeNetwork", Some("homepass"))?;
115//!
116//!     // ... later, switch to hotspot mode
117//!     wifi.start_hotspot("PiAP", Some("appassword"))?;
118//!
119//!     // ... later, switch back to client mode
120//!     wifi.connect("HomeNetwork", Some("homepass"))?;
121//!
122//!     Ok(())
123//! }
124//! ```
125
126mod error;
127mod manager;
128mod nmcli;
129mod types;
130
131// Re-export public types
132pub use error::{WifiError, WifiResult};
133pub use manager::WifiManager;
134pub use types::{
135    ConnectionStatus, ConnectivityResult, HotspotBand, HotspotConfig, NetworkInfo, SecurityType,
136    WifiMode,
137};
rpi_host/lib.rs

rpi_host/
lib.rs
