Activate a saved network configuration profile.

Args: id: Configuration profile ID to activate override_active: If True, force activation even if another profile is active

Watch a streaming capture another application is already running, read-only.

Use this streaming subscriber to see what a capture started elsewhere (the WebUI, a lab controller, another agent) is receiving, without taking control of it. This never starts, reconfigures or stops a capture; the role in the result is always 'subscriber'. The result includes the owner's running config (channels, width, dwell, filter), so it is clear what the summary does and does not cover.

Returns the same dissected summary as capture_scan (an 'aps' table with full security detail, plus per-frame 'frames'/'frame_types' with addresses, radiotap and decoded results). The raw pcapng is also saved on the device and its path returned in 'pcap_path' (fetch it with fetch_pcap_file). Use list_capture_sessions first if you want to see what is running.

Single-radio caveat: the owner's channel hopping can fail on devices where the capture interface shares a radio with the managed wlan0, so an observed capture may cover fewer channels than its config lists.

Args: session_id: Session to attach to (from list_capture_sessions). interface: Instead of a session id, the monitor-mode capture interface ('wlanpiN', e.g. 'wlanpi0') whose capture to watch. duration_s: How long to listen, 1-60 seconds. The tool call blocks for this whole window. max_frames: Cap on per-frame records in 'frames'; the 'frame_types' counts are always exact. Set 0 for AP table and counts only, or a negative value for no cap (every frame).

Run a live streaming Wi-Fi packet capture and return what was on the air.

This is a streaming capture: it captures real 802.11 frames off the air (unlike scan_wlan, which asks the driver for a scan), so it reports what is actually being transmitted. The call blocks for duration_s seconds and returns a dissected summary. The raw pcapng is also saved on the device and its path returned in 'pcap_path' (fetch it with fetch_pcap_file to verify the summary against the frames). For a capture longer than the 60 s window, use the non-streaming file-capture tools (start_pcap_file/fetch_pcap_file) instead.

The result has two parts:

• 'aps': one row per BSSID from beacons/probe-responses, with SSID, channel, signal, 802.11 amendments, advertised TX power, full security detail — the compact 'security' label plus 'akm' (the AKM suite list), 'pairwise_ciphers', 'group_cipher' and 'pmf' — and, when the AP advertises a QBSS/BSS Load element, 'stations' (the associated client count) and 'channel_utilization' (percent).

• 'frames' / 'frame_types': every frame's named type/subtype counted exactly in 'frame_types', plus up to max_frames per-frame records in 'frames'. Each record has the source/destination addresses (addr1..addr4), a full radiotap decode, and — for the frames that carry one — a decoded 'result': authentication algorithm+status, association status+AID, deauth/disassoc reason, or probe/assoc SSID.

The capture is owned by this call and is stopped before it returns. If another application is already capturing on the interface, this tool subscribes to that capture read-only instead of failing; the result always says whether the role was 'owner' or 'subscriber' and reports the running config.

Single-radio caveat: where the capture interface shares a radio with the managed wlan0, channel changes fail while wlan0 scans. Any such failures come back in 'channel_issues' — treat those results as partial rather than complete.

Args: interface: Monitor-mode capture interface, always named 'wlanpiN' (e.g. 'wlanpi0'), not 'wlan0'. Use get_network_interfaces or get_capture_channels to see what exists on this device. channels: Channel numbers to hop (e.g. [1, 6, 11, 36]); 6 GHz can be given as explicit frequencies in MHz. Omit to hop every channel the adapter supports. width: Channel width in MHz: 20, 40, 80 or 160. dwell_ms: Milliseconds to dwell on each channel (50-60000). duration_s: How long to capture, 1-60 seconds. The tool call blocks for this whole window. pcap_filter: Optional BPF/pcap filter, e.g. 'type mgt subtype beacon'. max_frames: Cap on per-frame records returned in 'frames'; per-kind counts in 'frame_types' are always exact. Set 0 to skip the per-frame records and get only the AP table and counts, or a negative value for no cap (every frame — a busy capture can then return tens of thousands of records, so use the file-capture tools for a full pcap instead). Beacons dominate a busy capture, so a pcap_filter such as 'not type mgt subtype beacon' makes the record list focus on the control/data/auth exchanges.

Create a new saved network configuration profile.

The config dict must include:

• id (str): Unique profile name (cannot be 'root' or 'default')

