Commander1024
ab6a8010ba
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.
70 lines
5.1 KiB
Markdown
70 lines
5.1 KiB
Markdown
# ESP32 Serial Swiss Army Knife
|
||
|
||
|
||
|
||
ESP32-S3 firmware for a secure, multi-transport RS-232 adapter. It operates one MAX3243-backed UART1 serial port and safely shares it between native USB CDC-ACM, an HTTPS/WebSocket browser terminal, and SSH: one connected client can write while others observe. The firmware also provides persistent serial and Wi-Fi configuration, a UART0 recovery console, and hardware diagnostics; it is not a general-purpose router, captive portal, or unauthenticated TCP serial server.
|
||
|
||
## Supported hardware
|
||
|
||
- ESP32-S3-DevKitC-1-compatible development board
|
||
- ESP32-S3-WROOM-1-N16R8 module
|
||
- 16 MB flash
|
||
- 8 MB octal PSRAM
|
||
- Adafruit MAX3243 full-pinout RS-232 breakout; the male connector version is preferred (see [Hardware wiring](docs/wiring.md) for supported connector variants)
|
||
- Optional 128×64 I²C OLED and three buttons, as described in the wiring guide
|
||
|
||
## Documentation
|
||
|
||
Start with [Getting started](docs/getting_started.md) for installation, first-time configuration, and USB or network access.
|
||
|
||
- [Hardware wiring](docs/wiring.md): GPIO assignments, power safety, cables, USB connectors, OLED, and buttons.
|
||
- [Electrical tests](docs/electrical_tests.md): safe hardware bring-up, loopback, flow control, and shared-serial checks.
|
||
- [Command reference](docs/command_reference.md): administration, serial, USB, Wi-Fi, discovery, SSH, and diagnostics.
|
||
- [Web administration](docs/web_administration.md): browser Serial, Admin, Settings, writer control, and reconnecting after changes.
|
||
- [User administration](docs/user_administration.md): accounts, passwords, SSH client keys, and local recovery.
|
||
- [Firmware update](docs/firmware_update.md): application upload through the browser, update precautions, and wired recovery.
|
||
- [Security operations](docs/security_operations.md): trusted-network use, identity verification, credentials, shutdown, and recovery.
|
||
|
||
## Build
|
||
|
||
Install PlatformIO Core and run from the project root:
|
||
|
||
```sh
|
||
pio run
|
||
```
|
||
|
||
The [getting-started guide](docs/getting_started.md#2-install-firmware-by-wire) covers prerequisites and first installation. The configured target is `esp32-s3-devkitc-1-n16r8`.
|
||
|
||
## Upload and monitor
|
||
|
||
Connect the board's **USB-to-UART** port for firmware upload and the UART0 recovery console:
|
||
|
||
```sh
|
||
pio run --target upload
|
||
pio device monitor -b 115200
|
||
```
|
||
|
||
If necessary, add `--upload-port` with your actual bridge device path. The bridge normally appears as `/dev/ttyUSB*`; it is separate from native USB CDC (`/dev/ttyACM*`), which carries UART1 data. At `serial-tool>`, press Enter and run `help`.
|
||
|
||
**Do not erase for routine updates.** Erasing destroys all persisted configuration and credentials. Migration from the former default/factory layout to the custom OTA layout is a separate destructive step; see [partition migration](docs/getting_started.md#partition-migration-and-erasing). Subsequent application-only updates can use the [web updater](docs/firmware_update.md).
|
||
|
||
## Before using network access
|
||
|
||
Create the first administrator on trusted UART0 with `user add <username> admin`; there is no default shared login. Use a separate `user` account for SSH serial access: SSH `admin` opens device administration instead. Verify HTTPS and SSH fingerprints locally before trusting a new or changed identity.
|
||
|
||
Serial, Wi-Fi, mDNS hostname, and display edits need their explicit Save commands to survive reboot. Account and device-identity changes persist immediately. USB host baud/framing choices do not change physical UART1 settings.
|
||
|
||
Use a trusted LAN or the password-protected device AP, not Internet exposure. HTTPS uses a device-specific self-signed certificate and password login; SSH accepts passwords and supported public keys. Browser logins expire after one hour, even during active use. **Disconnect** is not sign-out: use **Sign out** when finished.
|
||
|
||
The firmware is **not resistant to physical flash or RAM extraction**. Passwords are stored as salted PBKDF2-HMAC-SHA256 verifiers, but Wi-Fi secrets and private device keys remain recoverable from unencrypted NVS; offline password guessing and old flash copies also remain possible. Keep local ports physically controlled. Read [Security operations](docs/security_operations.md) before deployment.
|
||
|
||
## Development documentation
|
||
|
||
[Developer index](docs/devel/README.md) · [Roadmap and acceptance history](docs/devel/roadmap.md) · [Current development state](docs/agent/current-state.md)
|
||
|
||
Implementation contracts, regression procedures, PCB research, and the flash layout live under `docs/devel/`. Agent working memory lives under `docs/agent/`. Historical acceptance records are not claims that every fault or hardware test has passed; the carrier PCB remains a draft, not fabrication-ready.
|
||
|
||
## License
|
||
|
||
This project is licensed under the [GNU General Public License version 3 only](LICENSE) (`GPL-3.0-only`). Third-party components remain subject to their respective licenses. The integration baseline uses Espressif registry components `espressif/mdns` `1.12.0`, `wolfssl/wolfssl` `5.8.2~1`, and `wolfssl/wolfssh` `1.4.20`; review upstream security releases before production use.
|