Standalone firmware for the StackChan-Gotchi: a pwnagotchi-style WiFi/BLE reconnaissance companion that runs on the M5Stack CoreS3 + StackChan robot.
This is the gotchi app extracted from the M5Stack StackChan firmware (monorepo: firmware + app + server) into its own self-contained ESP-IDF project. No launcher, no AI-agent stack, no camera/audio — just the gotchi.
- M5Stack CoreS3 (ESP32-S3, 16MB Flash, 8MB PSRAM)
- StackChan robot body: 2x SCS feedback servos (UART1, SCSCL), 12x RGB neon LEDs (PY32 IO expander), head touch, RTC, IMU
- Optional: GPS-BDS Unit v1.1 on UART2 (PORT.C) for WARDIVE mode
- WiFi beacon capture (promiscuous mode, channel hopping 1-13)
- EAPOL handshake capture (802.11-2020 spec parser)
- BLE device scanning (NimBLE)
- 42-level XP system + 37 achievements + daily challenges + prestige
- 10 modes: IDLE, SCOUT, HUNT, WARDIVE, SPECTRUM, BLE-SCAN, ROGUE, CONFIG, STATS, HOME_NET
- Web config portal (AP: StackChan-Config @ 192.168.4.1)
- WiGLE / WPA-Sec uploads
- GPS wardriving with auto-save to wardrive.csv
- Persistent storage: NVS (XP/achievements/config) + 2MB FATFS partition
Requires ESP-IDF v5.5.4 (esp32s3 target).
cd gotchi-firmware
. $IDF_PATH/export.sh # or ~/esp/esp-idf/export.sh
idf.py build
idf.py -p /dev/ttyACM0 flash monitorThe CoreS3 enumerates as /dev/ttyACM0 (native USB).
| Partition | Size | Purpose |
|---|---|---|
| nvs | 24KB | XP, achievements, config (via Settings/NVS) |
| factory | 5MB | firmware |
| storage | 2MB | FATFS: wardrive.csv, handshakes, logs |
| coredump | 64KB | - |
There is no assets partition — the status-bar icons are embedded in the
firmware binary (see main/assets/).
main/
├── main.cpp - entry point: HAL init + AppGotchi + mooncake loop
├── gotchi/ - core scanning logic (pure ESP-IDF + FreeRTOS)
├── apps/app_gotchi/ - gotchi UI app (mooncake AppAbility + LVGL)
├── apps/common/ - loading page, status bar, home indicator
├── stackchan/ - avatar, motion, modifiers, neon lights
├── hal/ - slimmed HAL: board, display, touch, servo, RTC, RGB
│ └── board/ - CoreS3 bring-up (PMIC, display, touch) + hal_bridge
├── assets/ - embedded icon images
└── third_party/ - vendored xiaozhi-esp32 files (Settings, AXP2101,
I2cDevice, Backlight) - see third_party/README.md
components/ - vendored: mooncake, mooncake_log, smooth_ui_toolkit, ArduinoJson
Built from the StackChan-Gotchi fork of M5Stack/StackChan firmware v1.4.1 (xiaozhi-esp32 based). The gotchi core and app are the user's own code; the HAL/stackchan/mooncake layers are upstream M5Stack code kept under their original MIT licenses. See LICENSE files in each directory.
The pre-standalone monorepo (Go server, Flutter companion app, ESP-NOW remote,
and the gotchi embedded in the StackChan launcher firmware) is preserved on
the monorepo branch of this repository (tip daac836). It is not built or
maintained; the standalone firmware in main/ is the only supported code.
For educational and security research purposes only. Only test networks you own or have explicit permission to test.