Wireless discovery, packet dissection, and field telemetry instrument for the M5Stack Cardputer ADV.
An open-source RF instrumentation initiative by d3FRAG Networks.
Interactive Brand & UI Guide · Deck UI State (as-built) · Software Design (DESIGN.md) · Hardware Authority (Rev D) · Protocol Spec (OCP-SPEC.md) · Decisions
Important
◇ INVARIANT: RECEIVE-ONLY BY CONSTRUCTION
No transmit verb exists in protocol/ocp.h, no TX command is compiled into any Oscilla firmware build, and every radio scan is strictly passive (WIFI_SCAN_TYPE_PASSIVE). The probe's command table is the entire capability surface — with no TX verb in it, there is no reachable firmware code path to transmission on any radio. Tripwires (tools/check_rx_only.py) fail the build if transmit-capable driver APIs are reached.
Stated deliberately. See DESIGN.md §8, AGENTS.md §3, and D-8.
Oscilla splits physical responsibilities cleanly between two microcontrollers joined by a 4-pin Grove cable (UART 115200 8N1 crossover). They speak the Oscilla Control Protocol (OCP), compiling against the shared protocol/ocp.h header so the contract cannot silently drift.
┌──────────────────────────────────────────────┐ 4-Pin Grove Crossover Cable ┌──────────────────────────────────────────────┐
│ THE DECK │ (UART 115200 8N1 · Crossover) │ THE PROBE │
│ M5Stack Cardputer ADV │◄───────────────────────────────────────►│ Seeed XIAO C5 Radio Backpack │
│ │ G2 (TX) ──► D7 G1 (RX) ◄── D6 │ │
│ • ESP32-S3 Dual-Core (UI, Storage, GNSS) │ │ • ESP32-C5 RISC-V (2.4 / 5 GHz Wi-Fi 6) │
│ • 56-Key Matrix Keyboard + Navigation D-Pad │ OSCILLA CONTROL PROTOCOL │ • Bluetooth 5.0 LE (Coded PHY / 1M / 2M) │
│ • ST7789 240×135 Built-in Screen (Primary) │ `protocol/ocp.h` Contract │ • IEEE 802.15.4 MAC observer │
│ • ILI9341 320×240 External Panel (P5 plan) │ │ • Wio-SX1262 LoRa (862–930 MHz / Meshtastic)│
│ • MicroSD FAT32 Geotagged Storage Logs │ Framed ASCII Verbs · Escaped Octets │ • One external sub-GHz receiver (SX1262) │
│ • ATGM336H GNSS Fix & Timestamping Engine │ `[HELLO]` `[LORA]` `[SCAN]` `[BLE]` │ • Shared Hardware SPI Bus (D8/D9/D10) │
└──────────────────────────────────────────────┘ └──────────────────────────────────────────────┘
The C5 probe's v1 sub-GHz receiver is the Wio-SX1262. D-15 archives the
former CC1101 experiment in the separate cc1101 branch; it is not a product
mode.
| Peripheral | Primary Band | Demodulation Target | Example Target Traffic |
|---|---|---|---|
| Seeed Wio-SX1262 | 915 MHz (862–930 MHz) | LoRa Chirp Spread Spectrum | Meshtastic mesh, LoRaWAN sensors, decentralized telemetry |
- Isolation & Robustness: The deck is an ESP32-S3 with a keyboard and dual screens; its internal radios stay off in v1. The C5 is a dedicated RF platform with zero human interface. The UI never blocks on radio tasks, an RF fault never freezes the display, and the probe can be operated standalone over USB from a laptop workstation.
- Authoritative Geotagging: The probe never handles GPS coordinates. It streams timestamped observation frames; the deck attaches its own ATGM336H GNSS fix and fix-age before serializing to SD.
Oscilla's interface architecture pairs a built-in interactive console with a pure-data external instrument panel:
- Primary Screen (ST7789 240×135 @ 16:9): Integrated Cardputer deck screen. Carries the top system bar (battery, radio status dots, transport status), live navigable lists, interactive menus, and tactical footers.
- External Instrument Panel (ILI9341 320×240 @ 4:3): Secondary SPI DMA landscape panel. Pure data viewport with zero control redundancy, zero buttons, and high-contrast tactical visualizations.
Explore the complete master design system in docs/brand/oscilla-master-brand-ui-guide.html.
| Viewport | Instrument Visualization | Purpose & Metrics | Status |
|---|---|---|---|
| Spectrum | Continuous RF waterfall cascade & channel occupancy envelope | 60% burst threshold, focused-channel RF metrics, interference floor | P5 shell |
| Contacts | Polar RSSI proximity reticle & AP-client constellation filaments | Rogue beacon detection, BSSID/ESSID tracking, PMF/WPA3 audit | P7 |
| Drive Log | Dynamic N/W geospatial vector moving map & rolling density sparkline | GNSS track, heading rose, GPS accuracy error circle, serialized SD rate | P4/P7 |
| Frame List | LoRa chirp modulation spectrogram & live Protobuf packet dissector | Preamble/sync chirp ramps, bitstream pills, hex dump, SNR/RSSI telemetry | P3 proven |
| BLE Beacons | Polar advertiser proximity reticle & rotation burst tracker | Apple Find My / AirTag tracking, RPA epoch rotation bursts, range est. | P7/P8 |
| Mesh | Passive 802.15.4 PAN/node inventory | MAC-only PAN and address sightings; no route or network-layer claims | P7 capture proven; display unverified |
Current Milestone: P4 Complete; P5 next.
- Protocol contract (
protocol/ocp.h) and framing parser proven against hostile conformance fixtures. - Grove physical crossover link bench-verified with stable bidirectional communications.
- Passive Wi-Fi 2.4/5 GHz scanning verified on hardware.
- LoRa RX verified on hardware: Wio-SX1262 backpack receiving and decoding real MeshCore packets end-to-end with zero RX stalls over extended sessions (>66 min).
- Next Phase: P5 (external TFT shared-SPI integration).
See ROADMAP.md for full phase-by-phase entry/exit gates and test evidence, and WORKLOG.md for session-by-session engineering logs.
| Document / Directory | Role & Authority | Never |
|---|---|---|
Research/c5-backpack-design.md |
Hardware Authority (Rev D): Pins, rails, bus sharing, electrical limits. | Write a pin constant from any other file. |
DESIGN.md |
Software Authority: Architecture, task boundaries, module scope. | Exceed documented scope without a decision. |
protocol/ |
The Contract: ocp.h (literals) + OCP-SPEC.md (wire behavior). |
Hardcode a verb or marker string anywhere else. |
docs/DECISIONS.md |
Decision Register: D-numbered records of resolved/deferred questions. | Resolve a ⛔ decision by guessing. |
AGENTS.md |
Operating Manual: Invariants, authority hierarchy, and bench gotchas. | Break receive-only or run .sh on Windows. |
SECURITY.md |
Threat Model: Data handling, wardrive hygiene, disclosure policy. | Commit field CSVs or sensitive captures. |
firmware-c5/ |
The Probe: ESP-IDF v5.5.1 firmware for XIAO ESP32-C5. | Spin in tasks without explicit vTaskDelay. |
firmware-cardputer/ |
The Deck: PlatformIO / Arduino C++ firmware for Cardputer ADV. | Bypass the shared SD/TFT SPI bus lock. |
tools/ |
Host Client & Verification: CLI parser, REPL, and compliance test suites. | Require hardware for protocol verification. |
docs/brand/ |
Visual System: Master Brand & UI Guide for primary and external displays. | Deviate from brand color and font tokens. |
docs/deck-ui-state.html |
As-Built UI Reference: what the deck actually renders today, read from ui/*.cpp. |
Treat as design authority — that's docs/brand/. |
You can verify the protocol contract and parser conformance on your workstation using Python 3 and standard build tools:
# Verify ocp.h compiles clean, invariants hold, and no transmit verbs exist:
./tools/check_protocol.sh
# Run the OCP-SPEC §9 parser compliance test suite (27 checks):
python3 tools/ocp_repl.py --selftest
# Replay an adversarial fixture containing boot chatter, escaped octets, and split frames:
python3 tools/ocp_repl.py --replay tools/fixtures/boot_and_scan.txtWindows Host Note: Use native PowerShell / Python commands. Do not execute
.shscripts directly in pwsh without bash.
Connect the XIAO ESP32-C5 probe via USB-C to your workstation (pyserial required):
# Connect to probe via serial port (specify explicit chip type):
python3 tools/ocp_repl.py /dev/serial/by-id/usb-Espressif_...Both toolchains are installed on the bench machine:
- ESP-IDF v5.5.1 (
~/esp/esp-idf) for the ESP32-C5 probe. - PlatformIO Core 6.2.0 (
~/.platformio/penv) for the Cardputer ADV deck.
# Build both images:
./tools/build_firmware.sh
# Build only the C5 USB bench image (the CI optimization):
./tools/build_firmware.sh --bench --probe-only
# Or build individually:
source tools/env.sh
cd firmware-c5 && idf.py build
cd firmware-cardputer && pio run
# Flash the C5 over native USB Serial/JTAG. The reset modes in this helper
# are required for reliable C5 download-mode entry/exit, especially after a
# manual BOOT-button entry:
./tools/flash_c5.sh --bench # USB OCP bench image
./tools/flash_c5.sh --uart # Grove OCP image (default)
./tools/flash_c5.sh --uart --loader # if already in ROM loader modeCaution
Bench Power Rule: When testing on the bench, keep both boards connected to their own USB cables, and leave the Grove 5 V (red wire) disconnected and insulated. Grove-powered operation is deferred until P6 establishes a measured power budget.
Oscilla records the physical whereabouts of its operator and ambient wireless emitters. Wardrive logs, KML tracks, and raw packet captures belong strictly on the deck's local microSD card and must never be committed to the repository (.gitignore enforces extension rules).
Always sanitize observations and post analytical summaries rather than raw rows. See SECURITY.md for disclosure policies and data handling rules.
Oscilla stands on the shoulders of several pioneering open-source embedded RF and wireless reconnaissance projects:
- ESP32 Marauder by @justcallmekoko: Pioneered handheld ESP32 wireless field telemetry, wardriving, and tactical portable UI. Oscilla draws strong conceptual inspiration from Marauder's field utility and wardrive workflows, but structurally diverges by splitting into a dual-machine architecture (Deck + Probe) and enforcing a strict receive-only invariant (no deauthentication, no packet injection, zero transmit verbs).
- C5Lab projectZero (MIT): The primary architectural reference for early ESP32-C5 dual-band Wi-Fi (2.4/5 GHz) and IEEE 802.15.4 operations. Oscilla studied projectZero's multi-band sniffer patterns, NimBLE passive scanning, and adaptive channel selection.
- esp32-wifi-penetration-tool by Martin Risinek (@risinek, MIT): The upstream foundation from which projectZero descended. Provided foundational ESP32 Wi-Fi frame dissection and promiscuous sniffer hooks.
- Meshtastic & MeshCore: Inspires Oscilla's passive LoRa mesh topology inspection, hop tracing, and Protobuf dissector.
To maintain rigorous code health, modularity, and licensing integrity, Oscilla follows strict reuse boundaries (DESIGN.md §11):
| Component / Subsystem | Upstream Source | Integration Method | Implementation Status |
|---|---|---|---|
| 802.15.4 Recon | C5Lab projectZero (MIT) | Clean-room reimplementation; no source copied | P7 passive MAC PAN/node discovery in firmware-c5/main/zig_*.c; live capture and no-auto-ACK control verified, with no Zigbee/Thread identity or network decode (hardware evidence) |
| D-UCB Channel Picker | projectZero (MIT) | Clean-room reimplementation | Discounted-bandit adaptive channel allocation in firmware-c5/main/ |
| Wi-Fi Promiscuous Sniffer | @risinek / projectZero (MIT) | Clean-room reimplementation | Passive non-blocking 2.4/5 GHz frame parser in firmware-c5/main/ |
| NimBLE Passive Tracker | projectZero (MIT) | Clean-room reimplementation | BLE beacon, AirTag, and RPA rotation tracking in firmware-c5/main/ |
| SX1262 LoRa Driver | In-house (Oscilla) | Authored in-house | Bounded timeouts, Rev D pin mapping, strict RX-only in lora_radio.c |
| Cardputer Deck UI & HAL | M5Unified / M5GFX (MIT) | PlatformIO dependency | Pinned releases (M5Unified 0.2.21, M5GFX 0.2.28, M5Cardputer 1.1.1) |
Deliberately Excluded Upstream Code:
- All transmit & offensive engines: Oscilla rejects all deauth, beacon spam, PMKID injection, and active attack modules from upstream tools. Oscilla is strictly receive-only by construction (DESIGN.md §8, D-8).
- Monolithic source files: projectZero's
main.cmonolith is explicitly on the do-not-copy list (AGENTS.md §7.2). Oscilla enforces single-responsibility modules (~300 lines soft cap).- 802.15.4 recon: projectZero's
zig_recon/is a reference for behavior and protocol boundaries only. Oscilla's implementation is in-house, receive-only, and limited to passive MAC observations.