From 3579f52c1baea2e742f4cabbb8ce0d39d958f6e8 Mon Sep 17 00:00:00 2001 From: Jade Mattsson Date: Tue, 29 Oct 2024 12:21:12 +1100 Subject: [PATCH] Updated console module doc with CDC-ACM info. --- docs/modules/console.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/modules/console.md b/docs/modules/console.md index a53f02802..332142c5e 100644 --- a/docs/modules/console.md +++ b/docs/modules/console.md @@ -16,6 +16,15 @@ There is a helper script (`scripts/upload-file.py`) which can be used to easily upload files to NodeMCU via this module. The script may also be used as inspiration for integrating such functionality into IDEs. +If using a SoC with USB CDC-ACM as the console, consider increasing the receive +buffer from the default. This type of console is quite prone to overflows, and +increasing the receive buffer helps mitigate (but not completely resolve) that. +Look for `Component config -> ESP system settings -> Size of USB CDC RX buffer` +in the menuconfig (`ESP_CONSOLE_USB_CDC_RX_BUF_SIZE` in sdkconfig). Increasing +this value from the default 64 to 512 makes it match what is typically used +for a UART console. Some utilities and IDEs may have their own minimum +requirements for the receive buffer. + ## console.on() Used to register or deregister a callback function to handle console events. @@ -97,10 +106,14 @@ it reach the Lua interpreter. -- The chunk_cb gets called incrementally with partial stream data which is -- effectively unescaped. When the end of frame is encountered, the done_cb -- gets invoked. -function transmission_receiver(chunk_cb, done_cb) +-- To avoid overruns on slower consoles (e.g. CDC-ACM) each block gets +-- acknowledged by printing another prompt. This allows the sender to easily +-- throttle the upload to a maintainable pace. +function transmission_receiver(chunk_cb, done_cb, blocksize) local inframe = false local escaped = false local done = false + local len = 0 local STX = 2 local ETX = 3 local DLE = 16 @@ -110,6 +123,11 @@ function transmission_receiver(chunk_cb, done_cb) end return function(data) if done then return end + len = len + #data + while len >= blocksize do + len = len - blocksize + console.write("> ") + end local from local to for i = 1, #data @@ -160,8 +178,8 @@ function resume_interactive() end -- The 0 may be adjusted upwards for improved efficiency, but be mindful to --- always send enough data to reach the ETX marker. -console.on("data", 0, transmission_receiver(print_hex, resume_interactive)) +-- always send enough data to reach the ETX marker if so. +console.on("data", 0, transmission_receiver(print_hex, resume_interactive, 64)) console.mode(console.NONINTERACTIVE) ```