diff --git a/.gitignore b/.gitignore
index 00741cb..e8aa474 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,29 @@
.DS_Store
-.idea/
\ No newline at end of file
+.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/
\ No newline at end of file
diff --git a/README.md b/README.md
index 9cf3f7f..64248e3 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,152 @@
-# StackChan Open-Source
+# StackChan-Gotchi
-
+
+
+
+**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 (+1), handshakes captured (+25), channels visited (+5), BLE devices (+2), uptime (+1/min)
+- **42 levels** with robot-themed titles:
+ - Levels 1-8: Unit → Omega
+ - Levels 9-16: Observer, Probe, Analyst, Decoder, Tracker, Hunter, Crawler, Synth
+ - Levels 17-24: Cortex, Nexus, Matrix, Quantum, Singularity, Hyperion, Archon, Titan
+ - Levels 25-32: Prime, Alpha, Omega Prime, Supreme, Transcendent, Paramount, Glorious, Eternal
+ - Levels 33-39: Legendary, Mythic, Omnipotent, Infinite, Absolute, Ultimate, Paramount
+ - **Secret levels** exist beyond level 40...
+- Prestige system: Reset to level 1, keep prestige count, +10% XP bonus per prestige level
+- 37 achievements with XP rewards (hybrid system)
+- Daily challenges with streak tracking
+- 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
-|  |  |
-| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| [@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
\ No newline at end of file
diff --git a/firmware/.gitignore b/firmware/.gitignore
index 5c0083c..6a8b73e 100644
--- a/firmware/.gitignore
+++ b/firmware/.gitignore
@@ -65,3 +65,6 @@ sdkconfig
sdkconfig.old
xiaozhi-esp32/
+
+# Build output logs
+build_output.txt
diff --git a/firmware/build.bat b/firmware/build.bat
new file mode 100644
index 0000000..8a06904
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/firmware/clean_build.bat b/firmware/clean_build.bat
new file mode 100644
index 0000000..d599b42
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/firmware/erase_flash.bat b/firmware/erase_flash.bat
new file mode 100644
index 0000000..0d05859
--- /dev/null
+++ b/firmware/erase_flash.bat
@@ -0,0 +1,86 @@
+@echo off
+REM StackChan Firmware Flash Erase Script
+REM Usage: Run from ESP-IDF environment or adjust paths below
+
+setlocal EnableDelayedExpansion
+
+set "SCRIPT_DIR=%~dp0"
+set "PROJECT_DIR=%SCRIPT_DIR%"
+
+echo ========================================
+echo StackChan Firmware Flash Eraser
+echo ========================================
+echo.
+
+echo Looking for available COM ports...
+wmic path Win32_SerialPort get DeviceID,Name 2>nul
+echo.
+
+set /p PORT=Enter COM port (e.g., COM3):
+
+if not defined PORT (
+ echo ERROR: No port entered
+ pause
+ exit /b 1
+)
+
+echo.
+echo Choose erase option:
+echo 1) Erase NVS only (reset stats only)
+echo 2) Erase entire flash (full reset)
+echo 3) Exit
+echo.
+
+set /p choice=Enter choice (1-3):
+
+if "%choice%"=="1" goto erase_nvs
+if "%choice%"=="2" goto erase_full
+if "%choice%"=="3" exit
+
+echo Invalid choice.
+pause
+exit /b 1
+
+:erase_nvs
+echo.
+echo Erasing NVS partition (stats only)...
+echo This will reset: XP, Level, Networks found
+echo.
+esptool.py --chip esp32s3 --port %PORT% erase_region 0x9000 0x6000
+if errorlevel 1 (
+ echo FAILED!
+ pause
+ exit /b 1
+)
+echo.
+echo SUCCESS! NVS erased.
+echo Stats will reset on next boot.
+pause
+exit /b 0
+
+:erase_full
+echo.
+echo WARNING: This will erase EVERYTHING!
+echo - All stats
+echo - WiFi configs
+echo - BLE pairings
+echo.
+set /p confirm=Type YES to confirm:
+if not "%confirm%"=="YES" (
+ echo Cancelled.
+ pause
+ exit /b 0
+)
+echo.
+echo Erasing entire flash...
+esptool.py --chip esp32s3 --port %PORT% erase_flash
+if errorlevel 1 (
+ echo FAILED!
+ pause
+ exit /b 1
+)
+echo.
+echo SUCCESS! Full flash erased.
+echo You will need to flash the firmware again.
+pause
+exit /b 0
\ No newline at end of file
diff --git a/firmware/flash.bat b/firmware/flash.bat
new file mode 100644
index 0000000..8be8dc1
--- /dev/null
+++ b/firmware/flash.bat
@@ -0,0 +1,35 @@
+@echo off
+setlocal EnableDelayedExpansion
+
+set "SCRIPT_DIR=%~dp0"
+set "PROJECT_DIR=%SCRIPT_DIR%"
+
+set "ESP_IDF_PATH="
+if defined IDF_PATH (
+ set "ESP_IDF_PATH=%IDF_PATH%"
+) else (
+ 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! Set IDF_PATH or install ESP-IDF.
+ pause
+ exit /b 1
+)
+
+echo Looking for available COM ports...
+wmic path Win32_SerialPort get DeviceID,Name 2>nul
+echo.
+
+set /p PORT=Enter COM port (e.g., COM3) or press Enter for default COM8:
+if not defined PORT set PORT=COM8
+
+cd /d "%ESP_IDF_PATH%"
+call export.bat
+cd /d "%PROJECT_DIR%"
+
+idf.py -p %PORT% flash monitor
+pause
\ No newline at end of file
diff --git a/firmware/main/CMakeLists.txt b/firmware/main/CMakeLists.txt
index 22cfebb..7884cd9 100644
--- a/firmware/main/CMakeLists.txt
+++ b/firmware/main/CMakeLists.txt
@@ -14,9 +14,17 @@ file(GLOB_RECURSE STACK_CHAN_SOURCES
"stackchan/*.c"
"stackchan/*.cc"
"stackchan/*.cpp"
+ "gotchi/*.c"
+ "gotchi/*.cc"
+ "gotchi/*.cpp"
+ "gotchi/mode.cpp"
+ "gotchi/rogue_manager.cpp"
)
set(STACK_CHAN_INCLUDE_DIRS
"."
+ "gotchi"
+ "${CMAKE_CURRENT_SOURCE_DIR}/gotchi"
+ "${CMAKE_CURRENT_SOURCE_DIR}/apps/app_gotchi"
)
list(APPEND STACK_CHAN_SOURCES main.cpp)
@@ -316,6 +324,7 @@ idf_component_register(SRCS ${SOURCES}
mooncake
mooncake_log
smooth_ui_toolkit
+ esp_http_server
)
# Use target_compile_definitions to define BOARD_TYPE, BOARD_NAME
diff --git a/firmware/main/apps/app_gotchi/app_gotchi.cpp b/firmware/main/apps/app_gotchi/app_gotchi.cpp
new file mode 100644
index 0000000..1c2e717
--- /dev/null
+++ b/firmware/main/apps/app_gotchi/app_gotchi.cpp
@@ -0,0 +1,1561 @@
+/*
+ * SPDX-FileCopyrightText: 2026 StackChan-Gotchi
+ * SPDX-License-Identifier: MIT
+ */
+#include "app_gotchi.h"
+#include Current: Loading...
+Level: - | XP: - | Nets: -
+Mode Selection
+ + +Mode Permissions
+Quick Actions
+ + +Rogue Target Network
+ + + +Select from discovered networks to target in ROGUE mode
+Player Stats
+| Level | - |
| XP | - |
| Networks | - |
| Handshakes | - |
| Prestige | - |
| Uptime | - |
| Achievements | - |
Session Stats
+Session XP: -
+Session Time: -
+Discovered Networks
+Storage
+Free: -
+