Source code for boarddev

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Lazy end-device binding for board_peripherals -> board_config.

``board_peripherals.load_peripherals(globals())`` typically calls
``bind_lazy(ns, this_module)``. Apps normally use ``board_config.PERIPHERALS``
and attribute access instead of importing this module.

It also carries the one thing neither ``audiodev`` nor a board can answer on
its own: whether this machine's audio comes from a board or from a host
backend. See `pcm_out`.

And it is where the portable environment helpers live -- `env_get`,
`env_int`, `env_float`, `env_bool` and `env_set` --
because a board config, an app and every OmniPython package read their
``OMNIPYTHON_*`` settings through them, on interpreters where ``os.environ``
may not exist::

    from boarddev import env_int, env_set

    env_set("OMNIPYTHON_WIDTH", 800)   # before board_config is imported
    period = env_int("OMNIPYTHON_REFRESH_MS", 0)

This module imports nothing at module scope, so any package -- ``displaydev``
included -- can import from it without a cycle. Keep it that way.
"""


[docs] def bind_lazy(ns, peripherals_mod): """Install module ``__getattr__`` / ``__dir__`` on *ns* for lazy roles. Each name in ``peripherals_mod.PERIPHERALS`` maps to ``peripherals_mod.<name>``. Names in optional ``peripherals_mod.FACTORY_ROLES`` (a subset of ``PERIPHERALS``) are bound as the factory callable itself — first access does not invoke it. That is the audio pattern: ``board_config.audio_out(format=...)`` matches ``audiodev.auto.audio_out``. Every other role stays construct-on-getattr: first access calls the zero-arg factory, caches the object into ``ns[name]``, and further access hits the module dict (no ``__getattr__``). """ roles = peripherals_mod.PERIPHERALS factory_roles = frozenset(getattr(peripherals_mod, "FACTORY_ROLES", ())) def __getattr__(name): if name not in roles: raise AttributeError("module has no attribute {!r}".format(name)) factory = getattr(peripherals_mod, name) if name in factory_roles: ns[name] = factory return factory obj = factory() ns[name] = obj return obj def __dir__(): names = list(ns.keys()) for role in roles: if role not in ns: names.append(role) return sorted(names) ns["__getattr__"] = __getattr__ ns["__dir__"] = __dir__
# The module constant each audio role publishes its capability as, beside # ``role.capability``. _CAPABILITY_NAMES = {"audio_out": "AUDIO_OUT", "pcm_out": "AUDIO_OUT", "pcm_in": "AUDIO_IN"}
[docs] def replace_role(peripherals_mod, name, role): """Put *role* in place of the board's *name* role, for every caller. Assigning ``board_peripherals.audio_out = ...`` already reaches code that calls ``board_peripherals.audio_out()``. This does that and keeps the rest of the board's story true, so code that discovers roles or reads a capability sees the replacement too: - *name* joins ``PERIPHERALS`` and ``FACTORY_ROLES``, so ``"audio_out" in board_config.PERIPHERALS`` is true and ``board_config.audio_out`` is *role* itself, never a call of it. Pass what callers should get: the factory for an audio role, the object for a constructed one such as ``sdcard``. - The board's ``AUDIO_OUT`` becomes ``role.capability``, or None when *role* has none, once neither ``audio_out`` nor ``pcm_out`` is the board's own; ``AUDIO_IN`` the same for ``pcm_in``. A capability with a ``wire`` describes the board's codec, and an app that drives that wire itself would otherwise keep playing there. Replace ``audio_out`` and ``pcm_out`` together: the board's own roles read ``AUDIO_OUT``, so it stays while either is left. - ``board_config`` gets the same changes when it's already imported. Call it in ``main.py`` before the app is imported, and before anything has opened the old role. Args: peripherals_mod: The board's ``board_peripherals`` module. name: The role's name, such as ``"audio_out"``. role: What callers get in its place. Example: import board_peripherals import boarddev from usb.host import audio boarddev.replace_role(board_peripherals, "audio_out", audio.audio_out) """ import sys replaced = getattr(peripherals_mod, "_replaced_roles", None) if replaced is None: replaced = set() peripherals_mod._replaced_roles = replaced original = getattr(peripherals_mod, "PERIPHERALS", ()) replaced.add(name) cap_name = _CAPABILITY_NAMES.get(name) if cap_name is not None: for other, other_cap in _CAPABILITY_NAMES.items(): if other_cap == cap_name and other in original and other not in replaced: cap_name = None # a board role still reads the constant break cap = getattr(role, "capability", None) targets = [peripherals_mod] config = sys.modules.get("board_config") if config is not None and config is not peripherals_mod: targets.append(config) for mod in targets: setattr(mod, name, role) for listing in ("PERIPHERALS", "FACTORY_ROLES"): names = getattr(mod, listing, None) if names is None and listing == "FACTORY_ROLES" and mod is peripherals_mod: names = frozenset() if names is not None and name not in names: setattr(mod, listing, frozenset(names) | frozenset((name,))) if cap_name is not None: setattr(mod, cap_name, cap)
# --- host-or-board audio resolution --------------------------------------- # # An app that runs on both a board and a desktop used to write this by hand:: # # try: # from audiodev.auto import audio_out # pcm = audio_out(fmt, latency="low") # pcm = getattr(pcm, "transport", pcm) # which type did I get? # except (ImportError, OSError): # import board_config # pcm = board_config.audio_out.transport # # Both getattrs there are symptoms. The second is this question -- host or # board -- and it cannot be answered inside ``audiodev``: importing board # configs from there would cost audiodev its standalone-ness, and audiodev is # meant to be usable with no OmniPython board tree at all. ``boarddev`` is # already the seam between the two, so it answers here. # # Note it resolves to ``board_peripherals``, never ``board_config``. On some # boards importing ``board_config`` initialises the display -- on the # ESP32-P4 that means MIPI DSI, which stalls the VM -- and a headless audio # app has no use for a display anyway. That is the whole point of the # non-graphics idiom.
[docs] def audio_provider(): """Return the module supplying this machine's audio factories. ``board_peripherals`` when this machine has one, else ``audiodev.auto``. A desktop ``board_peripherals`` forwards to ``audiodev.auto`` itself, so preferring the board module is right in both cases. """ try: import board_peripherals return board_peripherals except ImportError: from audiodev import auto return auto
def _role(name, format, kwargs): provider = audio_provider() factory = getattr(provider, name, None) if factory is None: raise AttributeError( "{} provides no {!r} role".format( getattr(provider, "__name__", provider), name ) ) return factory(format, **kwargs)
[docs] def pcm_out(format=None, **kwargs): """Raw `PCMOutput <audiodev.PCMOutput>` from board or host, same call. Push bytes at it with ``write()``; no sample graph is pulled, so this needs no audiodsp in firmware. """ return _role("pcm_out", format, kwargs)
[docs] def pcm_in(format=None, **kwargs): """Raw `PCMInput <audiodev.PCMInput>` from board or host, same call.""" return _role("pcm_in", format, kwargs)
[docs] def audio_out(format=None, **kwargs): """`AudioOut <audiodev.sample_out.AudioOut>` sample player, board or host.""" return _role("audio_out", format, kwargs)
# --- portable environment variables --------------------------------------- # # CPython has ``os.environ``; MicroPython and CircuitPython have ``getenv`` # and sometimes ``putenv``, and some ports have neither. ``env_set`` records # every value in a process-local table as well as in whatever the host # offers, so a value a page or a board config sets is visible to every # reader in the same process, on every interpreter. # Process-local overrides for ports without ``os.environ`` / ``os.putenv``. _overrides = {}
[docs] def env_set(name, value): """Set an environment variable portably (CPython, MicroPython, CircuitPython). Always records a process-local override so ``env_bool`` sees the value even when the host ``os`` module has no ``environ``. When available, also updates ``os.environ`` or calls ``os.putenv``. """ text = "" if value is None else str(value) _overrides[name] = text import os environ = getattr(os, "environ", None) if environ is not None: try: environ[name] = text return except Exception: pass putenv = getattr(os, "putenv", None) if putenv is not None: try: putenv(name, text) except Exception: pass
[docs] def env_bool(name, default=False): """Read a truthy/falsey environment variable with a portable fallback chain.""" raw = _env_raw(name) if raw is None: return bool(default) text = str(raw).strip().lower() if text in ("1", "true", "yes", "on"): return True if text in ("0", "false", "no", "off"): return False return bool(default)
[docs] def env_get(name, default=None): """Read a string environment variable portably (honors ``env_set`` overrides).""" raw = _env_raw(name) if raw is None: return default return raw
[docs] def env_int(name, default=0): """Read an integer environment variable portably (honors ``env_set`` overrides).""" raw = _env_raw(name) if raw is None: return int(default) try: return int(str(raw).strip()) except (TypeError, ValueError): return int(default)
[docs] def env_float(name, default=0.0): """Read a floating-point environment variable portably.""" raw = _env_raw(name) if raw is None: return float(default) try: return float(str(raw).strip()) except (TypeError, ValueError): return float(default)
def _env_raw(name): if name in _overrides: return _overrides[name] import os environ = getattr(os, "environ", None) if environ is not None: try: value = environ.get(name) except Exception: value = None if value is not None: return value getenv = getattr(os, "getenv", None) if getenv is None: return None try: return getenv(name) except Exception: return None # --- the board's name ------------------------------------------------------ # # One name for everything a board shows: its hostname, its BLE and Bluetooth # names, its mDNS services and its setup access point. A saved name lives # where wifi_manager keeps networks, so the two survive the same things. #: The environment variable (a desktop, a browser) and the ``settings.toml`` #: key (CircuitPython) that hold a saved name. NAME_KEY = "OMNIPYTHON_BOARD_NAME" #: What a board's default name starts with, before the last three bytes of #: its unique ID in hex. NAME_PREFIX = "omnipython-" #: The longest name `name` takes. NAME_MAX = 20 _NVS_NAMESPACE = "omnipython" _NVS_KEY = "board_name" _NAME_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-" _DESKTOPS = ("linux", "darwin", "win32", "cygwin", "freebsd", "openbsd", "netbsd") _BROWSERS = ("webassembly", "emscripten") _GET = object() # name() with no argument _random_name = None # a browser's, made once per page load
[docs] def name(new=_GET): """The board's name, or give it a new one. Every stack that shows a name and is given none uses this one: the hostname `wifi_manager` sets before it joins (so DHCP, mDNS and Bluetooth Classic see it), the setup access point, bledev's services, medialink and hmilink. With no saved name, a board is ``omnipython-`` plus the last three bytes of its unique ID in hex (``omnipython-a1b2c3``), a desktop is the computer's name, and a browser is ``omnipython-`` plus six random hex digits, new on each page load. A new name is saved where `wifi_manager` keeps networks: ``esp32.NVS`` on an ESP32, ``OMNIPYTHON_BOARD_NAME`` in ``settings.toml`` on CircuitPython, ``/omnipython.json`` on other boards (``/flash`` on an STM32). On a desktop or in a browser it sets the ``OMNIPYTHON_BOARD_NAME`` environment variable for this process only; it never renames the computer. Stacks that already started keep the old name until the next start. Example:: import boarddev boarddev.name() # "omnipython-a1b2c3" boarddev.name("kitchen") # saved; the board is "kitchen" from the next start boarddev.name(None) # back to the default Args: new (str): The new name: one label of letters, digits and hyphens, not starting or ending with a hyphen, 1 to 20 characters, so it works unchanged as a hostname and as a BLE name. None forgets a saved name. Returns: str: The name, when called with no argument. Otherwise None. Raises: ValueError: The new name breaks one of the rules above. OSError: CircuitPython can't write ``settings.toml`` while a computer has the CIRCUITPY drive mounted. """ import sys store = _name_store(sys.implementation.name, sys.platform) if new is _GET: return _name_read(store) or _name_default(sys.implementation.name, sys.platform) if new is not None: check_name(new) _name_write(store, new) return None
[docs] def check_name(text): """Raise `ValueError` unless ``text`` can be a board's name (see `name`).""" if not isinstance(text, str): raise ValueError("a board name is a string, not %r" % (text,)) if not text: raise ValueError("a board name can't be empty") if len(text) > NAME_MAX: raise ValueError("a board name is at most %d characters: %r has %d" % (NAME_MAX, text, len(text))) for c in text: if c not in _NAME_CHARS: raise ValueError("a board name holds only letters, digits and hyphens: %r has %r" % (text, c)) if text[0] == "-" or text[-1] == "-": raise ValueError("a board name can't start or end with a hyphen: %r" % (text,))
def _name_store(impl, platform): """Where a saved name lives here: "env", "toml", "nvs" or "file".""" if impl == "circuitpython": return "toml" if platform in _BROWSERS or platform.startswith(_DESKTOPS): return "env" try: import esp32 if hasattr(esp32, "NVS"): return "nvs" except ImportError: pass return "file" def _name_file(): import sys return ("/flash" if sys.platform == "pyboard" else "") + "/omnipython.json" def _name_read(store): if store == "env": return env_get(NAME_KEY) or None if store == "toml": import os return os.getenv(NAME_KEY) or None if store == "nvs": import esp32 buf = bytearray(NAME_MAX) try: n = esp32.NVS(_NVS_NAMESPACE).get_blob(_NVS_KEY, buf) except OSError: # ESP_ERR_NVS_NOT_FOUND: nothing saved return None return bytes(buf[:n]).decode() or None import json try: with open(_name_file()) as f: return json.load(f).get("board_name") or None except (OSError, ValueError, AttributeError): return None def _name_write(store, new): if store == "env": env_set(NAME_KEY, new) return if store == "toml": _toml_write("/settings.toml", NAME_KEY, new) return if store == "nvs": import esp32 nvs = esp32.NVS(_NVS_NAMESPACE) if new is None: try: nvs.erase_key(_NVS_KEY) except OSError: pass else: nvs.set_blob(_NVS_KEY, new.encode()) nvs.commit() return import json path = _name_file() if new is None: import os try: os.remove(path) except OSError: pass return with open(path, "w") as f: json.dump({"board_name": new}, f) def _toml_write(path, key, value): """Set or remove ``key = "value"`` in a settings.toml, keeping every other line.""" try: with open(path) as f: lines = f.read().split("\n") except OSError: lines = [] kept = [line for line in lines if line.split("=", 1)[0].strip() != key] while kept and not kept[-1].strip(): kept.pop() if value is not None: kept.append('%s = "%s"' % (key, value)) try: with open(path, "w") as f: f.write("\n".join(kept) + "\n") except OSError as e: raise OSError("can't save the board name in %s: is CIRCUITPY mounted on a computer? (%s)" % (path, e)) def _name_default(impl, platform): if impl == "circuitpython": import microcontroller return _name_from_id(microcontroller.cpu.uid) if platform in _BROWSERS: return _name_random() if platform.startswith(_DESKTOPS): return _computer_name() or _name_random() import machine return _name_from_id(machine.unique_id()) def _name_from_id(uid): return NAME_PREFIX + "".join("%02x" % b for b in bytes(uid)[-3:]) def _name_random(): global _random_name if _random_name is None: import random _random_name = NAME_PREFIX + "%06x" % random.getrandbits(24) return _random_name def _computer_name(): """The computer's name without its domain, or None where it can't be read.""" text = None try: import socket text = socket.gethostname() except (ImportError, AttributeError, OSError): pass if not text: # MicroPython's unix and Windows ports have no gethostname(). text = env_get("COMPUTERNAME") or env_get("HOSTNAME") if not text: for path in ("/proc/sys/kernel/hostname", "/etc/hostname"): try: with open(path) as f: text = f.read().strip() except OSError: continue if text: break return text.split(".")[0] if text else None