• namespaces (list, optional): Namespace-based interface configs

• roots (list, optional): Root namespace interface configs

Each interface config in namespaces/roots needs:

• mode: 'managed' or 'monitor'

• iface_display_name: Human-readable name

• phy: PHY device (e.g. 'phy0')

• interface: Interface name (e.g. 'wlan0')

• namespace (namespaces only): Namespace name (e.g. 'testns')

• security (optional): {ssid, security, psk} for WPA2-PSK/WPA3-PSK networks

Args: config: Network configuration dict matching the NetConfig schema

Create (or replace) a VLAN on an ethernet interface.

Args: interface: Ethernet interface (e.g. 'eth0'). Cannot be 'all'. vlan_id: VLAN ID (1-4094) addresses: Optional list of IP addresses to assign, each a dict with 'family' (4 or 6), 'local' (IP string), and 'prefixlen' (int). Example: [{"family": 4, "local": "192.168.10.1", "prefixlen": 24}]

Deactivate a currently active network configuration profile.

Args: id: Configuration profile ID to deactivate override_active: If True, force deactivation even if flagged as active

Delete a saved network configuration profile.

Args: id: Configuration profile ID to delete force: If True, delete even if the profile is currently active

Delete a VLAN from an ethernet interface.

Args: interface: Ethernet interface (e.g. 'eth0'). Cannot be 'all'. vlan_id: VLAN ID to delete allow_missing: If True, don't error if the VLAN doesn't exist

Enable NTP automatic time synchronization on the WLAN Pi.

Fetch a non-streaming capture's pcapng file as a binary blob.

Returns the raw pcapng file (mime application/vnd.tcpdump.pcapng) for the capture named by capture_id (preferred) or by an explicit on-device path. Open it in Wireshark/tshark for analysis. Fetch after the capture has stopped for a complete file; fetching a still-running capture returns only the bytes written so far.

For safety this reads only files under the server's managed capture directory; any other path is refused.

Args: capture_id: The capture_id from start_pcap_file/list_pcap_files. path: Alternatively, the on-device file path (must be inside the managed capture directory). session_id: Deprecated alias for capture_id.

Get battery status on WLAN Pi models with a battery (e.g. WLAN Pi Pro).

Returns 'present': false on hardware without a battery, otherwise capacity percentage and charging status.

Check whether the Ethernet port blinker is currently running.

Get Bluetooth adapter status.

Includes the adapter name, address, power state, and list of paired devices.

List the channels each capture adapter on this WLAN Pi can tune to.

Capture adapters are the monitor-mode interfaces named 'wlanpiN'; the answer is namespace-aware and comes from the adapter's own radio, so it reflects the regulatory domain in force. Use it to pick the 'interface' and 'channels' arguments for capture_scan.

Each entry gives the frequency in MHz plus its channel number (6 GHz frequencies may have no channel number, in which case pass the frequency to capture_scan directly).

Get the WLAN Pi's current local date, time, and timezone.

Get WLAN Pi device identity: model, hostname, software version, and current operating mode.

Get the current WLAN Pi operating mode (classic, wconsole, hotspot, wiperf, server, bridge).

Get the WLAN Pi hardware model (e.g. WLAN Pi Pro, R4, M4).

Get WLAN Pi live system metrics: IP address, CPU usage, RAM usage, disk usage, CPU temperature, and uptime.

Get DHCP leases held by the WLAN Pi (parsed from dhclient lease files).

Get ethernet interface details for a specific interface.

Args: interface: Ethernet interface name (e.g. 'eth0'), or 'all' for every interface

Get the connected client count in hotspot mode.

Returns an error if the device is not in hotspot mode.

Args: iface: Optional AP interface name; auto-detected if omitted.

Get per-station link statistics for hotspot AP clients.

Reports signal, rates, and retries. Returns an error if the device is not in hotspot mode.

Args: iface: Optional AP interface name; auto-detected if omitted.

Get the hotspot SSID and WPA passphrase.

Read from the hostapd configuration. Returns an error if the device is not in hotspot mode.

List stations connected to the hotspot AP interface.

Returns an error if the device is not in hotspot mode.

Args: iface: Optional AP interface name; auto-detected if omitted.

Get per-interface link statistics (via ethtool): speed, duplex, errors, drops.

Args: interface: Interface name (e.g. 'eth0')

