diyHue Documentation Release 1.0 diyHue Team Sep 08, 2021 Contents: 1 Getting Started 1 1.1 Docker Install..............................................1 1.1.1 Beta install...........................................2 1.2 Host Install................................................3 1.2.1 Automatic install........................................3 1.2.2 Manual install..........................................3 1.3 OpenWrt Install.............................................4 1.4 OpenWrt Update.............................................5 1.4.1 Demo..............................................5 2 Configuration 7 2.1 Pairing diyHue with the Hue app....................................7 2.2 Configuration File............................................7 2.3 Adding lights...............................................7 2.4 Reset Linkbutton Password.......................................8 3 Lights 9 3.1 DIY Lights................................................9 3.1.1 Light GUI............................................9 3.1.2 Flashing Firmware....................................... 11 3.1.3 Connecting the lights to a Wi-Fi network............................ 11 3.1.4 Lights API........................................... 12 3.1.5 Firmware upgrade........................................ 14 3.2 IKEA Tradfri............................................... 14 3.2.1 Import Trafri Gateway Lights.................................. 14 3.2.2 Raspbee Module Setup..................................... 14 3.3 MiLight Hub............................................... 14 3.3.1 Import MiLight lights...................................... 14 3.3.2 Convert MiLight bulbs to Wi-Fi................................ 15 3.4 Hue Bridge Lights............................................ 15 3.5 ESPHome................................................ 15 3.5.1 General Configuration..................................... 15 3.5.2 Entertainment Mode...................................... 16 3.5.3 RGBW............................................. 16 3.5.4 CT................................................ 16 3.5.5 RGB............................................... 16 3.5.6 Dimmable............................................ 17 i 3.5.7 Toggle.............................................. 17 3.5.8 Sample Configuration...................................... 17 3.6 YeeLight................................................. 19 3.7 Raspbee.................................................. 19 3.7.1 ZigBee Devices With Built In Support............................. 19 3.7.2 Deconz installation....................................... 20 3.7.3 Sensors and Switches Configuration.............................. 21 3.8 MQTT - zigbee2mqtt........................................... 21 3.8.1 Configuration.......................................... 21 3.8.2 Zigbee2mqtt........................................... 22 3.8.3 Other mqtt lights........................................ 22 3.8.4 Protocol............................................. 22 3.9 Home Assistant.............................................. 23 3.9.1 Configuration.......................................... 23 3.9.2 Including/Excluding Lights in Home Assistant........................ 24 3.9.3 Configure Rooms/Zones/Groups in Home Assistant...................... 25 4 Additional Functions 27 4.1 Alexa................................................... 27 4.2 Sensors.................................................. 27 4.2.1 Switches............................................. 27 4.2.2 Motion Sensor......................................... 28 4.3 Hue Entertainment............................................ 28 4.3.1 Compilation Commands.................................... 31 4.4 Enable debug mode........................................... 31 4.4.1 Host install........................................... 31 4.4.2 Docker install.......................................... 31 4.4.3 HTTPS certificate check.................................... 31 4.5 Home Kit................................................. 33 4.6 Domoticz................................................. 34 4.6.1 Add a new light(s)....................................... 34 4.7 Command Line Arguments....................................... 35 4.7.1 IP................................................ 35 4.7.2 MAC.............................................. 35 4.7.3 IP Range............................................ 36 4.7.4 Deconz............................................. 36 4.7.5 Debug.............................................. 36 4.8 Alarm................................................... 36 5 Uninstall 37 5.1 Docker Uninstall............................................. 37 5.2 Host Uninstall.............................................. 37 5.2.1 Automatic Uninstall....................................... 37 6 FAQ 39 6.1 What lights can I use with this project?................................. 39 6.2 Do I need a Phillips Hue Bridge to control genuine Phillips Hue bulbs with diyHue?......... 39 6.3 Unable to Connect - diyHue Bridge is detected but i can´t pair!.................... 40 6.4 My Phillips TV detects diyHue Bridge but I am unable establish a connection............. 40 6.5 What do I need to use IKEA Tradfri devices?.............................. 40 6.6 App XYZ doesn’t work!......................................... 40 6.7 My Google Home / Google Assistant doesn’t find diyHue!....................... 40 6.8 Philips Hue App complains about Bridge v1 detected and not supported anymore........... 40 7 diyHue - Development 43 ii 7.1 Repository content............................................ 43 7.2 Docker development........................................... 44 7.3 Requirements............................................... 44 7.4 Build docker image............................................ 44 7.5 Start docker image............................................ 44 7.6 Publishing the docker image....................................... 45 8 Indices and tables 47 iii iv CHAPTER 1 Getting Started Setup is very quick and easy with two main installation methods currently supported. diyHue can be installed either directly on the host machine, or via a docker image. Currently, we recommend installation via Docker as it’s much easier to maintain, update and modify! Note: While the host and OpenWrt installation methods are currently supported, there are plans to depreciate these installation methods in the future. They will continue to be available, however, they will be community maintained instead of offically supported. For all new installations, we highly recommend using the Docker installation method. Please note that although running diyHue on Windows is theoretically possible, many scripts and functions rely on Linux commands. However, with Docker this is possible! Installation on OpenWrt is also supported. It is best to have at least one compatible light ready in order to setup and test the system with. 1.1 Docker Install Currently the docker image has been tested with x86 systems and ARMv7 systems (Raspberry Pi 2 and later). Cur- rently the ARM image has only been tested with a Raspberry Pi 3b+ If you have other ARM based devices and can test the image, please let us know on our Slack chat or in an issue. The images can be run with both host and bridge network modes. I recommend using the host network mode for ease, however this will give you less control over your docker networks. Using bridge mode allows you to control the traffic in and out of the container but requires more options to setup. To run the container with the host network mode: docker run-d--name diyHue--restart=always--network=host-e MAC=XX:XX:XX:XX:XX:XX- ,!v/mnt/hue-emulator/export:/opt/hue-emulator/export diyhue/core:latest Note: Edit -e MAC=XX:XX:XX:XX:XX:XX to your specific Interface Mac you are using to connect to your net- work! This has to be correct to generate a valid certificate for genuine Hue App connection 1 diyHue Documentation, Release 1.0 To run the container with bridge network mode: docker run-d--name diyHue--restart=always--network=bridge-v/mnt/hue-emulator/ ,!export:/opt/hue-emulator/export-e MAC=XX:XX:XX:XX:XX:XX-e IP=XX.XX.XX.XX-p 80:80/ ,!tcp-p 443:443/tcp-p 1900:1900/udp-p 2100:2100/udp-p 1982:1982/udp diyhue/ ,!core:latest Note: When running with the bridge network mode you must provide the IP and MAC address of the host device. Four ports are also opened to the container. These port mappings must not be changed as the hue ecosystem expects to communicate over specific ports. These commands will run the latest image available, however if you have automated updates enabled with a service such as watchtower, then using latest is not recommended. The images are automatically rebuilt upon a new commit to this repo. As such, larges changes could occur and updates will be frequent. Each image is also tagged with the commit hash. For example diyhue/core:391cc642072aac70d544fd428864f74bf9eaf636. It is then suggested you use one of these images instead and manually update every so often. Alternative tags are also available. Images are tagged as follows: • branch-commitid : This will be a particular commit from the specified branch. • branch : This is always the latest image from that particular branch. • runid : This can come from any branch. The run id is determined from our Github Actions page which will indicate the commit, branch, and run id of this image. • latest : This will always be the latest update from the master branch. The mount directory /mnt/hue-emulator/export/ can be changed