A pocket goblin that eats radio waves and gets stronger.
Firmware for the NM-CYD-C5 · ESP32-C5 · dual-band Wi-Fi 6 · BLE 5 · 802.15.4
⚡ Flash it in your browser · 🏆 Leaderboard · 🌐 scout.networkgoblin.dev · 🧌 Network Goblin Labs
You know Tamagotchis? You know Wi-Fi scanners? Somebody (a goblin) put them in a blender.
NG Scout is a little handheld pet that lives on a 2.8" touchscreen and feeds on the airwaves. Carry it around and it quietly listens for Wi-Fi networks, Bluetooth gadgets and smart-home mesh chatter. Every new thing it hears goes into the hoard. The hoard gives XP. XP makes the goblin level up. Levelling up makes the goblin insufferable.
It never connects to anything (except your own Wi-Fi, when you press Sync), never sends probes, and never stores the actual names or addresses of what it hears. It just sniffs. Respectfully. Like a goblin with manners.
Want one? Grab an NM-CYD-C5, plug it into a computer and press Install on the web flasher. Two minutes, no tools.
| 📡 Dual-band Wi-Fi sniffing | 2.4 and 5 GHz, passive beacon listening. Spots Wi-Fi 6, WPS, hidden networks, and the occasional WEP fossil. |
| 🔵 Bluetooth snooping | Passive BLE scans. iBeacons, Eddystone, named gadgets. Phones with rotating addresses count as sightings, not trophies (no farming!). |
| 🕸️ Mesh eavesdropping | The C5's third radio listens to 802.15.4: Zigbee bulbs, Thread sensors, Matter hubs. Your smart home is chattier than you think. |
| 💎 Loot rarity | Every new network or gadget is loot. The goblin works out what it found from the maker code: another Netgear? Common. An office access point left wide open? Legendary. A Starlink dish, a Tesla, AirPods, a Garmin, an Oura ring, a card terminal... 194 brands in 22 kinds, five rarities from Common (1 XP) to Legendary (50 XP), and a Hoard Book to fill in. Phones that keep changing their Bluetooth address only count the first time a brand turns up, so there's no farming. |
| 🐬 Hacker gear | The goblin notices the hacker toys: a Flipper Zero (a wild dolphin appears!), a Pwnagotchi, a Wi-Fi Pineapple, an ESP deauther and Bluetooth popup spam storms. Each one gets its own scene, XP, a trophy, and the Black Hat. Strictly listening: whoever owns the gear never knows. |
| 🦶 Squatch sightings | If a SquachWatch nearby has SquachMesh switched on, Squachy himself drops by (the real one, with his author's blessing): a synthwave sunset, a wave, a high five, and the watch's name if it has one. Fellow pets of the airwaves. |
| 👺 Goblin encounters | Two Scouts near each other notice each other (Pwnagotchi-style). Cue the encounter scene, sparks, hearts and +100 XP for a new friend. |
| 👃 Sniff-offs | Then they sniff each other's hoards. Bigger hoard wins (level breaks a tie) and both goblins get XP. Bragging rights not included, but strongly implied. |
| 🏷️ Tracker alert | Actually useful: if an AirTag, Tile, SmartTag or Google tracker keeps tagging along with you through 3+ places for 15+ minutes, the goblin sounds the alarm. Your own? Tap It's mine and it never nags about that one again. |
| 🏆 144 achievements | Bronze, silver, gold and shimmering-rainbow legendary. Some are secret. One involves petting the goblin a frankly concerning number of times. |
| ✨ A goblin with feelings | It bobs, blinks, hops when it finds something, glows when it levels up, and snores in pocket mode. It also talks (and babbles, if you wire up a speaker). Mostly about packets. |
| 🐈 Pets | The goblin can keep a cat (Setup → Pet): Pip the torico, Lily the tiny tortie, or both. They loaf, swish their tails, blink slowly, prick up their ears while it scans, hop when it finds something, purr when you pet the goblin and curl up together when it naps. |
| 🍖 Needs | It gets hungry (feed it new devices) and bored (show it new channels, places, networks and goblins). Keep both meters full and it earns +25% XP. Neglect it and it sulks. |
| 📜 Quests | A board of three challenges at a time: "Sniff out 20 new networks", "Find a Wi-Fi 6 router"... Clear the board for bonus XP, then a fresh one turns up. |
| 🎩 Hats | 18 hats, from party hat to wizard hat to tinfoil hat, unlocked by milestones, plus seasonal ones (Witch Hat in October, Santa Hat in December...). Your hat travels in the goblin beacon, so other goblins see it when you meet. Fashion matters. |
| 📡 Radar | A live sweep of everything heard in the last minute. Distance = signal strength, colour = radio, other goblins show up as little goblin heads. |
| 🪪 Share card | Hold the goblin (or Setup → Share card) for a trading card with its name, level, hat, stats and a QR code (to your goblin's leaderboard page once you've synced). Made for photos. |
| 🌙 Day & night | Dawn glow, dusk glow, a starry night sky, and a goblin that naps from 11 pm (it keeps sniffing in its sleep). Needs the time: GPS, or set the clock in Setup. |
| 🔋 Battery-aware (optional) | Add a LiPo and a fuel gauge (MAX17048, or the BQ27441 on a SparkFun Battery Babysitter; see docs/battery.md) for battery % and a charging bolt in the status bar, and a sleepy goblin when it runs low. |
| 🗺️ Exploration (GPS optional) | Plug in a GPS for daily streaks and "areas explored". Coordinates never leave the SD card. |
| 📈 Leaderboards | Press Sync (Setup → Sync & leaderboard) and your goblin uploads a summary of its hoard over your Wi-Fi to the leaderboard: XP, this week, Wi-Fi, Bluetooth, mesh, goblins met, trophies and sniff-offs, plus a profile page per goblin. Counts only, no account needed, and remove me takes you off again. |
| 📴 Offline first | No account, no cloud, no app needed. Syncing is optional and only happens when you press the button. The SD card is optional too (but without it the goblin forgets everything at bedtime). |
These are rendered on a PC from the real UI code (sh tools/preview/run.sh), so they're exactly what the
firmware draws, minus the smudges on your screen.
- Open scout.networkgoblin.dev/flash in Chrome or Edge on a computer.
- Plug the board in with a USB-C data cable.
- Press Install Scout (new board) or Update Scout (already running Scout), pick the board's port, wait a minute.
- Copy
sd_card/onto a FAT32 microSD card and slot it in. The goblin needs somewhere to keep its hoard. - Press RESET. Accept the disclaimer and name your goblin on the on-screen keyboard. Scanning starts after that.
The flasher always serves the latest tested release and writes every file at the right address.
- Download the files from the web flasher page (links under
Prefer the command line?), or from this repo's Actions tab → latest green build → Artifacts
(
ng-scout-<commit>, every commit, untested). - Flash
firmware.factory.binat0x0:- Browser: https://espressif.github.io/esptool-js/ (Chrome/Edge), add the file at
0x0, Program. - Command line:
pip install esptool, thenesptool --chip esp32c5 --port <COM5 or /dev/ttyACM0> write-flash 0x0 firmware.factory.bin
- Browser: https://espressif.github.io/esptool-js/ (Chrome/Edge), add the file at
- If it won't connect: hold BOOT, tap RESET, let go of BOOT, try again.
- SD card and first boot: as steps 4-5 above.
Your progress lives on the SD card (/scout/), so re-flashing doesn't touch it.
- Updates: the web flasher's Update Scout, or
firmware.binat0x10000by hand (app only, keeps the chip's settings too). - First install or recovery: flash
firmware.factory.binat0x0. This also wipes the chip's internal settings, but the goblin's name and ID are restored from the SD card at the next boot.
⚠️ Check the address before you press flash. Many tools (including Espressif's web tool) default to0x0.firmware.binwritten at0x0overwrites the bootloader, and the board boot-loops withinvalid header: 0x5d455b5don the serial log. Not bricked: flashfirmware.factory.binat0x0(or use the web flasher's Install) and it's back, progress included.
pip install platformio==6.2.0
pio run # build
pio run -t upload # flash
pio device monitor # watch the goblin think out loud (115200 baud)The first build downloads the pioarduino platform (Arduino core 3.3.x, the only one that speaks ESP32-C5). It's big. Make a sandwich.
- Tabs along the bottom: Home, Radar, Stats, Loot, Setup. Swipe left/right to flip tabs and pages.
- Tap the goblin to pet it. It likes that. Probably. Hold it to pull up its share card.
- Loot = quests, then the wardrobe (tap a hat to wear it), then the Hoard Book (every brand and kind of gadget found so far), then the trophy shelf. Tap a badge to read what it's for. Secret ones stay secret until you earn them.
- Setup keeps the everyday rows at the top: your goblin's name, Sync & leaderboard, Pet and Share card, then the radios and display. On/off rows only flip when you tap the switch itself, so a stray tap while scrolling won't turn a radio off.
- Setup → Pet picks a cat for your goblin: Pip, Lily, both, or none.
- Food & fun meters (top left of Home): a fed, entertained goblin earns +25% XP. Take it somewhere new.
- BOOT button = pocket mode: screen off, goblin keeps sniffing. Tap the screen to wake it.
- Setup → Turbo display runs the screen at full speed. If you see glitches, turn it off.
- Setup → Goblin beacon controls whether other goblins can find yours (see privacy below).
- Setup → Sync & leaderboard: pick your Wi-Fi once, then Sync now whenever you want your goblin's numbers on the leaderboard. The QR code on that screen opens your goblin's page. remove me (tap twice) takes your goblin off the boards; Sync puts it back.
- Back up
/scout/sync.keysomewhere safe: it's your goblin's leaderboard identity. If the SD card dies, copy it onto the new card and your goblin keeps its place. - Setup → Clock sets the time (no GPS needed; it's forgotten at power-off). With GPS it sets your time zone instead.
- Setup → About (the top row) to rename your goblin.
Something weird with a new board? Power on and press BOOT within 1.5 s while the splash says "press BOOT now for diagnostics". (Holding BOOT while plugging in puts the C5 into flashing mode instead. Ask us how we know.)
You get one screen, mirrored to serial every 2 s: PSRAM, SD card test, raw touch values, Wi-Fi / BLE / 802.15.4 scan counts, goblins seen, GPS, an I2C scan, LED colours and display colour swatches. Press RESET to leave.
The goblin is nosy, not creepy.
- Listening is passive. Wi-Fi listens for beacons (no probe requests), BLE never sends scan requests or connects, and 802.15.4 only listens.
- Nothing raw is stored. MAC addresses, SSIDs and mesh addresses are kept only as salted SHA-256 ids (the salt is random per device). You can count your hoard but you can't read it back.
- GPS stays home. Coordinates are written to the SD card and nowhere else: not the screen, not serial.
- Loot without logging. To rate a find, the goblin looks at the router's maker code (the first half of its address) and, for random addresses, a few name patterns ("DIRECT-", "iPhone"...), or at the company id in a Bluetooth advert, in memory at that moment. Only the brand ("Netgear") and the counts are kept. The maker lists come from the IEEE registry and the Bluetooth SIG.
- No farming. BLE devices with rotating private addresses (most phones) are sightings, not unique devices.
- Tracker alert stays local. Trackers are followed by salted id, in memory, to spot one that keeps following you. Nothing is sent anywhere. Works best with AirTags and other Find My tags, Tile and Google tags; trackers that change address often can slip through, so treat silence as "not seen", not "safe".
- Sync only when you say so. Goblin Sync joins your Wi-Fi only when you press Sync, uploads counts (level, XP, how many networks/devices, trophies, hats), then disconnects. Never names, addresses, ids or locations. Your Wi-Fi password stays on the device. Uploads are signed with a key that never leaves it (except once, over HTTPS, to register), so nobody else can post as your goblin.
- Goblins met, honestly. Sync also sends the random beacon ids of goblins you've met, so the server can count a meeting only when both goblins report it. The site only ever shows how many, never who met whom.
- Leave any time. Sync screen → remove me (tap twice) deletes your goblin's entry from the server. Pressing Sync later puts it back.
- The one thing it sends on its own is the goblin beacon: a non-connectable BLE advert with a random goblin id, a generated goblin name, its level and colour. It uses a random address made fresh at every boot (never the chip's real Bluetooth MAC). It also carries your hat and a rough hoard size for sniff-offs. Switch it off in Setup and you can still see other goblins.
/scout/salt.bin random per-device salt (don't share)
/scout/state.json XP, counters, channels, achievements, settings
/scout/wifi.csv id, ssid_id, channel, auth, rssi, unix_time, lat, lon (one line per new BSSID)
/scout/ssids.txt ids of unique SSIDs
/scout/ble.csv id, rssi, unix_time (one line per new stable BLE device)
/scout/154.csv id, pan_id, channel, zigbee|thread|?, rssi, unix_time (one line per new mesh device)
/scout/pans.txt ids of mesh networks (PAN id + channel)
/scout/peers.txt ids of goblins met, their level when you met
/scout/cells.txt ids of ~5 km exploration cells visited
/scout/trackers.txt ids of item trackers heard, and what kind
/scout/trackers_ok.txt trackers you said are yours (no alerts for these)
/scout/sync.key your goblin's leaderboard key (like salt.bin: don't share it)
/scout/met.txt beacon ids of goblins met (for the leaderboard's encounter cross-check)
/sprites/<pack>/ sprite packs (see below)
Don't like the default goblin? Rude, but fine. Drop a pack in /sprites/<name>/ and pick it in
Setup → Sprite pack. Example: the included pixel_goblin.
{
"name": "Pixel Goblin", "author": "you", "version": "1.0",
"states": {
"idle": ["idle_01.bmp", "idle_02.bmp"],
"scanning": ["scan_01.bmp", "scan_02.bmp"],
"happy": ["happy_01.bmp"],
"excited": [], "level_up": [], "achievement": [], "searching": [],
"sleep": [], "low_battery": [], "offline": [], "uploading": [], "sync_complete": []
}
}- BMP: 24-bit, 32-bit (alpha) or 16-bit RGB565, uncompressed, max 128×128.
- 64×64 or smaller gets drawn at 2× (pixel-art friendly). Magenta
#FF00FFis transparent. - Missing states fall back to
idle; a broken pack falls back to the built-in goblin. - Aliases:
discovered←happy,level_up←levelup,sleep←sleeping.
include/board.h pin map from the NM-CYD-C5 v1.0 schematic
include/config.h tunables: display, touch calibration, scan timing, XP rules
src/main.cpp wiring + main loop
src/hal/ display, touch, SD, GPS, LED/speaker, battery gauge
src/scanners/ one Scanner per radio: Wi-Fi, BLE, 802.15.4 (+ ScanManager)
src/social/ the goblin's identity, its "I'm a goblin" beacon, sniff-offs and Goblin Sync
src/core/ Engine (sighting → XP → achievements → SD), achievements list
src/ui/ screens, the animated goblin, widgets; gfx/ = tiny renderer
src/diag/ hardware bring-up mode
test/ PC unit tests (802.15.4 parser, beacon, quests, tracker alert, clock)
tools/preview/ renders the real UI on a PC into PNGs (CI also runs it under AddressSanitizer)
tools/bench/ counts instructions per frame on the ESP32-C5's CPU type (emulated)
tools/gen_assets.py turns assets/ (logo, fonts) into C++ headers
sd_card/ copy to the microSD card
- New radio? Implement
Scanner(begin / start / poll) andscans.add()it. The engine doesn't care where a sighting came from. - New achievement? Append a line to
ACHIEVEMENTS[]insrc/core/Achievements.cpp. Never reorder or rename ids; they're saved on SD. - New hat? Append to
kHats[]insrc/core/Hats.cppand draw it insrc/ui/HatArt.cpp. New quest type? Append toquests::TypeandkDefs[]insrc/core/Quests.cpp. - Share card link? Set
NG_SHARE_URLininclude/config.h. - New screen tweak? Run
sh tools/preview/run.shand look attools/preview/out/before flashing.
- Display, touch, SD, GPS (auto-detect), RGB LED, speaker
- Dual-band Wi-Fi + BLE sniffing, persistent dedupe
- 802.15.4 (Zigbee / Thread) sniffing
- Goblin encounters (needs two goblins, or a phone faking one; see
CLAUDE.md) - 144 achievements, levels, streaks, exploration
- Hunger & boredom, quest boards, 18 hats (4 seasonal), radar, share card with QR code
- Animated goblin and a UI that doesn't look like 1997
- First-run disclaimer, name your goblin, progress survives re-flashing
- Tracker alert, sniff-offs, day/night, seasonal hats
- Battery support in firmware (MAX17048 or BQ27441). The hardware side is DIY: docs/battery.md
- Goblin Sync, leaderboards and goblin profiles, self-service removal
- Web flasher: install and update from the browser
- Encounter cross-checks: the "goblins met" board counts only meetings both goblins report
- Loot rarity: 194 brands (Wi-Fi and Bluetooth), five rarities, a Hoard Book, and a Legendary finds board
- Hacker gear sightings: Flipper Zero, Pwnagotchi, Wi-Fi Pineapple, deauthers, Bluetooth popup spam
- SquachWatch visits (their SquachMesh hello, read from its published format), now with the real Squachy
- Pets: Pip the torico and Lily the tiny tortie
- A tidier Setup screen (everyday rows first, switches that don't flip by accident)
-
Temperature statthe on-board AHT20 turned out to be imaginary (not fitted)
- Goblin art: Network Goblin.
- Fonts: Orbitron and
Rajdhani, SIL Open Font License (see
assets/fonts/). - Board: RockBase NM-CYD-C5.
- Display library: Arduino_GFX.
- Maker codes: the IEEE OUI registry and the Bluetooth SIG company list
(via the
bluetooth-numberspackage), turned into a table bytools/gen_oui.py. Thanks to SquachWatch for the nudge to look at what the radios are saying (and for its careful notes on which maker codes can be trusted). - Squachy, the visiting sasquatch, is SquachWatch-CYD's
mascot by skizzophrenic, used with permission (his waving frames, unaltered, in
assets/squachy/). He isn't covered by this repo's licence: seeassets/squachy/CREDITS.mdbefore reusing him. - QR codes: Nayuki's QR Code generator (MIT), in
lib/qrcodegen/.
Feed the goblin. Respect the airwaves.

























