busylight-core 0.14.1

Busylight Core Implementation for Humans, presumably like you!

Busylight Core for Humans™

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™!

Features

• 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.

Supported Hardware

Vendor	Device Models
Agile Innovative	BlinkStick, BlinkStick Pro, BlinkStick Flex, BlickStick Nano, BlinkStick Strip, BlinkStick Square
CompuLab	fit-statUSB
EPOS	Busylight
Embrava	Blynclight, Blynclight Mini, Blynclight Plus
Kuando	Busylight Alpha, Busylight Omega
Luxafor	Flag, Mute, Orb, Bluetooth
MuteMe	MuteMe, MuteMe Mini, MuteSync
Plantronics	Status Indicator
ThingM	Blink(1)

Installation

Add to Your Project with uv

uv add busylight_core

Install with pip

python3 -m pip install busylight_core

Usage

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), sound=True)  # Red with audio alert
    light.dim()  # Reduce brightness

# 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
    kuando_light.keepalive()  # Required for Kuando devices
except NoLightsFoundError:
    print("No Kuando devices found")

Common Use Cases

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

Development

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.

---