ESP32_Serial_Swiss_Army_Knife/docs/command_reference.md

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

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 old shared admin credential is imported as a role-user account, not silently granted administrator rights. Run user bootstrap from physical UART0 to establish the administrator. Phase 8B now authenticates HTTPS and SSH passwords through this database and enables stored SSH public keys. Before bootstrap, web credentials rotate --force and web reset --force synchronize the migrated verifier; after bootstrap, that legacy credential is recovery-only and does not authenticate or alter role-based users.

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. Successful password, role, key, bootstrap, and delete operations invalidate only that username's outstanding WebSocket tickets and active WebSocket/SSH sessions; unrelated users remain connected.

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 migration/recovery credential; it is not a Phase 8B network login.
web credentials rotate --force	Replace the legacy recovery credential and synchronize the migrated pre-bootstrap account only.
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. Authenticate with any current user-database username/password; both user and admin roles receive the existing status and browser-terminal interface. The device serves vendored xterm.js without Internet access. Browser sessions use one-time account-bound tickets, binary WebSocket frames, and the broker's one-writer rule. Account mutations revoke only that account's tickets and sessions.

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 with account, user role, authentication method, and broker role.
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.

SSH listens on port 22 and accepts user-database passwords plus stored ssh-ed25519 and ecdsa-sha2-nistp256 public keys. wolfSSH verifies key possession after the database authorizes the username/key pair; unsigned key probes do not complete authentication. Both user and admin currently receive the same broker-backed interactive shell/PTY serial stream. The administrative SSH shell arrives in Phase 8C. SSH does not provide exec, SFTP, SCP, forwarding, or subsystems. Verify the host fingerprint from ssh host-key info before connecting.

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.