lightball-ble

Async BLE protocol and client for Holiday Show Home "Show Home" LED Balls — the battery-powered RGB orbs sold under the Holiday Showtime / Show Home brands. They speak Qualcomm/CSR's CSRmesh over a GATT bridge; this library reimplements that framing so you can control a ball from Python (and powers the Home Assistant lightball integration).

Install

pip install lightball-ble

Usage

You provide a bleak BLEDevice (the ball rotates its BLE address, so re-resolve it by the stable local name — e.g. LAB00001CEB11 — before each use):

from bleak import BleakScanner
from lightball_ble import LightBall

device = await BleakScanner.find_device_by_name("LAB00001CEB11")
ball = LightBall(device, "LAB00001CEB11")

await ball.set_state(mode=1, color=0, level=2)   # steady, red, mid brightness
await ball.set_show(6)                            # MultiColor animated show
await ball.turn_off()

# Re-resolve the address later, then reuse the client:
ball.set_ble_device(await BleakScanner.find_device_by_name("LAB00001CEB11"))

Command reference

• set_state(mode, color, level, *, turn_on=True) — commonMode: animation mode (0=off, 1=steady, 2=blink, 5=fade, 7=waves …), palette color index (0=red … 28=MultiColor), brightness level 0–4.
• set_show(show_sel, *, turn_on=True) — showView animated preset (0=Christmas … 6=MultiColor).
• turn_off().

Protocol

lightball_ble.protocol exposes the low-level framing if you need it:

• Network key: reverse(SHA-256(b"686868\x00MCP"))[:16] (a fixed, product-line shared key — derive_key()).
• Packet: AES-128 counter-mode payload + an 8-byte byte-reversed HMAC-SHA256 MIC
  • a trailing 0xFF (make_packet).
• Transport: packets > 20 bytes split across two GATT control points (split_writes).

This was reverse-engineered from the official "Show Home" Android app; see the lightball project for the full writeup.

Develop

pip install -e ".[test]"
pytest --cov=lightball_ble --cov-report=term-missing
ruff check . && ruff format --check .

License

Apache-2.0.