{"id":15163347,"url":"https://github.com/techniker/mqttbusypy","last_synced_at":"2026-01-20T06:02:12.320Z","repository":{"id":246032449,"uuid":"819901458","full_name":"techniker/MQTTBusyPy","owner":"techniker","description":"MQTT Busylight Controller for Kuando HID Busylights","archived":false,"fork":false,"pushed_at":"2025-12-13T03:33:21.000Z","size":18,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-14T17:49:26.304Z","etag":null,"topics":["busylight","hid","hid-device","kuando","led","mqtt","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/techniker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-25T12:02:47.000Z","updated_at":"2025-12-13T03:31:34.000Z","dependencies_parsed_at":"2024-06-25T13:42:10.170Z","dependency_job_id":null,"html_url":"https://github.com/techniker/MQTTBusyPy","commit_stats":null,"previous_names":["techniker/mqttbusypy"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/techniker/MQTTBusyPy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techniker%2FMQTTBusyPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techniker%2FMQTTBusyPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techniker%2FMQTTBusyPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techniker%2FMQTTBusyPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/techniker","download_url":"https://codeload.github.com/techniker/MQTTBusyPy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techniker%2FMQTTBusyPy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28597087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T02:08:49.799Z","status":"ssl_error","status_checked_at":"2026-01-20T02:08:44.148Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["busylight","hid","hid-device","kuando","led","mqtt","python"],"created_at":"2024-09-27T02:23:42.097Z","updated_at":"2026-01-20T06:02:12.308Z","avatar_url":"https://github.com/techniker.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MQTT Busylight Controller for Kuando HID Busylights\n\n## Overview\n\nThis project provides a simple  MQTT-based controller for Kuando HID-based Busylights (Alpha and Omega).\nIt allows controlling colors, blinking, fading effects, rainbow cycling, and ringtones by sending **plain text** MQTT payloads.\n\nIt supports:\n- Opening the device by **VID/PID**, **autodetect by VID**, or explicit **HID device path**\n- A keep-alive loop to prevent the Busylight from going idle\n- Periodic status output to the console\n- Optional daemon mode on POSIX systems (Linux)\n\n## Features\n\n- Control Kuando Busylights via MQTT.\n- Solid colors (`color_*`)\n- Blinking (`blink_color_*`)\n- Fade effect (`fade_*`, `fade_off`)\n- Rainbow effect (`rainbow_on`, `rainbow_off`)\n- Ringtones (`ring_*`, `stop_ringtone`)\n- Raw RGB payloads (`raw_color R,G,B`)\n- Device control (`reset_device`, `device_bootloader`)\n- Keep-alive thread (configurable interval/timeout)\n- Status logging (device/mqtt/effect/last command)\n- CLI options for all settings\n- Daemon option with pidfile (POSIX only)\n\n## Hardware Requirements\n\n- Kuando Busylight UC Omega or Alpha (HID USB device)\n\nUSB-IDs include:\n- `27bb:3bca` (PLENOM/Kuando devices)\n- `27bb:3bcf`, `27bb:3bcd` (other variants)\n- Some Alpha devices may use different VID/PID combinations\n\n## Software Requirements\n\n- Linux/OSX (recommended) or other OS supported by hidapi\n- Python 3.x\n- Python packages:\n  - `hid` (python-hidapi wrapper)\n  - `paho-mqtt`\n\n## Installation\n\nCreate and activate a virtual environment, then install dependencies:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install hid paho-mqtt\n```\n\n**Permissions (Linux / Debian)**\n\nIf the HID device only opens as root, you likely need a udev rule for /dev/hidraw*.\n\nExample rule for Kuando/Plenom (VID 27bb):\n\n```\nsudo tee /etc/udev/rules.d/99-busylight.rules \u003e/dev/null \u003c\u003c'RULE'\nSUBSYSTEM==\"hidraw\", ATTRS{idVendor}==\"27bb\", MODE=\"0660\", GROUP=\"plugdev\", TAG+=\"uaccess\"\nRULE\n\nsudo udevadm control --reload-rules\nsudo udevadm trigger\nsudo usermod -aG plugdev \"$USER\"\n```\n\n## Usage\n\n### List HID devices:\n\nUse this to verify VID/PID and to get a usable HID path:\n```\npython3 busylight_mqtt_v1.py --list-devices\n```\nPrint supported MQTT commands:\n```\npython3 busylight_mqtt_v1.py --print-commands\n```\nRun the controller (example with explicit VID/PID):\n```\npython3 busylight_mqtt_v1.py \\\n  --vendor-id 0x27bb --product-id 0x3bca \\\n  --mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \\\n  --mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'\n```\n\nRun with autodetect (VID only):\n\nIf you omit --product-id, the program will pick the first device matching the vendor ID:\n```\npython3 busylight_mqtt_v1.py \\\n  --vendor-id 0x27bb \\\n  --mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \\\n  --mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'\n```\n\nRun by HID path (most deterministic)\n```\npython3 busylight_mqtt_v1.py --list-devices\n```\n\nThen copy the PATH=... value and run:\n```\npython3 busylight_mqtt_v1.py \\\n  --device-path \"b'...your path bytes...'\" \\\n  --mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \\\n  --mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'\n````\n```\nDaemon mode (POSIX)\npython3 busylight_mqtt_v1.py --daemon --pidfile /run/busylight_mqtt.pid \\\n  --vendor-id 0x27bb --product-id 0x3bca \\\n  --mqtt-host mqtt.sixtopia.net --mqtt-port 1883 \\\n  --mqtt-user mqtt --mqtt-password 'YOUR_PASSWORD'\n```\n## MQTT Control\n\n### Topic\n```\nDefault topic:\n\nbusylight/control\n\n\nOverride with:\n\n--mqtt-topic \u003ctopic\u003e\n\nPayload format\n\nPayload is plain UTF-8 text\n\nOne command per message\n\nNo JSON required\n\nExample Commands\nSolid colors\n\ncolor_red\n\ncolor_green\n\ncolor_blue\n\ncolor_yellow\n\ncolor_cyan\n\ncolor_magenta\n\ncolor_white\n\ncolor_orange\n\ncolor_purple\n\ncolor_pink\n\ncolor_brown\n\nBlinking\n\nblink_color_red\n\nblink_color_green\n\nblink_color_blue\n\nblink_color_yellow\n\nblink_color_cyan\n\nblink_color_magenta\n\nblink_color_white\n\nblink_color_orange\n\nblink_color_purple\n\nblink_color_pink\n\nblink_color_brown\n```\n\n### Fade:\n\nAccepted forms:\n```\nfade_red, fade_green, fade_blue, ...\n\nfade_color_red, fade_color_green, ...\n\nStop fade:\n\nfade_off\n\nFade behavior is controlled by:\n\n--fade-step\n\n--fade-delay\n```\n\n### Rainbow effect:\n```\nrainbow_on\n\nrainbow_off\n\nRainbow speed is controlled by:\n\n--rainbow-delay\n```\n\n### Raw RGB color:\n\nFormat:\n```\nraw_color R,G,B\n```\n\nExample:\n\nraw_color 255,0,0\n\n\n### Ringtones:\n```\n\nring_off\n\nring_open_office\n\nring_quiet\n\nring_funky\n\nring_fairy_tale\n\nring_kuando_train\n\nring_telephone_nordic\n\nring_telephone_original\n\nring_telephone_pick_me_up\n\nring_buzz\n\nStop ringtone:\n\nstop_ringtone\n\nRingtone volume is controlled by:\n\n--ringtone-volume (0..7)\n```\n\n### Other device commands:\n```\n\noff — stop effects and turn LEDs off\n\nreset_device — send reset opcode\n\ndevice_bootloader — switch device into bootloader mode\n```\n\n### Status Output\n\n* The program periodically logs a line like:\n\n* device state (opened or not)\n\n* VID/PID\n\n* mqtt connection state\n\n* current effect (none/rainbow/fade)\n\n* last received command payload\n\nControl the interval with:\n\n--status-interval 5\n\n### Key options:\n\n* HID:\n\n--vendor-id 0x27bb\n\n--product-id 0x3bca\n\n--device-path \u003cpath\u003e\n\n--list-devices\n\n* MQTT:\n\n--mqtt-host \u003chost\u003e\n\n--mqtt-port \u003cport\u003e\n\n--mqtt-topic \u003ctopic\u003e\n\n--mqtt-client-id \u003cid\u003e\n\n--mqtt-user \u003cuser\u003e\n\n--mqtt-password \u003cpassword\u003e\n\n--mqtt-keepalive \u003cseconds\u003e\n\n* Effects:\n\n--rainbow-delay \u003cseconds\u003e\n\n--fade-step \u003c1..255\u003e\n\n--fade-delay \u003cseconds\u003e\n\n--ringtone-volume \u003c0..7\u003e\n\n* Keep-alive:\n\n--ka-timeout \u003c0..15\u003e\n\n--ka-interval \u003cseconds\u003e\n\n* Logging/status:\n\n--log-level DEBUG|INFO|WARNING|ERROR\n\n--status-interval \u003cseconds\u003e\n\n* Daemon:\n\n--daemon\n\n--pidfile \u003cfile\u003e\n\n* Daemon mode: optional POSIX daemonization with pidfile.\n\nLicense\n\nThis project is licensed under the MIT License. See the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechniker%2Fmqttbusypy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechniker%2Fmqttbusypy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechniker%2Fmqttbusypy/lists"}