feat(uart): improve example documentation#12745
Conversation
SuGlider
added
the
Type: Documentation
SuGlider
added
Type: Example
There was a problem hiding this comment.
Merge request must include a release note, or it needs to be processed first.
Details
👋 Hello SuGlider, we appreciate your contribution to this project! 📘 Please review the project's Contributions Guide for key guidelines on code, documentation, testing, and more. 🖊️ Please also make sure you have read and signed the Contributor License Agreement for this project. Click to see more instructions ...
Review and merge process you can expect ...
|
There was a problem hiding this comment.
Pull request overview
This PR improves end-user documentation for several ESP32 Serial examples, clarifying wiring/hardware requirements and refining usage instructions for baud-rate detection, IrDA mode, RS485 mode, and internal loopback/flow control behavior.
Changes:
- Add a new README for the
RS485_Echo_Demoexample with pin requirements, wiring notes, and usage steps. - Update IrDA example READMEs to better describe hardware constraints and expected output.
- Update flow-control and baud-detect READMEs to clarify internal-loopback behavior and user interaction during baud detection.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| libraries/ESP32/examples/Serial/RS485_Echo_Demo/README.md | New README describing RS485 echo demo wiring/pins/usage. |
| libraries/ESP32/examples/Serial/IrdaMode_TwoBoard_Demo/README.md | Adds IrDA hardware notes and adjusts example output snippet. |
| libraries/ESP32/examples/Serial/IrdaMode_DualUART_Demo/README.md | Adds IrDA hardware note for the single-board dual-UART demo. |
| libraries/ESP32/examples/Serial/HardwareFlowControl_Demo/README.md | Clarifies internal loopback helpers and updates referenced line numbers. |
| libraries/ESP32/examples/Serial/BaudRateDetect_Demo/README.md | Updates baud-detect range/usage instructions and failure behavior description. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | TX | UART transmit to transceiver | | ||
| | RTS | Drives transceiver DE/~RE (direction) | | ||
|
|
||
| **One-wire mode (`enableOneWireMode`) is not compatible with RS485.** Do not use the same GPIO for RX and TX; use an external RS485 transceiver (e.g. MAX485) with distinct TX, RX, and direction control. |
| - **User selects mode** at startup via Serial Monitor (press 'T' or 'R') | ||
| - **Real hardware required**: IR LED on TX board, IR receiver on RX board | ||
|
|
||
| **Note:** IrDA requires **separate** TX and RX GPIO pins on each board. One-wire UART (`enableOneWireMode`) is **not** supported in IrDA mode. |
| - **UART2**: Configured in IrDA RX mode (receiver) | ||
| - **Internal loopback**: UART1 TX pin internally connected to UART2 RX pin via GPIO matrix | ||
|
|
||
| **Note:** IrDA requires **separate** TX and RX GPIO pins (IR LED vs receiver). One-wire UART (`enableOneWireMode`) is **not** supported in IrDA mode. |
| The baud rate detection works over **300 to 230400 baud** (as noted in the sketch). The detected value is rounded to the nearest entry in the core’s internal baud-rate table used by `uartDetectBaudrate()`. | ||
|
|
||
| Examples of baud rates that can be detected include: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400, 256000, 460800, 921600, and others defined by the core. | ||
| Examples of baud rates that can be detected include: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, and 230400. |
| 3. **`uart_internal_loopback(uartNum, rxPin)`** (when `USE_INTERNAL_MATRIX_PIN_LOOPBACK = 1`) | ||
| - Creates internal GPIO matrix connection for TX→RX loopback | ||
| - Creates internal TX→RX loopback (peripheral loopback on native IOMUX RX pins, or GPIO-matrix routing otherwise) | ||
| - No external wires needed |
Description of Change
This pull request updates the documentation for several ESP32 Serial examples to clarify hardware requirements, usage instructions, and correct technical details. It also adds a new README for the RS485 Echo Demo. The main changes focus on improving accuracy, clarifying the use of internal loopback and IrDA/RS485 modes, and updating usage steps.
Documentation improvements and corrections:
BaudRateDetect_Demo/README.mdto specify support for 300 to 230400 baud (previously claimed up to 921600), and revised the list of detectable baud rates accordingly.BaudRateDetect_Demo/README.mdto emphasize the need to send data during the detection window insetup(), clarified fallback behavior, and improved example scenarios.Internal loopback and flow control clarification:
HardwareFlowControl_Demo/README.mdto clarify that internal loopback uses specific helper functions, corrected code line numbers, and improved descriptions of internal connections.IrDA and RS485 hardware requirements:
IrdaMode_DualUART_Demo/README.mdandIrdaMode_TwoBoard_Demo/README.mdthat IrDA mode requires separate TX and RX pins and does not support one-wire UART; also made minor corrections to example output.RS485_Echo_Demowith wiring instructions, hardware requirements, and usage steps, emphasizing that one-wire mode is not compatible with RS485 and that separate TX/RX/RTS pins are required.Test Scenarios
CI Only
Related links
None