# ESP32 Serial Swiss Army Knife ![ESP32 Serial Swiss Army Knife logo](/images/logo.png "ESP32 Serial Swiss Army Knife") Universal wireless serial adaptor firmware for the ESP32-S3. ## 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 RS-232 breakout, product 5988 The firmware has completed **Phase 0 hardware characterization** and the **Phase 1 serial-core foundation**. **Phase 2** adds a transport-neutral serial-session broker with one active writer, multiple observers, bounded per-client queues, event delivery, and slow-client isolation. The MAX3243 diagnostics and persistent serial configuration remain available. Neither the UART service nor an electrical test starts automatically at boot. ## Hardware wiring See [`wiring.md`](wiring.md) for the hardware profile, GPIO assignments, loopback diagrams, safety notes, and the recommended test sequence. The initial profile covers the ESP32-S3-DevKitC-1 N16R8 and the Adafruit MAX3243 full-pinout RS-232 breakout. ## 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 configuration and future Wi-Fi/provisioning 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 | Future LittleFS web assets, certificates, 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 partition table reserves OTA and LittleFS space but does not by itself implement OTA downloads, rollback confirmation, core-dump handling, NVS encryption, or filesystem mounting. Those features will be enabled deliberately in later phases. ### One-time migration from the default partition table The previous 1 MiB factory application began at `0x10000`, which is now inside the enlarged NVS address range. A normal upload does not erase all stale bytes there. Perform a full flash erase once when first switching to this layout: ```sh pio run --target erase pio run --target upload pio device monitor -b 115200 ``` This erases the currently saved serial configuration and all other flash contents. The firmware will boot with safe serial defaults and recreate NVS. Subsequent ordinary uploads do not require another full erase. PlatformIO's application-size report should now use the 4 MiB `ota_0` slot instead of the previous 1 MiB factory partition. ## Build ```sh pio run ``` ## Upload and monitor Connect the board's USB-to-UART port, then run: ```sh pio run --target upload pio device monitor -b 115200 ``` The firmware starts an interactive console on UART0 with the prompt `serial-tool>`. Type `help` to display command descriptions. ### Phase 1 serial service The `serial` command manages the working configuration and UART1 service: ```text serial status serial start serial stop serial set serial save serial load serial defaults serial reset serial counters serial clear-counters ``` Safe defaults are 115200 baud, 8 data bits, no parity, one stop bit, no flow control, and inactive DTR. Supported configuration values are: | Parameter | Values | |---|---| | `baud` | 110–1000000 | | `data-bits` | `7`, `8` | | `parity` | `none`, `even`, `odd` | | `stop-bits` | `1`, `2` | | `flow` | `none`, `rts-cts` | | `dtr` | `inactive`, `active`, `on-connect` | | `rts-threshold` | 1–127 bytes | `serial set` changes the working configuration and safely restarts UART1 if the service is running. It does not write flash; use `serial save` to commit the current configuration to NVS. `serial defaults` changes RAM only, while `serial reset` applies and persists defaults. The firmware never erases the shared NVS partition automatically when storage is incompatible or unavailable. The service uses independent software RX and TX streams. Calls into those streams are nonblocking, and a deasserted CTS cannot block service shutdown. UART data access is intentionally reserved for the session broker; the `serial` command controls configuration and lifecycle only. UART1 has exclusive ownership while the service runs. Phase 0 commands will refuse to touch the port until `serial stop` releases it. ### Phase 2 session broker The broker is initialized at boot and continuously drains the serial service whenever UART1 is running. It is transport-neutral: current console clients use the same API that native USB CDC, WebSocket, and SSH transports will use later. ```text broker status broker clients broker counters broker clear-counters broker connect broker disconnect broker request-writer broker release-writer broker force-writer broker send-hex broker read [maximum-bytes] broker events ``` Each connection receives a generation-safe numeric ID. Stale IDs from disconnected clients cannot address a newly reused slot. Up to eight clients may connect, each with a bounded 4096-byte output queue and a 16-entry event queue. UART RX is copied to every connected client. A full observer queue drops bytes only for that observer and records the loss; it never blocks UART reception or another client. With no clients, the broker still drains UART data and records it as unobserved. Exactly one client may hold the writer lease. Competing requests are denied and generate events. Administrative forced reassignment atomically revokes the old writer and grants the new one. Bytes already accepted before revocation remain queued for transmission; revocation prevents future admission rather than purging the UART TX stream. Connect, disconnect, writer grant, release, revoke, and denial events have a broker-global sequence number. Event queues are intentionally bounded, so future transports should reconcile sequence gaps against broker snapshots. The first and last broker connection also drive the Phase 1 `DTR=on-connect` policy. ### Phase 0 diagnostics The retained hardware-characterization commands are: ```text status transceiver drivers loopback-a loopback-b valid-test uart-loopback [8N1|8E1|8O1|8N2|7E1|7O1] [bytes] uart-suite cts-flow-test rts-flow-test ``` `uart-loopback` defaults to `8N1` and 256 bytes. Its accepted payload range is 1–512 bytes. `uart-suite` covers 300 through 250000 baud and all supported frame formats. `cts-flow-test` verifies transmit gating and exact resumption, while `rts-flow-test` uses UART2 as an internal traffic generator to verify automatic receive backpressure. Follow the command-specific loopback wiring in [`wiring.md`](wiring.md) before invoking any test. A mutex-protected port lease prevents diagnostics, UART1 service startup, and future clients from reconfiguring the same GPIOs concurrently. If a UART driver cannot be removed during cleanup, the firmware keeps the MAX3243 shut down and marks the port faulted until reboot rather than exposing an ambiguous hardware state. The onboard RGB LED reports the most recent test-harness state: | Color | Meaning | |---|---| | Blue | Idle; waiting for a command | | Yellow/orange | Test running | | Green | Last test passed | | Red | Last test failed | This hardware profile uses the onboard RGB LED on GPIO48. Official ESP32-S3-DevKitC-1 v1.1 boards commonly use GPIO38 instead, and compatible boards or clones may vary. A different board revision requires an adjusted board pin profile before running this firmware. ## License This project is licensed under the [GNU General Public License version 3 only](LICENSE) (`GPL-3.0-only`). This is compatible with using the GPLv3 releases of wolfSSL and wolfSSH later. Third-party components remain subject to their respective licenses.