ESP32_Serial_Swiss_Army_Knife/docs/web_administration.md

Web administration

Use the browser to operate the UART1 serial terminal and, with an administrator account, manage the device. Use a trusted LAN or the device's password-protected AP—not an Internet-exposed connection.

Related guides: Account provisioning, firmware updates, command reference, and security operations. Protocol and implementation details are in the preserved development contract.

Connect and sign in

1. Provision an account through physical UART0 first; see user administration. Native USB CDC carries UART1 data and is not the administration console.
2. Connect to the device's network and open its HTTPS address (port 443), using its configured hostname or reachable IP address. The terminal assets are served by the device; Internet access is not required.
3. Before entering credentials, compare the browser's SHA-256 certificate fingerprint with web certificate info on trusted UART0. Do not blindly accept an unexpected certificate warning.
4. Sign in with your account username and password. Both user and admin can use Serial; only admin can use Admin and Settings. SSH client keys do not replace the browser password.

A login expires one hour after sign-in, even while active. There are four login-session slots, two browser serial connections, and one browser admin connection; these are separate limits. Login attempts are globally limited to five per 60 seconds. If admission fails, close unused connections or sign out unused sessions and wait rather than repeatedly submitting credentials.

Disconnect closes the serial connection and pauses its automatic reconnect; Connect resumes it. Neither signs you out. Use Sign out when finished. If sign-out is not confirmed because the network failed, do not assume server-side logout succeeded; retry when reachable.

Serial: observer and writer

All transports share one physical RS-232 port. Exactly one broker client can write; other clients observe the incoming UART1 stream.

Connecting or reconnecting Serial automatically requests control. If no other client owns the writer lease, your connection becomes writer. Check Role after every reconnect; Release control applies to the current connection, not future reconnects.

• Check Role, Active writer, and the connection status before typing. The dashboard's Writer/Observer role is not your account's admin/user role.
• Choose Request control to request the writer lease. An administrator account does not automatically make this serial connection the writer. If another client owns control, coordinate with that operator.
• Type only when writer status is confirmed. Observer input is disabled.
• Choose Release control when finished transmitting so another client can write.
• Administrators can inspect Broker settings or the writer/client quick views and explicitly assign control to a selected current client. Refresh and deliberately reselect after a stale-target warning. Transfer cannot recall bytes already accepted for transmission.

Slow observers can lose their own output without blocking other clients. The browser has bounded output buffering and 5,000 lines of scrollback per terminal; it is not a durable recording. Observe reported drop counts when completeness matters. Serial transport remains binary-transparent: there are no in-band administration escape sequences.

Serial, Admin, and Settings

Switching views does not reconnect Serial or request/release its writer lease. Hidden connected terminals continue receiving output; keyboard input goes only to the selected terminal.

• Serial is the connected equipment's UART1 stream.
• Admin is the ESP32 command console, not the connected equipment. Choose Open admin explicitly. Closing Admin leaves Serial connected. One browser admin connection and two remote-console slots shared with admin SSH bound availability.
• Settings provides typed controls for Serial settings, Accounts, Network, Display, Broker, SSH, and HTTPS / Reboot. Opening a page, selecting a client, or opening a quick view does not apply changes.

Use the command reference for commands, but do not assume full UART0/SSH parity in the browser shell. Browser account commands are limited to selected operations on other accounts; use Accounts for supported self/password-generation/key workflows. Browser SSH identity/service mutations belong in typed SSH settings. Browser web commands are restricted to status, stop, and certificate rotation; recovery remains on UART0 or reachable admin SSH. Wi-Fi commands include hidden secret prompts and can immediately disconnect you. Avoid explicit secret-display commands in recorded/shared terminals.

Apply, Save, and persistent state

Area	Operator rule
Serial settings	Apply and Defaults change working RAM. Save persists the device's working values, not unsent browser drafts. Reconfiguration or stop discards pending serial-service data, though broker clients and writer ownership remain.
Network	Wi-Fi edits require explicit Save; hostname/mDNS settings have separate persistence. Start/Stop also change the RAM boot-enabled policy. Save only after checking the desired working state.
Display	Apply changes working configuration; Save persists it. Load reads saved state; Reset persists defaults.
Accounts and authorized keys	Successful mutations are committed immediately; there is no separate account Save. They revoke the affected account's network sessions.
HTTPS/SSH identities	Successful replacement persists immediately. Rotation is not an account-password change.
Broker/service controls	These operate on live connections/services; they are not saved configuration profiles.

Load, Defaults, and Reset are not synonyms. Read each confirmation and the command reference before discarding configuration. Network quick views intentionally omit password controls; use the full Network page. USB host baud/framing selections do not configure UART1; use Serial settings.

Save desired working settings before reboot or firmware upload. Saved configuration survives an ordinary reboot; unsaved RAM settings and browser drafts may not.

Disruptive changes and uncertain results

Plan a maintenance window and keep UART0 available before changing networking, identities, services, or firmware.

• Network: profile/AP changes, stop, or reconnect may cut off the result. An accepted operation is not proof of Wi-Fi association, address acquisition, or name resolution. Restore connectivity and inspect actual state before retrying.
• Accounts: changing your own password, role, or keys may revoke your login before the result appears. See account management.
• HTTPS stop/restart: closes all web logins and both browser terminal routes. A stopped web service cannot be restarted through its own page; use web start on UART0 or still-reachable admin SSH.
• HTTPS certificate rotation: verify the new fingerprint through UART0 before renewing browser trust. A failure after storage commit can leave a new stored identity even if restart fails; a retained server may still serve the old certificate. Do not repeat rotation blindly.
• SSH controls/host-key rotation: can close SSH sessions. Verify a changed host-key fingerprint with ssh host-key info on UART0 before updating client trust. HTTPS is not inherently restarted by SSH rotation.
• Reboot: interrupts every transport, including native USB and UART operation during restart. Reconnect and sign in explicitly afterward.
• Firmware upload: can stall or drop browser sessions before reboot. Follow the separate firmware procedure.

A timeout, lost response, navigation, logout, or revoked login does not cancel already admitted work. Settings results are temporary observations, not a durable operation history. Use Check Result/Refresh where offered (SSH and HTTPS / Reboot require manual checking), then inspect actual device state. Never replay a destructive action merely because its acknowledgement disappeared.

Recovery

1. If the page or session fails, restore network access, reload, and sign in again. Check identity warnings locally before entering credentials.
2. If networking or HTTPS is unavailable, use physical UART0 for status and repair. Reachable admin SSH can also recover HTTPS with web stop / web start when appropriate.
3. Repair forgotten passwords with normal UART0 account commands. user recover --force is destructive unavailable-database recovery, not a password-reset shortcut; see user administration.
4. If a firmware update prevents boot or web access, use wired recovery as described in the firmware guide.

Native USB remains network-independent UART1 access when network services fail, but cannot repair accounts or identities and does not promise uninterrupted data through flash operations or reboot. Keep local ports physically controlled. See security operations for backup limits, identity recovery, and physical-extraction risks.