LabzOS

An open-source, cyberpunk-themed firmware for the M5Stack Cardputer ADV — a pocket wireless-security multitool with a local-LLM voice assistant.

⚠️ Authorized use only. LabzOS includes WiFi/BLE/SubGHz transmit features (deauth, beacon/probe floods, BLE advertising spam, SubGHz replay, jammers) that are illegal to use against networks/devices you do not own or have explicit written permission to test. You are solely responsible for complying with all local laws. Use it on your own gear, in a lab, or under an authorized engagement — nothing else.

Features

• WiFi — AP/station scan, packet/beacon/probe/EAPOL-PMKID sniffers, Pwnagotchi & deauth detectors, deauth (broadcast + targeted), beacon spam, probe flood, Karma, Evil Portal, PCAP capture, wardrive
• Bluetooth LE — scan, AirTag/Flipper detect, card-skimmer detector, wardrive, advertising spam (Apple/Windows/Samsung/Google)
• Fox Hunter — unified WiFi+BLE threat/surveillance scanner (Flock, Meta, Pineapple, DJI, Flipper, AirTag) with a user-editable OUI watchlist
• SubGHz / 2.4GHz radio (optional CC1101 + nRF24 add-on) — scan, SubGHz replay/brute, nRF24 scan/jam
• LoRa / GNSS (optional add-on) — packet sniff, GNSS info, offline OSM map
• AI voice chat — talk to your own local LLM (Ollama-compatible) with optional Piper STT/TTS, plus an optional Google Gemini bridge
• Tools — calculator, hex/unit convert, timer, stopwatch, clock, metronome, tone gen, dB meter, level, protractor, compass, morse, TV-B-Gone, dice, and more
• IR — TV-B-Gone
• Neon Neo-Tokyo UI with selectable boot tunes, adjustable brightness/volume

Hardware

• M5Stack Cardputer ADV (ESP32-S3, no PSRAM)
• Optional: CC1101+nRF24 SubGHz/2.4GHz cap, or a LoRa+GNSS cap (they share the header — one at a time)
• microSD card (for PCAP/wardrive logs, notes, map tiles)

Build

Requires PlatformIO.

git clone <this-repo> && cd LabzOS
cp config_local.h.example config_local.h   # optional — see Configuration
pio run                                     # build

Flashing (Cardputer ADV, via M5Launcher SD-MSC — OTA is unreliable on this board): copy .pio/build/m5stack-cardputer/firmware.bin to the SD card as LabzOS.bin, then pick it in M5Launcher. Flash with any radio cap removed (the extra draw makes USB-CDC flap).

Configuration

Everything can be set on-device — no rebuild needed:

• WiFi — first-run setup wizard, or the USB-CDC wifi set <ssid> <pass> command
• LLM — the on-device Model picker (Fn+M) probes your LLM host for models

…or bake defaults into the build by copying config_local.h.example to config_local.h (git-ignored) and filling in WIFI_SSID, LLM_HOST, etc.

For AI chat you need an Ollama-compatible endpoint reachable from the device (/api/tags + /v1/chat/completions). Voice chat additionally needs a Piper STT/TTS proxy. Both are optional — the firmware is fully usable for the wireless tools without any LLM.

Credits & License

LabzOS ports and adapts techniques from several GPL projects, gratefully: ESP32 Marauder, Bruce, and Ghost ESP. Built on M5Cardputer, NimBLE-Arduino, and ArduinoJson.

Licensed under GPL-3.0 (see LICENSE) — required by the licenses of the projects it derives from.