Hubs

Hub — board-level peripherals (status LED, user button) for each supported MCU devkit.

Concrete hubs:

• ESP32DevkitHub — ESP32 DevKitC-V4: blue LED on GPIO 2.

• ESP32S3DevkitHub — ESP32-S3 DevKitC-1: onboard WS2812 RGB LED on GPIO 48.

Both hubs expect two momentary pushbuttons, each wired between a GPIO and GND:

• bluetooth_button_pin (default GPIO 5) — short-press toggles BLE on/off. Watched by openbricks.bluetooth_button.BluetoothToggleButton which the hub auto-wires when bluetooth=True (the default).

• The program button (default GPIO 4) — short-press starts or stops /program.py. Watched by openbricks.launcher directly, which the frozen default main.py starts via launcher.run().

Two pins → no duration-based dispatch. Each button does one thing on every short press.

We deliberately avoid GPIO 0 (BOOT) for either role: holding it during reset puts the ESP32 into the ROM bootloader, so sharing that pin with an application button would turn an accidental power-glitch into a flash-mode drop.

Both hubs auto-wire the BLE toggle button by default (bluetooth=True): constructing a hub restores the persisted BLE state, installs a short-press handler on the bluetooth_button_pin, and — on the S3 — paints the WS2812 blue (BLE on) or yellow (BLE off). Put hub = ESP32S3DevkitHub() in your main.py to turn that on; omit the call (or pass bluetooth=False) to keep the button free for your own use.

External I2C components like SSD1306 OLEDs are not part of the hub — they’re wired to any I2C bus the user chooses, instantiated directly from openbricks.drivers.ssd1306 or similar, and used alongside the hub rather than through it.

class openbricks.hub.StatusLED

Bases: object

A user-visible status LED on the hub.

Plain single-colour LEDs implement on / off. Addressable RGB LEDs (WS2812 and friends) additionally implement rgb.

on()

off()

rgb(r, g, b)

Set colour (each channel 0..255). Raises on non-addressable LEDs.

class openbricks.hub.Button

Bases: object

A momentary pushbutton on the hub.

pressed()

Return True while the button is held down.

class openbricks.hub.Hub

Bases: object

Board-level peripherals baked into a specific MCU devkit.

led = None

bluetooth_button = None

class openbricks.hub.SimpleLED(pin, active_high=True)

Bases: StatusLED

Single-colour LED driven by one digital pin.

on()

off()

class openbricks.hub.NeoPixelLED(pin, brightness=0.2)

Bases: StatusLED

Single-pixel WS2812 / NeoPixel driver — the onboard LED on ESP32-S3 DevKitC-1 and most modern ESP32-S3 compact boards.

Unlike SimpleLED this one implements rgb(r, g, b) too, which is what the Bluetooth-toggle button uses for blue / yellow feedback.

brightness scales every channel on write (0.0 – 1.0). 0.2 is a comfortable indoor default — the raw WS2812 at full brightness is dazzling.

on()

off()

rgb(r, g, b)

Set colour (each channel 0..255). Raises on non-addressable LEDs.

class openbricks.hub.PushButton(pin, active_low=True)

Bases: Button

Digital pushbutton with configurable active level and internal pull.

pressed()

Return True while the button is held down.

class openbricks.hub.ESP32DevkitHub(led_pin=2, bluetooth_button_pin=5, bluetooth=True)

Bases: Hub

ESP32 DevKitC-V4 onboard hub: blue LED on GPIO 2, BLE-toggle button on GPIO 5.

bluetooth default True wires the button to a long-press BLE toggle and restores the persisted state at boot (see openbricks.bluetooth_button / openbricks.bluetooth). The onboard LED is single-colour so no colour feedback, just the toggle. Pass bluetooth=False to skip the wiring entirely, or bluetooth_button_pin=<N> to use a different GPIO. Wire the button between the chosen GPIO and GND; an internal pull-up is enabled.

class openbricks.hub.ESP32S3DevkitHub(led_pin=48, bluetooth_button_pin=5, brightness=0.2, bluetooth=True)

Bases: Hub

ESP32-S3 DevKitC-1 onboard hub: WS2812 RGB LED on GPIO 48, BLE-toggle button on GPIO 5.

led_pin defaults to 48 (the DevKitC-1 onboard WS2812). Pass led_pin=None to disable the LED entirely, or any other GPIO for a WS2812 wired elsewhere. brightness (0.0 – 1.0) scales channel values on write; default 0.2 is comfortable indoors.

bluetooth_button_pin defaults to 5 — a safe, free pin on the DevKitC-1. Wire a momentary switch between GPIO 5 and GND; the pin is configured Pin.IN with PULL_UP so no external resistor is needed. Override via bluetooth_button_pin=<N>.