drjones/esp32-switch-blade
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7bf6abccfc331e9056414a422031bfb2b080b66e
esp32-switch-blade/README.md
drjones 7bf6abccfc Initial aether32 school lab bench tool 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-01 21:34:33 -07:00

13 KiB
Raw Blame History

aether32

aether32 is a school-lab bench tool built on ESP32-S3: a USB HID keyboard dongle with an onboard WiFi access point and a phone-friendly web UI. Plug it into a lab PC, control diagnostics from your phone, and pull inventory reports without an SD card — scan results are stored on LittleFS flash and downloaded over WiFi.

Made by Dr Jones.

Authorized use

Use only on machines you own or are explicitly authorized to administer (school IT, lab maintenance, help-desk with permission). This tool automates keystrokes and temporarily joins the target to the dongle’s WiFi to upload diagnostics. Do not use on student or staff machines without policy approval. The authors are not responsible for misuse.

What it does (today)

Capability Description
USB HID Types commands, shortcuts, and multi-line scripts on the target as a keyboard
WiFi AP + web UI ESP32 hosts aether32 WiFi; you browse 192.168.4.1 from a phone
Lab Scan Target joins AP, POSTs hostname/network/disk/AV/uptime/etc. to flash; you download a report
Saved buttons Up to 40 custom one-tap commands stored in flash
Auto-Run Optional plug-in delay, shell open, command, and/or automatic Lab Scan
No removable media SD/USB-MSC stack is not built (storage/ excluded in platformio.ini)

Hardware requirements

  • Any ESP32-S3 board with native USB (HID). Default env: esp32-s3-devkitm-1
  • 16 MB flash recommended (see platformio.ini); LittleFS partition for results + config
  • No microSD card required or supported in this build
  • Optional: NeoPixel/RGB LED (status feedback on plug / auto-run / typing)

Build and flash

  1. Install PlatformIO (VS Code extension or CLI).
  2. Open the aether32 folder as the project root.
  3. Adjust platformio.ini if your board differs (board = ..., USB mode flags).
  4. Build and upload (first flash also formats LittleFS as configured):
cd aether32
pio run -t upload

Monitor serial (optional): pio device monitor -b 115200

Note: Do not expect SD-card features from older docs — build_src_filter excludes components/storage/.

WiFi and web authentication

Setting Value
AP SSID aether32
AP password aether32-admin
Web URL http://192.168.4.1/
HTTP Basic Auth user drjones / password aether32-admin

The phone must join the aether32 network to use the UI. Most authenticated routes require HTTP Basic Auth; see API table below.

Data flow (Lab Scan)

Phone ──WiFi──► ESP32 AP (192.168.4.1)
                    ▲
                    │ POST /api/upload?name=<file>  (no auth; AP-local only)
                    │
Target PC ◄──USB HID── ESP32 types script:
    1. Open hidden PowerShell / Terminal (OS-specific)
    2. Add WLAN profile & connect to aether32
    3. Run diagnostics; HTTP POST each artifact to ESP32
    4. Screenshot → screen.png
    5. exit

