Commander1024
535c27350d
Add versioned NVS-backed configuration, buffered UART1 I/O, modem monitoring, counters, and serial console controls. Coordinate UART1 ownership with Phase 0 diagnostics and document loopback verification.
110 lines
4.6 KiB
Markdown
110 lines
4.6 KiB
Markdown
# 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 now includes the **Phase 1 serial-core foundation**. The MAX3243 diagnostics remain available, alongside a versioned NVS-backed serial configuration and a buffered UART1 service with modem-state monitoring and error counters. 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.
|
||
|
||
## 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 <baud|data-bits|parity|stop-bits|flow|dtr|rts-threshold> <value>
|
||
serial save
|
||
serial load
|
||
serial defaults
|
||
serial reset
|
||
serial counters
|
||
serial clear-counters
|
||
serial send-hex <hex-bytes>
|
||
serial read [maximum-bytes]
|
||
```
|
||
|
||
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. `serial send-hex` and `serial read` are temporary binary-safe console clients for validation before the session broker and USB/network clients are added.
|
||
|
||
UART1 has exclusive ownership while the service runs. Phase 0 commands will refuse to touch the port until `serial stop` releases it.
|
||
|
||
### Phase 0 diagnostics
|
||
|
||
The retained hardware-characterization commands are:
|
||
|
||
```text
|
||
status
|
||
transceiver <enable|disable>
|
||
drivers <tx 0|1> <dtr 0|1> <rts 0|1>
|
||
loopback-a
|
||
loopback-b
|
||
valid-test
|
||
uart-loopback <baud> [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.
|