Add GPL-3.0 license and document hardware wiring

2026-08-21 13:02:18 +02:00
parent 9fe4ac75fd
commit 146dfe51a7
3 changed files with 775 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Hardware wiring
+
+This document records hardware-specific pin assignments. Keeping each assignment tied to a named board combination allows additional wiring profiles to be added later without treating one GPIO map as universal.
+
+## Profile: ESP32-S3-DevKitC-1 N16R8 with Adafruit MAX3243
+
+This initial profile is for:
+
+- An ESP32-S3-DevKitC-1-compatible development board with an ESP32-S3-WROOM-1-N16R8 module, 16 MB flash, 8 MB octal PSRAM, two USB-C ports, and its onboard RGB LED on GPIO48.
+- The [Adafruit RS-232 Full Pinout Level-Shifter Breakout, product 5988](https://www.adafruit.com/product/5988), using a MAX3243 and a DE-9 female connector.
+
+The Adafruit board 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/connect-state 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 the development board when wiring a compatible clone; its physical header numbering may differ from the official DevKitC-1 documentation.
+
+### Wiring diagram
+
+The 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 pins
+
+UART1 is used for the external RS-232 data path. GPIO17 and GPIO18 are the ESP32-S3's conventional `U1TXD` and `U1RXD` pins. GPIO15 and GPIO16 are physically adjacent to them on header J1 and are routed to UART1 RTS and CTS through the ESP32-S3 GPIO matrix.
+
+The GPIO matrix means GPIO15 and GPIO16 can serve UART1 even though their fixed-function labels mention UART0 RTS and CTS. UART0 logging remains on GPIO43 and GPIO44 through the board's USB-to-UART bridge. GPIO19 and GPIO20 remain free for future native USB CDC-ACM support.
+
+RTS/CTS flow control will be configurable. When enabled, the UART peripheral can handle it in hardware so backpressure does not depend on application-task scheduling. When disabled, firmware must place the output signals in compatible idle states.
+
+### Modem-control signals
+
+GPIO4 through GPIO7 form a compact group for the remaining modem-control lines:
+
+- GPIO4 reads `DCD`.
+- GPIO5 reads `DSR`.
+- GPIO6 reads `RI`.
+- GPIO7 drives `DTR`.
+
+DCD, DSR, and RI are ordinary GPIO inputs rather than hardware-managed UART signals. Firmware will monitor them and make their state available to the serial session broker and user interfaces. DTR is a software-controlled GPIO output.
+
+`VLD` on GPIO8 reports whether the MAX3243 detects a valid RS-232 voltage on at least one receiver. It is a useful connection hint but does not prove that the cable, signal direction, or serial parameters are correct.
+
+The breakout's `OFF` pin is connected to the MAX3243 active-low `!FORCEOFF` input. High or unconnected keeps the transceiver enabled; low forces shutdown. Its onboard pull-up makes it safe to leave unconnected during initial testing. If firmware uses GPIO9 later, it should preferably configure it as an open-drain output that is released to enable the transceiver and driven low to disable it.
+
+### Power and cable notes
+
+- Connect breakout `Vin` to `3V3`, not `5V`. ESP32-S3 GPIOs are not 5 V tolerant.
+- The MAX3243 generates the positive and negative RS-232 voltages required 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 electrically DTE-style: `TX`, `RTS`, and `DTR` drive the DE-9, while `RX`, `CTS`, `DSR`, `DCD`, and `RI` receive from it.
+- A straight-through male-to-male gender changer changes connector gender only. Use a straight-through cable for a DCE peer and an appropriate null-modem cable for another DTE peer.
+
+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 instead of counting header positions.
+
+## Future hardware profiles
+
+Alternative boards—such as the LILYGO T-Display-S3—or different RS-232 transceivers will receive separate profiles here. GPIO assignments must be reviewed for each board's display, buttons, USB connection, flash/PSRAM wiring, boot-strapping pins, and onboard peripherals.