Skip to content

README.md

Latest commit

 

History

History
executable file
·
175 lines (131 loc) · 5.92 KB

README.md

File metadata and controls

executable file
·
175 lines (131 loc) · 5.92 KB
Raw

🧠 Mate - web control for JanOS

mate

⚡ Web control layer for JanOS / projectZero ecosystem
Control recon, attacks and wireless operations directly from your browser.

🏗️ Architecture

Phone (browser) ── WiFi AP ──> ESP32 WebClient ── UART 115200 ──> ESP32C5 Monster (JanOS)

The WebClient creates a WiFi AP. A phone connects to it and opens the captive portal SPA in a browser. The SPA sends REST API calls / uses WebSocket for real-time updates. The WebClient translates these into UART commands to Monster and parses responses.

Supported Boards

Board Chip Display Flash
XIAO-ESP32-C6 ESP32-C6 None 4MB
M5Stack CoreS3 SE ESP32-S3 ILI9342C 320x240 16MB
M5StickC PLUS2 ESP32 ST7789V2 135x240 8MB
AtomS3R Dev Kit ESP32-S3 GC9107 128x128 8MB
Atom Lite ESP32-Pico None 4MB
CardKB2 ESP32-C61 None 4MB

⚡ Quick Start

1. 🧱 Build Web UI

cd web
npm install
npm run build      # outputs to ../spiffs/

2. 🔧 Build & Flash Firmware

# Set target (pick one):
idf.py set-target esp32c6    # XIAO
idf.py set-target esp32s3    # CoreS3, AtomS3R
idf.py set-target esp32      # M5StickC PLUS2

# Configure board:
idf.py menuconfig
# → JanOS Web Client Configuration → Target board → select your board
# → UART Configuration → verify TX/RX pins for your wiring

# Build & flash:
idf.py build flash monitor

3. 📶 Connect

  • Connect to WiFi AP JanOS-XXXX (password: janos1337)
  • Phone auto-opens captive portal, or navigate to http://192.168.4.1

UART Wiring (Monster Connection)

Default pins are configurable via idf.py menuconfig.

M5Stack boards (Grove port)

  • Yellow wire 🟡 (Grove pin 1) → Monster TX → WebClient RX
  • White wire ⚪ (Grove pin 2) → Monster RX ← WebClient TX
  • Red 🔴 = 5V,
  • Black ⚫ = GND

XIAO-ESP32-C6

  • GPIO 20 = RX (from Monster TX)
  • GPIO 21 = TX (to Monster RX)

Atom Lite

  • GPIO 26 = RX (from Monster TX)
  • GPIO 32 = TX (to Monster RX)

🏭 Building All Firmware Permutations

tools/build_all.py uses the official espressif/idf Docker image to build every board/flash-size combination in one shot. No local ESP-IDF installation required — only Docker.

Default build matrix

Output folder Chip Flash
binaries/xiao-c6/ ESP32-C6 4 MB
binaries/cores3/ ESP32-S3 16 MB
binaries/atoms3r/ ESP32-S3 8 MB
binaries/stickc-plus2/ ESP32 8 MB
binaries/atom-lite/ ESP32-Pico 4 MB

Each folder contains: mate-<board>.bin, bootloader-<board>.bin, partition-table-<board>.bin, storage-<board>.bin.

Runs each build in the espressif/idf:release-v6.0 container — the same image (and board matrix) the CI workflow uses.

Usage

# Build all boards (default IDF v6.0.0)
python tools/build_all.py

# Specific IDF version
python tools/build_all.py --idf-version v5.3.2

# Only selected boards
python tools/build_all.py --targets xiao_c6,cores3

# Add extra flash-size variants (e.g. also build 4 MB and 16 MB versions)
python tools/build_all.py --flash-sizes 4,8,16

# Keep build/ directories for debugging
python tools/build_all.py --keep-build

# Custom output directory
python tools/build_all.py --output-dir /tmp/fw-release

💻 Web UI Development

cd web
npm run dev        # Vite dev server with hot reload

Configure the Vite proxy in vite.config.js to point to your ESP32's IP for testing against real hardware.

📡 REST API

Method Endpoint Description
POST /api/scan Start WiFi scan
GET /api/scan/results Get cached scan results
POST /api/select Select networks by index
POST /api/attack/deauth Start deauth
POST /api/attack/eviltwin Start evil twin
POST /api/attack/rogueap Start rogue AP
POST /api/attack/sae Start SAE overflow
POST /api/attack/handshake Start handshake capture
POST /api/attack/sniffer Start sniffer
POST /api/stop Stop all operations
GET /api/portals List HTML portal files
POST /api/portal/select Select portal by index
GET /api/passwords Get captured passwords
GET /api/status Get current state

WebSocket

Connect to ws://192.168.4.1/ws for real-time events:

  • scan_network — individual network from scan
  • scan_complete — scan finished
  • attack_started/stopped — attack state changes
  • password_received — captured password
  • handshake_captured — WPA handshake captured
  • sniffer_count — packet count update
  • uart_line — raw UART line for logging

⚡ Designed for control.
Control the chaos. LAB5.