docs/esp8266,esp32: Correct description of esp.osdebug().

projectgus · projectgus · commit a6154effafd7 · 2023-11-07T14:29:36.000+11:00
The behaviour described in the docs was not correct for either port.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton &lt;angus@redyak.com.au&gt;
diff --git a/docs/library/esp.rst b/docs/library/esp.rst
@@ -62,12 +62,18 @@ Functions
 
 .. function:: flash_erase(sector_no)
 
-.. function:: osdebug(level)
+.. function:: osdebug(uart_no, [level])
 
-    Turn esp os debugging messages on or off.
+    Change the level of OS serial debug log messages.
 
-    The *level* parameter sets the threshold for the log messages for all esp components.
-    The log levels are defined as constants:
+    On ESP8266, this output is initially disabled. On ESP32, it is initially
+    enabled for Error output only.
+
+    ``uart_no`` is the number of the UART peripheral which should receive
+    OS-level output. On ESP32, this parameter must be set to ``0``.
+
+    The optional *level* parameter is only supported on ESP32. It sets the threshold
+    for the log messages for ESP-IDF components. The log levels are defined as constants:
 
         * ``LOG_NONE`` -- No log output
         * ``LOG_ERROR`` -- Critical errors, software module can not recover on its own
@@ -77,6 +83,15 @@ Functions
         * ``LOG_VERBOSE`` -- Bigger chunks of debugging information, or frequent messages
           which can potentially flood the output
 
+    .. note:: ``LOG_DEBUG`` and ``LOG_VERBOSE`` are not compiled into the
+              MicroPython binary by default, to save size. A custom build with a
+              modified "``sdkconfig``" source file is needed to see any output
+              at these log levels.
+
+    .. note:: Log output on ESP32 is automatically suspended in "Raw REPL" mode,
+              to prevent communications issues. This means OS level logging is not
+              seen when using ``mpremote run`` and similar tools.
+
 .. function:: set_native_code_location(start, length)
 
     **Note**: ESP8266 only
