ESP32_Serial_Swiss_Army_Knife/docs/wiring.md

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

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

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. Power down before attaching or removing loose OLED wiring. Only perform live-removal fault tests with a connector designed to avoid shorts and unintended pin sequencing.

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 for Phase 7 OLED/button bring-up, persistent aging settings, optional-display and stuck-button fault recovery, safe loopback wiring, polarity checks, UART flow-control verification, and session-broker/concurrent-transport 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.