Skip to content

[SYS] Never block on native USB CDC serial logging - #2428

Merged
1technophile merged 2 commits into
1technophile:developmentfrom
MatthieuGrr:fix/hwcdc-nonblocking-serial
Nov 18, 2026
Merged

1technophile merged 2 commits into
1technophile:developmentfrom
MatthieuGrr:fix/hwcdc-nonblocking-serial

Conversation

@MatthieuGrr

@MatthieuGrr MatthieuGrr commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Description:

Fixes #2425.

On boards where Serial is the native USB CDC (HWCDC, ARDUINO_USB_CDC_ON_BOOT=1), once a host has opened the port, HWCDC::write() retries up to 20 × tx_timeout_ms when the TX ring is full and nobody reads it. A single log call can then stall the loop for about 2 s, which starves the MQTT keepalive: the gateway drops off the broker and the WebUI while still answering ping.

Following the suggestions in #2425, this PR:

  • enlarges the TX ring before Serial.begin() with SERIAL_TX_BUFFER_SIZE (default 1024), so bursts such as the boot log are not truncated when a monitor is reading;
  • sets the TX timeout to SERIAL_TX_TIMEOUT_MS (default 0) after begin(), so log output is dropped instead of blocking when nobody reads the port.

Both are on by default and can be overridden per environment. They only apply when ARDUINO_USB_MODE && ARDUINO_USB_CDC_ON_BOOT; UART builds are unchanged.

Affected shipped envs: lilygo-t3-s3-rtl_433, lilygo-t3-s3-rtl_433-fsk, esp32c3_lolin_mini_with_serial. Re-enabling logs on esp32c3_lolin_mini is left for a follow-up PR.

Testing

  • Builds: lilygo-t3-s3-rtl_433, esp32c3_lolin_mini_with_serial.
  • Soak on an ESP32-S3 + CC1101 (rtl_433) over native USB, plugged into a Linux host that had already opened the port, with nothing reading it: no LWT offline and no reboot over 3 h (SYStoMQTT uptime increasing steadily, RSSI and free heap stable). With the previous firmware, the same setup dropped off MQTT about 2 min after each boot.

Checklist:

  • The pull request is done against the latest development branch
  • Only one feature/fix was added per PR and the code change compiles without warnings
  • I accept the DCO.

On boards where Serial is HWCDC (ARDUINO_USB_CDC_ON_BOOT=1), once a host
has opened the port, HWCDC::write() retries up to 20 x tx_timeout_ms when
the TX ring is full and nobody reads it. Each log call can then stall the
loop for about 2 s, starving the MQTT keepalive: the gateway drops off the
broker and the WebUI while still answering ping.

Enlarge the TX ring before begin() (SERIAL_TX_BUFFER_SIZE, 2048 by default)
and set a 0 TX timeout (SERIAL_TX_TIMEOUT_MS) so log output is dropped
instead of blocking. Both macros can be overridden per environment.

Affects lilygo-t3-s3-rtl_433(-fsk) and esp32c3_lolin_mini_with_serial.

Fixes 1technophile#2425

Signed-off-by: Matthieu <93468141+MatthieuGrr@users.noreply.github.com>

@1technophile 1technophile left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this looks good. It implements both suggestions from #2425, and the soak result (port already opened once by the host, then left unread) covers exactly the condition that triggers the blocking.

Checked against arduino-esp32 3.3.x HWCDC.cpp:

  • Ordering is correct. begin() only creates the default 256-byte TX ring when none exists, so setTxBufferSize() before begin() takes effect.
  • No busy-wait. With a 0 timeout, xRingbufferSend() fails immediately, so the 20-retry loop in write() finishes in microseconds.
  • Core and ESP-IDF logs are covered too. log_e() / ets_printf go through the same tx_timeout_ms, so they stop blocking as well.
  • The guard is safe. On ESP8266 and UART builds the macros evaluate to 0 and nothing changes.

A few non-blocking notes:

  1. Serial.flush() discards the buffer with a 0 timeout. In HWCDC::flush(), tries starts at tx_timeout_ms (0), so the wait loop is skipped and it falls straight into connected = false; flushTXBuffer(NULL, 0). Any flush() would drop up to 2 KB of pending log, even with a monitor reading. Nothing calls it on these targets today (the only Serial.flush() in main/ is in gatewaySRFB.cpp, ESP8266-only), but a short comment next to setTxTimeoutMs() would save someone from adding a flush before a restart and wondering where the logs went.
  2. Concurrent writers can drop lines with a monitor attached. tx_lock is also taken with the 0 timeout, so a line from one task is lost while another task (BT, rtl_433) holds the lock. This is consistent with "drop instead of block" and fine as is.
  3. Nit: RAM cost. 2048 bytes of heap is fine on the T3-S3, but C3 BLE builds are tight. 1024 would probably still cover the boot burst. Your call.
  4. Scope: the TinyUSB path (ARDUINO_USB_MODE=0 with CDC on boot) isn't covered, but no shipped env uses it, so it's fine to leave out.

Agree with leaving the esp32c3_lolin_mini logging re-enable for a follow-up.

@MatthieuGrr

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough review!

Pushed 959db75:

  1. Added a comment next to setTxTimeoutMs() explaining that HWCDC::flush() discards the pending TX ring with a 0 timeout, so nobody relies on it before a restart.
  2. Agreed, dropping lines under contention is consistent with "drop instead of block"; left as is.
  3. Lowered the default SERIAL_TX_BUFFER_SIZE to 1024 to spare RAM on the C3 BLE builds. It stays overridable per env if a board wants more.
  4. Agreed, TinyUSB CDC left out since no shipped env uses it.

The esp32c3_lolin_mini logging re-enable will come as a separate PR.

@1technophile 1technophile left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested on hardware: ESP32-S3-DevKitC-1 cabled by its native USB port, env based on esp32s3-dev-c1-ble with -DARDUINO_USB_CDC_ON_BOOT=1 added and SYStoMQTT every 10 s.

Procedure, identical for both builds: reset the board over USB, read the port for 30 s (the "host has opened the port once" condition), close it, then leave it unread while watching LWT / SYStoMQTT and pinging the board once a minute.

Control: development @ 1b28de9 This PR @ 88595c3
Boot log while the port was read 245 lines, 42.4 KB 255 lines, 46.7 KB (not truncated)
After the port was closed loop stalled: uptime advanced 10 s over 88 s of wall time SYStoMQTT steady every 10 s (361 messages, max gap 10.3 s)
MQTT LWT offline ~3 min after boot, no recovery within the next 5 min online for the full 60 min (uptime 8 → 3610 s)
Ping answering throughout 60/60
Free heap – stable, 98.6–113 KB (min 82.7 KB)

The control reproduces #2425 exactly (pings, but gone from MQTT); with this PR the gateway stays up.

The soak ran on 88595c3 (2048-byte ring). 959db75 only lowers the ring to 1024 and adds the flush() comment, so the non-blocking behaviour is unchanged; only boot-log completeness with a monitor attached could differ slightly. Thanks for the quick follow-up.

@1technophile
1technophile merged commit 9b09fcd into 1technophile:development Nov 18, 2026
90 checks passed
@MatthieuGrr
MatthieuGrr deleted the fix/hwcdc-nonblocking-serial branch November 18, 2026 14:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ESP32-S3/C3 native USB CDC: gateway drops off MQTT when USB is connected to a host but the serial port is not read

2 participants