Source code for vtterm.console

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Put the board's REPL on a `Terminal <vtterm.Terminal>` with ``os.dupterm``.

`Console` is the stream ``os.dupterm`` reads from and writes to. What the
REPL prints is drawn on the display; what you type reaches the REPL from a
key source you give it (`KeyEvents <vtterm.keys.KeyEvents>`, or anything with
a ``read()`` that returns bytes) or from bytes you `Console.push`. The USB
or serial REPL keeps working beside it.

The console does what a tty does for a terminal: a bare ``\\n`` starts its
new line at column 0, so ``print`` on the unix port lines up.

Drawing is paced: while output streams, the display is redrawn at most every
``interval_ms``, and everything left over is drawn the next time the REPL
asks for input.

Example:
    >>> from board_config import display_drv
    >>> from vtterm import Terminal
    >>> from vtterm.console import Console
    >>> console = Console(Terminal(display_drv))
    >>> console.attach()
"""

import os

try:
    from micropython import schedule as _schedule
except ImportError:  # CPython
    _schedule = None

try:
    import io

    _IOBase = io.IOBase
except (ImportError, AttributeError):
    _IOBase = object

try:
    from time import sleep_ms, ticks_diff, ticks_ms
except ImportError:
    from time import monotonic, sleep

    def ticks_ms():
        return int(monotonic() * 1000)

    def ticks_diff(a, b):
        return a - b

    def sleep_ms(ms):
        sleep(ms / 1000)


_MP_STREAM_POLL = 3
_POLL_RD = 1


[docs] class Console(_IOBase): """A terminal as an ``os.dupterm`` stream. Args: terminal (Terminal): Where the REPL's output is drawn. keys: A key source with ``read()`` returning bytes or ``None``, polled whenever the REPL looks for input. Optional. interval_ms (int): Shortest time between redraws while output streams. idle_ms (int): How long ``read`` waits when there's nothing to read, so a REPL that polls in a loop (the unix port) doesn't spin. """ def __init__(self, terminal, keys=None, interval_ms=40, idle_ms=5): self.terminal = terminal terminal.parser.onlcr = True self.keys = keys self.interval_ms = interval_ms self.idle_ms = idle_ms self.index = None self._rx = bytearray() self._last = ticks_ms() self._busy = False
[docs] def attach(self, index=0): """Hand this console to ``os.dupterm`` slot ``index``. Raises: OSError: If another stream (WebREPL, the BLE REPL) holds the slot. """ held = os.dupterm(None, index) if held is not None and held is not self: os.dupterm(held, index) raise OSError("dupterm slot %d is held by %r" % (index, held)) os.dupterm(self, index) self.index = index
[docs] def detach(self): """Give the dupterm slot back and draw what's pending.""" if self.index is not None: os.dupterm(None, self.index) self.index = None self.terminal.render()
[docs] def push(self, data): """Queue ``data`` as typed input and tell the REPL it's there. Ctrl-C in ``data`` interrupts a running program, as it does over USB, on ports with ``os.dupterm_notify``. """ self._rx.extend(data) notify = getattr(os, "dupterm_notify", None) if notify is None: return if b"\x03" in data and _schedule is not None: # From a timer callback, the interrupt would be raised inside the # callback, and the timers keep it until the program next waits: # a busy loop never would. Scheduled, notify is called from C after # the callback returns, so the interrupt lands in the program. _schedule(notify, None) else: notify(None)
def _poll(self): t = self.terminal if self.keys is not None: data = self.keys.read() if data: self._rx.extend(data) answers = t.answers() if answers: self._rx.extend(answers) if not self._busy: self._busy = True try: t.render() self._last = ticks_ms() finally: self._busy = False
[docs] def refresh(self): """Draw what's waiting, unless the console is drawing already. Call it from a timer, so output a program printed shows up while nothing else redraws. A call that lands inside `write` does nothing. Returns: int: How many rows were drawn. """ if self._busy: return 0 self._busy = True try: return self.terminal.render() finally: self._busy = False
[docs] def write(self, buf): """Draw what the REPL printed. Returns ``len(buf)``.""" if self._busy: return len(buf) self._busy = True try: t = self.terminal t.feed(buf) now = ticks_ms() if ticks_diff(now, self._last) >= self.interval_ms: t.render() self._last = now finally: self._busy = False return len(buf)
[docs] def readinto(self, buf): """Fill ``buf`` with typed input. Returns the count, or ``None`` when there's none.""" self._poll() n = min(len(self._rx), len(buf)) if not n: return None buf[:n] = self._rx[:n] self._rx[:n] = b"" return n
[docs] def read(self, n=-1): """Return up to ``n`` bytes of typed input, or ``None`` when there's none.""" self._poll() if not self._rx: if self.idle_ms: sleep_ms(self.idle_ms) return None if n < 0 or n > len(self._rx): n = len(self._rx) out = bytes(self._rx[:n]) self._rx[:n] = b"" return out
[docs] def ioctl(self, op, arg): """Answer ``os.dupterm``'s poll: readable when input is waiting.""" if op == _MP_STREAM_POLL: self._poll() return _POLL_RD if (arg & _POLL_RD) and self._rx else 0 return 0