Dev

.gitignore

@@ -1,2 +1,29 @@
 .DS_Store
-.idea/
+.idea/
+.vscode/
+
+# Build outputs
+*.log
+build_output.txt
+
+# OS files
+Thumbs.db
+*.swp
+*~
+
+# Firmware build
+firmware/build/
+firmware/cmake-build-*/
+firmware/managed_components/
+firmware/sdkconfig
+firmware/sdkconfig.old
+
+# Go build
+server/*.exe
+server/stackchan-server
+server/tmp/
+
+# Node/Flutter (if applicable)
+node_modules/
+.pubspec.lock
+.dart_tool/

README.md

@@ -1,32 +1,143 @@
-# StackChan Open-Source
+# StackChan-Gotchi
 
-<img src="https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/K151_stack_chan_main_pictures_01.webp" width="60%">
+<p align="center">
+  <img src="https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/K151_stack_chan_main_pictures_01.webp" width="60%">
+</p>
 
-Here are StackChan related open-source resources, including source code of the StackChan firmware, remote controller firmware, mobile app (iOS and Android), and server. 
+A **pwnagotchi-style WiFi/BLE reconnaissance companion** for M5Stack CoreS3 robot (StackChan). Combines Tamagotchi-like gamification with network scanning, uniquely leveraging StackChan's robot capabilities—expressive face, head movement, and neon lights.
 
-Update of this repo could be a little late than the released firmware and mobile app. 
+---
 
-----
+## Overview
 
-<img src="https://cdn.shopify.com/s/files/1/0056/7689/2250/files/5a589623895f65487717894d9240f6b8.png" width="60%">
+**Goal**: Create an engaging WiFi/BLE reconnaissance tool that leverages StackChan's robot capabilities to make network security research more interactive and fun.
 
-**StackChan is a super kawaii AI desktop robot co-created by M5Stack and the user community.** It uses the M5Stack **flagship IoT development kit [CoreS3](https://docs.m5stack.com/en/core/CoreS3)** as its main controller, powered by an ESP32-S3 SoC featuring a 240 MHz dual-core processor, with 16MB Flash and 8MB PSRAM onboard, and supporting Wi-Fi and BLE. The main unit also integrates a 2.0-inch capacitive touch display with a high-strength glass cover, a 0.3 MP camera, a proximity & ambient light sensor, a 9-axis IMU (accelerometer + gyroscope + magnetometer), a microSD card slot, a 1W speaker, dual microphones, and power/reset buttons. 
+**Hardware**: M5Stack CoreS3 (ESP32-S3, 16MB Flash, 8MB PSRAM) + GPS Unit (optional)
 
-The **robot body**, connected to the main unit, includes a USB-C interface for power and data, a 550 mAh battery, two feedback servos (360-degree continuous rotation on the horizontal axis and 90-degree movement on the vertical axis), two rows totaling 12 RGB LEDs, infrared transmitter and receiver, a three-zone touch panel, and a full-featured NFC module. 
+**Inspiration**:
+- [pwnagotchi] (https://github.com/evilsocket/pwnagotchi) - the original security "gotchi" for rPi
+- [M5PORKCHOP](https://github.com/0ct0sec/M5PORKCHOP) - Gamification, XP system, multiple modes, personality
+- [M5Gotchi](https://github.com/Devsur11/M5Gotchi) - Pwnagotchi UI, auto mode, web interface
 
-The **factory firmware** is feature-rich, including an AI Agent, lively and expressive animations, ESP-NOW wireless remote control, and online app downloads. It can connect to a mobile app for video viewing, remote avatar control, and more, and also supports online updates (OTA). The product also supports programming via Arduino, UiFlow2, and other methods, and can connect to various expansion units in the M5Stack ecosystem, making it easy to implement a wide range of custom functions. 
+---
 
-> ⚠️ Do not forcibly rotate any movable parts connected to the motors by hand when you are unsure whether the motors are powered and under control, as this may cause hardware damage. 
+## Features
 
-- Purchase link: [M5Stack Official Store](https://shop.m5stack.com/products/stackchan-kawaii-co-created-open-source-ai-desktop-robot) | [淘宝 Taobao](https://item.taobao.com/item.htm?id=1042238294510)
+### Network Scanning
+- WiFi beacon frame capture (promiscuous mode)
+- Channel hopping (1-13, prioritizes 1/6/11)
+- EAPOL handshake capture
+- BLE device scanning via NimBLE
 
-- Product document page: [English](https://docs.m5stack.com/en/StackChan) | [日本語](https://docs.m5stack.com/ja/StackChan) | [中文](https://docs.m5stack.com/zh_CN/StackChan)
+### Gamification System
+- XP earned from: networks discovered, handshakes captured, channels scanned, uptime
+- 8 robot-themed levels (Unit → Omega)
+- Persistent XP storage via ESP32 NVS
 
-- Board support package: https://github.com/m5stack/StackChan-BSP
+### Modes
+| Mode | Description | Neon Color |
+|------|-------------|------------|
+| **IDLE** | Idle mode | Green |
+| **SCOUT** | Passive scanning, no transmission | Blue |
+| **HUNT** | Active WiFi monitoring, capture handshakes + deauth | Green/Cyan |
+| **WARDIVE** | Active wardriving with GPS logging | Orange |
+| **SPECTRUM** | Channel analysis | Rainbow |
+| **BLE-SCAN** | BLE device scanning | Blue/Purple |
+| **ROGUE** | Educational beacon spam on fixed channel 6 (OWN networks only!) | Orange |
+| **CONFIG** | Web config portal (AP: StackChan-Config, visit 192.168.4.1) | Purple |
+| **STATS** | View achievements, XP, prestige | Purple/White |
 
-Thank you to the contributors of the StackChan community, especially: 
+### StackChan Integration
+- Dynamic avatar emotions per mode
+- Head movement speed increases with activity
+- Neon light indicators color-coded by mode
+- Touch interaction for mode cycling
+- **Touch pauses robot motion** - touch screen to pause head movement
 
-| ![](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/avatar_stack_chan.jpg) | ![](https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1205/avatar_takao.jpg) |
-| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| [@stack_chan](https://x.com/stack_chan)                                          | [@mongonta555](https://x.com/mongonta555)                                   |
-| Shinya Ishikawa                                                                  | Takao Akaki                                                                 |
+### Additional
+- GPS support (GPS-BDS Unit on UART2)
+- Internal flash storage (~2MB FATFS)
+- On-screen stats display
+
+---
+
+## Hardware
+
+### Requirements
+- M5Stack CoreS3
+- (Optional) GPS-BDS Unit v1.1 for wardriving
+
+### Known Limitations
+- SD card unavailable (hardware pin conflict on CoreS3 - LCD and microSD share SPI3 pins)
+- Internal flash storage (~2MB FATFS partition) used instead
+
+---
+
+## Build & Flash
+
+### Quick Start (Windows CMD)
+```batch
+cd firmware
+menu.bat
+```
+Then select option 1 for clean build, or 3 to flash.
+
+### Manual Build
+```batch
+cd firmware
+idf.py build
+idf.py -p COM8 flash monitor
+```
+
+### Available Scripts
+| Script | Description |
+|--------|-------------|
+| `menu.bat` | Interactive build menu (recommended) |
+| `clean_build.bat` | Clean + build (removes build folder first) |
+| `build.bat` | Quick incremental build |
+| `flash.bat` | Flash to device (prompts for COM port) |
+| `erase_flash.bat` | Erase NVS or full flash |
+
+**Note**: Run scripts in CMD (not PowerShell or Git Bash).
+
+---
+
+## Project Structure
+
+```
+firmware/main/
+├── apps/app_gotchi/     - Main UI and mode handling
+├── gotchi/              - Core scanning logic (OOP refactored)
+│   ├── gotchi.cpp/h    - Core API (335 lines)
+│   ├── mode_manager.cpp/h    - Mode state machine
+│   ├── wifi_scanner.cpp/h     - WiFi promiscuous + hopping
+│   ├── handshake_parser.cpp/h - EAPOL parsing
+│   ├── deauth_manager.cpp/h  - Deauth attack logic
+│   ├── ble_scanner.cpp/h      - BLE GAP scanning
+│   ├── network_db.cpp/h      - Network/handshake/BLE storage
+│   ├── xp_system.cpp/h       - XP/level progression
+│   ├── achievement_system.cpp/h - Achievements & challenges
+│   ├── gps.cpp/h             - GPS NMEA parsing
+│   ├── rogue_manager.cpp/h   - ROGUE mode beacon spam
+│   └── web_manager.cpp/h     - CONFIG mode HTTP server
+└── hal/board/           - StackChan board initialization
+```
+
+---
+
+## Legal Warning
+
+This tool is for **educational and security research purposes only**.
+
+- Only test networks you own or have explicit permission to test
+- Unauthorized access to computer systems is illegal
+- The author takes no responsibility for misuse
+
+---
+
+## References
+
+- StackChan: https://github.com/M5Stack/M5Stack-StackChan
+- M5PORKCHOP: https://github.com/0ct0sec/M5PORKCHOP
+- M5Gotchi: https://github.com/Devsur11/M5Gotchi/
+- (THE OG) pwnagotchi: https://github.com/evilsocket/pwnagotchi

firmware/.gitignore

@@ -65,3 +65,6 @@ sdkconfig
 sdkconfig.old
 
 xiaozhi-esp32/
+
+# Build output logs
+build_output.txt

firmware/build.bat

@@ -0,0 +1,56 @@
+@echo off
+REM Build script for StackChan firmware
+REM Run this in CMD (not PowerShell or Git Bash)
+
+setlocal EnableDelayedExpansion
+
+REM Get script directory
+set "SCRIPT_DIR=%~dp0"
+set "PROJECT_DIR=%SCRIPT_DIR%"
+
+REM Find ESP-IDF - check IDF_PATH env var first, then common locations
+set "ESP_IDF_PATH="
+if defined IDF_PATH (
+    set "ESP_IDF_PATH=%IDF_PATH%"
+) else (
+    REM Check common installation paths
+    if exist "C:\esp\esp-idf" set "ESP_IDF_PATH=C:\esp\esp-idf"
+    if exist "D:\esp\esp-idf" set "ESP_IDF_PATH=D:\esp\esp-idf"
+    if exist "C:\Users\%USERNAME%\esp\esp-idf" set "ESP_IDF_PATH=C:\Users\%USERNAME%\esp\esp-idf"
+    if exist "C:\Espressif\frameworks\esp-idf" set "ESP_IDF_PATH=C:\Espressif\frameworks\esp-idf"
+)
+
+if not defined ESP_IDF_PATH (
+    echo ERROR: ESP-IDF not found!
+    echo Please set IDF_PATH environment variable or install ESP-IDF.
+    echo.
+    echo Common installation paths:
+    echo   C:\esp\esp-idf
+    echo   D:\esp\esp-idf
+    echo   C:\Espressif\frameworks\esp-idf
+    echo.
+    pause
+    exit /b 1
+)
+
+echo ========================================
+echo Building StackChan firmware...
+echo ESP-IDF: %ESP_IDF_PATH%
+echo Project: %PROJECT_DIR%
+echo ========================================
+echo.
+
+cd /d "%ESP_IDF_PATH%"
+call export.bat
+
+cd /d "%PROJECT_DIR%"
+
+echo.
+echo Starting build...
+echo.
+
+idf.py build
+
+echo.
+echo Build complete!
+pause

firmware/clean_build.bat

@@ -0,0 +1,67 @@
+@echo off
+REM Clean and build script for StackChan firmware
+REM Run this in CMD (not PowerShell or Git Bash)
+
+setlocal EnableDelayedExpansion
+
+REM Get script directory
+set "SCRIPT_DIR=%~dp0"
+set "PROJECT_DIR=%SCRIPT_DIR%"
+
+REM Find ESP-IDF - check IDF_PATH env var first, then common locations
+set "ESP_IDF_PATH="
+if defined IDF_PATH (
+    set "ESP_IDF_PATH=%IDF_PATH%"
+) else (
+    REM Check common installation paths
+    if exist "C:\esp\esp-idf" set "ESP_IDF_PATH=C:\esp\esp-idf"
+    if exist "D:\esp\esp-idf" set "ESP_IDF_PATH=D:\esp\esp-idf"
+    if exist "C:\Users\%USERNAME%\esp\esp-idf" set "ESP_IDF_PATH=C:\Users\%USERNAME%\esp\esp-idf"
+    if exist "C:\Espressif\frameworks\esp-idf" set "ESP_IDF_PATH=C:\Espressif\frameworks\esp-idf"
+)
+
+if not defined ESP_IDF_PATH (
+    echo ERROR: ESP-IDF not found!
+    echo Please set IDF_PATH environment variable or install ESP-IDF.
+    echo.
+    echo Common installation paths:
+    echo   C:\esp\esp-idf
+    echo   D:\esp\esp-idf
+    echo   C:\Espressif\frameworks\esp-idf
+    echo.
+    pause
+    exit /b 1
+)
+
+echo ========================================
+echo Cleaning and Building StackChan firmware
+echo ESP-IDF: %ESP_IDF_PATH%
+echo Project: %PROJECT_DIR%
+echo ========================================
+echo.
+
+cd /d "%ESP_IDF_PATH%"
+call export.bat
+
+cd /d "%PROJECT_DIR%"
+
+echo.
+echo Cleaning build directory...
+echo.
+
+if exist "build" (
+    rmdir /s /q "build"
+    echo Build directory cleaned.
+) else (
+    echo No build directory found.
+)
+
+echo.
+echo Starting fresh build...
+echo.
+
+idf.py build
+
+echo.
+echo Build complete!
+pause