btbricks 0.2.3

A MicroPython Bluetooth library for remote controlling LEGO hubs via BLE

btbricks

btbricks is MicroPython Bluetooth library. It implements BLE (Bluetooth 5, Bluetooth Low Energy). Of the know BLE services, this library implements Nordic Uart Service (NUS), LEGO Service and MIDI service. The library contains both the BLE Central (client) and BLE Peripheral (server) classes.

The BLE services allow controlling LEGO hubs running official firmware. You can also create custom Bluetooth peripherals: RC controllers, MIDI devices, and more. For LEGO hub control, a hub expansion board like the LMS-ESP32 is recommended.

Table of Contents

• Features
• Installation
• Quick Start
• Documentation
• Supported Platforms
• License
• Author

Features

• 🔌 BLE Communication: Comprehensive Bluetooth Low Energy support via MicroPython's ubluetooth
• 🎮 Hub Control: Control LEGO MINDSTORMS hubs, SPIKE sets, and smart hubs over Bluetooth
• 📱 Custom Peripherals: Create RC controllers, MIDI controllers, and other BLE peripherals compatible with LEGO hubs
• 🚀 MicroPython Ready: Optimized for MicroPython on ESP32, LEGO SPIKE, and other platforms
• 📡 LEGO Protocol: Full support for LEGO Bluetooth protocols (LPF2, LPUP, CTRL+)
• 🎛️ Multiple Interfaces: Nordic UART, MIDI, RC control, and native LEGO hub communication
• ⚙️ Advanced BLE: Automatic MTU negotiation, descriptor handling, and efficient payload management

Installation

Using ViperIDE Package Manager (Recommended)

1. Open ViperIDE on your device
2. Go to Tools → Package Manager
3. Select Install Package via Link
4. Enter the package link: https://github.com/antonvh/btbricks.git
5. Follow the on-screen prompts to complete installation

On LMS-ESP32

The module should be included in the latest Micropython firmware from https:/firmware.antonsmindstorms.com. If not, use ViperIDE as described above.

On SPIKE Legacy or MINDSTORMS Robot Inventor

Use the installer script in mpy-robot-tools: https://github.com/antonvh/mpy-robot-tools/blob/master/Installer/install_mpy_robot_tools.py

Deprecated: using micropip from PyPI

import micropip
await micropip.install("btbricks")

Note: micropip must be available on the target board and may require an internet connection from the device.

Quick Start

Connect to a LEGO Hub

from btbricks import BtHub

# Create hub instance
hub = BtHub()

# Connect to a nearby hub
hub.connect()

if hub.is_connected():
    # Set hub LED to green
    hub.set_led_color(6)  # GREEN constant
    
    # Read accelerometer data
    acc = hub.acc()
    if acc:
        print(f"Accelerometer: {acc}")
    
    # Control motor on port A with 50% power
    hub.dc("A", 50)
    
    hub.disconnect()

Create an RC Receiver (Hub-side)

Use the examples in the examples/ folder for full, runnable code. Minimal receiver/transmitter snippets:

from btbricks import RCReceiver, R_STICK_HOR, R_STICK_VER
from time import sleep_ms

# Create RC receiver (advertises as "robot" by default)
rcv = RCReceiver(name="robot")

print("Waiting for RC transmitter to connect...")
try:
    while True:
        if rcv.is_connected():
            steering = rcv.controller_state(R_STICK_HOR)
            throttle = rcv.controller_state(R_STICK_VER)
            print(f"Steering: {steering}, Throttle: {throttle}")
            sleep_ms(100)
        else:
            sleep_ms(500)
except KeyboardInterrupt:
    rcv.disconnect()

from btbricks import RCTransmitter, L_STICK_HOR, R_STICK_VER
from time import sleep

# Create RC transmitter (central)
tx = RCTransmitter()

if tx.connect(name="robot"):
    try:
        while tx.is_connected():
            # Set stick values in range [-100, 100]
            tx.set_stick(L_STICK_HOR, 0)
            tx.set_stick(R_STICK_VER, 50)
            tx.transmit()
            sleep(0.1)
    except KeyboardInterrupt:
        tx.disconnect()

Create a MIDI Controller

from btbricks import MidiController
from time import sleep

# Create MIDI controller (advertises as "amh-midi" by default)
midi = MidiController(name="amh-midi")

print("MIDI controller started, connect from your DAW...")

try:
    while True:
        # Send MIDI note on: middle C (note 60), velocity 100
        midi.note_on(60, 100)
        sleep(0.5)
        
        # Send MIDI note off
        midi.note_off(60)
        sleep(0.5)
        
        # Or send a chord
        midi.chord_on("C4", velocity=100, style="M")  # C major chord
        sleep(1)
        midi.note_off(60)  # Stop the chord
        
except KeyboardInterrupt:
    print("MIDI controller stopped")

Documentation and API reference

See the full documentation and API reference at:

docs.antonsmindstorms.com

Core Classes

• BLEHandler: Low-level Bluetooth communication
• UARTCentral: Nordic UART client mode
• UARTPeripheral: Nordic UART server mode
• RCReceiver: Receive RC control signals
• RCTransmitter: Send RC control signals
• MidiController: Send MIDI commands over BLE
• BtHub: High-level hub communication interface

Control Constants

• Sticks: L_STICK_HOR, L_STICK_VER, R_STICK_HOR, R_STICK_VER
• Triggers: L_TRIGGER, R_TRIGGER
• Buttons: BUTTONS
• Settings: SETTING1, SETTING2

Supported Platforms

• LEGO MINDSTORMS EV3 (with MicroPython firmware)
• LEGO SPIKE Prime/Prime Essential (with MINDSTORMS firmware)
• LEGO SPIKE Robot Inventor
• ESP32 with MicroPython
• Other MicroPython boards with ubluetooth support

License

MIT License

Author

Anton Vanhoucke