129 lines
9.2 KiB
Markdown
129 lines
9.2 KiB
Markdown
# 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|parity|stop-bits|flow|dtr|rts-threshold> <value>` | Change the working serial configuration and safely restart a running service. |
|
||
| `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>` | Administratively assign or clear the writer lease. |
|
||
| `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 <slot> <priority> <mixed|wpa3> <ssid>` | Set a station profile. |
|
||
| `wifi profile secret <slot>` | Set a profile password through a no-echo prompt. |
|
||
| `wifi profile enable|disable|delete <slot>` | Manage a station-profile slot. |
|
||
| `wifi ap policy <off|fallback|always>` | Configure fallback AP behavior. |
|
||
| `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|defaults|reset` | Persist, restore, reset in RAM, or reset and persist configuration. |
|
||
| `wifi counters|clear-counters` | Show or clear Wi-Fi 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>` | Enable or shut down the MAX3243. |
|
||
| `debug drivers <tx 0|1> <dtr 0|1> <rts 0|1>` | Drive static TX, DTR, and RTS logic levels for measurement. |
|
||
| `debug loopback-a` / `debug loopback-b` | Test MAX3243 driver/receiver loopback configurations. |
|
||
| `debug valid-test` | Verify valid RS-232 voltage detection. |
|
||
| `debug uart-loopback <baud> [8N1|8E1|8O1|8N2|7E1|7O1] [bytes]` | Run a parameterized UART loopback test. |
|
||
| `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|checker|grid|corners|layout>` | Draw a full-screen electrical and geometry test pattern; `layout` renders separate status- and content-panel text. |
|
||
| `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>` | Enable or disable OLED pixel inversion. |
|
||
| `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](electrical_tests.md) 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.
|