diff options
| -rw-r--r-- | docs/library/os.rst | 31 |
1 files changed, 31 insertions, 0 deletions
diff --git a/docs/library/os.rst b/docs/library/os.rst index 710875e34..bd552e36f 100644 --- a/docs/library/os.rst +++ b/docs/library/os.rst @@ -133,6 +133,37 @@ Terminal redirection and duplication The function returns the previous stream-like object in the given slot. +.. function:: dupterm_notify(obj_in, /) + + Notify the MicroPython REPL that input is available on a stream-like object + previously registered via `os.dupterm()`. + + This function should be called by custom stream implementations (e.g., UART, + Bluetooth, or other non-USB REPL streams) to inform the REPL that input is + ready to be read. Proper use ensures that special characters such as + Ctrl+C (used to trigger KeyboardInterrupt) are processed promptly by the + REPL, enabling expected interruption behavior for user code. + + The *obj_in* parameter is ignored by `os.dupterm_notify()`, but is required to allow calling + dupterm_notify from an interrupt handler such as `UART.irq()`. + + Example: + + .. code-block:: python + + from machine import UART + import os + uart = UART(0) + os.dupterm(uart, 0) + uart.irq(os.dupterm_notify, machine.UART.IRQ_RX) + + .. note:: + If the ``dupterm_notify()`` function is not called, input from the custom stream + may not be detected or processed until the next REPL poll, potentially delaying + KeyboardInterrupts or other control signals. + This is especially important for UART, Bluetooth and other + non-standard REPL connections, where automatic notification is not guaranteed. + Filesystem mounting ------------------- |