BusyLight for Humans™ gives you control of USB attached LED lights from a variety of vendors. Lights can be controlled via the command-line or using a HTTP API. Please consider Busylight Core if you'd like to integrate USB light control into your own Python application.

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

Features

• Control lights from the command-line.
• Control lights via HTTP API.
• Supported on MacOS and Linux
• Windows support is in progress.
• Support for twenty-three devices from nine vendors:

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

Request support for a new device by opening an issue in the Busylight Core project.

Basic Install

Installs only the command-line busylight tool and associated modules.

uvx

uvx --from busylight-for-humans busylight list

pip

python3 -m pip install busylight-for-humans 

Web API Install

Installs uvicorn and FastAPI in addition to busylight:

uvx

uvx --from "busylight-for-humans[webapi]" busyserve

pip

python3 -m pip install busylight-for-humans[webapi]

Development Install

This project is managed using uv for:

• dependency management
• pytest configuration
• versioning
• optional dependencies
• virtual environment creation
• building packages
• publishing packages to PyPi via GitHub Actions

$ python3 -m pip install uv
$ cd path/to/busylight
$ uv sync --all-extras
$ source .venv/bin/activate
<venv> $ which busylight
<venv> $ which busyserve
<venv> $ pytest

After installing into the virtual environment, the project is now available in editable mode. Changes made in the source will be reflected in the runtime behavior when running in the uv managed virtual environment.

Linux Post-Install Activities

Linux controls access to USB devices via the udev subsystem. By default it denies non-root users access to devices it doesn't recognize. I've got you covered!

You'll need root access to configure the udev rules:

$ busylight udev-rules -o 99-busylights.rules
$ sudo cp 99-busylights.rules /etc/udev/rules.d
$ sudo udevadm control -R
$ # unplug/plug your light
$ busylight on

Command-Line Examples

$ busylight on               # light turns on green
$ busylight on red           # now it's shining a friendly red
$ busylight on 0xff0000      # still red
$ busylight on #00ff00       # now it's blue!
$ busylight blink            # it's slowly blinking on and off with a red color
$ busylight blink green fast # blinking faster green and off
$ busylight --all on         # turn all lights on green
$ busylight --all off        # turn all lights off

HTTP API Examples

First start the busylight API server using the busyserv command line interface:

$ busyserve -D
INFO:     Started server process [40064]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
...

The API is fully documented and available via these URLs:

• https://localhost:8000/redoc
• https://localhost:8000/docs

Now you can use the web API endpoints which return JSON payloads:

  $ curl -s http://localhost:8000/lights/status | jq
  ...
  
  $ curl -s http://localhost:8000/light/0/status | jq
  ...
  
  $ curl -s http://localhost:8000/light/0/on | jq
  {
    "light_id": 0,
    "action": "on",
    "color": "green",
    "rgb": [0, 128, 0]
  }
  
  $ curl -s http://localhost:8000/light/0/off | jq
  {
    "light_id": 0,
    "action": "off"
  }
  
  $ curl -s http://localhost:8000/light/0/on?color=purple | jq
  {
    "light_id": 0,
    "action": "on",
    "color": "purple",
    "rgb": [128, 0, 128]
  }
  
  $ curl -s http://localhost:8000/lights/on | jq
  {
    "light_id": "all",
    "action": "on",
    "color": "green",
    "rgb", [0, 128, 0]
  }
  
  $ curl -s http://localhost:8000/lights/off | jq
  {
    "light_id": "all",
    "action": "off"
  }
  
  $ curl -s http://localhost:8000/lights/rainbow | jq
  {
    "light_id": "all",
    "action": "effect",
    "name": "rainbow"
  }

Authentication

The API can be secured with a simple username and password through HTTP Basic Authentication. To require authentication for all API requests, set the BUSYLIGHT_API_USER and BUSYLIGHT_API_PASS environmental variables before running busyserve.

⚠️ SECURITY WARNING: HTTP Basic Auth sends usernames and passwords in cleartext (i.e., unencrypted). Use of SSL is highly recommended!

Gratitude

Thank you to @todbot and the very nice people at ThingM who graciously and unexpectedly gifted me with two blink(1) mk3 lights!

---