busylight-for-humans 0.12.3

Control USB connected LED lights, like a human.

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.

Six Lights Attached to One Host
Back to Front, Left to Right
BlyncLight, BlyncLight Plus, Busylight
Blink(1), Flag, BlinkStick

Features

• Control lights from the command-line.
• Control lights via a Web API.
• Import busylight into your own project.
• Supports Six Vendors & Multiple Models:
  • Agile Innovative BlinkStick
  • Embrava Blynclight
  • Kuando BusyLight
  • Luxafor Flag
  • Plantronics Status Indicator
  • ThingM Blink1
• Works on MacOS, Linux, probably Windows and BSD too!
• Tested extensively on Raspberry Pi 3b+, Zero W and 4

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, and any public hardware documentation you are aware of.

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]

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:

$ busylight serve
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
  ...
  $ curl -s http://localhost:8888/light/0/on | jq
  {
    "light_id": 0,
    "action": "on",
    "color": "green"
  }
  $ curl -s http://localhost:8888/light/0/off | jq
  {
    "light_id": 0,
    "action": "off"
  }
  $ curl -s http://localhost:8888/light/0/on/purple | jq
  {
    "light_id": 0,
    "action": "on",
    "color": "purple"
  }
  $ curl -s http://localhost:8888/light/0/off | jq
  {
    "light_id": 0,
    "action": "off"
  }
  $ curl -s http://localhost:8888/lights/on | jq
  {
    "light_id": "all",
    "action": "on",
    "color": "green"
  }
  $ 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"
  }

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))

Slightly More Complicated

The busylight package includes a manager class that great for working with multiple lights or lights that require a little more direct intervention like the Kuando Busylight series.

from busylight.manager import LightManager, ALL_LIGHTS
from busylight.effects import rainbow

manager = LightManager()
for light in manager.lights:
   print(light.name)

manager.apply_effect_to_light(ALL_LIGHTS, rainbow)
...
manager.lights_off(ALL_LIGHTS)