Skip to main content

wifi_station/
lib.rs

1//! Async WiFi station (STA) lifecycle manager for embedded Linux.
2//!
3//! `wifi-station` runs and supervises a `wlan1` STA interface alongside an
4//! existing `wlan0` AP on dongles and MiFi-style devices, so a host can roam
5//! onto upstream WiFi while continuing to serve its own clients.
6//!
7//! It targets the messy realities of small embedded systems: quirky vendor
8//! drivers, busybox userspace, AP+STA coexistence locks, kernel module crashes,
9//! and stalled data paths. Recovery is built in.
10//!
11//! # Mental model
12//!
13//! [`run_wifi_client`] spawns a long-lived Tokio task that creates the STA
14//! interface, runs `wpa_supplicant` and `udhcpc`, installs policy routing so
15//! STA traffic does not displace an existing default route (e.g. cellular
16//! `rmnet`), and watches the link. When the data path stalls or the interface
17//! disappears it walks a graduated recovery ladder — `wpa_cli reassociate`,
18//! `wpa_supplicant` restart, interface cycle, and finally a full `wlan.ko`
19//! `rmmod`/`insmod` — before giving up after a fixed cap.
20//!
21//! Live state is published through a [`WifiStatus`] held behind an
22//! `Arc<RwLock<_>>` so the rest of the application can read it. Shutdown is
23//! cooperative via a [`CancellationToken`].
24//!
25//! [`CancellationToken`]: tokio_util::sync::CancellationToken
26//!
27//! # Quick start
28//!
29//! ```no_run
30//! use std::sync::Arc;
31//! use tokio::sync::RwLock;
32//! use tokio_util::sync::CancellationToken;
33//! use tokio_util::task::TaskTracker;
34//! use wifi_station::{WifiConfig, WifiStatus, run_wifi_client};
35//!
36//! # async fn run() {
37//! let tasks = TaskTracker::new();
38//! let shutdown = CancellationToken::new();
39//! let status = Arc::new(RwLock::new(WifiStatus::default()));
40//!
41//! let config = WifiConfig { wifi_enabled: true, ..Default::default() };
42//! run_wifi_client(&tasks, &config, shutdown.clone(), status.clone());
43//!
44//! // ...later, on shutdown:
45//! shutdown.cancel();
46//! tasks.close();
47//! tasks.wait().await;
48//! # }
49//! ```
50//!
51//! Provisioning a network means writing the `wpa_supplicant` config file
52//! before (or while) the supervisor is running; [`format_wpa_conf`] and
53//! [`update_wpa_conf`] are safe writers that escape user-supplied SSIDs and
54//! passwords. [`scan_wifi_networks`] performs a one-shot scan via `iw`.
55//!
56//! # Runtime requirements
57//!
58//! The host must provide `iw`, `wpa_supplicant`, `udhcpc`, `ip`, and
59//! `killall` on `PATH` (or paths configured via [`WifiConfig`]).
60//! Module-reload recovery additionally uses `rmmod`, `insmod`, `hostapd`,
61//! `brctl`, and `ifconfig`. Defaults match a typical busybox + Android-derived
62//! rootfs.
63//!
64//! # Cargo features
65//!
66//! - `utoipa` — derives `utoipa::ToSchema` on [`WifiStatus`], [`WifiState`],
67//!   [`SecurityType`], and [`WifiNetwork`] for inclusion in OpenAPI specs.
68
69use std::path::Path;
70
71use serde::{Deserialize, Serialize};
72
73mod client;
74mod config;
75mod diagnostics;
76mod monitor;
77mod recovery;
78mod routing;
79mod scan;
80
81pub use config::{
82    format_wpa_conf, read_network_from_wpa_conf, read_ssid_from_wpa_conf, update_wpa_conf,
83};
84pub use monitor::run_wifi_client;
85pub use scan::{WifiNetwork, scan_wifi_networks};
86
87#[cfg(test)]
88pub(crate) use config::update_wpa_conf_at;
89#[cfg(test)]
90pub(crate) use routing::parse_default_route;
91#[cfg(test)]
92pub(crate) use scan::parse_iw_scan;
93
94#[derive(Clone, Default)]
95pub struct WifiConfig {
96    pub wifi_enabled: bool,
97    pub dns_servers: Option<Vec<String>>,
98    pub wifi_ssid: Option<String>,
99    pub wifi_password: Option<String>,
100    pub security_type: Option<SecurityType>,
101    pub wpa_supplicant_bin: Option<String>,
102    pub hostapd_conf: Option<String>,
103    pub ctrl_interface: Option<String>,
104    pub udhcpc_hook_path: Option<String>,
105    pub dhcp_lease_path: Option<String>,
106    pub wpa_conf_path: Option<String>,
107    pub iw_bin: Option<String>,
108    pub udhcpc_bin: Option<String>,
109    pub crash_log_dir: Option<String>,
110    pub wakelock_name: Option<String>,
111}
112
113#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
114#[serde(rename_all = "snake_case")]
115#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
116pub enum SecurityType {
117    #[default]
118    WpaPsk,
119    Sae,
120}
121
122pub(crate) const DEFAULT_WPA_CONF_PATH: &str = "/etc/wpa_supplicant/wpa_sta.conf";
123pub(crate) const DEFAULT_WPA_BIN: &str = "wpa_supplicant";
124pub(crate) const DEFAULT_IW_BIN: &str = "iw";
125pub(crate) const DEFAULT_UDHCPC_HOOK_PATH: &str = "/tmp/wifi-station-udhcpc-hook.sh";
126pub(crate) const DEFAULT_DHCP_LEASE_PATH: &str = "/tmp/wifi-station-dhcp-lease";
127pub(crate) const DEFAULT_CRASH_LOG_DIR: &str = "/tmp/wifi-station-crash-logs";
128pub(crate) const DEFAULT_WAKELOCK_NAME: &str = "wifi-station";
129
130pub(crate) const UDHCPC_HOOK_SCRIPT: &str = r#"#!/bin/sh
131LEASE_FILE="{}"
132
133case "$1" in
134    bound|renew)
135        ip addr flush dev "$interface"
136        ip addr add "$ip/$mask" dev "$interface"
137        echo "gateway=$router" > "$LEASE_FILE"
138        echo "dns=$dns" >> "$LEASE_FILE"
139        ;;
140    deconfig)
141        ip addr flush dev "$interface"
142        rm -f "$LEASE_FILE"
143        ;;
144esac
145"#;
146pub(crate) const DEFAULT_DNS: &[&str] = &["9.9.9.9", "149.112.112.112"];
147pub(crate) const MAX_RECOVERY_ATTEMPTS: u32 = 5;
148pub(crate) const BASE_BACKOFF_SECS: u64 = 30;
149pub(crate) const HOSTAPD_CONF: &str = "/data/misc/wifi/hostapd.conf";
150pub(crate) const AP_IFACE: &str = "wlan0";
151pub const STA_IFACE: &str = "wlan1";
152
153/// Error prefix emitted when `iw interface add` can't create the STA iface.
154/// Matched in monitor.rs to decide whether a module reload should recover.
155pub(crate) const ERR_CREATE_STA: &str = "failed to create STA interface";
156
157const BRIDGE_CANDIDATES: &[&str] = &["bridge0", "br0"];
158
159pub fn detect_bridge_iface() -> &'static str {
160    for name in BRIDGE_CANDIDATES {
161        if Path::new(&format!("/sys/class/net/{name}")).exists() {
162            return name;
163        }
164    }
165    BRIDGE_CANDIDATES[0]
166}
167
168/// Possible wifi client states
169#[derive(Clone, Copy, PartialEq, Serialize, Default)]
170#[serde(rename_all = "camelCase")]
171#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
172pub enum WifiState {
173    #[default]
174    Disabled,
175    Connecting,
176    Connected,
177    Failed,
178    Recovering,
179    DataPathDead,
180}
181
182/// The status of the wifi client
183#[derive(Clone, Serialize, Default)]
184#[serde(rename_all = "camelCase")]
185#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
186pub struct WifiStatus {
187    /// The state of the wifi connection
188    pub state: WifiState,
189    #[serde(skip_serializing_if = "Option::is_none")]
190    /// Connected SSID
191    pub ssid: Option<String>,
192    #[serde(skip_serializing_if = "Option::is_none")]
193    /// Connected IP
194    pub ip: Option<String>,
195    #[serde(skip_serializing_if = "Option::is_none")]
196    /// String containing error messages
197    pub error: Option<String>,
198    #[serde(skip_serializing_if = "Option::is_none")]
199    /// Count of packets transmitted
200    pub tx_packets: Option<u64>,
201}
202
203#[cfg(test)]
204mod tests {
205    use super::*;
206
207    #[test]
208    fn test_parse_iw_scan_basic() {
209        let output = "\
210BSS aa:bb:cc:dd:ee:ff(on wlan1)
211\tTSF: 12345 usec
212\tfreq: 2412
213\tsignal: -45.00 dBm
214\tSSID: MyNetwork
215\tRSN:\t * Version: 1
216BSS 11:22:33:44:55:66(on wlan1)
217\tsignal: -72.00 dBm
218\tSSID: OtherNet
219\tWPA:\t * Version: 1
220";
221        let networks = parse_iw_scan(output);
222        assert_eq!(networks.len(), 2);
223        assert_eq!(networks[0].ssid, "MyNetwork");
224        assert_eq!(networks[0].signal_dbm, -45);
225        assert_eq!(networks[0].security, "WPA2");
226        assert_eq!(networks[1].ssid, "OtherNet");
227        assert_eq!(networks[1].signal_dbm, -72);
228        assert_eq!(networks[1].security, "WPA");
229    }
230
231    #[test]
232    fn test_parse_iw_scan_dedup_keeps_strongest() {
233        let output = "\
234BSS aa:bb:cc:dd:ee:ff(on wlan1)
235\tsignal: -80.00 dBm
236\tSSID: DupNet
237\tRSN:\t * Version: 1
238BSS 11:22:33:44:55:66(on wlan1)
239\tsignal: -50.00 dBm
240\tSSID: DupNet
241\tRSN:\t * Version: 1
242";
243        let networks = parse_iw_scan(output);
244        assert_eq!(networks.len(), 1);
245        assert_eq!(networks[0].ssid, "DupNet");
246        assert_eq!(networks[0].signal_dbm, -50);
247    }
248
249    #[test]
250    fn test_parse_iw_scan_hidden_ssid_filtered() {
251        let output = "\
252BSS aa:bb:cc:dd:ee:ff(on wlan1)
253\tsignal: -45.00 dBm
254\tSSID:
255";
256        let networks = parse_iw_scan(output);
257        assert_eq!(networks.len(), 0);
258    }
259
260    #[test]
261    fn test_parse_iw_scan_open_network() {
262        let output = "\
263BSS aa:bb:cc:dd:ee:ff(on wlan1)
264\tsignal: -60.00 dBm
265\tSSID: OpenCafe
266";
267        let networks = parse_iw_scan(output);
268        assert_eq!(networks.len(), 1);
269        assert_eq!(networks[0].security, "Open");
270    }
271
272    #[test]
273    fn test_parse_iw_scan_wpa3_only() {
274        let output = "\
275BSS aa:bb:cc:dd:ee:ff(on wlan1)
276\tsignal: -45.00 dBm
277\tSSID: WPA3Net
278\tRSN:\t * Version: 1
279\t\t * Group cipher: CCMP
280\t\t * Pairwise ciphers: CCMP
281\t\t * Authentication suites: SAE
282\t\t * Capabilities: MFP-required
283";
284        let networks = parse_iw_scan(output);
285        assert_eq!(networks.len(), 1);
286        assert_eq!(networks[0].security, "WPA3");
287    }
288
289    #[test]
290    fn test_parse_iw_scan_wpa3_transition() {
291        let output = "\
292BSS aa:bb:cc:dd:ee:ff(on wlan1)
293\tsignal: -50.00 dBm
294\tSSID: TransitionNet
295\tRSN:\t * Version: 1
296\t\t * Group cipher: CCMP
297\t\t * Pairwise ciphers: CCMP
298\t\t * Authentication suites: PSK SAE
299";
300        let networks = parse_iw_scan(output);
301        assert_eq!(networks.len(), 1);
302        assert_eq!(networks[0].security, "WPA3 (transition)");
303    }
304
305    #[test]
306    fn test_parse_iw_scan_wpa2_explicit_psk() {
307        let output = "\
308BSS aa:bb:cc:dd:ee:ff(on wlan1)
309\tsignal: -55.00 dBm
310\tSSID: WPA2Net
311\tRSN:\t * Version: 1
312\t\t * Group cipher: CCMP
313\t\t * Pairwise ciphers: CCMP
314\t\t * Authentication suites: PSK
315";
316        let networks = parse_iw_scan(output);
317        assert_eq!(networks.len(), 1);
318        assert_eq!(networks[0].security, "WPA2");
319    }
320
321    #[test]
322    fn test_parse_iw_scan_mixed_networks() {
323        let output = "\
324BSS aa:bb:cc:dd:ee:ff(on wlan1)
325\tsignal: -40.00 dBm
326\tSSID: SecureWPA3
327\tRSN:\t * Version: 1
328\t\t * Group cipher: CCMP
329\t\t * Pairwise ciphers: CCMP
330\t\t * Authentication suites: SAE
331BSS 11:22:33:44:55:66(on wlan1)
332\tsignal: -60.00 dBm
333\tSSID: ClassicWPA2
334\tRSN:\t * Version: 1
335\t\t * Group cipher: CCMP
336\t\t * Pairwise ciphers: CCMP
337\t\t * Authentication suites: PSK
338BSS 77:88:99:aa:bb:cc(on wlan1)
339\tsignal: -70.00 dBm
340\tSSID: OpenCafe
341";
342        let networks = parse_iw_scan(output);
343        assert_eq!(networks.len(), 3);
344        let wpa3 = networks.iter().find(|n| n.ssid == "SecureWPA3").unwrap();
345        assert_eq!(wpa3.security, "WPA3");
346        let wpa2 = networks.iter().find(|n| n.ssid == "ClassicWPA2").unwrap();
347        assert_eq!(wpa2.security, "WPA2");
348        let open = networks.iter().find(|n| n.ssid == "OpenCafe").unwrap();
349        assert_eq!(open.security, "Open");
350    }
351
352    #[tokio::test]
353    async fn test_update_wpa_conf_writes_and_removes() {
354        let dir = tempfile::tempdir().unwrap();
355        let path = dir.path().join("wpa_sta.conf");
356        let path_str = path.to_str().unwrap();
357
358        let mut config = WifiConfig {
359            wifi_ssid: Some("TestNet".to_string()),
360            wifi_password: Some("pass123".to_string()),
361            ..Default::default()
362        };
363
364        update_wpa_conf_at(&config, path_str).await;
365
366        let content = tokio::fs::read_to_string(&path).await.unwrap();
367        assert!(content.contains("ssid=\"TestNet\""));
368        assert!(content.contains("psk=\"pass123\""));
369
370        config.wifi_ssid = None;
371        config.wifi_password = None;
372        update_wpa_conf_at(&config, path_str).await;
373        assert!(!path.exists());
374    }
375
376    #[tokio::test]
377    async fn test_update_wpa_conf_ssid_without_password_is_noop() {
378        let dir = tempfile::tempdir().unwrap();
379        let path = dir.path().join("wpa_sta.conf");
380        let path_str = path.to_str().unwrap();
381
382        let config = WifiConfig {
383            wifi_ssid: Some("TestNet".to_string()),
384            wifi_password: None,
385            ..Default::default()
386        };
387
388        update_wpa_conf_at(&config, path_str).await;
389        assert!(!path.exists());
390    }
391
392    #[test]
393    fn test_parse_default_route() {
394        let (gw, dev) = parse_default_route("default via 192.168.1.1 dev bridge0").unwrap();
395        assert_eq!(gw, "192.168.1.1");
396        assert_eq!(dev, "bridge0");
397
398        let (gw, dev) =
399            parse_default_route("default via 10.0.0.1 dev rmnet_data0 metric 100").unwrap();
400        assert_eq!(gw, "10.0.0.1");
401        assert_eq!(dev, "rmnet_data0");
402
403        assert!(parse_default_route("default dev bridge0 scope link").is_none());
404        assert!(parse_default_route("").is_none());
405    }
406
407    #[test]
408    fn test_format_wpa_conf_basic() {
409        let conf = format_wpa_conf("MyNetwork", "mypassword", None, SecurityType::WpaPsk);
410        assert!(conf.contains("ssid=\"MyNetwork\""));
411        assert!(conf.contains("psk=\"mypassword\""));
412        assert!(conf.contains("key_mgmt=WPA-PSK"));
413        assert!(conf.starts_with("ctrl_interface=/var/run/wpa_supplicant\n"));
414    }
415
416    #[test]
417    fn test_format_wpa_conf_escapes_quotes() {
418        let conf = format_wpa_conf("My\"Net", "pass\"word", None, SecurityType::WpaPsk);
419        assert!(conf.contains("ssid=\"My\\\"Net\""));
420        assert!(conf.contains("psk=\"pass\\\"word\""));
421    }
422
423    #[test]
424    fn test_format_wpa_conf_escapes_backslashes() {
425        let conf = format_wpa_conf("Net\\work", "pass\\word", None, SecurityType::WpaPsk);
426        assert!(conf.contains("ssid=\"Net\\\\work\""));
427        assert!(conf.contains("psk=\"pass\\\\word\""));
428    }
429
430    #[test]
431    fn test_format_wpa_conf_strips_newlines() {
432        let conf = format_wpa_conf(
433            "legit",
434            "pass\n}\nnetwork={\n    ssid=\"evil\"",
435            None,
436            SecurityType::WpaPsk,
437        );
438        assert_eq!(
439            conf.lines().count(),
440            format_wpa_conf("legit", "clean", None, SecurityType::WpaPsk)
441                .lines()
442                .count(),
443            "newlines in password must not inject extra config lines"
444        );
445    }
446
447    #[test]
448    fn test_format_wpa_conf_sae() {
449        let conf = format_wpa_conf("SAENet", "saepass", None, SecurityType::Sae);
450        assert!(conf.contains("key_mgmt=SAE"));
451        assert!(conf.contains("ieee80211w=2"));
452        assert!(conf.contains("sae_password=\"saepass\""));
453        assert!(!conf.contains("psk="));
454    }
455
456    #[test]
457    fn test_format_wpa_conf_sae_escapes() {
458        let conf = format_wpa_conf("SAENet", "pass\"w\\ord", None, SecurityType::Sae);
459        assert!(conf.contains("sae_password=\"pass\\\"w\\\\ord\""));
460    }
461
462    #[test]
463    fn test_read_ssid_from_wpa_conf() {
464        let dir = tempfile::tempdir().unwrap();
465        let path = dir.path().join("wpa.conf");
466        let conf = format_wpa_conf("TestSSID", "password123", None, SecurityType::WpaPsk);
467        std::fs::write(&path, conf).unwrap();
468
469        let ssid = read_ssid_from_wpa_conf(path.to_str().unwrap());
470        assert_eq!(ssid, Some("TestSSID".to_string()));
471    }
472
473    #[test]
474    fn test_read_ssid_roundtrips_special_chars() {
475        let dir = tempfile::tempdir().unwrap();
476        let path = dir.path().join("wpa.conf");
477        let conf = format_wpa_conf("My\"Net\\work", "pass", None, SecurityType::WpaPsk);
478        std::fs::write(&path, conf).unwrap();
479
480        let ssid = read_ssid_from_wpa_conf(path.to_str().unwrap());
481        assert_eq!(ssid, Some("My\"Net\\work".to_string()));
482    }
483
484    #[test]
485    fn test_read_network_wpa_psk() {
486        let dir = tempfile::tempdir().unwrap();
487        let path = dir.path().join("wpa.conf");
488        let conf = format_wpa_conf("PskNet", "pskpass", None, SecurityType::WpaPsk);
489        std::fs::write(&path, conf).unwrap();
490
491        let (ssid, sec) = read_network_from_wpa_conf(path.to_str().unwrap()).unwrap();
492        assert_eq!(ssid, "PskNet");
493        assert_eq!(sec, SecurityType::WpaPsk);
494    }
495
496    #[test]
497    fn test_read_network_sae() {
498        let dir = tempfile::tempdir().unwrap();
499        let path = dir.path().join("wpa.conf");
500        let conf = format_wpa_conf("SaeNet", "saepass", None, SecurityType::Sae);
501        std::fs::write(&path, conf).unwrap();
502
503        let (ssid, sec) = read_network_from_wpa_conf(path.to_str().unwrap()).unwrap();
504        assert_eq!(ssid, "SaeNet");
505        assert_eq!(sec, SecurityType::Sae);
506    }
507
508    #[test]
509    fn test_read_ssid_missing_file() {
510        assert_eq!(read_ssid_from_wpa_conf("/nonexistent/path"), None);
511    }
512}