System Overview
The Orange Pi is the gateway and browser-facing host. It serves these HTML pages through nginx, exposes API routes under /api/*, proxies selected commands to the ESP32 over network APIs, and keeps the public Tailscale / Funnel endpoint available.
The ESP32-S3 is the device being managed. It handles firmware features such as Wi-Fi association, USB host behavior, VCOM command processing, OTA, and live diagnostics. Some pages talk to the ESP32 through gateway HTTP endpoints, while the browser terminal adds a WebSocket layer on top of the gateway so the terminal feels interactive.
Main separation: the Orange Pi is the web gateway and orchestrator. The ESP32 is the target device. The physical USB VCOM port seen by a PC and the remote browser terminal are two different transports into the same command engine.
Page Directory
| Page | Primary use |
|---|
| / | Gateway dashboard, status summary, safe process controls, hardware inventory, and launch point for all tools. |
| /esp32-studio.html | Unified ESP32 operator shell for diagnostics, OTA update, and VCOM settings from one route. |
| /esp32-hcs12-vault.html | Gateway-side HCS12 firmware vault browser, current build evidence, and local S-record upload staging with restore intentionally disabled. |
| /network-config.html | Orange Pi network changes, Tailscale / Funnel recovery, ESP32 network target/apply. |
| /mcp-control.html | MCP bootstrap contract, orangepi-gateway-ops tool families, Playwright target checks, GitHub MCP setup, and the exact Codex config blocks for the MCP lanes used in active work. |
| /desktop-openclaw.html | Launch lane for the Windows-hosted OpenClaw surface over the Tailscale HTTPS hostname, with reachability and auth-boundary guidance. |
| /remote-access.html | Orange Pi-hosted Mesh remote desktop lane for the full Windows desktop experience, including screen, keyboard, mouse, clipboard, and file transfer when the Mesh session is healthy. |
| /usb-operations.html | Unified USB operations page: USB File Manager and VCOM Settings surfaces. Legacy routes /esp32-usb-files.html and /vcom-settings.html still work directly. |
| /ftp-operations.html | Unified FTP operator shell for the local Orange Pi FTP server and the remote RPi4 FTP workflow. |
| /ftp-client.html | Gateway-side FTP client for remote file transfer operations. |
| /scripts-and-probes.html | Single selector-driven page for repository scripts, deployment pipeline guidance, and HCS12 workflow surfaces. |
| /test-runner.html | Functional and regression checks, including the VCOM terminal probe. |
| /backup.html | Backup manager, Orange Pi clone-image and RPi4 raw-image libraries, bootable SD swap workflows, disk-usage summary, package deletion, FTPS clone targets, restore workflows, and backup test semantics. |
Use the page directory as a routing guide, not as the documentation itself. The important parts are the workflows below: what to use before a deploy, what to use before a network move, what to use for ESP32 Wi-Fi changes, and what to use when you need real recovery media. Legacy ESP32 and FTP deep links still work, but they now forward into the unified pages instead of being promoted as first-class dashboard destinations.
Transport Model
Gateway HTTP APIs
Most pages use gateway endpoints such as /api/network/esp32/*, /api/network/pi/*, and other host-side APIs.
Browser terminal
/vcom-settings.html opens a WebSocket to /api/vcom/terminal/ws. The gateway then relays terminal open, input, poll, and close calls to the ESP32 web-terminal API.
Physical USB VCOM
A local PC running RealTerm or PuTTY can still use the actual USB VCOM transport if USB transport is enabled in the ESP32 settings.
Single-owner rule: the browser-side web terminal is single-owner. If a tab dies or the network drops, reconnect or wait for stale-session recovery before opening another browser session.
Remote Access Boundary
/remote-access.html is the Mesh-based full desktop lane for the Windows machine. It is the browser path for the actual remote Windows desktop session when the Mesh target is enrolled and connected. /desktop-openclaw.html is a separate path that launches the Windows-hosted OpenClaw UI itself over the Tailscale HTTPS hostname.
Do not expose the Windows target directly to the public internet. Keep both the Mesh desktop lane and the Windows-hosted OpenClaw UI inside the Tailscale / Orange Pi trust boundary, and do not conflate the full desktop session with the Windows-hosted OpenClaw login page.
- Use /remote-access.html when you need the full remote Windows desktop experience through Mesh.
- Use /desktop-openclaw.html when you need the Windows-hosted OpenClaw UI itself, not the full desktop.
- Expect the Windows-hosted OpenClaw page to open in a separate tab because that UI sends frame-blocking headers.
MCP Control And GitHub
/mcp-control.html is the MCP reference page for this repo. The backend relies on three distinct Model Context Protocol (MCP) "lanes" that do not cross boundaries. Each is authorized for a specific type of AI tooling:
1. orangepi-gateway-ops (The Repo Primary)
- Features: Custom local MCP server for Orange Pi health checks, SPI bus testing, SD clone backups, network diagnostics, OTA flashes, and orchestrated deployments.
- How to use: Agents ping this immediately on session start to prove the Orange Pi is active. Runs as a local process. No remote cloud tokens required.
2. Playwright MCP (The UI Lane)
- Features: Strict browser automation. Spawns headless browsers to load the gateway dashboard, verify Javascript consoles, check 404s, and catch visual layout regressions.
- How to use: Triggered automatically after UI code is updated. Safely targets https://orangepirv2.tail59ab20.ts.net locally.
3. GitHub MCP (The Remote Repo Lane)
- Features: Official cloud integration. Manages remote repository issues, comments on Pull Requests, triggers GitHub Actions, and performs cloud-side codebase diffs.
- How to use: Requires strict authentication. You must inject a GITHUB_PAT_TOKEN into your command line / Windows environment before executing.
Critical Workflow Rule: You cannot "hot-attach" or reboot an MCP server while an AI chat is already active. Update your MCP config, load any required token environment variables, and then start a new chat session so the agent adopts the fully active state.
Dashboard And Process Controls
The main dashboard is now the dense operator summary page. It surfaces gateway status, ESP32 health, attached hardware, running-card/target-card metadata, and a constrained set of runtime process actions.
The process controls are intentionally safe-action oriented. They are for operator recovery and diagnostics, not arbitrary PID killing or general host process management. If the UI hides details you expect, treat that as a documentation/UI gap rather than assuming the backend lacks the data.
- Use the dashboard first for current host/ESP32 state and attached media inventory.
- Use Diagnostics for deeper runtime details and task state.
- Use Backup Manager for clone-image and SD-swap workflows.
Backup And Clone Workflows
/backup.html is no longer just archive backup/restore. It is also the operator surface for Orange Pi clone-image creation, quick/full verify, remote clone targets, a separate RPi4 raw-image library, and the bootable SD swap planner.
- Quick verify gives a fast sanity pass and can show QUICK PASS.
- Full verify is the archival-confidence pass and is what makes a clone USABLE.
- Image ID identifies the clone image lineage.
- Boot ID is a per-card issuance/provenance record for one physical SD card.
- Failsafe proof order is clone lineage first, exact byte compare on the raw write second, and any later per-card issuance stamp after that proof step.
- Operator sequence on /backup.html is now raw write, written-card verify, then explicit Boot ID issuance if you need a per-card record.
- The Orange Pi and RPi4 image libraries are separate collapsible sections, and the page remembers their last open/closed state.
- Each image package can now be deleted row-by-row; deleting a package removes the image, checksum, and stored metadata sidecars together.
- The planner can show removable-target USB link-speed warnings before you trust a write or swap card.
- The backup Test modal now separates required checks from optional content so non-applicable archive content is informative rather than presented as a false failure.
- Config backup validation passes when either the project config/ payload or the embedded system-config set is present, matching backend restore semantics.
Practical rule: use quick verify for fast operator feedback, use full verify before treating a clone as your restore-ready spare, and treat BYTE_COMPARE_MATCH=yes as the exact-write proof only before any later per-card issuance stamp changes the card bytes.
Size note: full backups can be only slightly larger than project backups because the extra system-config payload is a small embedded archive relative to the project payload.
VCOM Terminal Guide
What the page controls
The VCOM page controls three main things: whether the USB transport is enabled, whether the web transport is enabled, and whether the web session is allowed to send commands or is observer-only.
Internal-tooling rule: the Orange Pi browser pages are development and operator surfaces. Customers do not use this backend directly, so the VCOM page documents the real crash-test workflow instead of hiding it behind a special lab-only UI.
Common operating modes
- USB ON, Web OFF: local COM-port workflow only.
- USB OFF, Web ON: remote browser-only workflow.
- USB ON, Web ON: both transports available.
- Web Write OFF: browser can watch output but cannot inject commands.
Terminal interaction rules
- Typed commands such as !STATUS, !HELP, !WIFI, and !SCAN work directly at the prompt.
- Typing ? then Enter opens the interactive menu when menu mode is enabled.
- Inside the menu, arrow keys move the highlight and Enter runs the selected command.
- After a command runs from the menu, the menu wrapper stays active until Enter returns to the menu or Esc / q exits back to the normal prompt.
- !PANIC is the deliberate crash-report validation command. The red Test Panic button on the VCOM page is just the safer memorable front-end for that same command.
Controlled panic and crash-report workflow
- Connect the browser terminal or a local COM22 session.
- Run !HELP and confirm that !PANIC is advertised in the active firmware.
- Use the red Test Panic button or send raw !PANIC.
- Expect the ESP32 to abort, persist the coredump, and reboot. The terminal dropping during that reboot is normal.
- After reconnect, verify the stored crash report from /esp32-diagnostics.html or the gateway API route /api/network/esp32/crash-report.
- Clear the stored report after validation so the next crash test starts from a known clean state.
The red panic control is not a convenience reboot. It is an intentional firmware abort used to validate persisted crash reporting and the Orange Pi proxy path. If the VCOM page says the current session does not expose !PANIC, do not keep clicking it; confirm the active firmware contract first.
Recommended remote Wi-Fi workflow
- Connect the browser terminal.
- Run !STATUS first so you know the prompt is healthy.
- Run !SCAN or choose it from the menu.
- Wait for the numbered list and prompt.
- Type the network number or exact SSID, then Enter.
- Type the password, then Enter.
- Wait for the reconnect result and the printed Wi-Fi block before assuming the move succeeded.
Important VCOM troubleshooting
- If the browser terminal keeps retrying, check that Web Transport and Web Write Access are both ON.
- If the page says a session is already active, another tab or stale session still owns the browser terminal.
- If the terminal is completely dark, Silent Mode may be ON.
- If opening COM22 in RealTerm resets the ESP32 or makes the API pages flap offline, disable RTS in RealTerm or use PuTTY instead. Verified live behavior: asserting RTS on this board resets the ESP32-S3.
- If !SCAN finishes but the browser reconnects, the ESP32 may have briefly changed Wi-Fi state mid-command; reconnect and verify with !WIFI or the diagnostics page.
Why no process restart when recovering VCOM?
The "Orange Pi Process Tree" shows Linux services running on the gateway. The VCOM Web Terminal is not a gateway process—it is a connection that passes through the Pi directly to the ESP32.
Since the ESP32 only allows one connection at a time, abandoned tabs can leave sessions locked, causing [transport retry] loops. Pressing Recover VCOM Web Terminal sends a forceful cleanup command (POST /api/vcom/terminal/recover) to the ESP32 to release that lock so your browser can reconnect.
Expected terminal sequence on success: [stale terminal recovered] → [opening terminal session] → [connected to esp32-web-terminal]. You will not see any gateway services restart on the Pi.
Operator rule: if you are doing a remote Wi-Fi move from the browser terminal, trust the terminal prompt flow more than the surrounding page state. Wait for the numbered scan prompt, type the choice, type the password, then verify with !STATUS or !WIFI after reconnect.
Backup and Recovery
What the Backup Manager is actually for
/backup.html is not a single backup tool. It combines Orange Pi tar backups, ESP32 firmware artifact capture, raw ESP32 flash backup/restore, restore-from-file handling, an Orange Pi clone-image library, and a separate RPi4 raw-image library stored on the same backup volume.
Choose the correct backup type
- Full Backup: default rollback point before deploys, service changes, restore tests, or system-config edits.
- Project Only / Source Only / Config Only: smaller targeted snapshots when you do not need a full runtime recovery point.
- ESP32 OTA Cache Backup: preserves the last OTA binary already staged on the Pi.
- ESP32 Raw Flash Backup: bit-for-bit ESP32 flash image over USB serial, including NVS and OTA data.
How to interpret Test results
The backup test modal is type-aware. Required checks represent content that archive type promises to contain. Optional content is shown separately so it does not look like corruption when a smaller archive intentionally omits it. Config backups are valid when they contain either the project-side config/ payload or the embedded system-config set. Full backups include both the project payload and the extra system-config archive, which is why they can be very close in size to Project backups while still carrying a slightly broader restore surface.
Disk Status summary
The top summary cards on /backup.html now track the backup USB volume rather than the Orange Pi root filesystem. Backup Volume and Free on Volume are the size and free space of the mounted backup disk. Tracked Data is the space currently used by the managed image/checksum library on that volume. The Orange Pi clone-image library root is /mnt/opi-backup/images, the checksum library is /mnt/opi-backup/checksums, the RPi4 raw-image library is /mnt/opi-backup/images/rpi4-clawbot, and tar/bin backups live under the configured backup directory reported by the API. File Backups is only the count of tar/bin backup files; it does not count clone-image packages.
Clone libraries and SD workflows
- Refresh Probe first so you know what disk and root source you are looking at.
- Create Image Clone is the Orange Pi storage-level recovery path, not the same thing as a tar backup.
- Quick verify is an operator-speed check. Full verify is the confidence check you should require before calling an image ready for disaster recovery or SD writing.
- Failsafe proof order: keep clone lineage in the image itself with Image ID or another clone marker, perform the raw SD write, prove it with exact byte compare while the card is still otherwise unmodified, then add any later per-card issuance record such as a Boot ID or external issuance log.
- If the selected reader does not currently expose a readable SD card, the write attempt is rejected before the job starts. Reseat the card and refresh the probe first.
- Delete on either image row removes the entire package: image file, checksum, and metadata sidecars.
- The Orange Pi and RPi4 sections are collapsible and the page remembers their last fold state.
Important boundary: a per-card issuance stamp is provenance, not byte-for-byte proof of the original image. On same-size cards, a later unique card stamp changes bytes, so you should keep the successful exact-compare record as the proof of the raw write.
Tar restore vs clone restore
Tar restores are for recovering files and configuration back onto a still-booting Orange Pi environment. Clone images are for recovering from storage failure, migrating to replacement media, or rebuilding when the runtime disk itself is the problem. If you only keep tar backups, you still do not have a full disaster-recovery story.
Minimum sane backup routine
- Create a Full Backup before risky work.
- Run Test on the backup.
- Export it off-box with Download or maintain a verified clone disk.
- After major milestones, refresh the backup set so the newest working state is protected too.
ESP32 Diagnostics
This is the best live browser view of the firmware state without entering the terminal. It is the page to use after OTA, after a Wi-Fi move, or when you need a clean status snapshot to compare against expected behavior.
- Use it to confirm SSID, IP, RSSI, uptime, and firmware phase.
- Use the ESP32 Task Tree to see the live runtime branches built from telemetry and current VCOM settings.
- Use the ESP32 Partitions And Activity Associations card to connect the live firmware state to the source-backed flash layout: nvs, otadata, app0, app1, spiffs, and coredump.
- app0 and app1 are both 0x500000 because they are equal-size A/B OTA slots; the page explains that relationship but does not guess the active slot when telemetry does not expose it.
- Use the log panel after USB host issues, unexpected resets, OTA attempts, or network failures.
- Use the Persisted Crash Report panel after a !PANIC test to confirm the coredump was captured, summarized correctly, and then cleared cleanly.
- Remember these logs are fetched over HTTP through the gateway, not captured from a raw serial monitor.
Practical split: the VCOM page is where you trigger the panic, but the Diagnostics page is where you review the stored crash-report summary and confirm the Orange Pi proxy path is serving the expected evidence.
Network Config
This page is for host-network changes on the Orange Pi and target / apply operations for the ESP32 network endpoints. Use it carefully because host-side changes can move the web UI to a different address.
- Run Refresh Status first.
- Before changing the Orange Pi network, note the replacement LAN or Tailscale URL.
- Use Move Health Check before and after a recovery attempt.
- Use the snapshot JSON when handing off a network problem or comparing before/after states.
OTA Update
The OTA page is for uploading and applying a new ESP32 firmware image through the running firmware path. It is not the same as flashing from a serial toolchain.
- Use it when the ESP32 is reachable over its network API.
- After OTA, confirm success on the diagnostics page and with a terminal status check.
- If OTA appears to succeed but verification fails, check that the firmware came back on the expected host and port.
OTA success is not "the upload returned 200." OTA success is "the ESP32 rebooted, came back on the expected network target, and diagnostics or terminal status now show the new runtime state."
USB File Manager
This page reflects the ESP32 USB-host workflow, not the Orange Pi staging area. Use it when you need to inspect or operate on USB storage attached to the ESP32 host-side path.
- Use diagnostics and terminal USB commands if file operations fail and you need mount-state evidence.
- Do not confuse ESP32 USB-host media with files stored on the Orange Pi itself.
FTP Server and FTP Client
The FTP Server page controls the runtime FTP service on the Orange Pi. The FTP Client page is the gateway-side tool for making outbound FTP connections and transfers.
- Server page: runtime service control, configuration, and exposure.
- Client page: saved sites, connection state, uploads, downloads, and remote browsing.
- If one page works and the other does not, treat them as different subsystems.
Regression and Smoke Testing
The system relies on automatic safeguards to prevent UI and infrastructure breaks.
- The vcom-terminal probe covers websocket connect, direct command execution, menu open, menu move, !SCAN open, and safe cancel. Use scripts\\vcom-terminal-probe.bat --base-url https://orangepirv2.tail59ab20.ts.net.
- The hardware coredump regression path uses pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\esp32-coredump-regression.ps1 to flash the standard dev firmware, trigger !PANIC, verify the persisted crash report, clear it, and then rerun the COM22 smoke test.
- Playwright UI E2E tests enforce that every frontend change must survive browser checks without breaking layouts, 404s, or generating Javascript console errors. Automatically run via npx playwright test.
- Use scripts\\deploy-and-regress.bat for the normal deployment gate.
These probes matter because the fragile parts of this system are not static HTML rendering. They are the terminal open/close lifecycle, stale-session recovery, websocket bridging, interactive scan prompts, UI layout logic, and reconnect behavior during ESP32 Wi-Fi changes.
Troubleshooting Reference
| Symptom | Most likely cause | What to do |
|---|
| Browser terminal says session already active | Another browser tab or stale single-owner session | Close the other tab, wait briefly, reconnect, or refresh and reconnect. |
| Terminal is dark | Silent Mode is enabled | Turn Silent Mode off from VCOM Settings, save, then reconnect. |
| Menu command runs, then confusing prompt behavior | You are still inside the menu wrapper | Press Enter to go back to the menu or Esc / q to return to the normal prompt. |
| ESP32 status page fails but terminal still works | Diagnostics endpoint path issue, not total device failure | Verify the ESP32 target host/port and use terminal commands for immediate confirmation. |
| Host network change drops the browser | The Orange Pi moved to a different address | Use the replacement LAN or Tailscale URL noted before the change. |
| OTA started but state is unclear after reboot | Device came back on a new network path or later than expected | Check diagnostics, status, and target host/port before retrying. |
| FTP client fails while server page looks fine | Outbound FTP session problem, saved-site issue, or target issue | Treat client and server separately and inspect the client error path. |
Operator Notes
Use this help page as the broad system reference. Use each individual page when you need to act. The page-level help popups remain useful for page-specific context, but the dashboard `Help` entry now points here so you can navigate the full system documentation from one place.