From a800ed5ae34f8a9bbe075e007de55109f33c7592 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@redyak.com.au>
Date: Tue, 7 Nov 2023 14:11:20 +1100
Subject: [PATCH] docs/library/esp: Correct the description of esp.osdebug().

The behaviour described in the docs was not correct for either port.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>
---
 docs/library/esp.rst | 40 ++++++++++++++++++++++++++++++++++++----
 ports/esp32/modesp.c |  4 ++--
 2 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/docs/library/esp.rst b/docs/library/esp.rst
index 8920c8241e..9c20b5e8b2 100644
--- a/docs/library/esp.rst
+++ b/docs/library/esp.rst
@@ -62,12 +62,35 @@ Functions
 
 .. function:: flash_erase(sector_no)
 
-.. function:: osdebug(level)
+.. function:: osdebug(uart_no)
 
-    Turn esp os debugging messages on or off.
+    .. note:: This is the ESP8266 form of this function.
 
-    The *level* parameter sets the threshold for the log messages for all esp components.
-    The log levels are defined as constants:
+    Change the level of OS serial debug log messages. On boot,
+    OS serial debug log messages are disabled.
+
+    ``uart_no`` is the number of the UART peripheral which should receive
+    OS-level output, or ``None`` to disable OS serial debug log messages.
+
+.. function:: osdebug(uart_no, [level])
+    :no-index:
+
+    .. note:: This is the ESP32 form of this function.
+
+    Change the level of OS serial debug log messages. On boot, OS
+    serial debug log messages are limited to Error output only.
+
+    The behaviour of this function depends on the arguments passed to it. The
+    following combinations are supported:
+
+    ``osdebug(None)`` restores the default OS debug log message level
+    (``LOG_ERROR``).
+
+    ``osdebug(0)`` enables all available OS debug log messages (in the
+    default build configuration this is ``LOG_INFO``).
+
+    ``osdebug(0, level)`` sets the OS debug log message level to the
+     specified value. 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 +100,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 never
+              seen when using ``mpremote run`` and similar tools.
+
 .. function:: set_native_code_location(start, length)
 
     **Note**: ESP8266 only
diff --git a/ports/esp32/modesp.c b/ports/esp32/modesp.c
index 4726ce5874..f51ba6ab34 100644
--- a/ports/esp32/modesp.c
+++ b/ports/esp32/modesp.c
@@ -37,12 +37,12 @@
 #include "py/mphal.h"
 
 STATIC mp_obj_t esp_osdebug(size_t n_args, const mp_obj_t *args) {
-    esp_log_level_t level = LOG_LOCAL_LEVEL;
+    esp_log_level_t level = LOG_LOCAL_LEVEL; // Maximum available level
     if (n_args == 2) {
         level = mp_obj_get_int(args[1]);
     }
     if (args[0] == mp_const_none) {
-        // Disable logging
+        // Set logging back to boot default of ESP_LOG_ERROR
         esp_log_level_set("*", ESP_LOG_ERROR);
     } else {
         // Enable logging at the given level