Phone ◄── GET /api/download, /api/download/bundle ── reads LittleFS /results/*

Operator checklist: desktop unlocked, user session active, allow ~25–40 s after starting Lab Scan for uploads. Target briefly uses WiFi on the dongle AP (may disconnect from school WiFi during upload).

Web UI tabs

Mobile-oriented single-page app (dark theme).

My Buttons

  • Grid of saved commands (up to 40), stored in flash (/btns.dat)
  • Tap to run: opens shell (Win+R, CMD, PowerShell, or Elevated CMD) and types the command
  • Color tiles are UI-only (picker index); not persisted server-side

+ Builder

  • Create buttons: label, shell type, command text, key delay (5–200 ms)
  • Manage / delete saved buttons

Tricks

One-shot HID actions (no flash storage):

  • Launch apps: Calculator, Notepad, CMD, PowerShell, Elevated CMD, Task Manager, Settings, Control Panel, File Explorer
  • Window control: Show desktop, minimize all, lock, close window, Alt+Tab (+ spam), Win snap arrows, screenshot shortcut, F5
  • Keyboard: Caps Lock, Ctrl+A/C/V/Z/S, zoom in/out, spam Enter/Esc
  • Recon (opens CMD): ver, ipconfig, whoami, tree C:\
  • Party / demo: fake error, ASCII art, telnet Star Wars, fake BSOD line, flip screen, Google/YouTube

Shell

  • Run command: shell selector + arbitrary command
  • Type raw text: into active window; optional Notepad first, Enter after, delay

Collect

  • Lab Scan — full Windows-oriented inventory (see artifacts); retries with OS auto-detect profile if needed
  • Live status — phase, last upload, file count, OS, hostname (polls /api/status every 2 s)
  • Quick lab fixes (Windows): Flush DNS, Device Manager, Disk Management, clear %TEMP% (elevated)
  • Advanced scan: auto-detect profile, Windows-only profile, screenshot only, IP config, systeminfo
  • Download: bundled labscan_<hostname>.txt, screen.png, per-file view/download
  • Collected files — browser for everything in /results/

Auto-Run

Stored in flash (/cfg.dat):

  • Enable Auto-Run — after USB plug-in delay, open shell and optionally type a command
  • Lab Scan on plug-in — after delay (+ extra 4 s if auto-run enabled), run collect_lab_scan() automatically
  • Delay — 500 ms–12 s (default 3.5 s) after USB enumerate
  • Shell — elevated CMD (default), CMD, PowerShell, or Win+R only
  • Optional command — typed after shell opens
  • LED: orange on connect, red while firing, green when done

Tools

  • Clear HID traces — elevated cleanup under C:\Windows\Temp\temp*
  • Restart dongle — reboot ESP32 (WiFi AP restarts)

Lab Scan artifacts

Files are written under LittleFS /results/ (plain text unless noted).

Full Lab Scan (Windows profile)

File Contents
os.txt windows
hostname.txt hostname + whoami
network_macs.txt getmac /v
network_full.txt ipconfig /all
arp.txt ARP table
routes.txt route print
netstat.txt netstat -an
collected_at.txt ISO timestamp
disk_space.txt PSDrives + logical disk sizes
logged_in_user.txt whoami + query user
uptime.txt last boot + uptime
av_status.txt Defender status or Security Center AV
os_version.txt Get-ComputerInfo + OS version
ram.txt physical RAM total (GB)
gateway_dns.txt default route + DNS servers
screen.png primary display screenshot

macOS / Linux Lab Scan

Same logical set where applicable (os.txt = macos or linux), using ifconfig/ip, df, sw_vers or /etc/os-release, screencapture / scrot, etc. Scripts no-op if uname does not match.

Lighter “profile” collect (Advanced Scan)

Subset: os.txt, hostname.txt, network files, collected_at.txt, screen.png (no disk/AV/uptime extras unless full Lab Scan).

Optional individual collects (API via collect_<id>)

May be triggered from firmware (collect_dispatch) — not all exposed in UI:

disk_space, logged_in_user, uptime, av_status, os_version, ram, gateway_dns, sysinfo → sysinfo.txt, network → network_full.txt, arp, netstat, routes, hostname, users → whoami.txt, processes → processes.txt, screenshot, profile_auto / profile_windows / profile_macos / profile_linux, lab_scan

Bundled download (/api/download/bundle) merges: os.txt, hostname.txt, collected_at.txt, network_macs.txt, network_full.txt, arp.txt, routes.txt, netstat.txt, sysinfo.txt, processes.txt (skips missing files).

API summary

Method Path Auth Purpose
GET / Yes Main web UI (HTML SPA)
POST /run Yes Run shell command (cmd, shell, delay)
POST /type Yes Type text (text, delay, enter, notepad)
POST /trick Yes HID trick or collect_* (id)
POST /restart Yes Reboot ESP32
POST /clear_trace Yes HID temp cleanup on target
GET /api/buttons Yes List saved buttons (JSON)
POST /api/buttons Yes Add button
POST /api/buttons/delete Yes Delete by index (id)
POST /api/upload No Target uploads body (?name=filename, max ~250 KB)
GET /api/results Yes List result files
GET /api/file?path=/results/<name> Yes Read text result
GET /api/profile Yes OS, hostname, file list
GET /api/status Yes Scan phase, uploads, counts
GET /api/download?path=/results/<name> Yes Download file
GET /api/download/bundle Yes Combined text report
GET/POST /api/config Yes Auto-run / lab-scan-on-plug settings

Limitations

  • Target needs WiFi (built-in or USB) for Lab Scan uploads; machine joins dongle AP briefly
  • Unlocked session required; timing depends on boot/login speed (increase Auto-Run delay on slow PCs)
  • OS-specific: full Lab Scan UI path is Windows-first; Mac/Linux use terminal scripts with best-effort tools (nmcli, scrot, etc.)
  • Network disruption: while connected to aether32, the PC may drop school WiFi
  • HID constraints: UAC dialogs, focus stealing, non-US keyboards, and VM/USB policies can break typing
  • Flash size: large screenshots + many scans fill LittleFS; clear old results or reflash filesystem if needed
  • Concurrent requests: heavy parallel web traffic can stress the soft AP stack
  • Legacy code: old browser-exfil / SD-MSC paths are not in this firmware build

Tested configuration

  • Board: ESP32-S3-DevKitM-1 (and similar S3 USB boards)
  • Framework: PlatformIO, Arduino-ESP32
  • Targets: Windows 10/11 (primary), macOS/Linux (partial Lab Scan)

Planned features (roadmap)

School-lab IT focus — diagnostic and inventory only (no credential harvesting).

Reliability

  1. Upload acknowledgment & retry — target retries failed POSTs until ESP32 confirms each file
  2. STA mode + school WiFi — ESP32 joins lab VLAN so PCs never leave corporate SSID during scan
  3. Upload progress WebSocket/SSE — phone sees per-file receive status in real time
  4. Pre-flight connectivity check — HID script verifies 192.168.4.1 reachable before typing long payloads
  5. Graceful scan cancel — stop in-progress collect from phone without reboot

Inventory & reporting

  1. Asset tag / seat / room fields — operator enters metadata; embedded in report filename and bundle
  2. CSV export of all scans — append-only log on flash for semester audits
  3. Scan history timeline — list past hostnames/timestamps on device; tap to re-download
  4. Compare to golden baseline — diff installed software/services vs. a reference machine JSON
  5. Missing-software checklist — flag absent apps (Chrome, Office, lab license tools) from baseline

Fleet helpers

  1. Batch mode queue — arm next N machines; auto-clear results between seats
  2. QR code on dongle — sticker opens captive URL + WiFi join hints for substitutes
  3. Hostname dedup warning — alert if scan overwrites an existing result without confirm
  4. Scheduled plug-in profile — weekday vs. exam-week auto-run presets

Push to PC (authorized fixes)

  1. Deploy script from flash — store .ps1/.bat on ESP32; push to %TEMP% and execute from phone
  2. Typed macro sequences — multi-step “fix printer” / “rejoin domain” without full shell scripts
  3. Software install helper — silent install switches for approved MSI/EXE paths (IT-provided list only)
  4. Registry-free network reset — documented keystroke sequence for winsock reset (with confirm)

UX

  1. Light/dark theme toggle — outdoor lab visibility
  2. Improved mobile layout — larger tap targets, offline-friendly cached UI shell
  3. Pin favorites tab — default to Collect or My Buttons per tech preference
  4. Button color persisted — store color index in /btns.dat with each command

Security appropriate for schools

  1. Role-separated HTTP auth — read-only student tech vs. admin PIN for destructive actions
  2. Audit log on device — who ran which trick/collect (phone session id + timestamp)
  3. Explicit “diagnostics only” build flag — compile-time removal of prank tricks for production lab kits
  4. Result encryption at rest — optional passphrase for downloads if dongle is lost
  5. Auto-wipe results after download — reduce data left on flash between classes

Credits

  • ESP32 Arduino USB HID stack
  • Lab workflow and firmware: Dr Jones
  • Historical references (not used in current no-SD build): HackBrowserData, esp32-sdcard-msc
Reference in New Issue View Git Blame Copy Permalink