Skip to content

Commit 55681cf

Browse files
JnyJnyJnyJny
committed
docs: update README with current implementation details
- Remove marketing language, use direct technical descriptions - Add LED parameter documentation for multi-LED device support - Update command-line examples with LED targeting options - Enhance HTTP API examples with LED parameter usage - Add LED parameter reference section with device-specific behavior - Update vendor table to show LED support capabilities - Simplify development install instructions - Reflect current architecture and feature set accurately
1 parent b3a68fa commit 55681cf

File tree

1 file changed

+100
-88
lines changed

1 file changed

+100
-88
lines changed

‎README.md‎

Lines changed: 100 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,9 @@
1212
![Monthly Downloads][monthly-downloads]
1313
<br>
1414

15-
[BusyLight for Humans™][busylight-for-humans] gives you control of USB
16-
attached LED lights from a variety of vendors. Lights can be
17-
controlled via the command-line or using a HTTP API. Please consider
18-
[Busylight Core][busylight-core] if you'd like to integrate USB light
19-
control into your own Python application.
15+
[BusyLight for Humans][busylight-for-humans] controls USB LED lights from multiple vendors.
16+
Use the command-line interface or HTTP API to turn lights on/off, change colors, and apply effects.
17+
For Python integration, use [Busylight Core][busylight-core] directly in your applications.
2018

2119
![All Supported Lights][DEMO]
2220
Flag<sup>1</sup>,
@@ -35,23 +33,23 @@ MuteSync<sup>13</sup>,
3533
Blynclight Plus<sup>14</sup>
3634

3735
## Features
38-
- Control lights from the command-line.
39-
- Control lights via HTTP API.
40-
- Supported on MacOS and Linux
41-
- Windows support is in progress.
42-
- Support for twenty-three devices from nine vendors:
43-
44-
| **Vendor** | **Models** |
45-
|------------|-------------|
46-
| [**Agile Innovative**][2] | BlinkStick, BlinkStick Pro, BlinkStick Square, BlinkStick Strip, BlinkStick Nano, BlickStick Flex |
47-
| [**Compulab**][8] | fit-statUSB |
48-
| [**EPOS**][11] | Busylight |
49-
| [**Embrava**][3] | Blynclight, Blynclight Mini, Blynclight Plus |
50-
| [**Kuando**][4] | Busylight Alpha, BusyLight Omega |
51-
| [**Luxafor**][5] | Bluetooth, Flag, Mute, Orb, Busy Tag |
52-
| [**Plantronics**][3] | Status Indicator |
53-
| [**MuteMe**][7] | MuteMe Original, Mute Mini, MuteSync |
54-
| [**ThingM**][6] | Blink(1) |
36+
- Command-line interface with color, effect, and LED targeting options
37+
- HTTP API with full documentation and authentication support
38+
- Individual LED control for multi-LED devices (Blink1 mk2, BlinkStick variants)
39+
- Cross-platform support: macOS and Linux (Windows in development)
40+
- Support for 23 devices from 9 vendors:
41+
42+
| **Vendor** | **Models** | **LED Support** |
43+
|------------|-------------|-----------------|
44+
| [**Agile Innovative**][2] | BlinkStick, BlinkStick Pro, BlinkStick Square, BlinkStick Strip, BlinkStick Nano, BlinkStick Flex | Multi-LED targeting |
45+
| [**Compulab**][8] | fit-statUSB | Single LED |
46+
| [**EPOS**][11] | Busylight | Single LED |
47+
| [**Embrava**][3] | Blynclight, Blynclight Mini, Blynclight Plus | Single LED |
48+
| [**Kuando**][4] | Busylight Alpha, BusyLight Omega | Single LED |
49+
| [**Luxafor**][5] | Bluetooth, Flag, Mute, Orb, Busy Tag | Single LED |
50+
| [**Plantronics**][3] | Status Indicator | Single LED |
51+
| [**MuteMe**][7] | MuteMe Original, Mute Mini, MuteSync | Single LED |
52+
| [**ThingM**][6] | Blink(1), Blink(1) mk2 | Blink(1) mk2: Multi-LED |
5553

5654
Request support for a new device by [opening an issue][busylight-core-issues]
5755
in the Busylight Core project.
@@ -87,15 +85,7 @@ python3 -m pip install busylight-for-humans[webapi]
8785

8886
## Development Install
8987

90-
This project is managed using [uv][uv-docs] for:
91-
- dependency management
92-
- pytest configuration
93-
- versioning
94-
- optional dependencies
95-
- virtual environment creation
96-
- building packages
97-
- publishing packages to PyPi via GitHub Actions
98-
88+
This project uses [uv][uv-docs] for dependency management, virtual environments, and packaging.
9989

10090
```console
10191
$ python3 -m pip install uv
@@ -107,10 +97,7 @@ $ source .venv/bin/activate
10797
<venv> $ pytest
10898
```
10999

110-
After installing into the virtual environment, the project is now
111-
available in editable mode. Changes made in the source will be
112-
reflected in the runtime behavior when running in the uv managed
113-
virtual environment.
100+
The project installs in editable mode. Source changes are reflected immediately when running in the virtual environment.
114101

