Source code for vtterm.keyboards

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Keyboards on the USB host port and over BLE, read from a timer.

Each source has ``poll()``, which never waits and returns a list of
``events.Key`` records (possibly empty), ``status``, a line saying what it's
connected to, and ``close()``. Sources look for a keyboard on their own and
find it again after it's unplugged or switched off.
"""

import events
import keys

# Imported once here: on MicroPython, importing a built-in module such as
# time inside a function looks for a file of that name on every call, which
# took 77 ms a time on an ESP32-S3 and starved the REPL.
from .console import ticks_diff, ticks_ms

#: How often a source with no keyboard looks for one, in ms.
LOOK_MS = 1000


def _now():
    return ticks_ms()


def _due(last, ms):
    return last is None or ticks_diff(ticks_ms(), last) >= ms


[docs] class UsbKeyboard: """A keyboard on the board's USB host port, in boot protocol. Starting the host takes the port: a board whose REPL is on its native USB loses that until `close`. """ def __init__(self): import usb.core from usb.host import hid self._core = usb.core self._hid = hid usb.core.start(classes=("hid",)) self.kbd = None self.status = "USB: no keyboard yet" self._looked = None def _look(self): hid = self._hid self._looked = _now() dev = self._core.find(custom_match=hid.Device.match(hid.KEYBOARD)) if dev is None: return self.kbd = hid.Device(dev, protocol=hid.KEYBOARD, boot=True) self.status = "USB: %s %s" % (dev.manufacturer or "%04x" % dev.idVendor, dev.product or "%04x" % dev.idProduct) def poll(self): KEY_DOWN, KEY_UP = self._hid.KEY_DOWN, self._hid.KEY_UP if self.kbd is None: if _due(self._looked, LOOK_MS): self._look() return [] out = [] try: while True: ev = self.kbd.read(1) # ms; 0 would wait forever, as in pyusb if not ev: break kind, usage = ev[0], ev[1] if kind != KEY_DOWN and kind != KEY_UP: continue pressed = events.KEYDOWN if kind == KEY_DOWN else events.KEYUP mod = keys.hid_modifiers(ev[2]) if 0xE0 <= usage <= 0xE7: code = keys.HID_MODIFIERS[usage - 0xE0][1] else: code = keys.hid_keycode(usage) if code is not None: out.append(events.Key(pressed, keys.keyname(code), code, mod, usage, None)) except self._core.USBError: # Unplugged: look again. self._drop() self.status = "USB: keyboard gone" return out def _drop(self): kbd, self.kbd = self.kbd, None if kbd is not None: try: kbd.close() except Exception: pass def close(self): self._drop() self._core.stop()
async def _yield(): # asyncio.sleep_ms(0) itself isn't a coroutine, so run() refuses it. import asyncio await asyncio.sleep_ms(0)
[docs] class BleKeyboard: """The first BLE keyboard advertising the HID service, as a host. bledev runs on asyncio, and the REPL runs no event loop, so `poll` runs the loop's ready tasks for one pass each time it's called. """ def __init__(self, timeout_ms=8000): import asyncio import bledev.auto self._asyncio = asyncio self.ble = bledev.auto.adapter() self.host = None self.status = "BLE: looking for a keyboard" self.timeout_ms = timeout_ms self._task = asyncio.create_task(self._keep()) self._closed = False async def _keep(self): import bledev.hid while not self._closed: try: host = await bledev.hid.connect(self.ble, timeout_ms=self.timeout_ms) except Exception as e: # noqa: BLE001 - none near, or it went away: say so and look again self.status = "BLE: %s" % (e,) if str(e) else "BLE: no keyboard found" await self._asyncio.sleep_ms(LOOK_MS) continue self.host = host name = getattr(host.connection, "name", None) or "keyboard" self.status = "BLE: %s" % name # poll() drops self.host when a read fails; this loop watches its own copy. while not self._closed and self.host is host and host.connection.is_connected(): await self._asyncio.sleep_ms(200) self.host = None try: await host.close() except Exception: # noqa: BLE001 - it's gone either way pass if not self._closed: self.status = "BLE: keyboard gone" def _pump(self): self._asyncio.run(_yield()) def poll(self): self._pump() host = self.host if host is None: return [] try: return [e for e in host.poll() if hasattr(e, "key")] except Exception as e: # noqa: BLE001 - the link dropped; _keep finds it again self.status = "BLE: %s" % (e,) self.host = None return [] def close(self): self._closed = True host, self.host = self.host, None if host is not None: try: self._asyncio.run(host.close()) except Exception: pass self._task.cancel() try: self._pump() except Exception: pass
[docs] def start_all(): """Start every keyboard source this board can have. Returns: tuple: ``(sources, missing)``: the sources that started, and a line for each that couldn't, saying why. """ out, missing = [], [] for name, cls in (("USB", UsbKeyboard), ("BLE", BleKeyboard)): try: out.append(cls()) except ImportError: missing.append("%s: not in this firmware" % name) except Exception as e: # noqa: BLE001 - one source failing leaves the other missing.append("%s: %s" % (name, e)) return out, missing