#Interfaces and Tools

The IsolaRail control plane combines device firmware, a local daemon, a CLI, and the Web app. The current owner-facing entrypoint is the isolarail CLI; isolarail-devd is the local service and should not require ordinary users to manage it manually.

#Layering

user
  ├─ isolarail CLI
  │    └─ native IPC -> isolarail-devd serve
  │          └─ USB JSONL / flash / reset / monitor
  ├─ Web app
  │    ├─ Wi-Fi / LAN HTTP
  │    ├─ Web Serial
  │    └─ explicit Local USB bridge from isolarail-devd web
  └─ direct firmware links
       ├─ USB CDC JSONL
       └─ HTTP / LAN v1

The default path is isolarail automatically finding or starting isolarail-devd serve. isolarail-devd web is explicit and only for browser development or same-origin Web hosting.

#Naming and identity

These names are owned by docs/specs/pw97u-control-plane-alignment/SPEC.md. Web, CLI, README, and diagnostics should not invent alternate product names.

#USB JSONL

Firmware exposes core operations over USB Serial/JTAG JSONL:

• info
• ports.get
• port.power_set
• port.replug
• wifi.get
• wifi.set
• wifi.clear
• reboot

The info response must include device identity, MAC, firmware name, version, and uptime. The companion uses those fields for identity checks so flashing and control commands are not sent to an unrelated board.

port.power_set and port.replug only accept port1..port4; historical USB-A, USB-C, and route models are not current control-plane IDs.

#HTTP / LAN

The target device-side HTTP v1 surface includes:

• GET /api/v1/health
• GET /api/v1/info
• GET /api/v1/ports
• GET /api/v1/ports/{portId}
• POST /api/v1/ports/{portId}/power
• POST /api/v1/ports/{portId}/actions/replug
• GET /api/v1/wifi
• POST /api/v1/reboot

Device HTTP v1 is not an account or cloud-auth surface. Wi-Fi writes still require a USB-backed device path.

Seeing the device on LAN does not authorize Wi-Fi credential writes.

#isolarail-devd modes

isolarail-devd has two modes:

• serve: default native IPC daemon for local CLI/desktop paths.
• web: explicit localhost Web companion for browser development and same-origin Web hosting.

Do not treat localhost HTTP as the default daemon transport. The Web runtime must not scan localhost ports; usable origins must come from same-origin bootstrap or explicit DEVD_ORIGINS.

Ordinary users should not need to start the daemon first; the CLI connects to an existing instance or starts serve.

#CLI selectors

The CLI separates temporary devices from saved hardware:

• --device <device-id>: currently connected temporary USB target.
• --hardware <saved-id>: saved hardware profile.

Wi-Fi write and clear operations require --device or USB-backed --hardware. --url and Wi-Fi/LAN saved hardware stay read-only.

#Common commands

Read-only checks:

just discover
just devices
just hardware-available
SELECTOR='--device <device-id>' just status
SELECTOR='--device <device-id>' just device-ports
SELECTOR='--device <device-id>' just wifi-show

Device actions:

SELECTOR='--device <device-id>' PORT=port1 ENABLED=true just port-power
SELECTOR='--device <device-id>' PORT=port1 just port-replug
SELECTOR='--device <device-id>' just device-reset

Diagnostics:

SELECTOR='--device <device-id>' TAIL=200 just device-monitor
SELECTOR='--device <device-id>' just diagnostics-export

State-changing commands should run sequentially. The companion enforces mutual exclusion for the same serial path, so overlapping requests can legitimately return device busy.

#Diagnostics export

just diagnostics-export should aggregate:

• status
• ports
• wifi
• recent Local USB serial session traces
• daemon-observed identity and selector information

The goal is to reproduce what state one board was in, not just capture the last error line.

#Web app boundary

The Web app arbitrates three channels:

• Wi-Fi / LAN
• Web Serial
• Local USB bridge

It does not scan localhost, does not point users at implicit port discovery, and does not bypass isolarail-devd identity checks.

Web runtime arbitration:

• Wi-Fi / LAN, Web Serial, and Local USB bridge may all be available.
• The same device must not appear as duplicates just because channels differ.
• Last successful channel wins; if it fails, promote another available channel.
• unsupported, busy, offline, and USB-only states must show clear next actions.

#References

• README.md
• docs/specs/pw97u-control-plane-alignment/SPEC.md
• docs/specs/q9d7h-cli-devd-flash-migration/SPEC.md