uos.dupterm() behavior in underspecified, implementations broken
While not directly related to HW API, https://github.com/micropython/micropython/wiki/Hardware-API#os-module-additions specifies os.dupterm(), used for:
os.dupterm([stream_obj]) get or set duplication of controlling terminal, so that REPL can be redirected to UART or other (note: could allow to duplicate to multiple stream objs but that's arguably overkill and could anyway be done in Python by making a stream multiplexer)
Unfortunately, this description is not clear/detailed enough, or alternatively, current implementations of it in stmhal and cc3200 ports are not general or just broken. First of all, it should be made clear if the talk is about duplicating "controlling terminal", or replacing it. If there's talk about duplicating, then there should be immediate talk about non-blocking streams. Otherwise this line https://github.com/micropython/micropython/blob/master/cc3200/hal/cc3200_hal.c#L187 will simply hang the entire REPL, as it will wait until a character is available on that particular stream, ignoring all other input sources.
And then if there's requirement to non-blocking streams, it should be kept in mind that all other REPL sources should be non-blocking too, otherwise standard source can block custom installed one. But requirement of non-blocking sources is merely a minimal condition to get it all working, but working quite inefficiently and requiring weird workaround to not make it burn CPU cycles (and a battery of battery-powered device), e.g. https://github.com/micropython/micropython/blob/master/cc3200/hal/cc3200_hal.c#L196. So, next step is making requirement that REPL sources are pollable, and actually poll them.
That's quite a bunch of requirements to get it working in the general case, sure.
esp8266: Change UART(0) to attach to REPL via uos.dupterm interface.
This patch makes it so that UART(0) can by dynamically attached to and
detached from the REPL by using the uos.dupterm function. Since WebREPL
uses dupterm slot 0 the UART uses dupterm slot 1 (a slot which is newly
introduced by this patch). UART(0) must now be attached manually in
boot.py (or otherwise) and inisetup.py is changed to provide code to do
this. For example, to attach use:
import uos, machine
uart = machine.UART(0, 115200)
uos.dupterm(uart, 1)
and to detach use:
uos.dupterm(None, 1)
When attached, all incoming chars on UART(0) go straight to stdin so
uart.read() will always return None. Use sys.stdin.read() if it's needed
to read characters from the UART(0) while it's also used for the REPL (or
detach, read, then reattach). When detached the UART(0) can be used for
other purposes.
If there are no objects in any of the dupterm slots when the REPL is
started (on hard or soft reset) then UART(0) is automatically attached.
Without this, the only way to recover a board without a REPL would be to
completely erase and reflash (which would install the default boot.py which
attaches the REPL).
See #2891 and #3277 for previous attempts at this.