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.

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 shared admin credentials.
web credentials rotate --force	Replace credentials 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 web material.

HTTPS listens on port 443 only. Authenticate to https://<device-address>/ as admin with the credential shown on UART0. 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.

SSH listens on port 22 and uses the same admin credentials as HTTPS, but a separate host key. It accepts password-authenticated interactive shell/PTY sessions only; it does not provide public-key authentication, 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.