115102
## Linux Post-Install Activities
116103

@@ -130,17 +117,26 @@ $ busylight on
130117

131118
## Command-Line Examples
132119

120+
### Basic Usage
133121
```console
134122
$ busylight on # light turns on green
135-
$ busylight on red # now it's shining a friendly red
136-
$ busylight on 0xff0000 # still red
137-
$ busylight on #0000ff # now it's blue!
138-
$ busylight blink # it's slowly blinking on and off with a red color
139-
$ busylight blink green fast # blinking faster green and off
123+
$ busylight on red # turns red
124+
$ busylight on 0xff0000 # red using hex
125+
$ busylight on #0000ff # blue using hex
126+
$ busylight blink # slow red blinking
127+
$ busylight blink green fast # fast green blinking
140128
$ busylight --all on # turn all lights on green
141129
$ busylight --all off # turn all lights off
142130
```
143131

132+
### LED Targeting (Multi-LED Devices)
133+
```console
134+
$ busylight on red --led 1 # turn on top LED only (Blink1 mk2)
135+
$ busylight on blue --led 2 # turn on bottom LED only
136+
$ busylight blink green --led 1 --count 5 # blink top LED 5 times
137+
$ busylight off # turn off all LEDs (default)
138+
```
139+
144140
## HTTP API Examples
145141

146142
First start the `busylight` API server using the `busyserv` command line interface:
@@ -161,57 +157,73 @@ The API is fully documented and available via these URLs:
161157

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

160+
### Basic Operations
164161
```console
165-
$ curl -s http://localhost:8000/lights/status | jq
166-
...
167-
168-
$ curl -s http://localhost:8000/light/0/status | jq
169-
...
170-
171-
$ curl -s http://localhost:8000/light/0/on | jq
172-
{
173-
"light_id": 0,
174-
"action": "on",
175-
"color": "green",
176-
"rgb": [0, 128, 0]
177-
}
178-
179-
$ curl -s http://localhost:8000/light/0/off | jq
180-
{
181-
"light_id": 0,
182-
"action": "off"
183-
}
184-
185-
$ curl -s http://localhost:8000/light/0/on?color=purple | jq
186-
{
187-
"light_id": 0,
188-
"action": "on",
189-
"color": "purple",
190-
"rgb": [128, 0, 128]
191-
}
192-
193-
$ curl -s http://localhost:8000/lights/on | jq
194-
{
195-
"light_id": "all",
196-
"action": "on",
197-
"color": "green",
198-
"rgb", [0, 128, 0]
199-
}
200-
201-
$ curl -s http://localhost:8000/lights/off | jq
202-
{
203-
"light_id": "all",
204-
"action": "off"
205-
}
206-
207-
$ curl -s http://localhost:8000/lights/rainbow | jq
208-
{
209-
"light_id": "all",
210-
"action": "effect",
211-
"name": "rainbow"
212-
}
162+
$ curl -s http://localhost:8000/lights/status | jq
163+
# Returns status of all lights
164+
165+
$ curl -s http://localhost:8000/light/0/on | jq
166+
{
167+
"light_id": 0,
168+
"action": "on",
169+
"color": "green",
170+
"rgb": [0, 128, 0],
171+
"led": 0
172+
}
173+
174+
$ curl -s http://localhost:8000/light/0/on?color=purple | jq
175+
{
176+
"light_id": 0,
177+
"action": "on",
178+
"color": "purple",
179+
"rgb": [128, 0, 128],
180+
"led": 0
181+
}
182+
183+
$ curl -s http://localhost:8000/light/0/blink?color=red&count=3 | jq
184+
{
185+
"light_id": 0,
186+
"action": "blink",
187+
"color": "red",
188+
"rgb": [255, 0, 0],
189+
"count": 3,
190+
"led": 0
191+
}
213192
```
214193

194+
### LED Targeting (Multi-LED Devices)
195+
```console
196+
$ curl -s "http://localhost:8000/light/0/on?color=red&led=1" | jq
197+
{
198+
"light_id": 0,
199+
"action": "on",
200+
"color": "red",
201+
"rgb": [255, 0, 0],
202+
"led": 1
203+
}
204+
205+
$ curl -s "http://localhost:8000/light/0/blink?color=blue&led=2&count=5" | jq
206+
{
207+
"light_id": 0,
208+
"action": "blink",
209+
"color": "blue",
210+
"rgb": [0, 0, 255],
211+
"count": 5,
212+
"led": 2
213+
}
214+
```
215+
216+
## LED Parameter Reference
217+
218+
For devices with multiple LEDs (like Blink1 mk2), use the `--led` option (CLI) or `led` parameter (API):
219+
220+
- `led=0`: Control all LEDs (default behavior)
221+
- `led=1`: Control first/top LED
222+
- `led=2`: Control second/bottom LED
223+
- `led=3+`: Control additional LEDs (BlinkStick variants)
224+
225+
Single-LED devices ignore the LED parameter. Device-specific LED indexing varies by manufacturer.
226+
215227
### Authentication
216228
The API can be secured with a simple username and password through
217229
[HTTP Basic Authentication][BASICAUTH]. To require authentication

0 commit comments

Comments
 (0)