hub

Board-provided hub module.

Exposes the on-device peripherals: LPF2 ports (hub.ports), hub LED, IMU (hub.imu), buttons, LCD (LVGL), status log and power-off. Objects here are singletons created by the C firmware — this module is a stub; the real implementation lives in the ESP32 port.

Attributes

accelerometer	Built-in accelerometer wrapped as a Devices.accelerometer.
audio	Raw-PCM audio player via NS4168 I2S amp (see _audio_module). Only present when board has NS4168.
battery	Battery voltage + charging status (see _battery_module).
board	Board-specific constants (see _board_module).
buttons	Button API (see _buttons_module).
gyro	Built-in gyroscope wrapped as a Devices.gyroscope.
i2c	Shared internal I2C bus (Grove + on-board devices). See _i2c.
imu	Fused IMU (see _imu_module).
lcd	LCD + LVGL control (see _lcd_module).
led	Built-in hub RGB LED.
log	Firmware log control.
ports	Hub ports (see _ports_module).
pwm	On-board PCA9685 PWM driver (see _pwm_module).
video	MJPEG-in-AVI video player (see _video_module). Only present when board has an LCD.

Functions

exit(→ NoReturn)	Exit the running user script cleanly. Raises SystemExit.
flush_output(→ None)	Flush any buffered framed stdout data as a #FR:OUT frame.
on(…)	Register a callback for a firmware event. Currently only "poll" is supported.
powerOff(→ NoReturn)	Turn the hub off immediately. Does not return.
raw_write(→ int)	Write bytes to stdout bypassing the framing wrapper. Returns bytes written.
sd_card(→ Optional[machine.SDCard])	Return the mounted machine.SDCard instance, or None if no SD card is present.
sd_remount(→ None)	Unmount the cached SD card handle and re-mount the SD card at /sd.
set_frame_sink(→ None)	Register a callback that mirrors framed and raw stdout bytes elsewhere.
set_framed_output(→ None)	Enable/disable C-level stdout framing (#FR:OUT <len>n<bytes>).
set_usb_msc(→ None)	Enable or disable USB Mass Storage Class (SD card).
usb_msc_mode(→ bool)	Return True if USB Mass Storage Class is currently active.

Module Contents

hub.exit() → NoReturn

Exit the running user script cleanly. Raises SystemExit.

The program runner catches SystemExit and shows the “Done” screen. Safe to call from anywhere — button callbacks, loops, top-level code.

hub.flush_output() → None

Flush any buffered framed stdout data as a #FR:OUT frame.

hub.on(name: _PollName) → Callable[[_PollFn], _PollFn]

hub.on(name: _PollName, fn: _PollFn) → _PollFn

Register a callback for a firmware event. Currently only "poll" is supported.

"poll" callbacks are scheduled on mp_task via mp_sched_schedule every ~20 ms by the C firmware loop. They run even while a user script is executing.

hub.powerOff() → NoReturn

Turn the hub off immediately. Does not return.

If the hardware power latch does not hold (e.g. USB power is present), the firmware performs an orderly shutdown: disables LPF2 ports and motor PWM outputs, turns off the LCD backlight, deinitialises BLE and WiFi, signals the MicroPython task to exit (GC runs before the task deletes itself), throttles the CPU to 80 MHz, then enters a low-activity loop that keeps the battery status LED updated. Pressing the right button restarts the firmware.

hub.raw_write(buf: bytes) → int

Write bytes to stdout bypassing the framing wrapper. Returns bytes written.

Flushes any pending framed output first so raw bytes never interleave inside a framed payload.

hub.sd_card() → machine.SDCard | None

Return the mounted machine.SDCard instance, or None if no SD card is present.

The card is initialised and mounted at /sd before boot.py runs. Returns None on boards without HAS_SD_CARD or when mount failed.

hub.sd_remount() → None

Unmount the cached SD card handle and re-mount the SD card at /sd.

Call after disabling USB MSC so the SDMMC host is freed and can be re-initialised via machine.SDCard.

hub.set_frame_sink(cb: Callable[[bytes], None] | None) → None

Register a callback that mirrors framed and raw stdout bytes elsewhere.

Called from mp_hal_stdout_tx_strn under the GIL after every framed flush and every raw_write(). Used to forward the same byte stream to BLE NUS (since os.dupterm only exposes slot 0 = REPL on this port). Pass None to detach. Exceptions inside the callback are swallowed.

hub.set_framed_output(enabled: bool) → None

Enable/disable C-level stdout framing (#FR:OUT <len>n<bytes>).

When enabled, every mp_hal_stdout_tx_strn call is wrapped so the host protocol parser can separate program output from binary frames. Used by the HubProtocol layer since sys.stdout is an immutable dummy in this build and can’t be replaced from Python.

hub.set_usb_msc(enabled: bool) → None

Enable or disable USB Mass Storage Class (SD card).

When enabling, the SDMMC host is opened without a VFS mount so TinyUSB can own the SD card. When disabling, the SDMMC host is released so sd_remount() can re-mount it via MicroPython.

hub.usb_msc_mode() → bool

Return True if USB Mass Storage Class is currently active.

hub.accelerometer: lpf2.devices.accelerometer

Built-in accelerometer wrapped as a Devices.accelerometer.

hub.audio: _audio_module

Raw-PCM audio player via NS4168 I2S amp (see _audio_module). Only present when board has NS4168.

hub.battery: _battery_module

Battery voltage + charging status (see _battery_module).

hub.board: _board_module

Board-specific constants (see _board_module).

hub.buttons: _buttons_module

Button API (see _buttons_module).

hub.gyro: lpf2.devices.gyroscope

Built-in gyroscope wrapped as a Devices.gyroscope.

hub.i2c: _i2c

Shared internal I2C bus (Grove + on-board devices). See _i2c.

hub.imu: _imu_module

Fused IMU (see _imu_module).

hub.lcd: _lcd_module

LCD + LVGL control (see _lcd_module).

hub.led: lpf2.devices.hub_led

Built-in hub RGB LED.

hub.log: _log_module

Firmware log control.

hub.ports: _ports_module

Hub ports (see _ports_module).

hub.pwm: _pwm_module

On-board PCA9685 PWM driver (see _pwm_module).

hub.video: _video_module

MJPEG-in-AVI video player (see _video_module). Only present when board has an LCD.