Get the full details of a saved network configuration by ID.

Args: id: Configuration profile ID (use list_network_configs to see available IDs)

Get the status of all saved network configurations, showing which is active.

Get a full network snapshot.

Covers all interfaces, WLAN details, ethernet IP config, VLAN info, LLDP/CDP neighbours, and public IP address. Best starting point for network diagnostics.

Get network interface details including IP addresses, flags, MTU, and link state.

Args: interface: Optional interface name (e.g. 'eth0'). If omitted, returns all interfaces.

Get the current status of the wlanpi-profiler.

Returns whether the profiler is running, its SSID, channel, and interface.

Get the WLAN Pi's public IPv6 address and related details.

Test WLAN Pi network reachability.

Pings the default gateway, checks DNS resolution, and verifies internet access. Use this to diagnose connectivity problems.

Get the current Wi-Fi regulatory domain.

Returns 'country' as an ISO 3166-1 alpha-2 code.

Get the structured IP routing table.

Args: namespace: Optional network namespace to query (default: root namespace)

Get the running status of a WLAN Pi service.

Args: name: Service name (use list_allowed_services to see valid names)

Get active TCP sockets/connections on the WLAN Pi.

Args: namespace: Optional network namespace to query (default: root namespace)

Get the WLAN Pi's current system timezone.

Get active UDP sockets on the WLAN Pi.

Args: namespace: Optional network namespace to query (default: root namespace)

Get the current UFW firewall status and active rules on the WLAN Pi.

List USB network adapters currently plugged into the WLAN Pi.

Get VLAN interfaces on the WLAN Pi.

Args: interface: Ethernet interface to filter by (e.g. 'eth0'). If omitted, returns all interfaces. vlan_id: VLAN ID to filter by. If omitted, returns all VLANs.

Get Wi-Fi adapter capabilities.

Returns 'iw phy' capability dumps for each PHY, including supported bands, channels, HT/VHT/HE features, and interface modes.

Get Wi-Fi regulatory domain information reported by the kernel.

List PCI/platform wireless devices and their bound WLAN drivers.

Comes from lspci, covering built-in Wi-Fi radios.

List USB-attached WLAN adapters and their bound drivers.

If 'adapters' is empty but interfaces_scanned > 0, the radios are PCI/on-board — use get_wlan_pci_drivers instead.

List all services that can be managed on this WLAN Pi (started, stopped, or queried).

List the packet captures currently running on this WLAN Pi.

Each session reports its session_id, the owning principal, the monitor-mode interfaces ('wlanpiN') it holds, its network namespace, and the running config (channels, width, dwell, pcap filter). A session's interface cannot be captured on by anyone else — use capture_observe to watch it read-only.

List all saved network configuration profiles.

Returns a dict mapping config ID to active state (True/False).

List the non-streaming, file-backed captures this server has started.

Includes captures that are running or done. Each entry gives the capture_id, interface, on-device pcapng path, status (running/completed/stopped/error), current size and configured duration. Use stop_pcap_file to end a running one and fetch_pcap_file to retrieve the file. Files left on disk from an earlier server run are also listed, with status 'on_disk' — they can still be fetched.

List all timezones available on the WLAN Pi (for use with set_timezone).

Reboot the WLAN Pi immediately.

Active sessions and captures will be interrupted. Can be disabled via ALLOW_POWER_CONTROL=false in the server config.

Renew the DHCP lease for an interface.

The renewal happens in the interface's current namespace, and the interface IP address may change as a result.

Args: interface: Interface name (e.g. 'eth0')

Restart a WLAN Pi service.

Args: name: Service name (use list_allowed_services to see valid names)

Revert a WLAN interface from its namespace back to the root namespace.

Args: interface: WLAN interface name (e.g. 'wlan0') namespace: Network namespace to revert from (default: 'testns') delete_namespace: Delete the namespace after reverting

Run an internet speed test from the WLAN Pi.

Uses LibreSpeed CLI; slow, typically taking 30-90 seconds to complete. Returns download/upload speed, ping, IP address, and the test server used.

Scan for Wi-Fi networks.

Namespace-aware, with automatic monitor adapter selection. If multiple monitor adapters exist and no interface is given, returns 'needsSelection' with candidates instead of scanning — call again with one of the candidate interfaces.

To connect to a network found by this scan, create and activate a network configuration (create_network_config / activate_network_config).

