blecontroller 0.1.0

Universal BLE LED controller for cheap WS2812B/BLE devices

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

Device	Profile	Notes
Hello Fairy (20x20 curtain)	hello-fairy	400 WS2812B LEDs, tested
Generic BLE LED controllers	generic-ble-led	Common cheap controllers

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