A unified Python library for controlling USB status lights (busylights) from multiple vendors

busylight-core provides a consistent interface to control various USB-connected status lights, commonly used for indicating availability, meeting status, or system notifications. Were you looking for a command-line interface to control your lights? Check out Busylight for Humans™!

• Multi-Vendor Support - Control devices from nine vendors.
• Multiple Connection Types - HID and Serial device support.
• Python Library - Clean, object-oriented API for easy integration.
• Input Detection - Button press handling on interactive devices.
• Multi-LED Support - Control devices with 1-192 individual LEDs.
• Extensible Architecture - Easy to add support for new devices.

uv add busylight_core

python3 -m pip install busylight_core

Basic usage (any compatible device):

from busylight_core import Light

lights = Light.all_lights()

print(f"Found {len(lights)} light(s)")

for light in lights:
    light.on((255, 0, 0))  # Turn on red
    light.off()            # Turn off

Vendor-specific usage (recommended for production):

from busylight_core import EmbravaLights, LuxaforLights, KuandoLights

# Get all Embrava devices
embrava_lights = EmbravaLights.all_lights()
if embrava_lights:
    light = embrava_lights[0]
    light.on((255, 0, 0))  # Red

# Get all Luxafor devices
luxafor_lights = LuxaforLights.all_lights()
for light in luxafor_lights:
    light.on((0, 255, 0))  # Green

# Get first Kuando device
try:
    kuando_light = KuandoLights.first_light()
    kuando_light.on((0, 0, 255))  # Blue
except NoLightsFoundError:
    print("No Kuando devices found")

Meeting Status Indicator:

from busylight_core import Light

red = (255, 0, 0)
green = (0, 128, 0)
yellow = (255, 255, 0)

# Any device approach
light = Light.first_light()

# Available
light.on(green)

# In meeting  
light.on(red)

# Away
light.on(yellow)

light.off()

Enhanced Meeting Status with Audio (Embrava devices):

from busylight_core import EmbravaLights, NoLightsFoundError

try:
    light = EmbravaLights.first_light()
    
    # Available (quiet green)
    light.on((0, 255, 0))
    
    # In meeting (red with audio alert)
    light.on((255, 0, 0), sound=True)
    
    # Away (dim yellow)
    light.on((255, 255, 0))
    light.dim()
    
except NoLightsFoundError:
    print("No Embrava devices found")

For detailed documentation including API reference, advanced usage examples, and device-specific information:

• Full Documentation: https://JnyJny.github.io/busylight_core/
• Installation Guide: Getting Started
• Quick Start Guide: Usage Guide
• API Reference: API Docs

This project and it's virtual environment is managed using uv and is configured to support automatic activation of virtual environments using direnv. Development activites such as linting and testing are automated via Poe The Poet, run poe after cloning this repo for a list of tasks.

Check out CONTRIBUTING.md for more development details.