5.5 KiB
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
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 for phase status and validation details.
Documentation
- Hardware wiring: hardware profile, GPIO assignments, connector guidance, and safety notes.
- Electrical tests: MAX3243, UART loopback, and session-broker verification procedures.
- Command reference: 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 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:
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
pio run
Upload and monitor
Connect the board's USB-to-UART port for firmware upload and the UART0 development console, then run:
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 (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.