Source code for openbricks.pins

# SPDX-License-Identifier: MIT
"""
Reserved-GPIO guard: fail pin misuse at construction time, loudly.

Drivers that take raw GPIO numbers call :func:`check` before touching
``machine.Pin``. Two kinds of mistakes are caught:

* **Chip-reserved pins** — pins that can never work for user wiring on
  the running chip: nonexistent numbers, the SPI-flash pins, the
  ESP32-S3's native-USB pair, and (for output roles) the classic
  ESP32's input-only range. Claiming these either crashes the chip,
  bricks the USB connection, or fails somewhere far from the real
  mistake; the guard names the pin and the reason instead.
* **Pins the firmware runtime already owns** — the program button, the
  Bluetooth-toggle button, and the status LED register themselves via
  :func:`claim` when the hub / launcher wire them at boot. A driver
  constructed on one of those pins gets an error naming the owner
  ("in use as the program button") plus the constructor argument that
  moves the owner elsewhere. A driver's own claims (a QTR array's
  pins) last for the program that made them: the launcher releases
  them at the next program boundary.

Chip detection reads ``os.uname().machine`` and recognizes the two
supported targets (ESP32, ESP32-S3). Off-chip — CPython tests, the
MuJoCo sim, unix MicroPython — no chip is detected and the
chip-reserved rules are skipped (the runtime-claims check still
applies); pins there are fakes, not wiring. Tests pin a chip
explicitly with :func:`set_chip`.

Strapping pins (0/3/45/46 on the S3) are deliberately *not* blocked:
they work as regular GPIOs after boot and are routinely used. The
wiring guides in ``docs/hardware.md`` cover the soft cases.
"""

import os


# ---- the ESP32-S3 wiring convention ---------------------------------------

# GPIO -> role, the single source of truth for "which pin does what"
# on the reference build (docs/hardware.md, "GPIO map"). Drivers
# default their pin arguments from it, shipped examples are tested
# against it (tests/test_example_pins.py), and the user-facing docs
# reproduce it. A pin absent from the table is free for user wiring
# (subject to :func:`check`).
ESP32S3_CONVENTION = {
    # ADC1 bank — the QTRLineSensor window. Nothing else may sit
    # here: every other role was moved off it deliberately.
    1: "qtr", 2: "qtr", 3: "qtr", 4: "qtr", 5: "qtr",
    6: "qtr", 7: "qtr", 8: "qtr", 9: "qtr", 10: "qtr",
    11: "spi_miso", 12: "spi_sck", 13: "spi_mosi", 17: "spi_cs",
    14: "uart1_tx", 41: "uart1_rx",
    15: "i2c_sda", 16: "i2c_scl",
    19: "usb", 20: "usb",
    21: "ws2812",
    38: "ble_button", 39: "program_button",
    43: "uart0_tx", 44: "uart0_rx",
    48: "status_led",
}
SERVO_BUS_TX = 14
SERVO_BUS_RX = 41


[docs] class ReservedPinError(ValueError): """A GPIO was requested that can't (or shouldn't) be user-wired."""
# ---- chip detection --------------------------------------------------- # None = autodetect from os.uname(); set_chip() overrides. _chip_override = None _CHIPS = ("esp32", "esp32s3")
[docs] def set_chip(chip): """Force the chip model the guard validates against. ``chip`` is ``"esp32"``, ``"esp32s3"``, or ``None`` to return to autodetection. Used by tests; harmless elsewhere. """ global _chip_override if chip is not None and chip not in _CHIPS: raise ValueError("chip must be one of %r or None (got %r)" % (_CHIPS, chip)) _chip_override = chip
def _detect_chip(): if _chip_override is not None: return _chip_override try: machine_str = os.uname().machine except AttributeError: return None m = machine_str.replace("-", "").replace("_", "").upper() # Variant names contain the plain "ESP32" substring, so rule the # unsupported ones out first rather than misapplying classic-ESP32 # pin rules to them. for variant in ("ESP32S3",): if variant in m: return "esp32s3" for variant in ("ESP32S2", "ESP32C3", "ESP32C6", "ESP32H2", "ESP32P4"): if variant in m: return None if "ESP32" in m: return "esp32" return None # ---- runtime claims (buttons, LED) ------------------------------------ # pin -> (role, hint). Written by the hub / launcher when they wire # their pins at boot; read by driver check() calls. Re-claiming the # same pin overwrites — the hub classes and launcher own their # lifecycle, this dict just mirrors it for error messages. _claims = {} # The pins in _claims that a driver claimed for one program (a QTR # array's ADC pins). The launcher releases them at the program # boundary; the boot-time claims above them survive. _program_claims = set()
[docs] def claim(pin, role, hint="", program=False): """Record that the firmware runtime owns ``pin`` (e.g. a button). ``program=True`` marks a claim a driver makes for the running program only: :func:`release_program_claims` hands it back when the program ends, so the next program may wire that pin anew. """ pin = int(pin) _claims[pin] = (role, hint) if program: _program_claims.add(pin) else: _program_claims.discard(pin)
[docs] def release(pin): """Forget a claim — for callers that hand a pin back (e.g. after ``hub.bluetooth_toggle.stop()``). Unknown pins are a no-op.""" pin = int(pin) _claims.pop(pin, None) _program_claims.discard(pin)
[docs] def release_program_claims(): """Forget every claim made with ``program=True`` — the launcher calls this at the program boundary. Boot-time claims stay.""" for pin in _program_claims: _claims.pop(pin, None) _program_claims.clear()
def _claims_reset(): """Test helper: drop every claim.""" _claims.clear() _program_claims.clear() # ---- validation -------------------------------------------------------- def _die(pin, role, reason): raise ReservedPinError( "GPIO %d requested for %s, but it is %s" % (pin, role, reason))
[docs] def check(pin, role, output=True): """Validate that ``pin`` is usable for ``role`` on this chip. Args: pin: GPIO number the caller is about to wire. role: human-readable purpose ("L298N IN1", "HC-SR04 echo") — appears in the error message. output: the pin must drive (True) or only read (False). Only matters on the classic ESP32, where GPIO 34-39 are input-only. Raises: ReservedPinError: with the pin, the role, and the reason. """ pin = int(pin) if pin in _claims: owner, hint = _claims[pin] # Same role re-checking its own pin is fine — the frozen # main.py wires the hub/launcher at boot, and a user program # constructing its own Hub afterwards re-checks the same pins # under the same roles. if owner != role: _die(pin, role, "in use as the %s%s" % (owner, (" (%s)" % hint) if hint else "")) chip = _detect_chip() if chip is None: return if chip == "esp32s3": if pin < 0 or pin > 48 or 22 <= pin <= 25: _die(pin, role, "not a GPIO on the ESP32-S3 (valid: 0-21, 26-48)") if 26 <= pin <= 32: _die(pin, role, "connected to the module's SPI flash on the ESP32-S3 " "(GPIO 26-32)") if pin in (19, 20): _die(pin, role, "the ESP32-S3's native USB D-/D+ pair — wiring it " "breaks USB flashing and the USB REPL") else: # classic esp32 if pin < 0 or pin > 39 or pin == 20 or pin == 24 or 28 <= pin <= 31: _die(pin, role, "not a GPIO on the ESP32 " "(valid: 0-19, 21-23, 25-27, 32-39)") if 6 <= pin <= 11: _die(pin, role, "connected to the module's SPI flash on the ESP32 " "(GPIO 6-11)") if output and 34 <= pin <= 39: _die(pin, role, "input-only on the ESP32 (GPIO 34-39 have no output " "driver); use it for encoder/sensor inputs instead")