# 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 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.