Control USB connected LED lights, like a human.
Project description
BusyLight for Humans™ gives you control of USB attached LED lights from a variety of vendors. Lights can be controlled via the command-line, using a HTTP API or imported directly into your own Python project.
Flag1,
Busylight Alpha2,
Status Indicator3,
Blink(1)4,
Mute5,
Blynclight6.
Orb7,
BusyLight Omega8,
BlinkStick Square9,
Blynclight Mini10,
MuteMe Original11,
fit-statUSB12,
MuteSync13,
Blynclight Plus14
Features
- Control lights from the command-line.
- Control lights via a Web API.
- Import
busylight
into your own Python project. - Supported on MacOS and Linux
- Windows not currently supported.
- Supports nine vendors & fifteen devices:
Vendor | |||
---|---|---|---|
Agile Innovative | BlinkStick Square | ||
Compulab | fit-statUSB | ||
Embrava | Blynclight | Blynclight Mini | Blynclight Plus |
Kuando | Busylight Alpha | BusyLight Omega | |
Luxafor | Flag | Mute | Orb |
Plantronics | Status Indicator | ||
MuteMe | MuteMe Original | Mute Mini | |
MuteSync | MuteSync | ||
ThingM | Blink(1) |
If you have a USB light that's not on this list open an issue with:
- the make and model device you want supported
- where I can get one
- any public hardware documentation you are aware of
Or even better, open a pull request!
Gratitude
Thank you to @todbot and the very nice people at ThingM who
graciously and unexpectedly gifted me with two blink(1) mk3
lights!
Basic Install
Installs only the command-line busylight
tool and associated
modules.
$ python3 -m pip install busylight-for-humans
Web API Install
Installs uvicorn
and FastAPI
in addition to busylight
:
$ python3 -m pip install busylight-for-humans[webapi]
Development Install
I use the tool poetry to manage various aspects of this project, including:
- dependencies
- pytest configuration
- versioning
- optional dependencies
- virtual environment creation
- building packages
- publishing packages to PyPi
$ python3 -m pip install poetry
$ cd path/to/busylight
$ poetry shell
<venv> $ poetry install -E webapi
<venv> $ which busylight
<venv> $ which busyserve
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 poetry initiated shell.
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 [20189]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8888 (Press CTRL+C to quit)
The API is fully documented and available @ https://localhost:8888/redoc
Now you can use the web API endpoints which return JSON payloads:
$ curl -s http://localhost:8888/lights/status | jq
...
$ curl -s http://localhost:8888/light/0/status | jq
...
$ curl -s http://localhost:8888/light/0/on | jq
{
"light_id": 0,
"action": "on",
"color": "green",
"rgb": [0, 128, 0]
}
$ curl -s http://localhost:8888/light/0/off | jq
{
"light_id": 0,
"action": "off"
}
$ curl -s http://localhost:8888/light/0/on?color=purple | jq
{
"light_id": 0,
"action": "on",
"color": "purple",
"rgb": [128, 0, 128]
}
$ curl -s http://localhost:8888/lights/on | jq
{
"light_id": "all",
"action": "on",
"color": "green",
"rgb", [0, 128, 0]
}
$ curl -s http://localhost:8888/lights/off | jq
{
"light_id": "all",
"action": "off"
}
$ curl -s http://localhost:8888/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
.
:warning: SECURITY WARNING: HTTP Basic Auth sends usernames and passwords in cleartext (i.e., unencrypted). Use of SSL is highly recommended!
Code Examples
Adding light support to your own python applications is easy!
Simple Case: Turn On a Single Light
In this example, we pick an Embrava Blynclight to activate with the color white.
from busylight.lights.embrava import Blynclight
light = Blynclight.first_light()
light.on((255, 255, 255))
Not sure what light you've got?
from busylight.lights import USBLight
light = USBLight.first_light()
light.on((0xff, 0, 0xff))
Slightly More Complicated
The busylight
package includes a manager class that's great for
working with multiple lights or lights that require a little
more direct intervention like the Kuando Busylight family.
from busylight.manager import LightManager
from busylight.effects import Effects
manager = LightManager()
for light in manager.lights:
print(light.name)
rainbow = Effects.for_name("spectrum")(duty_cycle=0.05)
manager.apply_effect(rainbow)
...
manager.off()
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for busylight-for-humans-0.22.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2560d076cf7eba2be683c65129a1ec7d8b39f3010ff0d6ee44c10117dbb7f342 |
|
MD5 | 70427ee14e6ab0e37e7b2d8dcfa8d3c0 |
|
BLAKE2b-256 | 26eef8e77185b4687a32384d8bd7ae90fd7506bb8410f78e2a86bb3b9afa80c2 |
Hashes for busylight_for_humans-0.22.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 14be9bc9f5488ae7b6b1a122b2e17c3c1410a956952da1154b88947bc7bf164f |
|
MD5 | 6ef5fc765bce9f830dca944705ae2937 |
|
BLAKE2b-256 | 11ffa2a96d55c65f89630203600e4768bcd887a9a69713dc4869f06756545723 |