kawaiifi

kawaiifi is a Wi-Fi scanning library for Linux, macOS, and Windows.

It discovers local Basic Service Sets (BSSs) and reports their SSID, BSSID, signal strength, channel, channel width, security protocols, and information elements (IEs).

Usage

[dependencies]
kawaiifi = "0.2"

Obtaining a Wi-Fi Interface

Use kawaiifi::default_interface() to get the first available interface.

use kawaiifi::Interface;

let interface: Interface = kawaiifi::default_interface()?.ok_or("No Wi-Fi interface found")?;

Use kawaiifi::interfaces() to get all available interfaces.

use kawaiifi::Interface;

let interfaces: Vec<Interface> = kawaiifi::interfaces()?;

Some Interface properties are platform-specific.

#[cfg(target_os = "linux")]
println!("Index: {}", interface.index());

#[cfg(target_os = "macos")]
println!("Noise: {} dBm", interface.noise_dbm());

#[cfg(target_os = "windows")]
println!("Description: {}", interface.description());

Triggering a Wi-Fi Scan

Blocking scans are triggered using Interface::scan_blocking().

use kawaiifi::Scan;

let scan: Scan = interface.scan_blocking()?;

Asynchronous scans are triggered using Interface::scan().

use kawaiifi::Scan;

let scan: Scan = interface.scan().await?;

Accessing BSS Data

Scan contains a list of BSSs that are accessed through Scan::bss_list().

use kawaiifi::Bss;

let bss_list: &[Bss] = scan.bss_list();
println!("Found {} BSS(s)", bss_list.len());

Bss exposes common properties that are available on all platforms.

println!("BSSID: {:?}", bss.bssid());
println!("SSID: {:?}", bss.ssid());
println!("Frequency: {} MHz", bss.frequency_mhz());
println!("Band: {}", bss.band());
println!("Channel: {}", bss.channel_number());
println!("Channel Width: {}", bss.channel_width());
println!("Signal: {} dBm", bss.signal_dbm());
println!("Security: {}", bss.security_protocols());
println!("Wi-Fi Protocols: {}", bss.wifi_protocols());
println!("Wi-Fi Amendments: {}", bss.wifi_amendments());
println!("Max Rate: {} Mbps", bss.max_rate_mbps());

Some Bss properties are platform-specific.

#[cfg(target_os = "linux")]
println!("Status: {:?}", bss.status());

#[cfg(target_os = "macos")]
println!("Noise: {} dBm", bss.noise_dbm());

#[cfg(target_os = "windows")]
println!("Link Quality: {}", bss.link_quality());

Accessing Information Elements

Bss contains a list of 802.11 Information Elements (IEs) that are accessed through Bss::ies().

use kawaiifi::Ie;

let ies: &[Ie] = bss.ies();
println!("Found {} IE(s)", ies.len());

Ie exposes basic properties such as the information element's name, ID, and a summary.

println!("IE: {} ({}) - {}", ie.name(), ie.id, ie.summary());

Ie also exposes the information element's underlying data through Ie::data.

use kawaiifi::IeData;

match &ie.data {
    IeData::Ssid(ssid) => println!("SSID: {}", ssid.to_string_lossy()),
    IeData::DsParameterSet(ds) => println!("Channel: {}", ds.current_channel),
    IeData::Tim(tim) => println!("DTIM Period: {}", tim.dtim_period),
    IeData::VhtCapabilities(vht_caps) => {
        println!("Max MPDU Length: {}", vht_caps.vht_capabilities_info.maximum_mpdu_length)
    }
    _ => {}
}

Troubleshooting

See the repository troubleshooting notes for platform-specific permissions and location-services behavior.

Changelog

See the repository changelog for release notes.

License

Dual-licensed under MIT or Apache 2.0.