Virtual RF: Add userspace Virtual Bluetooth and Virtual Wi-Fi subsystem

[yunhanw-google]

Summary

Adds userspace Virtual Bluetooth (cirque/virtual_bt/) and Virtual Wi-Fi (cirque/virtual_wifi/) radio subsystems, Wireshark PCAP capture (PcapCapability), and headless KVM Android emulator (AndroidDockerNode) support to Cirque, removing the dependency on host kernel radio simulation modules (mac80211_hwsim, wmediumd, btvirt, and host bluetoothd).

Problem

• Cirque's existing Bluetooth and Wi-Fi capabilities rely on host Linux kernel modules (mac80211_hwsim, wmediumd, btvirt) and host-shared bluetoothd D-Bus state:
  • Environment portability: Unprivileged CI runners, cloud workstations, and nested container hosts frequently lack mac80211_hwsim or btvirt kernel modules, preventing BLE and Wi-Fi tests from running.
  • State isolation: Sharing a single host bluetoothd daemon across multiple Docker containers causes adapter index collisions and cross-test interference.
  • No mobile controller coverage: Cirque lacked a node abstraction to run an Android emulator connected to the same virtual BLE, Wi-Fi, and Thread Border Router medium as containerized IoT end devices.

Solution

+-------------------------------------------------------------------------+
|                        Cirque Host Orchestrator                         |
|                                                                         |
|   +-----------------------------+     +-----------------------------+   |
|   |   VirtualBluetoothServer    |     |      VirtualWiFiServer      |   |
|   |  - LinkLayerHub (BLE LL)    |     |  - 802.11 Mgmt & Beacons    |   |
|   |  - VirtualBTController (H4) |     |  - WPA2 EAPOL 4-Way Key SM  |   |
|   |  - Dynamic ATT/GATT Router  |     |  - Userspace DHCPv4 & SLAAC |   |
|   +--------------+--------------+     +--------------+--------------+   |
|                  | TCP H4 / RF                       | TCP L2 / EAPOL   |
+------------------|-----------------------------------|------------------+
                   |                                   |
     +-------------+-------------+       +-------------+-------------+
     |                           |       |                           |
+----+--------------------+ +----+-------+------------+ +------------+----+
| IoTEndDevice Container  | | AndroidDockerNode (KVM) | |   WiFiAPNode    |
| - org.bluez D-Bus + PTY | | - /dev/bluetooth0->pty  | | - Virtual AP    |
| - wpa_supplicant1 D-Bus | | - cirque_tap0 -> wlan0  | |   10.0.1.1/24   |
+-------------------------+ +-------------------------+ +-----------------+

• Userspace Virtual Bluetooth (cirque/virtual_bt/):
  • Implements an HCI H4 over TCP transport (hci_h4.py) with segmented BIND <controller_id> preamble reassembly (server.py), virtual controller state machine (controller.py), BLE link-layer hub (link_layer.py), dynamic ATT/GATT server and attribute discovery (att_db.py, matter_ble_bridge.py), and per-container org.bluez D-Bus service (bluez_dbus_daemon.py, bluez_gatt_mixin.py).
• Userspace Virtual Wi-Fi (cirque/virtual_wifi/):
  • Implements an IEEE 802.11i WPA2-Personal (CCMP / PBKDF2-SHA1 / PTK / GTK) 4-way EAPOL-Key state machine (wpa2_crypto.py, eapol.py, wpa2_supplicant_sm.py), association-gated Ethernet L2 switch, userspace DHCPv4 (10.0.1.0/24) and ICMPv6 SLAAC (fd11:22::/64) servers (server.py), and a per-container fi.w1.wpa_supplicant1 D-Bus daemon (wpa_dbus_daemon.py, docker_wifi_bridge.py).
• Wireshark PCAP Capture (cirque/capabilities/pcapcapability.py, cirque/pcap/):
  • Captures per-controller HCI H4 frames (DLT_BLUETOOTH_HCI_H4_WITH_PHDR = 201), shared BLE link-layer PDUs with a 10-byte RF pseudo-header and CRC-24 (DLT_BLUETOOTH_LE_LL_WITH_PHDR = 256), and Wi-Fi Ethernet/EAPOL/DHCP/UDP frames (DLT_EN10MB = 1), with a summary inspection CLI (cirque.pcap.summarize_pcap).
• Headless KVM Android Emulator Node (cirque/nodes/androiddockernode.py, cirque/home/virtual_home_topology.py):
  • Launches a headless Android emulator (Pixel_6_API_34) inside cirque-android-runner with built-in radio emulation disabled (-feature -BluetoothEmulation -feature -WiFiPacketStream), bridges guest /dev/bluetooth0 (bt_vhci_forwarder -> /dev/vhci) over pty_bridge to VirtualBluetoothServer, bridges guest wlan0 via -wifi-tap cirque_tap0 to VirtualWiFiServer, and provides Flask REST endpoints (/init_android_emulator, /commission_chiptool, /commission_chiptool_thread, /toggle_chiptool, /read_chiptool) and MP4 screen recording during commissioning.
• Container & Network Reliability (cirque/nodes/dockernode.py, cirque/connectivity/homelan.py):
  • Disconnects leftover container endpoints before removing IPv6 Docker networks on teardown.
  • Installs a lightweight bind() preload guard on DockerNode containers to clear SO_REUSEPORT/SO_REUSEADDR on ephemeral (port == 0) UDP sockets while preserving fixed-port bindings (5353, 5540).

Caveats

• Full KVM Android emulator execution requires /dev/kvm access on the host; when /dev/kvm is unavailable, AndroidDockerNode unit tests validate node lifecycle and CLI logic without launching QEMU.

Testing

• Unit Tests & Coverage Gate:
  • Executed python3 -m unittest discover -s cirque -p 'test_*.py' (218 unit tests covering virtual_bt, virtual_wifi, pcapcapability, dockernode, androiddockernode, homelan, and virtual_home_topology; 99% statement coverage on the Virtual RF and Home Topology gate in .github/workflows/main.yml).
• End-to-End Validation & CI Smoke Scripts:
  • Verified Linux BLE + Wi-Fi commissioning (examples/validate_virtual_home.sh and examples/test_virtual_home_ble_wifi_e2e.py).
  • Verified live KVM Android emulator radio-path smoke (examples/run_android_ci_smoke.py) and CHIPTool.apk BLE + Wi-Fi and BLE + Thread commissioning (examples/validate_virtual_android_home.sh).