Skip to content

README.md

Latest commit

 

History

History
354 lines (220 loc) · 5.65 KB

README.md

File metadata and controls

354 lines (220 loc) · 5.65 KB

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.