141 lines
9.4 KiB
Markdown
141 lines
9.4 KiB
Markdown
# Hardware wiring
|
||
|
||
This document records the GPIO assignments for the initial hardware profile. Additional profiles should use separate sections rather than treating this GPIO map as universal.
|
||
|
||
## Profile: ESP32-S3-DevKitC-1 N16R8 with Adafruit MAX3243
|
||
|
||
This profile supports:
|
||
|
||
- An ESP32-S3-DevKitC-1-compatible board with an ESP32-S3-WROOM-1-N16R8 module, 16 MB flash, 8 MB octal PSRAM, two USB-C ports, and an onboard RGB LED on GPIO48.
|
||
- The [Adafruit RS-232 Full Pinout Level-Shifter Breakout](https://www.adafruit.com/product/5988), which uses a MAX3243 and has a DE-9 connector.
|
||
|
||
Both the male and female Adafruit breakout versions can be used. Prefer the male breakout because it is the cleaner arrangement for the intended cable topology. A female breakout usually needs a gender changer; use a straight-through changer only to change connector gender, not to cross signals.
|
||
|
||
The breakout provides three logic-to-RS-232 drivers (`TX`, `RTS`, and `DTR`), five RS-232-to-logic receivers (`RX`, `CTS`, `DSR`, `DCD`, and `RI`), valid-signal detection, and shutdown control. It is a level shifter, not a galvanic isolator.
|
||
|
||
### Wiring table
|
||
|
||
| Adafruit breakout pin | Direction at ESP32 | ESP32-S3 connection | DevKit header | Purpose |
|
||
|---|---:|---:|---:|---|
|
||
| `Vin` | Power | `3V3` | J1-1 or J1-2 | Power the MAX3243 with 3.3 V logic levels |
|
||
| `GND` | Power | `GND` | J1-22 | Common logic and RS-232 signal ground |
|
||
| `TX` | ESP32 → breakout | GPIO17 | J1-10 | UART1 transmit |
|
||
| `RX` | Breakout → ESP32 | GPIO18 | J1-11 | UART1 receive |
|
||
| `RTS` | ESP32 → breakout | GPIO15 | J1-8 | UART1 hardware receive-flow-control output |
|
||
| `CTS` | Breakout → ESP32 | GPIO16 | J1-9 | UART1 hardware transmit-flow-control input |
|
||
| `DTR` | ESP32 → breakout | GPIO7 | J1-7 | Software-controlled data-terminal-ready output |
|
||
| `DSR` | Breakout → ESP32 | GPIO5 | J1-5 | Data-set-ready input |
|
||
| `DCD` | Breakout → ESP32 | GPIO4 | J1-4 | Carrier-detect input |
|
||
| `RI` | Breakout → ESP32 | GPIO6 | J1-6 | Ring-indicator input |
|
||
| `VLD` | Breakout → ESP32 | GPIO8 | J1-12 | Valid RS-232 voltage indication |
|
||
| `OFF` | ESP32 → breakout | GPIO9 | J1-15 | Optional active-low transceiver shutdown |
|
||
|
||
Use the GPIO labels printed on a compatible development board; physical header numbering may differ from the official DevKitC-1 documentation.
|
||
|
||
### Wiring diagram
|
||
|
||
Arrows show signal direction at the breakout's 3.3 V logic header.
|
||
|
||
```text
|
||
ESP32-S3-DevKitC-1 N16R8 Adafruit MAX3243 breakout
|
||
──────────────────────── ──────────────────────────
|
||
3V3 ────────────> Vin
|
||
GND ────────────> GND
|
||
|
||
GPIO17 / U1TXD ────────────> TX
|
||
GPIO18 / U1RXD <──────────── RX
|
||
|
||
GPIO15 / U1RTS ────────────> RTS
|
||
GPIO16 / U1CTS <──────────── CTS
|
||
|
||
GPIO7 ────────────> DTR
|
||
GPIO5 <──────────── DSR
|
||
GPIO4 <──────────── DCD
|
||
GPIO6 <──────────── RI
|
||
|
||
GPIO8 <──────────── VLD
|
||
GPIO9 ────────────> OFF
|
||
```
|
||
|
||
### UART and flow control
|
||
|
||
UART1 is the external RS-232 data path. GPIO17 and GPIO18 are the ESP32-S3's conventional `U1TXD` and `U1RXD` pins. GPIO15 and GPIO16 are routed to UART1 RTS and CTS through the GPIO matrix, so their fixed-function labels do not constrain this use.
|
||
|
||
UART0 logging remains on GPIO43 and GPIO44 through the board's USB-to-UART bridge. GPIO19 and GPIO20 are reserved for native USB CDC-ACM. When RTS/CTS flow control is enabled, the UART peripheral handles it in hardware; when disabled, firmware places the signals in compatible idle states.
|
||
|
||
### Modem-control signals
|
||
|
||
GPIO4 through GPIO7 provide modem-control lines:
|
||
|
||
- GPIO4 reads `DCD`.
|
||
- GPIO5 reads `DSR`.
|
||
- GPIO6 reads `RI`.
|
||
- GPIO7 drives `DTR`.
|
||
|
||
`DCD`, `DSR`, and `RI` are GPIO inputs monitored by the firmware. `DTR` is a software-controlled GPIO output. `VLD` on GPIO8 indicates that the MAX3243 sees a valid RS-232 voltage on at least one receiver; it is a connection hint, not proof of correct cabling or serial settings.
|
||
|
||
The breakout's `OFF` pin drives the MAX3243 active-low `!FORCEOFF` input. High or unconnected enables the transceiver; low forces shutdown. Its onboard pull-up makes it safe to leave unconnected during initial testing. If controlled by firmware, GPIO9 should be open-drain: released to enable and driven low to disable.
|
||
|
||
### Power and cable notes
|
||
|
||
- Connect breakout `Vin` to `3V3`, never `5V`; ESP32-S3 GPIOs are not 5 V tolerant.
|
||
- The MAX3243 generates the positive and negative RS-232 voltages on the DE-9 side.
|
||
- The breakout is not isolated: ESP32 ground, breakout ground, USB ground, and DE-9 pin 5 are electrically connected.
|
||
- The breakout is DTE-style: `TX`, `RTS`, and `DTR` drive the DE-9; `RX`, `CTS`, `DSR`, `DCD`, and `RI` receive from it.
|
||
- Use a straight-through cable for a DCE peer and a suitable null-modem cable for another DTE peer.
|
||
- A female breakout can be used with a male-to-male straight-through gender changer. The changer changes physical gender only; it does not replace a null-modem cable where signal crossing is required.
|
||
|
||
GPIO8 and GPIO9 are not adjacent on the official J1 header. GPIO3 and GPIO46 lie between them and are boot-strapping pins, so follow the printed GPIO labels rather than counting header positions.
|
||
|
||
### Development and native USB connectors
|
||
|
||
| DevKit connector | ESP32-S3 path | Typical Linux device | Purpose |
|
||
|---|---|---|---|
|
||
| `USB-to-UART` | UART0 on GPIO43/44 through the bridge chip | `/dev/ttyUSB*` | Firmware upload, logs, and `serial-tool>` console |
|
||
| `USB` | Native USB OTG, GPIO19 `D-` and GPIO20 `D+` | `/dev/ttyACM*` | CDC-ACM client connected to the session broker |
|
||
|
||
GPIO19 and GPIO20 must not be assigned to the MAX3243 or other peripherals while USB CDC is enabled. Both connectors may be attached during testing, but compatible clones can differ in connector labels and power-path design; consult the board schematic to avoid back-powering.
|
||
|
||
The USB-to-UART bridge's DTR/RTS controls serve automatic boot/reset and do not reveal whether a terminal is open. After an unattended boot, press Enter once in an ANSI-capable terminal to enable enhanced console editing.
|
||
|
||
Native USB CDC DTR controls the lifetime of the `usb-cdc` broker client but is not forwarded to physical DE-9 DTR. Physical DTR follows the `serial` configuration. CDC RTS is status information only; GPIO15/DE-9 RTS remains UART1 receive flow control when `flow=rts-cts` is enabled.
|
||
|
||
## Phase 7A OLED and button wiring
|
||
|
||
Phase 7A hardware validation used the following connections for the 128×64 I²C OLED and three local buttons. The selected module acknowledges at 7-bit I²C address `0x3c` (8-bit `0x78` write / `0x79` read) and has separate yellow rows 0–15 and blue rows 16–63, divided by a narrow physical black separator:
|
||
|
||
| Device connection | ESP32-S3 connection | Electrical behavior | Purpose |
|
||
|---|---:|---|---|
|
||
| OLED `VCC` | `3V3` | 3.3 V power only | OLED power and I²C pull-up rail |
|
||
| OLED `GND` | `GND` | Common ground | OLED return and I²C reference |
|
||
| OLED `SDA` | GPIO11 | I²C data | Display data |
|
||
| OLED `SCL` | GPIO12 | I²C clock | Display clock |
|
||
| Previous/back button | GPIO10 to `GND` | Active-low input with internal pull-up | Previous item or back |
|
||
| Select/confirm button | GPIO13 to `GND` | Active-low input with internal pull-up | Select or confirm |
|
||
| Next button | GPIO14 to `GND` | Active-low input with internal pull-up | Next item |
|
||
|
||
```text
|
||
ESP32-S3-DevKitC-1 N16R8 128×64 I²C OLED
|
||
──────────────────────── ────────────────
|
||
3V3 ────────────> VCC
|
||
GND ────────────> GND
|
||
GPIO11 / SDA <───────────> SDA
|
||
GPIO12 / SCL ────────────> SCL
|
||
|
||
GPIO10 ───── previous/back button ───── GND
|
||
GPIO13 ───── select/confirm button ──── GND
|
||
GPIO14 ───── next button ────────────── GND
|
||
```
|
||
|
||
> **OLED voltage warning:** Power OLED `VCC` from `3V3`, not 5 V. Many OLED modules connect their SDA/SCL pull-up resistors directly to `VCC`; powering such a module from 5 V could expose the ESP32-S3 GPIOs to unsafe I²C levels.
|
||
|
||
Before applying power, verify whether the module already includes SDA and SCL pull-ups and where they terminate. Any module-mounted or external I²C pull-ups must go to 3.3 V. If pull-ups are absent, add suitable external pull-ups from SDA and SCL to `3V3`; if they are present, account for their parallel resistance before adding more. The buttons normally need no external pull-ups because firmware enables the ESP32 internal pull-ups.
|
||
|
||
## Electrical verification
|
||
|
||
See [Electrical tests](electrical_tests.md) for Phase 7A OLED/button bring-up, safe loopback wiring, polarity checks, UART flow-control verification, and session-broker loopback testing.
|
||
|
||
## Future hardware profiles
|
||
|
||
Alternative boards—such as the LILYGO T-Display-S3—or different RS-232 transceivers require separate profiles. Review display, buttons, USB, flash/PSRAM wiring, boot-strapping pins, and onboard peripherals before assigning GPIOs.
|