Args: interface: WLAN interface to scan with (e.g. 'wlan0'); auto-selected if omitted namespace: Optional network namespace the interface lives in include_hidden: Include hidden SSIDs in results detail: 'short' for list-friendly fields plus RF extensions, 'full' for everything

Turn Bluetooth on or off.

Args: action: 'on' to enable Bluetooth, 'off' to disable it

Set the Wi-Fi regulatory domain (country code) on the WLAN Pi.

This controls which channels and transmit power levels are permitted. Use a valid ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB', 'DE').

Args: country_code: Two-letter ISO 3166-1 alpha-2 country code

Set the WLAN Pi system timezone.

Args: timezone: Timezone name, e.g. 'America/Denver' (use list_timezones for valid values)

Shut down the WLAN Pi immediately.

The device must be powered back on manually. Can be disabled via ALLOW_POWER_CONTROL=false in the server config.

Start the Ethernet port blinker.

This is a cable finder: it flashes the port LED so the cable can be located at the switch end.

Args: interface: Ethernet interface to blink (default 'eth0')

Put the WLAN Pi into Bluetooth discoverable pairing mode.

Starts bt-timedpair so a phone or laptop can pair with it.

Start a background, non-streaming packet capture to a pcapng file.

This is the non-streaming counterpart to capture_scan: unlike that streaming tool, it does not block and does not return a dissected summary. It starts a capture, keeps the core WebSocket open in the background, and writes the raw pcapng bytes to a file under a managed directory on the device. Because nothing is held in memory or returned inline, the capture can run far longer than the 60 s capture_scan window — up to the server's configured maximum. The call returns immediately with the capture_id and file path; the capture then runs on its own until duration_s elapses or you call stop_pcap_file. Retrieve the file with fetch_pcap_file(capture_id=...) (a pcapng blob) once it has stopped.

This tool always owns the interface. If a capture is already running on it, this returns an error rather than taking it over — watch that one with capture_observe instead.

Args: interface: Monitor-mode capture interface, always 'wlanpiN' (e.g. 'wlanpi0'), not 'wlan0'. See get_capture_channels. channels: Channel numbers to hop (e.g. [1, 6, 11, 36]); 6 GHz can be given as explicit frequencies in MHz. Omit to hop every channel the adapter supports. width: Channel width in MHz: 20, 40, 80 or 160. dwell_ms: Milliseconds to dwell on each channel (50-60000). duration_s: How long the background capture runs, in seconds, from 1 up to the server maximum (default max 3600). The call itself returns immediately. pcap_filter: Optional BPF/pcap filter, e.g. 'type mgt subtype beacon'.

Start the wlanpi-profiler to capture 802.11 client capability information.

The profiler brings up a fake AP and captures association frames from clients to determine their 802.11 capabilities (PHY support, spatial streams, etc.).

Args: interface: WLAN interface to use (e.g. 'wlan0') channel: 802.11 channel number to operate on frequency: Frequency in MHz (alternative to channel) ssid: SSID for the fake AP (default chosen by profiler) no11r: Disable 802.11r (Fast BSS Transition) support no11ax: Disable 802.11ax (Wi-Fi 6) support no11be: Disable 802.11be (Wi-Fi 7) support wpa3_personal: Enable WPA3-Personal only mode wpa3_personal_transition: Enable WPA3-Personal Transition mode noAP: Run without bringing up an AP (passive capture only) debug: Enable debug logging in profiler

Start a WLAN Pi service.

Args: name: Service name (use list_allowed_services to see valid names)

Stop the Ethernet port blinker.

Stop a running non-streaming file capture before its duration elapses.

Signals the background capture to stop, waits for it to flush and close its file, and returns the final path, status and size. A capture that has already ended on its own is returned as-is. Fetch the file with fetch_pcap_file.

Args: capture_id: The capture_id returned by start_pcap_file (also shown by list_pcap_files). session_id: Deprecated alias for capture_id.

Stop the wlanpi-profiler and return summary results.

Stop a WLAN Pi service.

Args: name: Service name (use list_allowed_services to see valid names)

Update an existing network configuration profile.

The config_update dict may include:

• namespaces (list, optional): Updated namespace interface configs

• roots (list, optional): Updated root namespace interface configs

Args: id: Configuration profile ID to update config_update: Partial config update (namespaces and/or roots)