The newest generation of the open-world hacking Real Life Game (RLG): a handheld where the real wireless networks around you become the game. Scan the city, wardrive and run live ops like it's Watch Dogs.
You carry it in the field. Your GPS is the player, the Wi-Fi / BLE / LoRa devices around you are the map, and real reconnaissance, wardriving and attacks are the gameplay — scored with XP, hacker ranks and badges, all behind a cyberpunk game UI.
⚠️ For authorized security testing, research and education only. It drives real radios and can scan, capture, disrupt and impersonate wireless networks and devices. Use it only on equipment you own or are explicitly permitted to test. You are solely responsible for how you use it — see Legal & responsible use. No warranty, no liability.
- What it is · Screenshots · Hardware
- Install · Running · Controls · Updating
- Connect to WDGWars · Flashing firmware
- Cluster Wardrive · What it talks to
- Features · Extras
- Loot: backup, restore, move
- Configuration & hardware overrides
- Data & privacy · Legal & responsible use · License
WatchDogsGo NG turns a ClockworkPi uConsole + an ESP32-C5 radio into a portable pentest and signals-intelligence rig that plays like a game:
- A live map centered on you (real GPS). Discovered networks are plotted around you; walk the city and the map fills in.
- Real tooling, game loop. Every scan, handshake, evil-twin and wardrive is a real action against real RF — it just earns XP, ranks and badges while it runs.
- Online metagame. Links to the WDGWars community — upload your wardriving, climb a ranking, chase objectives on the map.
Required
- ClockworkPi uConsole (CM4 / CM5) — or any Raspberry Pi OS / Debian / Ubuntu Linux box.
- ESP32-C5 radio on USB — Seeed XIAO ESP32-C5 (no SD, USB-JTAG) or an ESP32-C5 WROOM dev kit — running the projectZero / JanOS firmware (flashable from inside the app, see below).
Optional (unlock more features)
- GPS (AIO v2 UART, USB GPS, or
/dev/ttyAMA0//dev/ttyS0) — for the live map & wardriving. - LoRa SX1262 (SPI) — MeshCore messenger + WDGWars LoRa chat.
- RTL-SDR dongle — ADS-B radar, 433 MHz scanner, emergency-services radio.
- A monitor-mode USB Wi-Fi card (e.g. an AC1200 / RTL8812AU) — host-side Wi-Fi scan / wardrive / handshake / deauth as a second radio alongside (or instead of) the ESP32.
- Bluetooth (host
hci0) — proximity radar, BLE HID. - uConsole AIO v2 board — software-switched power rails for GPS / LoRa / SDR / USB.
One-liner (uConsole / Raspberry Pi OS / Debian / Ubuntu):
curl -sL https://locosp.github.io/WatchDogsGo/install-ng | sudo bashOr clone it yourself:
git clone https://github.com/LOCOSP/WDGoNG.git ~/python/WatchDogsGo-NG
cd ~/python/WatchDogsGo-NG
bash setup.sh # creates the venv, installs everything (apt + pip), builds dump1090setup.sh is idempotent — re-run it any time; it skips what's already present.
./wdgong_ui/run_ui.sh # or double-click the "WatchDogsGo NG" desktop iconThe launcher auto-detects the ESP32 serial port, powers the AIO USB rail, stops
meshtasticd (which holds the SPI bus), and self-heals dependencies — if a core
module is missing it runs setup.sh for you before starting. It runs under sudo
for serial / GPIO / raw-socket access.
Global keys (work almost everywhere):
| Key | Action |
|---|---|
TAB |
open / close the menu (and the node panel on mesh / cluster screens) |
| ←/→ · ↑/↓ | switch tab · move item (or pan a value on sub-screens) |
| ENTER / item's letter | run the selected (or lettered) menu item |
| + / − · 0 | map zoom in / out · reset to DISTRICT (zoom-out stops when the map fills the screen) |
| H | expand ⇄ shrink the 433 Hunter / Capture panel |
` or L · P |
loot screen · captured-credentials screen |
| G · F | FIELD view · fullscreen toggle |
| S | hard STOP — halt every scan / attack / radio at once |
| U · ESC | game-update screen · quit prompt (power modules off / leave / restore) |
Context keys (only on the screen named):
| Screen | Keys |
|---|---|
| LoRa Mesh chat | Ctrl+T flip MeshCore ⇄ Meshtastic · ←/→ cycle band/region |
| Cluster fleet | ↑/↓ select node · ←/→ pin a node's band · A adopt a join request · X stop the fleet |
| ADS-B tracks map | A toggle aircraft tracks · K export the current view to KML · C cycle coverage overlay |
| 433 Hunter | K learn the fob in the target window · J reset the target to the car-key default |
| Map markers | C cluster-select (step through grid-clustered markers) |
Press ESC to quit. If any radio is still powered, the prompt lists the active modules (GPS / LoRa / SDR) and asks what to do with them:
YOFF & QUIT — stop every scan / attack and power those rails down.LLEAVE ON — quit but leave them running (a background Meshtastic daemon or an SDR capture keeps going after the game exits).RRESTORE PRE-LAUNCH — put the rails back to exactly how they were when you launched the game (shown only when something actually changed).N— cancel and go back.
The USB rail is never touched — it powers the ESP32-C5, so the game always keeps it on. Your loot on the SD card is safe whichever you pick.
In-game (recommended): SYSTEM → Update Game. It does a git pull --ff-only and
restarts itself. Your data is never touched — loot/ (XP, sessions, handshakes, chat),
secrets.conf and the venv are all gitignored. (The pull runs as your login user so it
can reach the repo over SSH even though the app runs as root.)
Manual:
cd ~/python/WatchDogsGo-NG && git pull --ff-only && ./wdgong_ui/run_ui.shDon't download a ZIP over the folder — that breaks the git checkout and leaves stale files. Updates are always a
git pull(only changed code is replaced).
WDGWars is the community metagame — upload your wardriving, climb the ranking, chase objectives on the map. Link your device in one of two ways:
A) Pair with a code (easiest — no typing a 64-char key):
ADDONS → WDGWars Pair. Register / log in at wdgwars.pl, open the
device-pairing page, and enter the short code the game shows. The key is fetched and stored
for you.
B) Paste the API key manually:
- Register at wdgwars.pl; you get a 64-character hex API key.
- Copy the template and add the key:
cp secrets.conf.example secrets.conf nano secrets.conf # set: WARDRIVE_API_KEY=your-64-char-hex-key - Restart the game.
secrets.confis gitignored — it never leaves your device and updates never touch it.
Running your own server? Also set WARDRIVE_API_URL=https://your-server/api/upload/.
The same secrets.conf holds the optional WPA-sec and WiGLE keys (see the template for each).
The radio runs the projectZero / JanOS firmware (our public ESP32-C5 fork). You flash and update it from inside the app — no cables-and-IDE dance.
SYSTEM → Flash ESP32→ pick your board:- XIAO ESP32-C5 — auto-reset over USB-JTAG (no BOOT button; the AIO USB rail is power-cycled for you).
- ESP32-C5 WROOM — standard dev-kit reset.
- The app downloads the latest firmware release from GitHub and flashes it with
esptoolat the right offsets (bootloader0x2000, partition table0x8000, app0x20000), then the radio reboots. - Auto-check: the app reads the firmware version over serial and shows a pulsing
[FW] update availablebanner when a newer release is out — one click to flash it.
Instead of one radio hopping 40 channels, Cluster Wardrive turns the XIAO embedded in your uConsole into the core of an ESP-NOW node fleet: a swarm of XIAO / T-Dongle C5 nodes each sweep a slice of the band at once and stream their hits back to you. The host merges, de-dups, GPS-stamps and scores everything into your normal loot — you just get the whole spectrum covered in parallel.
The intelligence lives on the uConsole, in Python — not in the firmware:
- The XIAO is a thin ESP-NOW bridge (a "dumb pipe"): it only relays frames on and off the air and over USB serial. It holds no fleet secret and no protocol logic.
- The brain is the host (
wdgong_ui/cluster_*.py): authentication, the node registry and identity, channel-slice assignment, BLE-duty election, de-dup, GPS stamping and node adoption all run here. The wire format is documented indocs/cluster-serial-protocol.md.
That split is deliberate: the public firmware binary reveals nothing about how the fleet is coordinated — all of that is host-side.
- Bridge firmware on the uConsole's XIAO: projectZero / JanOS ≥ 1.7.5
(adds the ESP-NOW bridge mode). Flash it from
SYSTEM → Flash ESP32like any update. - Fleet key at
~/.wdgo/fleet.key(16 raw bytes) — the shared secret the whole fleet signs its frames with. It is gitignored and never committed or logged; put the same key your nodes already use there. Without it the host can still hear nodes but can't command adopted ones. (Override the path withWDGO_FLEET_KEY=/path/to/key.) - Nodes running the WDGWMarauderV8 node firmware (the Marauder V8 fleet node — WiFi 2.4/5 GHz + BLE + GPS), already carrying that fleet key, on the same control channel. Nodes do not need reflashing to join an existing fleet.
Launch the game normally and open SNIFF → Cluster Wardrive. The bridge path is the
default whenever the fleet key is present — no environment flags needed. The fleet
starts, nodes latch onto the core, dump their buffered records, and the hits flow into your
loot (wardriving.csv, XP, map) exactly like a normal wardrive. GPS-stamped when you have a
fix; indoors with no fix the hits are still logged and placed on the map once a fix lands.
| Key | Action |
|---|---|
| ↑ / ↓ | select a node in the health table |
| ← / → | set the selected node's scan band: AUTO → 2.4G → 5G → 5G-lo → 5G-hi (a manual pin; the rest auto-split around it) |
| A | adopt a node that is requesting to join the fleet |
| X | stop the fleet core |
| ESC | hide the screen — the fleet keeps collecting in the background; re-open it any time |
| S | hard STOP everything, the fleet included |
- Coverage radar (left): each node sits at the centre of the channel slice it scans, so the ring reads as real spectrum coverage and an uncovered gap is visible at a glance.
- Summary tiles: nodes online, fleet records/min, records this run, WiFi nets and BLE devices (counted separately).
- Per-node health table: role, channel slice (a
*marks a manual pin), records/min, de-dup fill, on-die temperature, uptime, drop-outs and a state badge.
- Automatic by default: the brain splits the whole 2.4 GHz + 5 GHz channel set into contiguous slices, one per WiFi node, and re-balances as nodes come and go.
- BLE duty: with two or more nodes, one is always kept on Bluetooth; the choice is sticky.
- Manual override: pick a node and press ←/→ to pin its band; the rest auto-split around it.
- One radio: the XIAO has a single radio, so the fleet core and a normal capture can't run
at once. Starting any scan / wardrive / sniffer / attack automatically yields the radio and
stops the fleet (
[CLUSTER] yielding the radio…).
WDGO_CLUSTER_SIM=1 synthesises a realistic fleet straight into the UI so you can explore
the whole screen — telemetry, coverage, a join request, the live record stream — with no
nodes attached. The demo never writes to your real loot / XP.
WatchDogsGo NG is a hub for a lot of real hardware. What it auto-detects and drives:
| Device | Over | What you get |
|---|---|---|
| ESP32-C5 (XIAO / WROOM, projectZero/JanOS) | USB serial | Wi-Fi + BLE scan, wardrive, sniffer, handshake, deauth, evil twin, SAE flood |
| WDGWars Marauder V8 node fleet (XIAO / T-Dongle C5) | ESP-NOW bridge → USB | Cluster Wardrive — many radios sweep at once |
| Flipper Zero | USB CDC (auto-detect 0483:5740) |
SubGHz RX/TX, NFC, device info, storage — and .sub RAW files the 433 Capture tool writes are Flipper-ready |
| Monster RF SubGHz (CC1101) | USB serial (CH340) | sub-GHz capture / replay on a dedicated board |
| RTL-SDR (R820T etc.) | USB | ADS-B radar + tracks, 433 MHz scanner, 433 Hunter fox-hunt, 433 Capture, emergency-services radio |
| LoRa SX1262 | SPI | MeshCore + native Meshtastic mesh chat, node mapping, WDGWars LoRa chat |
| AC1200 / RTL8812AU monitor-mode Wi-Fi card | USB (iw / monitor) |
host-side Wi-Fi scan / wardrive / handshake / deauth as a second radio |
| PipBoy / ESP32-S3 watch | BLE | companion watch integration (work in progress) |
| uConsole AIO v2 | GPIO rails | software power switching for GPS / LoRa / SDR / USB |
With both an ESP32 and a host Wi-Fi card present, SYSTEM → Radio (WiFi card) gives you a
per-function matrix (scan / wardrive / handshake / deauth / BLE → ESP32 / host / auto) so you
choose which radio serves what, or let auto keep the ESP32 as primary.
- Live GPS map centered on you; discovered Wi-Fi/BLE plotted as geographic markers, grid-clustered as you zoom; a gorilla-operator avatar marks your position.
- Offline world basemap — a bundled whole-world, ctOS-styled map renders under the markers; fully offline, anywhere on Earth. Zoom out to a regional/world view; zoom in DISTRICT → STREET → BLOCK.
- XP, hacker ranks & badges — ranks climb
NOOB → … → GHOST → ZERO_DAY → … → FINAL_BOSS. - WDGWars account chip in the top bar when linked.
- WiFi Scan, BLE Scan, BT Tracker (follow a MAC), AirTag Scan.
- WiFi / BT Wardrive — continuous, firmware-streamed capture in WiGLE 1.6 format.
- Cluster Wardrive — the ESP-NOW fleet core (see its section above).
- Packet Sniffer, Handshake Capture (plus a no-SD serial variant that streams the PCAP straight to the host).
- Deauth (targeted) · Blackout (all-channel) · Evil Twin (clone an SSID, serve a captive portal, capture credentials) · SAE Flood (WPA3) · Evil Portal · Dragon Drain (WPA3 SAE flood, host-side) · MITM (ARP spoof + capture).
- BlueDucky / RACE Attack — BLE HID injection & Airoha exploit (work-in-progress).
Use only against your own networks / devices or where you are explicitly authorized.
- LoRa Mesh — one entry for both stacks: MeshCore and native Meshtastic, under a single picker (stack → region / band → preset), a shared chat and a node panel on TAB. Every node the radio hears is saved to loot (deduped, uploaded to WDGWars) and, if it advertised a position, drawn on the map — MeshCore as a purple diamond, Meshtastic as a green hex. On a single SX1262 only one stack listens at a time, so Ctrl+T in the chat flips MeshCore ⇄ Meshtastic (and ←/→ cycles the band). If the LoRa rail is already powered when the game starts, the last-used configured stack auto-resumes in the background; if nothing is configured the radio idles, and if the rail is off nothing mesh-related starts.
- WDGWars Chat (Reticulum / LXMF, over the TCP hub or LoRa).
- RTL-SDR tools — ADS-B Radar (live aircraft + track log + KML export), 433 MHz
Scanner, Emergency Radio (fire VHF / police TETRA detector), 433 Hunter (fox-hunt
a 433 MHz fob with a live RSSI bar + spectrum and a closing-in beep), 433 Capture (record
every 433 MHz signal to raw
.cu8+ a decoded log + a Flipper-ready RAW.sub). - Flipper Zero, Monster RF SubGHz (CC1101), PipBoy Watch (ESP32-S3 watch).
- Proximity Radar — sense other WDGWars players nearby over BLE. Proximity is a shared protocol across the WDGW firmware family (uConsole, Marauder V8, the Badger 2350 badge, and more), so the gear recognises its own in the field — using a rotating, privacy-preserving identity: devices can tell "this is WDGW" without exposing who you are or letting anyone track a specific person.
- WDGWars Sync — upload your wardriving / ADS-B / MeshCore loot to the community server.
- WDGWars Pair — link this device to your account with a short code.
- Chase the White Rabbit — portal objectives drawn on your map, with an edge-of-screen arrow + distance to the nearest off-screen target.
- Game-state HUD — your uConsole ranking, team, decaying territory tiles and active contracts, pulled live and shown on the map.
- Unique device identity — each uConsole gets a stable per-board name
(
<account>-uConsole-<hwid>) used on chat, mesh and the portal.
Loot & data — see backup / restore
- Loot screen (
`/ L): an all-time stats dashboard plus a SESSION LOG journal — browse every capture session by date like a case drawer and preview any file. - WPA-sec upload / download — submit handshakes for distributed cracking and pull back cracked passwords (honest per-handshake accounting).
- Backup / Restore — one-file export of all your data.
Hardware toggles (GPS / LoRa / SDR / USB power rails), Radio (WiFi card) matrix, Whitelist (ignore your own MACs), Reboot ESP32, Flash ESP32, Update Game, Backup / Restore Data, Session Data (browse/delete loot sessions), Captured Data (Evil Twin / portal credential history), Upload WPA-SEC / WiGLE.
Extras are self-contained mini-apps that run inside the game, in their own tab. They can
draw to the screen, read input, and (with permission, if the hardware is present) read GPS,
read/write loot and use per-extra storage — all through a small ctx facade. Third-party
extras run sandboxed in a separate, non-root process: they never touch your files directly
and only exchange draw-ops and permitted data over IPC.
- Install / browse:
EXTRAStab in the game → the hub lists available extras with a rating (🍌 = yes, 🍑 peel = no), search, screenshots and an install button. Official extras (author LOCOSP, shown in green) are made by LOCOSP; everything else is written by its own author. A place in the hub means an extra was reviewed, not that it is endorsed — install and run only extras you understand and trust. - The public hub: https://locosp.github.io/WDGoNG-HUB/ (repo
LOCOSP/WDGoNG-HUB). Catalogue entries are signed offline with a hardware key, so the game can verify what it installs.
Start with the bundled example hello_wardriver (it explains itself on first run), then:
- docs/EXTRAS_authoring.md — the practical guide: folder layout,
extra.jsonmanifest, the entry module & lifecycle, thectxAPI, images and the icon. - docs/EXTRAS_spec.md — the full spec: the security model, the two trust tiers, exclusive-hardware leases, and the permission broker.
- docs/EXTRAS_hub.md — how to submit an extra to the hub and how it is reviewed and signed.
You develop an extra against a local examples folder (WDGO_EXTRAS_EXAMPLES=/path), then open a
PR to the hub when it's ready.
Everything you earn and capture lives under loot/ (XP, badges, sessions, handshakes,
cracked passwords, wardriving CSVs, chat identity) and your keys live in secrets.conf.
Both are gitignored — updates never touch them and nothing is committed.
Back up (one file): SYSTEM → Backup / Restore Data → Export. It writes a single archive
to your home directory:
~/wdgo-backup-<YYYY-MM-DD_HH-MM-SS>.tar.gz # contains loot/ + secrets.conf
Restore on the same device: SYSTEM → Backup / Restore Data → Restore. It restores the
newest ~/wdgo-backup-*.tar.gz, keeps the data it replaced at loot.pre-restore/ as an undo,
and restarts the game.
Move to a new install / new uConsole:
- On the old device: Export (step above).
- Copy the archive to the home directory of the new device, e.g.
scp ~/wdgo-backup-*.tar.gz user@new-box:~/. - Install the game on the new device (Install).
- In the game: Restore — it picks up the newest
~/wdgo-backup-*.tar.gzand relaunches.
Prefer to do it by hand? Just copy the
loot/folder andsecrets.confinto the new checkout before first launch — that's all the game keeps.
A lightweight periodic auto-backup of the loot DB also runs in the background while you play, so a crash can't lose your stats.
Most things auto-detect. When your wiring differs, override via secrets.conf (API keys) or
environment variables (device paths — set them in your shell or at the top of
wdgong_ui/run_ui.sh).
API keys — secrets.conf (copy secrets.conf.example):
| Key | For |
|---|---|
WARDRIVE_API_KEY / WARDRIVE_API_URL |
WDGWars upload (64-char hex key; URL only if self-hosting) |
WDG_WPASEC_KEY |
WPA-sec handshake upload / cracked-password download |
WDG_WIGLE_NAME / WDG_WIGLE_TOKEN |
wigle.net wardriving upload |
Device paths & behaviour — environment variables:
| Variable | Default | Effect |
|---|---|---|
WDGO_PORT |
auto-detect | Force the ESP32 serial port (e.g. /dev/ttyACM0). Auto-detect scans ttyUSB* / ttyACM* and prefers native-USB (XIAO) over a CH340 (Monster RF). |
WDG_GPS_DEVICE |
/dev/ttyAMA0 |
GPS serial device. The uConsole's built-in GPS is the mini-UART — pin it with WDG_GPS_DEVICE=/dev/ttyS0. Auto-probe also tries ttyUSB* / ttyACM* / ttyAMA* / ttyS0. |
WDG_GPS_BAUD |
9600 |
GPS baud rate. |
WDGO_FLEET_KEY |
~/.wdgo/fleet.key |
Path to the 16-byte Cluster fleet key. |
WDGO_CLUSTER_SIM |
off | =1 runs the Cluster screen against a simulated fleet (no hardware, no real loot writes). |
The ESP32 serial is always 115200 8N1. If a second ESP32-C5 (e.g. Monster RF on a CH340)
is present, the game keeps the native-USB board for Wi-Fi/BLE and leaves the CH340 to the
sub-GHz manager — pin with WDGO_PORT if your setup is unusual.
All your data lives under loot/ and secrets.conf. Both are gitignored and never leave
your device — updates (git pull) never touch them, and nothing is committed to the repo.
Captured handshakes and credentials stay local; the game does not upload cracking material to
WDGWars. Configure optional API keys in secrets.conf, or link WDGWars with WDGWars Pair.
WatchDogsGo NG drives real radio hardware and includes tooling that can scan, capture, disrupt and impersonate wireless networks and devices. It is built for security research, education and authorized testing.
Only use it on equipment you own, or where you have explicit, written permission from the owner. Scanning or attacking networks and devices without authorization is illegal in most jurisdictions, as is transmitting on frequencies or at power levels you are not licensed for. Knowing and following the law where you operate is your job, not the software's.
No responsibility. The author (LOCOSP) and contributors accept no liability for any use or misuse of this software, or for any damage, data loss, legal consequence or other harm that results from it. Everything you do with WatchDogsGo NG, you do on your own responsibility and at your own risk.
No warranty. The software is provided "as is", without warranty of any kind, express or implied, including fitness for a particular purpose.
Extras. Extras marked official in the hub (author LOCOSP, shown in green) are made by LOCOSP. All other extras are written by their own authors, not by LOCOSP. A place in the hub means an extra was reviewed, not that it is guaranteed safe or endorsed. Install and run only extras you understand and trust — you do so at your own risk.
Don't be a skid. This is a tool for learning how wireless systems work and for testing what you are allowed to test. Pointing it at strangers' networks, public infrastructure or anyone who did not agree to it is not hacking; it is just being a nuisance with someone else's code, and it gets tools like this banned for everyone. Learn the protocols, break your own lab, report what you find responsibly.
WatchDogsGo NG is source-available under the PolyForm Noncommercial License 1.0.0
(see LICENSE): you may use, study, modify and share it for any noncommercial
purpose — commercial use is not permitted. The supported way to extend it is to write an
extra and publish it through the hub; see the extras docs
to get started.





