busylight-core 0.3.0

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.

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.
• Rich Light Control - Colors, brightness, flash patterns, fade effects.
• Audio Capabilities - Sound playback and mute/unmute on supported devices.
• Input Detection - Button press handling on interactive devices.
• Multi-LED Support - Control devices with 1-192 individual LEDs.
• Async Task Management - Built-in support for animations and effects.
• Extensible Architecture - Easy to add support for new devices.

Supported Hardware

Vendor	Device Models	Special Features
Embrava	Blynclight, Blynclight Mini, Blynclight Plus	Audio playback, flash control, dim/bright
Kuando	Busylight Alpha, Busylight Omega	Keepalive functionality
Luxafor	Flag, Mute, Orb, Bluetooth	Button input (Mute model)
ThingM	Blink(1)	Fade effects, feature reports
Agile Innovative	BlinkStick (multiple variants)	1-192 LEDs, channel control
MuteMe	MuteMe, MuteMe Mini	Button input detection
MuteSync	Button	Button input detection
Plantronics	Status Indicator	Basic light control
CompuLab	fit-statUSB	Basic light control

Installation

Install with uv

uv add busylight_core

Install with pip

python3 -m pip install busylight_core

Usage

from busylight_core import Light

# Find all connected lights
lights = Light.available()
print(f"Found {len(lights)} device(s)")

# Control a specific device
if lights:
    light = lights[0]
    light.on((255, 0, 0))  # Turn on red
    light.off()            # Turn off

Common Use Cases

Meeting Status Indicator:

from busylight_core import Light

light = Light.first_light()

# Available - green
light.on((0, 255, 0))

# In meeting - red  
light.on((255, 0, 0))

# Away - yellow
light.on((255, 255, 0))

light.off()

Documentation

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

• Full Documentation: https://JnyJny.github.io/busylight_core/
• Quick Start Guide: Getting Started
• Examples: Usage Examples
• 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][poethepoet], run poe after cloning this repo for a list of tasks.

Clone

git clone https://github.com/JnyJny/busylight_core
cd busylight_core

Allow Direnv optional but recommended

direnv allow

Install Dependencies

uv sync --all-groups

Run poe

poe --help

Release Management

This project uses automated release management with GitHub Actions:

Version Bumping

• poe publish_patch - Bump patch version, commit, tag, and push
• poe publish_minor - Bump minor version, commit, tag, and push
• poe publish_major - Bump major version, commit, tag, and push

Any of the publish tasks will trigger testing, publishing to PyPi, and a GitHub release.

Release Notes

• poe changelog - Generate changelog since last tag
• poe release-notes - Generate release notes file

Automatic Releases

When you push a version tag (e.g., v1.0.0), the unified GitHub Actions workflow will:

1. Test - Run tests across all supported Python versions and OS combinations
2. Publish - Build and publish to PyPI (only if tests pass)
3. GitHub Release - Create GitHub release with auto-generated notes and artifacts (only if PyPI publish succeeds)

This ensures a complete release pipeline where each step depends on the previous step's success.

MkDocs Documentation

• poe docs-serve - Serve documentation locally
• poe docs-build - Build documentation
• poe docs-deploy - Deploy to GitHub Pages

---