blecontroller

Universal BLE LED controller for cheap WS2812B/BLE devices.

Control BLE-controlled LED curtain lights, strip lights, and panels from Python via Bluetooth Low Energy.

Supported Devices

Install

pip install blecontroller

Quick Start

import asyncio
from blecontroller import BLELEDController

async def main():
    async with BLELEDController("Hello Fairy-0B09") as led:
        await led.power_on()
        await led.set_brightness(100)
        
        # Solid red
        await led.set_color((255, 0, 0))
        await asyncio.sleep(2)
        
        # Rainbow
        await led.rainbow()
        await asyncio.sleep(3)
        
        await led.power_off()

asyncio.run(main())

Per-Pixel Control

import asyncio
from blecontroller import BLELEDController, solid_color, gradient

async def main():
    async with BLELEDController("Hello Fairy-0B09", num_pixels=400) as led:
        await led.power_on()
        
        # Half red, half blue
        colors = [(255,0,0)] * 200 + [(0,0,255)] * 200
        await led.set_pixels(colors)
        
        # Gradient from red to blue
        colors = gradient(400, (255,0,0), (0,0,255))
        await led.set_pixels(colors)
        
        await asyncio.sleep(3)
        await led.power_off()

asyncio.run(main())

Custom Device Profiles

from blecontroller import BLELEDController, DeviceProfile, DEVICE_PROFILES

# Add your own device
DEVICE_PROFILES["my-device"] = DeviceProfile(
    name="My LED Panel",
    write_char="0000ffe1-0000-1000-8000-00805f9b34fb",
    notify_char="0000ffe2-0000-1000-8000-00805f9b34fb",
    power_on=bytes([0x71, 0x23, 0x0A, 0x01]),
    power_off=bytes([0x71, 0x23, 0x0A, 0x00]),
    pixel_cmd=0x71,
    max_chunk=20,
)

async with BLELEDController("MyDevice-XX", profile="my-device") as led:
    await led.rainbow()

Connect by MAC Address

async with BLELEDController(address="BE:29:FC:00:0B:09") as led:
    await led.rainbow()

Color Utilities

from blecontroller.packets import hsv_to_rgb, rainbow_colors, gradient, solid_color

# HSV to RGB
r, g, b = hsv_to_rgb(128, 255, 255)  # cyan

# Generate color arrays
rainbow = rainbow_colors(400)
reds = solid_color(400, (255, 0, 0))
blend = gradient(400, (255, 0, 0), (0, 255, 0))

Requirements

• Python 3.9+
• bleak >= 0.20
• BLE adapter on your system (e.g., hci0 on Linux)

License

MIT