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:

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