{"id":29246936,"url":"https://github.com/timothydodd/hubitat-wled-mqtt","last_synced_at":"2025-07-03T23:39:28.289Z","repository":{"id":301797026,"uuid":"1010326541","full_name":"timothydodd/hubitat-wled-mqtt","owner":"timothydodd","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-28T21:26:59.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-28T22:28:49.226Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timothydodd.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,"zenodo":null}},"created_at":"2025-06-28T20:43:26.000Z","updated_at":"2025-06-28T21:27:02.000Z","dependencies_parsed_at":"2025-06-28T22:28:50.310Z","dependency_job_id":"ac2c1397-34f3-4aca-9424-e567a2e1fae1","html_url":"https://github.com/timothydodd/hubitat-wled-mqtt","commit_stats":null,"previous_names":["timothydodd/hubitat-wled-mqtt"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/timothydodd/hubitat-wled-mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothydodd%2Fhubitat-wled-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothydodd%2Fhubitat-wled-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothydodd%2Fhubitat-wled-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothydodd%2Fhubitat-wled-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timothydodd","download_url":"https://codeload.github.com/timothydodd/hubitat-wled-mqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothydodd%2Fhubitat-wled-mqtt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263421620,"owners_count":23464020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-07-03T23:39:16.057Z","updated_at":"2025-07-03T23:39:28.278Z","avatar_url":"https://github.com/timothydodd.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WLED MQTT Driver for Hubitat Elevation\n\n**Enhanced Version 2.0.0** - Complete WLED control via MQTT\n\nThis is a comprehensive device driver for Hubitat Elevation that provides full control over WLED devices via MQTT. It supports all major WLED features including colors, effects, palettes, presets, segments, and more.\n\n## ✨ Features\n\n### Core Lighting Control\n- **Switch Control**: Turn WLED on/off\n- **Brightness Control**: Dimming from 0-100% with smooth transitions\n- **Color Control**: Full RGB and HSV color management\n- **Color Temperature**: White balance control (2700K-6500K)\n\n### Advanced WLED Features\n- **Effects**: Access to all WLED effects with speed and intensity control\n- **Palettes**: Color palette selection and management\n- **Presets**: Save and load WLED presets\n- **Segments**: Multi-segment color control\n- **Transitions**: Configurable fade timing\n\n### Modern API Support\n- **JSON API**: Recommended modern WLED JSON API (v0.13+)\n- **Legacy XML**: Backward compatibility with older WLED versions\n- **Auto-Discovery**: Automatic detection of effects and palettes\n- **HTTP Fallback**: Direct HTTP API calls when needed\n\n### Robust Communication\n- **MQTT Authentication**: Username/password support for secure brokers\n- **Auto-Reconnection**: Intelligent reconnection with backoff\n- **Error Handling**: Comprehensive error detection and recovery\n- **State Synchronization**: Real-time state updates via MQTT\n\n## 🚀 Quick Start\n\n\u003e **⚠️ IMPORTANT**: When entering the WLED IP address, use **IP only** (e.g. `192.168.1.50`) - **DO NOT** include `http://` or paths like `/json`. This is the most common configuration error that causes 408 timeout errors!\n\n### 1. Installation\n1. Copy the driver code from `wled-mqtt-driver.groovy`\n2. In Hubitat: **Drivers Code** → **New Driver** → Paste code → **Save**\n3. **Devices** → **Add Device** → **Virtual** → Select \"WLED MQTT Light\"\n\n### 2. Basic Configuration\n```yaml\nMQTT Broker: \"192.168.1.100:1883\"\nMQTT Topic: \"wled/livingroom\"  # Your WLED device topic\nUse JSON API: ✅ Enabled (recommended)\nWLED IP Address: \"192.168.1.50\"  # For auto-discovery (IP ONLY!)\n```\n\n### 3. WLED Setup\nEnsure your WLED device has MQTT enabled:\n- **Settings** → **Sync Interfaces** → **MQTT**\n- Set broker IP and topic to match Hubitat configuration\n- Enable \"Send notifications on direct change\"\n\n## 📋 Configuration Options\n\n### MQTT Settings\n| Setting | Description | Example |\n|---------|-------------|---------|\n| **MQTT Broker** | Broker address and port | `192.168.1.100:1883` |\n| **MQTT Topic** | WLED device topic | `wled/devicename` |\n| **Username** | MQTT authentication (optional) | `mqttuser` |\n| **Password** | MQTT authentication (optional) | `mqttpass` |\n\n### WLED Settings\n| Setting | Description | Example |\n|---------|-------------|---------|\n| **WLED IP Address** | IP for HTTP API discovery | `192.168.1.50` ← **IP ONLY** |\n| **Use JSON API** | Modern API (recommended) | ✅ Enabled |\n| **Auto-refresh** | State update interval | 30 seconds |\n\n### Advanced Settings\n| Setting | Description | Default |\n|---------|-------------|---------|\n| **Max Segments** | Maximum LED segments | 16 |\n| **Transition Time** | Default fade duration | 700ms |\n| **Debug Logging** | Enable detailed logs | ✅ Enabled |\n\n## 🎮 Available Commands\n\n### Basic Control\n```groovy\ndevice.on()                          // Turn on\ndevice.off()                         // Turn off\ndevice.setLevel(75)                  // Set brightness to 75%\ndevice.setLevel(50, 3)               // Fade to 50% over 3 seconds\n```\n\n### Color Control\n```groovy\ndevice.setColor([hue: 120, saturation: 100, level: 80])  // Green\ndevice.setHue(240)                   // Blue hue\ndevice.setSaturation(50)             // 50% saturation\ndevice.setColorTemperature(3000)     // Warm white (3000K)\n```\n\n### Effects\n```groovy\ndevice.setEffect(\"Rainbow\")          // Set effect by name\ndevice.setEffect(12)                 // Set effect by number\ndevice.setNextEffect()               // Next effect\ndevice.setPreviousEffect()           // Previous effect\ndevice.setEffectSpeed(200)           // Effect speed (0-255)\ndevice.setEffectIntensity(150)       // Effect intensity (0-255)\n```\n\n### Palettes \u0026 Presets\n```groovy\ndevice.setPalette(\"Rainbow\")         // Set palette by name\ndevice.setPalette(5)                 // Set palette by number\ndevice.setPreset(1)                  // Load preset 1\n```\n\n### Advanced Features\n```groovy\ndevice.setSegmentColor(0, \"#FF0000\") // Set segment 0 to red\ndevice.setSegmentColor(1, \"255,128,0\") // Set segment 1 to orange\ndevice.setTransition(2)              // Set 2-second transitions\ndevice.configure()                   // Auto-discover effects/palettes\ndevice.refresh()                     // Request state update\n```\n\n## 🔧 Setup \u0026 Discovery\n\n### Auto-Discovery\nRun the `configure()` command to automatically discover:\n- Available effects list\n- Color palettes\n- Device information\n- Current state\n\nThis populates the device with all available WLED features.\n\n### Manual Configuration\nIf auto-discovery isn't available, effects and palettes will use numeric IDs:\n- Effects: 0-73+ (depends on WLED version)\n- Palettes: 0-43+ (depends on WLED version)\n\n## 📊 Hubitat Capabilities\n\nThe driver implements these Hubitat capabilities:\n\n| Capability | Purpose |\n|------------|---------|\n| **Switch** | On/off control |\n| **SwitchLevel** | Brightness control |\n| **ColorControl** | RGB/HSV color management |\n| **ColorTemperature** | White balance control |\n| **Light** | Light device identification |\n| **LightEffects** | Effect management |\n| **Initialize** | Setup and configuration |\n| **Actuator** | Device control interface |\n\n## 🔍 Troubleshooting\n\n### ⚠️ Configuration Issues (Most Common)\n- **IP Address Format**: Enter IP only (e.g. `192.168.1.50`) - **DO NOT** include `http://` or paths\n- **MQTT Topic Format**: Use simple topic (e.g. `wled/livingroom`) - no leading/trailing slashes  \n- **408 Timeout Errors**: Usually caused by including URLs like `http://192.168.1.50/json` in IP field\n- **Auto-Fix**: Driver now automatically cleans malformed IP addresses\n\n### Connection Issues\n- Verify MQTT broker is running and accessible\n- Check MQTT topic matches between Hubitat and WLED\n- Ensure WLED MQTT is enabled and configured\n- Try without authentication first\n\n### Discovery Problems\n- Set WLED IP address in device preferences (IP only!)\n- Run `configure()` command manually\n- Check WLED HTTP API is accessible at `http://[IP]/`\n- Verify JSON API is enabled in WLED\n\n### State Sync Issues\n- Enable \"Send notifications on direct change\" in WLED\n- Check MQTT topic subscriptions\n- Verify JSON vs XML API setting matches WLED\n- Monitor Hubitat logs for MQTT messages\n\n### Performance\n- Adjust auto-refresh interval (10-300 seconds)\n- Use JSON API for better performance\n- Reduce transition times if needed\n- Check MQTT broker capacity\n\n## 🆕 Version 2.0.0 Changes\n\n### New Features\n- Complete color temperature support\n- Multi-segment control\n- Enhanced effect management\n- Modern JSON API support\n- Auto-discovery via HTTP API\n- MQTT authentication support\n- Improved error handling\n- Comprehensive state management\n- **Auto-cleanup of malformed IP addresses**\n\n### Breaking Changes\n- JSON API is now default (can be disabled)\n- MQTT topics changed for JSON mode\n- Some attribute names updated\n- Enhanced configuration options\n\n### Migration from v1.x\n1. Update device preferences\n2. Enable JSON API (recommended)\n3. Run `configure()` for auto-discovery\n4. Test all functionality\n\n## 📝 Requirements\n\n- **Hubitat Elevation** Hub (any version)\n- **WLED** v0.13.0+ (recommended for JSON API)\n- **MQTT Broker** (Mosquitto, Home Assistant, etc.)\n- Network connectivity between all components\n\n## 🤝 Contributing\n\nThis driver is based on the original WLED MQTT Light driver by **Mikhail Diatchenko** from his [hubitat repository](https://github.com/muxa/hubitat/blob/master/drivers/wled-light.groovy). \n\n**Enhanced and refactored by Tim Dodd** with significant improvements including:\n- Modern WLED JSON API support  \n- Complete color temperature implementation\n- Full effects and palettes functionality (was commented out in original)\n- Multi-segment support\n- Auto-discovery via HTTP API\n- Robust error handling and reconnection logic\n- MQTT authentication support\n- Input validation and auto-cleanup\n- Comprehensive documentation and troubleshooting\n- Enhanced state management\n\nThis represents a substantial refactoring and enhancement of the original driver while maintaining compatibility with the core MQTT communication approach.\n\nFeel free to submit issues, feature requests, or improvements!\n\n## 📄 License\n\nLicensed under the Apache License, Version 2.0. See the LICENSE file for details.\n\n## 🔗 Links\n\n- **WLED Project**: https://github.com/Aircoookie/WLED\n- **WLED Documentation**: https://kno.wled.ge/\n- **Hubitat Documentation**: https://docs.hubitat.com/\n- **Original Driver**: https://github.com/muxa/hubitat/blob/master/drivers/wled-light.groovy\n\n---\n\n**Version**: 2.0.0  \n**Original Author**: Mikhail Diatchenko (muxa)  \n**Enhanced by**: Tim Dodd (dodd)  \n**Last Updated**: December 2024","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothydodd%2Fhubitat-wled-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimothydodd%2Fhubitat-wled-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothydodd%2Fhubitat-wled-mqtt/lists"}