Control USB LED status lights from Python.
26 devices · 9 vendors · CLI · HTTP API · Python library

Flag¹, Busylight Alpha², Blynclight Plus³, Blink(1)⁴, Mute⁵, Blynclight⁶, Orb⁷, BusyLight Omega⁸, BlinkStick Square⁹, Blynclight Mini¹⁰, MuteMe Original¹¹, fit-statUSB¹², MuteSync¹³, Status Indicator¹⁴

Quick Start

# Turn on a green light right now
uvx --from busylight-for-humans busylight on

# Red, blinking, then off
uvx --from busylight-for-humans busylight blink red
uvx --from busylight-for-humans busylight off

# Or from Python
from busylight_core import Light

light = Light.first_light()
light.on((0, 128, 0))   # green
light.off()

Supported Hardware

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

Multi-LED targeting supported on BlinkStick variants, Luxafor Flag, and Blink(1) mk2.

Packages

This repository contains two packages that work together:

Busylight for Humans™ — CLI & Web API

The user-facing tools. Install this if you want to control lights from the command line or expose an HTTP API for automation.

pip install busylight-for-humans

Command line:

busylight on red          # solid red
busylight blink blue      # blinking blue
busylight rainbow         # cycle through colors
busylight on green --led 1  # target specific LED
busylight off             # turn off

Web API:

pip install busylight-for-humans[webapi]
busyserve  # starts on http://localhost:8000

curl "http://localhost:8000/light/0/on?color=red"
curl "http://localhost:8000/lights/off"

Full documentation

Busylight Core for Humans™ — Python Library

The device communication layer you can use if you're building your own tools or integrating status lights into a larger system.

uv add busylight_core

from busylight_core import Light

# Find and control lights
for light in Light.all_lights():
    print(f"{light.name} by {light.vendor}")
    light.on((255, 0, 0))  # red

# Async effects
import asyncio
light = Light.first_light()
asyncio.run(light.blink(color=(0, 0, 255), speed=1))

Features: multi-vendor abstraction, HID and serial support, async effects, button/input detection, multi-LED targeting, plugin architecture for adding new devices.

Full documentation

Platform Support

• macOS — works out of the box
• Linux — requires udev rules for USB access:

  busylight udev-rules -o 99-busylights.rules
  sudo cp 99-busylights.rules /etc/udev/rules.d/
  sudo udevadm control -R

• Windows — may work, untested, patches welcome

Contributing

Contributions welcome! See CONTRIBUTING.md for development setup, workflow, and guidelines. This is a uv workspace — one clone, one venv, both packages.

Gratitude

Thank you to @todbot and ThingM for gifting blink(1) mk3 lights to support this project.

License

Both packages are licensed under the Apache License 2.0.