Restructure project documentation
Separate operator guides from development contracts, relocate implementation notes under `docs/devel/`, and update cross-references and hardware tooling paths. Add getting-started, user administration, and firmware update guides while preserving firmware behavior.
This commit is contained in:
@@ -0,0 +1,178 @@
|
||||
# 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](#3-open-the-recovery-console). Review [security operations](security_operations.md) 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](wiring.md). 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](electrical_tests.md) 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](https://docs.platformio.org/en/latest/core/installation/index.html), 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.
|
||||
|
||||
```sh
|
||||
pio run
|
||||
```
|
||||
|
||||
Connect the **USB-to-UART** port, then upload:
|
||||
|
||||
```sh
|
||||
pio run --target upload
|
||||
```
|
||||
|
||||
If automatic port selection is ambiguous, specify your actual bridge port; for example:
|
||||
|
||||
```sh
|
||||
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](#partition-migration-and-erasing) first. Subsequent application-only updates can use the [browser firmware updater](firmware_update.md).
|
||||
|
||||
## 3. Open the recovery console
|
||||
|
||||
Use the bridge port at **115200 baud**:
|
||||
|
||||
```sh
|
||||
pio device monitor -b 115200
|
||||
```
|
||||
|
||||
Alternatively, on Linux with picocom installed and the actual bridge at `/dev/ttyUSB0`:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```text
|
||||
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**:
|
||||
|
||||
```text
|
||||
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](command_reference.md#serial-service) 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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](user_administration.md) 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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](command_reference.md#wi-fi); 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](web_administration.md) 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:
|
||||
|
||||
```sh
|
||||
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](command_reference.md#ssh-serial-transport) for connection details. Inspect the writer with `broker clients` on an administration connection; coordinate before deliberately transferring control through [Broker settings](web_administration.md#serial-observer-and-writer) 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](command_reference.md#mdns). |
|
||||
| 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:
|
||||
|
||||
```sh
|
||||
pio run --target erase
|
||||
pio run --target upload
|
||||
```
|
||||
|
||||
Then provision the device again and verify its new HTTPS/SSH fingerprints locally. See [flash layout](devel/flash_layout.md) for the partition map and [firmware recovery](firmware_update.md#wired-recovery) for recovery that does not routinely erase NVS.
|
||||
Reference in New Issue
Block a user