feat: Linux WiFi + BLE + HS Capture bridge (no ESP32 required)

[FusedStamen]

Background

Running WatchDogsGo on a uConsole CM4 with HackerGadgets AIO v1 with no ESP32/C5 available. Built a Python bridge script (wdg_wifi_bridge.py) that emulates the projectZero serial protocol over a PTY, enabling full game functionality using the host's native Linux WiFi and Bluetooth adapters.

wdg_wifi_bridge.py

How it works

The bridge creates a PTY at /tmp/esp32-pty and symlinks it so the game can be launched with:

sudo ./run.sh /tmp/esp32-pty

It intercepts game serial commands and handles them natively on Linux:

Command | Handler -- | -- scan_networks | iw dev wlan1 scan scan_bt | bleak BLE scanner on hci adapter start_sniffer | tcpdump in monitor mode → pcapng start_handshake / start_handshake_serial | airodump-ng + hcxpcapngtool polling

Hardware tested on

• uConsole CM4, HackerGadgets AIO v1
• AC1200 WiFi card (wlan1) — wardriving + BLE
• AWUS036ACM / MT7612U (wlan2) — packet sniff + HS capture
• Internal UART Bluetooth (hci1) — BLE scanning

HS Capture approach

airodump-ng handles the mt76x2u driver better than hcxdumptool on kernel 6.12.x (radiotap header compatibility). The bridge polls the capture file every 10 seconds with hcxpcapngtool to detect new EAPOL/PMKID hashes and fires the game's handshake event (SSID:{name} AP:{bssid}) which triggers 200 XP, the handshake_hunter badge, and map marker.

Systemd service

ini

[Unit]
Description=WatchDogsGo WiFi + BLE Bridge
After=network.target bluetooth.target

[Service]
ExecStart=/home/fusedstamen/python/WatchDogsGo/.venv/bin/python3 /home/fusedstamen/python/WatchDogsGo/wdg_wifi_bridge.py --iface wlan1 --bt-iface hci1 --sniffer-iface wlan2 --no-monitor --loot-dir /home/fusedstamen/python/WatchDogsGo/loot
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Notes

• You mentioned in issue uConsole Wardriving without ESP32 #1 you'd consider landing a sanitised bridge script under extras/ with a proper security review pass — happy to work on that if useful
• The script is in my fork at github.com/FusedStamen/WatchDogsGo
• Dependencies: bleak, airodump-ng, hcxpcapngtool, tcpdump, iw

[FusedStamen]

UPDATED BRIDGE SCRIPT

wdg_wifi_bridge.py

BLE fast-fail detection — _do_ble_scan now times each scan and logs a warning if it completes in under 2 seconds with 0 results, indicating the Bluetooth adapter has dropped out

Packet sniffer — start_sniffer / stop_sniffer commands put wlan2 (AWUS036ACM) in monitor mode and capture to pcapng via tcpdump, saved to loot directory

Handshake capture — start_handshake / start_handshake_serial commands use airodump-ng on wlan2 for WPA handshake and PMKID capture; polls with hcxpcapngtool every 10 seconds to detect new hashes and fires the game's handshake event (SSID/AP format for 200 XP + badge)

wlan1 restore on HS stop — after stopping handshake capture, wlan1 is brought back up since hcxdumptool/airodump-ng can bring it down

--sniffer-iface — new argument for dedicated capture interface (default wlan2), separate from wardriving interface (wlan1)

--loot-dir — new argument to specify where captures are saved

[LOCOSP]

Linked your bridge as a community contribution in README (commit a09318f) — leaving this issue open as the canonical reference so people who land here from search / Discord can find the latest script attachment and the systemd recipe.

Why we're not landing it under extras/ in this repo

After re-reading the latest 378-line version (with start_sniffer + start_handshake added), the calculus tilts toward keeping it as a community-maintained tool rather than a maintained part of the core, for these reasons:

• The handshake capture path (airodump-ng + hcxpcapngtool polling) duplicates what the ESP32 firmware does over serial. If both run at once they fight for the radio. The bridge is correct for ESP32-less setups, but inside the main repo it would need explicit ESP32-or-bridge mode selection in the game itself.
• Adding airodump-ng + hcxpcapngtool to setup.sh changes the dependency footprint for every user, including the 95% who use a real ESP32 and don't need them.
• The bridge is the right shape for community-maintained: tracks the projectZero serial protocol, lives next to the user's hardware quirks (which interface, AIO v1 vs v2, MT7612U vs RTL88xx), and gets iterated faster outside our release cycle.

What we did ship that helps the bridge

• 0.9.7 — _looks_like_serial(path) accepts any character device, so the symlink at /tmp/esp32-pty works directly with sudo ./run.sh /tmp/esp32-pty (no more sed-patching __main__.py).
• 0.9.6 — wardrive plugin no longer marks the active session as uploaded, so handshake events the bridge fires while the user is uploading don't get silently dropped.
• 0.9.4 — setup.sh now installs iw (used by your scan_networks path) and builds FlightAware dump1090 from source.

If you want to land it as a sanitised PR

Five things from the earlier security review that would need addressing:

1. TOCTOU on /tmp/esp32-pty symlink — os.path.exists() → os.unlink() → os.symlink() race. Sticky bit on /tmp reduces it but mkdtemp + atomic rename is cleaner.
2. No SIGTERM handler — systemctl stop leaves monitor mode active and the symlink dangling. signal.signal(SIGTERM, …) calling restore_managed_mode() + os.unlink(symlink) fixes it.
3. pip install bleak --break-system-packages in the log message is bad advice (clobbers system packages on Debian) — point at the venv-local pip instead.
4. No --iface validation — currently a typo can take the user's default route down. A check against ip route get 8.8.8.8 | grep dev before flipping monitor mode would be a friendly safety net.
5. Always runs as root — after the monitor-mode flip and PTY creation, os.setresuid() to a normal user (e.g. nobody or _bridge) keeps the read-only iw scan / bleak calls out of root context.

If you do that pass plus a short extras/wdg_wifi_bridge/README.md (deps install, AIO v1 quirks, systemd unit), open a PR against main from a fresh branch (not the main of your fork — that one carries the unrelated commits we discussed in #4/#5/#6) and we'll review.

Otherwise: thanks for the work, the README link will keep it discoverable. 👍

[JustinHoMi]

I’d love to see this built-in. For Uconsole owners with the aiov2, it makes more sense to just use the internal ac1200 since it’s an all-in-one package without any external hardware requirement.