84 lines
5.5 KiB
Markdown
84 lines
5.5 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.
|
|
|
|
## Initial hardware target
|
|
|
|
- ESP32-S3-DevKitC-1-compatible development board
|
|
- ESP32-S3-WROOM-1-N16R8 module
|
|
- 16 MB flash
|
|
- 8 MB octal PSRAM
|
|
- [Adafruit MAX3243 full-pinout male RS-232 breakout](https://www.adafruit.com/product/6253)
|
|
|
|
## Development status
|
|
|
|
Hardware characterization, the serial core, USB CDC-ACM, Wi-Fi, HTTPS/WebSocket, SSH serial transport, and the local display/control interface are implemented. Phase 8A adds the bounded role-based user database and physical UART0 user administration; target-hardware validation and the later HTTPS/SSH authentication cutover are still pending. See the [Roadmap](docs/roadmap.md) for phase status and validation details.
|
|
|
|
## Documentation
|
|
|
|
- [Hardware wiring](docs/wiring.md): hardware profile, GPIO assignments, connector guidance, and safety notes.
|
|
- [Electrical tests](docs/electrical_tests.md): MAX3243, UART loopback, and session-broker verification procedures.
|
|
- [Command reference](docs/command_reference.md): UART0 administration, serial, broker, USB, Wi-Fi, web, SSH, and diagnostic commands.
|
|
|
|
## Flash partition layout
|
|
|
|
The N16R8 target has 16 MiB flash and 8 MiB octal PSRAM. PlatformIO uses the custom [`partitions.csv`](partitions.csv) layout:
|
|
|
|
| Partition | Offset | Size | Purpose |
|
|
|---|---:|---:|---|
|
|
| `nvs` | `0x009000` | 512 KiB | Serial, Wi-Fi, role-based users, legacy network credential, HTTPS identity, and SSH host-key data |
|
|
| `otadata` | `0x089000` | 8 KiB | Active OTA-slot selection metadata |
|
|
| `phy_init` | `0x08B000` | 4 KiB | Optional PHY initialization data |
|
|
| `nvs_key` | `0x08C000` | 4 KiB | Reserved for future encrypted-NVS keys |
|
|
| `coredump` | `0x08D000` | 128 KiB | Reserved for flash core dumps |
|
|
| `ota_0` | `0x0B0000` | 4 MiB | Primary application/OTA slot |
|
|
| `ota_1` | `0x4B0000` | 4 MiB | Alternate application/OTA slot |
|
|
| `storage` | `0x8B0000` | 7488 KiB | Reserved for future LittleFS web assets, logs, and files |
|
|
|
|
Application offsets are aligned to the ESP32-S3's required 64 KiB boundary. The final storage partition ends at `0x1000000`, exactly the end of the 16 MiB flash chip.
|
|
|
|
The table reserves OTA and storage space; it does not implement OTA downloads, rollback confirmation, core-dump handling, NVS encryption, or filesystem mounting.
|
|
|
|
### One-time migration from the default partition table
|
|
|
|
The previous 1 MiB factory application began at `0x10000`, which now lies inside the enlarged NVS range. A normal upload does not erase stale data in that range. When first switching to this layout, erase the flash completely:
|
|
|
|
```sh
|
|
pio run --target erase
|
|
pio run --target upload
|
|
pio device monitor -b 115200
|
|
```
|
|
|
|
This removes saved serial configuration and all other flash contents. The firmware recreates NVS with safe defaults. Subsequent ordinary uploads do not need a full erase.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
pio run
|
|
```
|
|
|
|
## Upload and monitor
|
|
|
|
Connect the board's **USB-to-UART** port for firmware upload and the UART0 development console, then run:
|
|
|
|
```sh
|
|
pio run --target upload
|
|
pio device monitor -b 115200
|
|
```
|
|
|
|
The firmware provides an interactive UART0 console at `serial-tool>`. Run `help` for available commands. The USB-to-UART bridge normally appears as `/dev/ttyUSB*`; it is separate from the native USB CDC serial transport, which normally appears as `/dev/ttyACM*`.
|
|
|
|
The console supports session history, line editing, cursor movement, and hierarchical Tab completion. After an unattended boot, attach an ANSI-capable terminal and press Enter once to enable enhanced editing; this avoids blocking while no terminal is attached.
|
|
|
|
Serial configuration and Wi-Fi edits remain in RAM until explicitly saved with `serial save` or `wifi save`. During Phase 8A, retrieve the legacy HTTPS/SSH network credential only from physical UART0 with `web credentials show`; manage the new role-based accounts with the `user` command group.
|
|
|
|
## Security notes
|
|
|
|
The HTTPS interface uses a device-specific self-signed certificate and HTTP Basic authentication over TLS; there is no plaintext HTTP or TCP serial listener. During Phase 8A, HTTPS and SSH continue to use the legacy shared `admin` credential while role-aware password/public-key authentication remains scheduled for Phase 8B. New user passwords are stored as salted PBKDF2-HMAC-SHA256 verifiers, but the legacy network password, HTTPS private key, SSH private key, and Wi-Fi credentials remain recoverable from unencrypted application-owned NVS blobs. Offline password guessing and stale append-oriented flash copies also remain possible. The reserved `nvs_key` partition does not enable encryption. Do not treat this firmware as resistant to physical flash or RAM extraction until the planned hardening work is complete.
|
|
|
|
## 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 `wolfssl/wolfssl` `5.8.2~1` and `wolfssl/wolfssh` `1.4.20`; review upstream security releases before production use.
|