ESP32_Serial_Swiss_Army_Knife/docs/getting_started.md

Getting started

This guide takes a supported, wired board from its first firmware installation to USB or network serial access. If firmware is already installed, start at Open the recovery console. Review security operations before enabling network access.

1. Check the hardware

Use the ESP32-S3-DevKitC-1-compatible N16R8 target (16 MB flash, 8 MB octal PSRAM) and the Adafruit MAX3243 breakout described in Hardware wiring. Follow that GPIO map, not a generic ESP32 pinout.

• Wire with power disconnected. Power the breakout and optional OLED from 3.3 V, not 5 V.
• Never connect RS-232 voltage directly to ESP32 GPIOs. The MAX3243 is a level shifter, not a galvanic isolator.
• Select a straight-through cable for a DCE peer or a suitable null-modem cable for another DTE peer. A gender changer alone does not cross signals.
• Use Electrical tests to verify a new assembly before attaching valuable equipment. Active RS-232 diagnostics require the serial service to be stopped.

There are two distinct USB paths:

Board connector	Typical Linux device	Use
USB-to-UART bridge	/dev/ttyUSB*	Firmware installation, UART0 logs, and the serial-tool> administration/recovery console
Native USB	/dev/ttyACM*	UART1 serial data shared with browser and SSH clients

Names and connector labels vary between boards. Identify the actual port rather than assuming the example device name. Consult the board schematic before powering through both connectors.

2. Install firmware by wire

Install PlatformIO Core, obtain a trusted project checkout, and run these commands from its root. PlatformIO downloads the configured toolchain and dependencies on the first build, so initial setup needs network access.

pio run

Connect the USB-to-UART port, then upload:

pio run --target upload

If automatic port selection is ambiguous, specify your actual bridge port; for example:

pio run --target upload --upload-port /dev/ttyUSB0

Do not erase for ordinary installation over a compatible layout or for routine updates. If migrating from the former default/factory layout or unrelated firmware, read Partition migration and erasing first. Subsequent application-only updates can use the browser firmware updater.

3. Open the recovery console

Use the bridge port at 115200 baud:

pio device monitor -b 115200

Alternatively, on Linux with picocom installed and the actual bridge at /dev/ttyUSB0:

picocom /dev/ttyUSB0 -b 115200

After an unattended boot, press Enter once in an ANSI-capable terminal to enable line editing, history, cursor movement, and hierarchical Tab completion. At serial-tool>, run:

help
serial status
wifi status

This console controls the ESP32, not the equipment attached to RS-232. Keep it available while changing network settings or credentials. Physical UART0 access is not protected by network account passwords.

4. Set the equipment's serial parameters

Match UART1 to the attached equipment. For example, for 115200 baud, 8N1, no hardware flow control:

serial set baud 115200
serial set data-bits 8
serial set parity none
serial set stop-bits 1
serial set flow none
serial status
serial save

Use serial set flow rts-cts only when the peer and cable support it. DTR is configured separately with serial set dtr inactive, active, or on-connect; choose the behavior your equipment requires. See the serial command reference for supported values.

Working serial edits are RAM-only until serial save. Reconfiguration or stopping the service discards pending serial-service data, so do it while traffic is idle. USB terminal baud/framing choices do not configure physical UART1.

5. Use native USB without networking

Connect the native USB port and open its CDC device with a serial terminal that asserts DTR. This creates the usb-cdc client, starts UART1 if needed, and requests writer ownership. If another client already owns it, USB joins as an observer.

On UART0, inspect:

usb status
broker clients

Exactly one client can write to UART1; others receive the incoming serial stream. Coordinate with the current writer before requesting control with usb request-writer; use usb release-writer to give it up. A slow observer may lose its own buffered output without blocking other clients.

Native USB remains usable when network services fail. It is not the account-recovery console and does not provide uninterrupted operation through reboot.

6. Provision network access

On trusted UART0, create an administrator and, if desired, a separate SSH serial account:

user add maint admin
user add operator user

Enter unique passwords at the hidden prompts. There is no default shared login. Account changes persist immediately. See User administration for password rules, SSH keys, and recovery.

Inspect wifi profiles first to avoid replacing an existing profile. For a new device, this example configures slot 0; replace the example SSID with your trusted network's name:

wifi profile set 0 0 mixed "Your network name"
wifi profile secret 0
wifi profile enable 0
wifi start
wifi status

Enter the Wi-Fi password at the secret prompt, not in the command line. Connection changes are asynchronous: check wifi status again for the resulting connection and addresses. Once correct, run:

wifi save
mdns status
web certificate info
ssh host-key info

Record the public identity fingerprints through this trusted local connection. Wi-Fi and mDNS hostname settings have separate Save commands. For device-AP policy and password setup, see the Wi-Fi reference; revealing an AP secret with wifi ap show-secret should only be done in a private, unrecorded console.

Browser

Open https:// followed by the hostname reported by mdns status, or a reachable IP address. Compare the browser certificate fingerprint with the local web certificate info output before entering credentials. Sign in and follow the browser guide to connect Serial and manage control. Connecting or reconnecting automatically requests the writer lease; check Role before typing.

SSH

Compare the client's host-key fingerprint with ssh host-key info before trusting it. Use an interactive SSH connection to the device address with the desired account:

• user accounts open the UART1 stream.
• admin accounts open device administration, not UART1.

For example, replace DEVICE_ADDRESS with the reported hostname or IP:

ssh operator@DEVICE_ADDRESS

A serial SSH connection starts UART1 if needed and automatically requests writer ownership. If USB or another client already owns it, SSH remains an observer and typed input is discarded, not queued for later. Check ownership before typing. Releasing the other writer does not automatically promote this session; deliberately assign it control from administration, or reconnect after the lease is free.

SSH supports interactive shells, not exec commands, file transfer, or forwarding. Use the SSH reference for connection details. Inspect the writer with broker clients on an administration connection; coordinate before deliberately transferring control through Broker settings or broker force-writer <client-id>.

If something does not work

Symptom	First checks
No serial-tool> prompt	Check that you opened the bridge, not native USB; use 115200 baud and press Enter.
USB opens but cannot transmit	Check host DTR, usb status, and the current writer in broker clients.
Garbled or missing serial data	Check UART1 settings, cable crossing, ground, and RTS/CTS support. Use the safe loopback procedures before changing wiring.
Browser or SSH is unreachable	Inspect wifi status, web status, and ssh status on UART0; test a reachable numeric address to separate discovery from connectivity.
Hostname works on one computer only	Check that the other client supports local mDNS resolution for the required IPv4/IPv6 family. See network discovery.
Forgotten account password	Use normal user password on UART0. Do not erase or invoke unavailable-database recovery for a healthy database.
Lost response after a settings change	Reconnect and inspect actual state before retrying; disconnection does not cancel accepted work.

Partition migration and erasing

Erasing the whole flash destroys all persisted configuration, accounts, Wi-Fi credentials, and device identities. Record what you need to reprovision first. Do not use it as routine troubleshooting or an ordinary update step.

The first migration from the former default/factory partition layout to this project's custom OTA layout requires an erase. Migration from unrelated firmware or another layout may also require it. Only when deliberately performing such a migration or a complete destructive reset:

pio run --target erase
pio run --target upload

Then provision the device again and verify its new HTTPS/SSH fingerprints locally. See flash layout for the partition map and firmware recovery for recovery that does not routinely erase NVS.