https://github.com/techniker/mqttbusypy
MQTT Busylight Controller for Kuando HID Busylights
https://github.com/techniker/mqttbusypy
busylight hid hid-device kuando led mqtt python
Last synced: 5 months ago
JSON representation
MQTT Busylight Controller for Kuando HID Busylights
- Host: GitHub
- URL: https://github.com/techniker/mqttbusypy
- Owner: techniker
- License: mit
- Created: 2024-06-25T12:02:47.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2025-12-13T03:33:21.000Z (6 months ago)
- Last Synced: 2025-12-14T17:49:26.304Z (6 months ago)
- Topics: busylight, hid, hid-device, kuando, led, mqtt, python
- Language: Python
- Homepage:
- Size: 17.6 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MQTT Busylight Controller for Kuando HID Busylights
## Overview
This project provides a simple MQTT-based controller for Kuando HID-based Busylights (Alpha and Omega).
It allows controlling colors, blinking, fading effects, rainbow cycling, and ringtones by sending **plain text** MQTT payloads.
It supports:
- Opening the device by **VID/PID**, **autodetect by VID**, or explicit **HID device path**
- A keep-alive loop to prevent the Busylight from going idle
- Periodic status output to the console
- Optional daemon mode on POSIX systems (Linux)
## Features
- Control Kuando Busylights via MQTT.
- Solid colors (`color_*`)
- Blinking (`blink_color_*`)
- Fade effect (`fade_*`, `fade_off`)
- Rainbow effect (`rainbow_on`, `rainbow_off`)
- Ringtones (`ring_*`, `stop_ringtone`)
- Raw RGB payloads (`raw_color R,G,B`)
- Device control (`reset_device`, `device_bootloader`)
- Keep-alive thread (configurable interval/timeout)
- Status logging (device/mqtt/effect/last command)
- CLI options for all settings
- Daemon option with pidfile (POSIX only)
## Hardware Requirements
- Kuando Busylight UC Omega or Alpha (HID USB device)
USB-IDs include:
- `27bb:3bca` (PLENOM/Kuando devices)
- `27bb:3bcf`, `27bb:3bcd` (other variants)
- Some Alpha devices may use different VID/PID combinations
## Software Requirements
- Linux/OSX (recommended) or other OS supported by hidapi
- Python 3.x
- Python packages:
- `hid` (python-hidapi wrapper)
- `paho-mqtt`
## Installation
Create and activate a virtual environment, then install dependencies:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install hid paho-mqtt
```
**Permissions (Linux / Debian)**
If the HID device only opens as root, you likely need a udev rule for /dev/hidraw*.
Example rule for Kuando/Plenom (VID 27bb):
```
sudo tee /etc/udev/rules.d/99-busylight.rules >/dev/null <<'RULE'
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="27bb", MODE="0660", GROUP="plugdev", TAG+="uaccess"
RULE
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo usermod -aG plugdev "$USER"
```
## Usage
### List HID devices:
Use this to verify VID/PID and to get a usable HID path:
```
python3 busylight_mqtt_v1.py --list-devices
```
Print supported MQTT commands:
```
python3 busylight_mqtt_v1.py --print-commands
```
Run the controller (example with explicit VID/PID):
```
python3 busylight_mqtt_v1.py \
--vendor-id 0x27bb --product-id 0x3bca \
--mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \
--mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'
```
Run with autodetect (VID only):
If you omit --product-id, the program will pick the first device matching the vendor ID:
```
python3 busylight_mqtt_v1.py \
--vendor-id 0x27bb \
--mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \
--mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'
```
Run by HID path (most deterministic)
```
python3 busylight_mqtt_v1.py --list-devices
```
Then copy the PATH=... value and run:
```
python3 busylight_mqtt_v1.py \
--device-path "b'...your path bytes...'" \
--mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \
--mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'
````
```
Daemon mode (POSIX)
python3 busylight_mqtt_v1.py --daemon --pidfile /run/busylight_mqtt.pid \
--vendor-id 0x27bb --product-id 0x3bca \
--mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \
--mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'
```
## MQTT Control
### Topic
```
Default topic:
busylight/control
Override with:
--mqtt-topic
Payload format
Payload is plain UTF-8 text
One command per message
No JSON required
Example Commands
Solid colors
color_red
color_green
color_blue
color_yellow
color_cyan
color_magenta
color_white
color_orange
color_purple
color_pink
color_brown
Blinking
blink_color_red
blink_color_green
blink_color_blue
blink_color_yellow
blink_color_cyan
blink_color_magenta
blink_color_white
blink_color_orange
blink_color_purple
blink_color_pink
blink_color_brown
```
### Fade:
Accepted forms:
```
fade_red, fade_green, fade_blue, ...
fade_color_red, fade_color_green, ...
Stop fade:
fade_off
Fade behavior is controlled by:
--fade-step
--fade-delay
```
### Rainbow effect:
```
rainbow_on
rainbow_off
Rainbow speed is controlled by:
--rainbow-delay
```
### Raw RGB color:
Format:
```
raw_color R,G,B
```
Example:
raw_color 255,0,0
### Ringtones:
```
ring_off
ring_open_office
ring_quiet
ring_funky
ring_fairy_tale
ring_kuando_train
ring_telephone_nordic
ring_telephone_original
ring_telephone_pick_me_up
ring_buzz
Stop ringtone:
stop_ringtone
Ringtone volume is controlled by:
--ringtone-volume (0..7)
```
### Other device commands:
```
off — stop effects and turn LEDs off
reset_device — send reset opcode
device_bootloader — switch device into bootloader mode
```
### Status Output
* The program periodically logs a line like:
* device state (opened or not)
* VID/PID
* mqtt connection state
* current effect (none/rainbow/fade)
* last received command payload
Control the interval with:
--status-interval 5
### Key options:
* HID:
--vendor-id 0x27bb
--product-id 0x3bca
--device-path
--list-devices
* MQTT:
--mqtt-host
--mqtt-port
--mqtt-topic
--mqtt-client-id
--mqtt-user
--mqtt-password
--mqtt-keepalive
* Effects:
--rainbow-delay
--fade-step <1..255>
--fade-delay
--ringtone-volume <0..7>
* Keep-alive:
--ka-timeout <0..15>
--ka-interval
* Logging/status:
--log-level DEBUG|INFO|WARNING|ERROR
--status-interval
* Daemon:
--daemon
--pidfile
* Daemon mode: optional POSIX daemonization with pidfile.
License
This project is licensed under the MIT License. See the LICENSE file for details.