14 KiB
Command reference
Use these commands from the UART0 serial-tool> administration console. Run help for the available root commands and <group> help for a group summary. Configuration changes are RAM-only unless explicitly saved.
System
| Command | Description |
|---|---|
memory |
Show free memory, minimum free memory, and largest blocks for internal RAM, DMA-capable RAM, and PSRAM. |
reboot |
Drain console output briefly and restart the ESP32. |
status |
Show quick MAX3243 signal state. |
Role-based users (Phase 8A)
| Command | Description |
|---|---|
user status / user list |
Show database generation, capacity, administrator/bootstrap state, and all secret-free account summaries. |
user show <username> |
Show one account's role, ID, authentication generation, and SSH-key fingerprints. |
user bootstrap |
Set and confirm the admin password without echo, then promote the migrated account to admin. |
user bootstrap --generate |
Bootstrap admin with a generated 24-character password displayed once. |
| `user add <user | admin>` |
| `user add <user | admin> --generate` |
user delete <username> --force |
Delete an account; the pre-bootstrap migrated admin and final administrator are protected. |
| `user role <user | admin> --force` |
user password <username> |
Set and confirm a new password without echo. |
user password <username> --generate |
Replace a password with a generated value displayed once. |
user key add <username> |
Prompt for one bounded OpenSSH public-key line. |
user key delete <username> <0..2> --force |
Delete one key by the index shown by user show. |
user key clear <username> --force |
Delete all public keys for an account. |
user recover --force |
When normal user-database initialization failed, explicitly replace its blob from the current legacy network credential. |
Usernames must match [a-z][a-z0-9_-]{0,15}. Passwords contain 12–64 printable ASCII characters. The fixed database supports eight users and three SSH keys per user; initial key types are ssh-ed25519 and ecdsa-sha2-nistp256. A key may belong to only one account. Password verifiers, salts, raw key blobs, and passwords are absent from ordinary status output. Ctrl-C cancels a password or key prompt, and generated passwords are shown once.
On the first Phase 8A boot, the existing shared admin HTTPS/SSH credential is imported as a role-user account, not silently granted administrator rights. Run user bootstrap from physical UART0 to establish the administrator. Before bootstrap, web credentials rotate --force and web reset --force synchronize the migrated verifier; reboot reconciliation retries an interrupted synchronization. After bootstrap, the legacy HTTPS/SSH credential and user-database passwords are intentionally separate until Phase 8B performs the authentication cutover. SSH public-key login is likewise enabled in Phase 8B, not Phase 8A.
user recover --force is a destructive physical recovery operation and succeeds only while the database is unavailable. It replaces the user blob with one role-user account derived from the current legacy credential; run user bootstrap afterward. It does not erase unrelated NVS data.
Local display
| Command | Description |
|---|---|
display status |
Show the runtime aging settings and OLED service state. |
display set dim-seconds <0..86400> |
Set the RAM inactivity delay before contrast drops to 1; 0 disables dimming. |
display set off-seconds <0..86400> |
Set the RAM inactivity delay before the OLED switches off; 0 disables automatic off. |
display save / display load |
Save the working aging settings to NVS or load them. |
display defaults / display reset |
Apply 300/600-second defaults in RAM, or apply and persist them. |
When both transitions are enabled, off-seconds must be greater than dim-seconds. Applying settings counts as local UI activity. At normal boot, an initialized OLED shows a bounded five-second identity animation before the status UI begins; it scrolls the device name in yellow and draws the compact upright-terminal logo in blue. A missing OLED remains nonfatal; after reconnecting it safely, one new button press requests a bounded reprobe and is consumed without navigating.
Serial service
| Command | Description |
|---|---|
serial status |
Show UART1 state, configuration, modem signals, and ownership. |
serial start / serial stop |
Start or release the physical UART1 service. |
| `serial set <baud | data-bits |
serial save / serial load |
Save the working configuration to NVS or load it. |
serial defaults / serial reset |
Apply defaults in RAM, or apply and persist them. |
serial counters / serial clear-counters |
Show or clear serial counters. |
Defaults are 115200 baud, 8 data bits, no parity, one stop bit, no flow control, and inactive DTR. Supported values: baud 110–1000000; data bits 7 or 8; parity none, even, or odd; stop bits 1 or 2; flow none or rts-cts; DTR inactive, active, or on-connect; and RTS threshold 1–127 bytes. The broker exclusively owns serial data access.
Session broker
| Command | Description |
|---|---|
broker status / broker clients |
Show broker state or connected clients. |
broker counters / broker clear-counters |
Show or clear broker counters. |
broker connect <name> / broker disconnect <client-id> |
Create or remove a console test client. |
broker request-writer <client-id> / broker release-writer <client-id> |
Request or relinquish the single writer lease. |
| `broker force-writer <client-id | none>` |
broker send-hex <client-id> <hex-bytes> |
Send hexadecimal bytes through a writer client. |
broker read <client-id> [maximum-bytes] |
Read queued serial output for a client. |
broker events <client-id> |
Show ownership and connection events for a client. |
Each client has a generation-safe ID. There can be one writer and multiple observers; a slow observer loses only its own queued output.
Native USB CDC-ACM
| Command | Description |
|---|---|
usb / usb help |
Show USB command usage. |
usb status |
Show CDC connection, broker role, and runtime state. |
usb counters / usb clear-counters |
Show or clear USB counters. |
usb request-writer / usb release-writer |
Request or release USB writer ownership. |
Opening /dev/ttyACM* with DTR asserted creates the usb-cdc broker client, starts UART1 if needed, and requests writer ownership. It becomes an observer if another client is writer. USB data is binary-transparent. Supported host line coding is 110–1000000 baud, 7/8 data bits, none/odd/even parity, and 1/2 stop bits; settings apply only while USB owns the writer lease and are not saved automatically.
Wi-Fi
| Command | Description |
|---|---|
wifi status / wifi profiles |
Show Wi-Fi state or configured station profiles. |
wifi start / wifi stop / wifi reconnect |
Start, stop, or reconnect Wi-Fi. |
wifi next-profile |
Queue a switch to the enabled station profile after the currently active profile in priority order; wraps safely. |
| `wifi profile set <mixed | wpa3> ` |
wifi profile secret <slot> |
Set a profile password through a no-echo prompt. |
| `wifi profile enable | disable |
| `wifi ap policy <off | fallback |
wifi ap ssid <ssid> / wifi ap channel <1..11> |
Set the AP name or channel. |
wifi ap secret / wifi ap show-secret |
Set or reveal the AP password. |
| `wifi save | load |
| `wifi counters | clear-counters` |
wifi ping <host> [count] |
Send 1–20 IPv4 or IPv6 ICMP probes. |
wifi nslookup <host> |
Resolve and display unique IPv4/IPv6 addresses. |
wifi traceroute <host> [max-hops] |
Run IPv4 ICMP traceroute with up to 30 hops. |
ping, nslookup, and traceroute are root aliases. The four station-profile slots use lower priority values first. Passwords are not displayed by ordinary status output.
HTTPS web terminal
| Command | Description |
|---|---|
web / web help |
Show web-service command usage. |
web status |
Show HTTPS and WebSocket state. |
web start / web stop |
Start or stop HTTPS service. |
web counters / web clear-counters |
Show or clear web counters. |
web credentials show |
Display the physical-console-only legacy Phase 8A network credential. |
web credentials rotate --force |
Replace the legacy credential, apply pre-bootstrap migration synchronization, and disconnect web and SSH sessions. |
web certificate info |
Display certificate identity and fingerprint. |
web certificate rotate --force |
Replace the HTTPS certificate and private key. |
web reset --force |
Explicitly replace missing, incompatible, or damaged legacy credentials and web material. |
HTTPS listens on port 443 only. During Phase 8A, authenticate to https://<device-address>/ as admin with the legacy credential shown on UART0; role-aware user-database authentication begins in Phase 8B. The device serves its vendored xterm.js terminal without Internet access. Browser sessions use binary WebSocket frames and follow the broker's one-writer rule.
SSH serial transport
| Command | Description |
|---|---|
ssh / ssh help |
Show SSH command usage. |
ssh status |
Show service state and resource information. |
ssh start / ssh stop |
Start or stop the SSH server. |
ssh sessions |
List active SSH sessions and broker roles. |
ssh disconnect <session-id> |
Disconnect one SSH session. |
ssh counters / ssh clear-counters |
Show or clear SSH counters. |
ssh host-key info |
Display the OpenSSH host-key fingerprint. |
ssh host-key rotate --force |
Replace the persistent SSH host key. |
ssh reset --force |
Explicitly replace invalid or missing SSH material. |
During Phase 8A, SSH listens on port 22 and uses the same legacy admin credential as HTTPS, but a separate host key. It accepts password-authenticated interactive shell/PTY serial sessions only. Stored per-user public keys and roles become active in Phase 8B/8C; Phase 8A does not yet provide public-key login or the administrative SSH shell. SSH does not provide exec, SFTP, SCP, forwarding, or subsystems. Verify the fingerprint from ssh host-key info before accepting an SSH host key.
Hardware diagnostics
| Command | Description |
|---|---|
| `debug transceiver <enable | disable>` |
| `debug drivers <tx 0 | 1> <dtr 0 |
debug loopback-a / debug loopback-b |
Test MAX3243 driver/receiver loopback configurations. |
debug valid-test |
Verify valid RS-232 voltage detection. |
| `debug uart-loopback [8N1 | 8E1 |
debug uart-suite |
Test supported baud rates and frame formats. |
debug cts-flow-test / debug rts-flow-test |
Verify hardware transmit gating or receive backpressure. |
debug display status |
Show the current display diagnostic state. |
debug display probe |
Probe the expected OLED addresses 7-bit 0x3c and 0x3d, initially using 100 kHz I²C. The tested module responds at 0x3c. |
debug display scan --force |
Scan usable 7-bit addresses 0x08–0x77 at 100 kHz; use only on this dedicated local-UI bus. |
debug display init [address] |
Initialize the OLED at 7-bit 0x3c/0x3d, or their 8-bit write/read aliases: 0x78/0x79 and 0x7a/0x7b. |
debug display off |
Turn off the initialized OLED. |
| `debug display pattern <clear | fill |
debug display row <0..63> |
Draw the selected one-pixel display row for addressing and color-boundary checks. |
debug display contrast <0..255> |
Set the OLED contrast to the specified bounded value. |
| `debug display invert <on | off>` |
debug buttons status |
Show the current active-low state of previous/back GPIO10, select/confirm GPIO13, and next GPIO14. |
debug buttons test [seconds] |
Run the bounded button event test for 1–30 seconds; the default is 10 seconds. |
Follow the exact wiring in Electrical tests before invoking diagnostics. The OLED must be powered from 3.3 V because module I²C pull-ups may connect to VCC; verify that all external pull-ups also terminate at 3.3 V. Display diagnostics probe the standard SSD1315-compatible 7-bit 0x3c/0x3d addresses. The currently tested module acknowledges at 0x3c, whose 8-bit write/read forms are 0x78/0x79; an explicit scan --force is available only for the dedicated local-UI bus. Diagnostics initially run at 100 kHz and treat an absent display as nonfatal. RS-232 diagnostics that require UART1 refuse to use it until serial stop releases it. The RGB LED shows test state: blue idle, yellow/orange running, green passed, red failed.