Hubs

Board-level peripherals — the onboard LED and buttons — behind one Hub object per supported devkit.

from openbricks.hub import ESP32S3DevkitHub

hub = ESP32S3DevkitHub()
hub.led.rgb(0, 80, 0)          # onboard NeoPixel: dim green
if hub.bluetooth_button.pressed():
    print("button held at boot")

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 (classic ESP32 default GPIO 5; ESP32-S3 default GPIO 38 — the S3 has only ten analog-capable pins, ADC1 = GPIO 1-10, and a button doesn’t need one) — 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()

Turn the LED on (RGB LEDs restore their last colour).

off()

Turn the LED 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()

Turn the LED on (RGB LEDs restore their last colour).

off()

Turn the LED 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()

Turn the LED on (RGB LEDs restore their last colour).

off()

Turn the LED 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 short-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=38, brightness=0.2, bluetooth=True)

Bases: Hub

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

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 38 (was 5 until 1.66.3): the S3 has exactly ten analog-capable pins (ADC1, GPIO 1-10) and a button needs none of them — parking the default there cost an analog channel the moment a sensor array arrived. GPIO 38 is free, non-strapping and digital-only. Wire a momentary switch between GPIO 38 and GND; the pin is configured Pin.IN with PULL_UP so no external resistor is needed. Override via bluetooth_button_pin=<N> (a hub wired to the old default passes 5).