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 to any directory you wish. Backups of the config.json and cert.pem are saved here when changes are made to these files. They are then restored upon container reboot. If you need to make manual changes to these files, do so with the files mounted on the host (rather than the files in the container) and then restart the container to import your changes. To perform a manual export at any time, visit http://{emualtor ip}/save. If there are no files in the mounted directory then they will be regenerated at container start. To update the container: • Delete the existing container (Don’t worry! This won’t delete your configuration as this is stored in the mounted directory.)
docker rm -f diyHue
• Recreate the container using the commands above, changing the tag if necessary. Alternatively, you may utilize the docker-compose file found in the .build directory of the repository to setup diy- Hue. Once copied, it may be started using docker-compose up and stopped using docker-compose down. Updates can be achieved by changing the tag in the configuration and restarting docker-compose restart. The container will auto-start on host boot or a container crash.
1.1.1 Beta install
Currently diyHue is under heavy development. As the Official API has changed and needs to be reverse engineered, this BETA release will incorporate the latest changes. In order to use the most recent official Hue APP you need to use this branch. Roadmap for this Beta:
2 Chapter 1. Getting Started diyHue Documentation, Release 1.0
• Implement new API v2 – In Progress • Redesign the Ui – In Progress • Modular Code Structure – In Progress • Integrate Protocols and Smarthome Systems ( e.g. Home Assistant, Yeeelight, Mi-Light etc) – In Progress To run the beta container with the host network mode: docker run-d--name diyHue-beta--restart=always--network=host-e
˓→MAC=XX:XX:XX:XX:XX:XX-v/mnt/hue-emulator/config:/opt/hue-emulator/config diyhue/
˓→core:beta
Change the MAC=XX:XX:XX:XX:XX:XX to your specific network interface MAC (use lowercase characters)
1.2 Host Install
When installing diyHue directly on the host, you have two installation methods available. An easy automatic installa- tion script or the commands to install it manually. The automatic install is highly recommended and is kept most up to date.
1.2.1 Automatic install
Just run the following command to install: curl-fsSL https://get.diyhue.org-o install.sh sudo bash install.sh
Note: Choose Branch to be installed: Master (recommended for normal usage) Dev (latest features and fixes) Beta (Work in Progress - latest API implementation)
Choose your Network Interface (if you have multiple) Once complete, diyHue is installed and running. It will also automatically start on boot. diyHue can also be stopped, started and restarted with the following command: sudo systemctl [start/stop/restart] hue-emulator.service
1.2.2 Manual install
• Download or clone the mirror with git (recommended) git clone https://github.com/diyhue/ diyHue.git • Install nmap package for lights autodiscover sudo apt install nmap. On windows nmap utility is miss- ing and the lights must be added manually in configuration witch is not simple. • Create startup systemd file based on the following example:
sudo nano/lib/systemd/system/hue-emulator.service
• Paste the following code and edit the path of the emulator script:
1.2. Host Install 3 diyHue Documentation, Release 1.0
[Unit] Description=Hue Emulator Service After=multi-user.target
[Service] Type=idle Restart=always RestartSec=30 StartLimitInterval=200 StartLimitBurst=5
WorkingDirectory=/home/pi ExecStart=/home/pi/HueEmulator.py
[Install] WantedBy=multi-user.target
• Save and execute the following commands:
sudo chmod 644/lib/systemd/system/hue-emulator.service sudo systemctl daemon-reload sudo systemctl enable hue-emulator.service sudo systemctl start hue-emulator.service
If you want to disable logging to syslog you must add in systemd file StandardOutput=null. you can check the service status with sudo systemctl status hue-emulator.service
1.3 OpenWrt Install
First, run following command: opkg update&& opkg install wget ca-bundle nano
You will need to change to the temporary directory: cd/tmp
It is also necessary to change 3 lines of code from port 80 to 82: nano/etc/config/uhttpd
Change. . . list listen_http 0.0.0.0:80 list listen_http [::]:80 to. . . list listen_http 0.0.0.0:82 list listen_http [::]:82 and also: nano/etc/lighttpd/lighttpd.conf
Change this. . .
4 Chapter 1. Getting Started diyHue Documentation, Release 1.0
server.port= 80 to this. . . server.port= 82
Finally, run the following command to run the install: wget--no-check-certificate https://raw.githubusercontent.com/diyhue/diyHue/master/
˓→BridgeEmulator/easy_openwrt.sh&& sh easy_openwrt.sh
The installation in OpenWrt requires a change to the configuration file for the GUI of luci since it runs on port 80 by default, and diyHue must run on port 80, so it was changed to port 82 following the instructions above. Therefore to enter the OpenWrt configuration you must access: http://192.168.8.1:82/cgi-bin/luci instead.
1.4 OpenWrt Update
Run the following command to update: cd/tmp&& wget--no-check-certificate https://raw.githubusercontent.com/diyhue/
˓→diyHue/master/BridgeEmulator/update_openwrt.sh&& sh update_openwrt.sh
After the update has finished, the system will restart automatically.
1.4.1 Demo
1.4. OpenWrt Update 5 diyHue Documentation, Release 1.0
6 Chapter 1. Getting Started CHAPTER 2
Configuration
Most configuration can be done either in the Hue app or in the diyHue web UI.
2.1 Pairing diyHue with the Hue app
To pair a new device to diyHue, first head to http://{IP_ADDRESS}/hue/linkbutton. The default username is Hue with a password of Hue also. At this point you should open the Hue app on your phone and start searching for hubs. To speed this up you can click the Help button and then enter the IP address of your diyHue device. Once the bridge has been detected, click the green Set up button. At this point, the app will prompt you to press the link button on your Hue bridge. To do so, click the Activate button on the web page you loaded at the start. The Hue app should now prompt you through the rest of the setup. For specific details on how to setup specific lights, browse the lights section in the navigation bar to the left.
2.2 Configuration File
The entire configuration is saved in the config.json file. Changes to the bridge are saved in real time or every hour automatically. In case of state change of lights or sensors the configuration is not saved to avoid extensive writes to the SD card on Raspberry Pi’s. If you want to save the configuration manually, you can do so by accessing http:/ /{emualtor ip}/save. If you want to manually edit the configuration file to change any kind of resource, I recommend backing up the file first. In case the configuration file is corrupted, you can look for backups that are done automatically every Sunday night.
2.3 Adding lights
Depending on which lights you plan to use, the setup method will vary. For detailed setup instructions, please chose the correct type of light you wish to setup from the menu on the left.
7 diyHue Documentation, Release 1.0
2.4 Reset Linkbutton Password
If you forgot the changed Password, edit the linkbutton_auth Field in config.json to the default Hash SHVlOkh1ZQ==. This will reset the Password to Hue:Hue
8 Chapter 2. Configuration CHAPTER 3
Lights
3.1 DIY Lights
The following devices are currently supported: • Generic PWM CCT lights (2 channels) - ex Milight bicolor • generic PWM RGB lights (3 channels) • generic PWM RGBW lights (4 channels) - ex. Feican bulbs • generic PWM RGB-CCT lights (5 chnnels - ex Milight FUT015) • SK6812 Neopixels • WS2812B Neopixels • All ZigBee lights - check Raspbee module page A lot of Wi-Fi lights from the market are ESP8266 based and can be used very easily with this project by flashing the firmware with one provided. Almost all dimmable lights that are not ESP8266 based (ex MiLight bulbs) can be converted to Wi-Fi with one ESP-12S module by connecting the outputs directly to led drivers (picture available). If you decide to convert a MiLight bulb to ESP-12S, then I recommend to use a micro step down buck converter in order to avoid overheating issues. All lights are two way synchronized so any change made by 3rd party device will also be added to the bridge emulator on the first request to each light group. By default any light that become unreachable will be marked as unreachable and will be displayed as off. This is because a lot of people still use classic light switches.
3.1.1 Light GUI
All lights have an internal web GUI that can be accesses with any browser and offers the following options: • Turn the light on/off • Set startup option:
9 diyHue Documentation, Release 1.0
10 Chapter 3. Lights diyHue Documentation, Release 1.0
– Light Off (default) – Light On – Last State (Turns the light on to the same state as it was the last time it was on) • Change the scene. This will change also the power on scene • Change any light parameter (bri, color, ct, xy, etc)
3.1.2 Flashing Firmware
The easiest way to get our custom firmware onto one of the ESP8266 based Microcontrollers (NodeMcu / Wemos etc) is to you our Web Installer. https://install.diyhue.org Select the Sketch according to your hardware. Flash! Configure your new diyHue Light by connecting your smartphone to the new Wifi Accespoint. Enter your local Wifi Settings and Password. Save Search for new Lights in your App. Enjoy Note: You need to use Chrome Browser or Edge Regular Way: In the new version is mandatory add SPIFFS storage to the ESP module. Try to choose the maximum possible size. For NodeMcu/Wemos D1 mini that have 4Mb of flash select 4M with 3M SPIFFS. You will know if the SPIFFS storage is properly set by looking at wifi manager broadcast SSID, if is in format ESPxxxxx then you must try different SPiFFS option. Future upgrades can be performed manually by exporting the compiled binary file from Arduino and upload it using any browser by accessing /update http location of the light.
Neopixels
Before compiling the code, you must set the lightsCount and pixelCount variables. lightsCount is the number of virtual lights to create from your NeoPixel strip. pixelCount is the total number of NeoPixel LED’s in the connected strip . transitionLeds represents the number of LEDs used for smooth transitions of colours between lights. I recommend using atleast 3 lights, one light at every 20 - 50 LED’s so you can enjoy Hue scenes and Hue Entertainment. The data pin of the LED’s must be connected to RX pin of the ESP8266 board. Make sure to disconnect this when uploading or it could fail.
Generic lights
If your device is factory ESP8266 based, then you must specify the pins used by that device in setting page of the light web gui. If you don’t know what pins are used or what color is controlled on a pin then try random pins. I recommend using the MiLight FUT15 bulbs converted to ESP-12S because of it’s high brightness and good color reproduction.
3.1.3 Connecting the lights to a Wi-Fi network
All lights are using WiFiManager and on power up, will broadcast for 2 minutes with the SSID set in the light_name variable (the defaultis Hue .....) Connect to this network with you phone or computer and browse to http:// 192.168.4.1 From here you can choose the SSID of the network you would like the light to connect to and enter its password. After the light is present on your network open the official Hue application and scan for new lights. In case no lights are found, check if the nmap package is installed. Note: The app will often say no lights found but the lights will then appear a few seconds after this notification. So be patient!
3.1. DIY Lights 11 diyHue Documentation, Release 1.0
3.1.4 Lights API
The lights use the same Hue protocol however, for sketches with multiple lights the state of every light is added in a root key that identify the light id. detection url: http://{light ip}/detect sample output:
{"name":"Living ","protocol":"native_single","modelid":"LCT015","type":"rgb-cct","mac
˓→":"A0:20:A6:2C:FB:26","version":2}
API for light control or state read http path: http://{light ip}/state http mode: GET for read, PUT to set a new state with json body Example json body for devices with single light (generic RGB, generic RGBW, generic RGB-CCT): {"on":true,"bri":144,"xy":[0.53, 0,21]} Example json body for devices with multiple lights: {1: {"on":true,"bri":144,"xy":[0. 53, 0,21]}, 2: {"on":true,"bri":144,"ct":370}, 3: {"on":false}} to read the state of a light is required to specify the light id in the url http://{light ip}/state? light=2. If not light is specified the state of light id 1 will be returned. Arguments that can be passed in the URL: • on: 1 to set light on, 0 to set the light off. • r, g, b: Set the light color using RGB values between 0 and 255. • x and y: Values between 0.0 and 1.0 to set the light color using a CIE chart. • ct: Value between 153 (max warm white) and 500 (max could white) http://en.wikipedia.org/wiki/Mired
12 Chapter 3. Lights diyHue Documentation, Release 1.0
3.1. DIY Lights 13 diyHue Documentation, Release 1.0
• hue: Value between 0 and 65535, representing the hue of the light. • sat: Set the saturation of the light. 255 is the most saturated and 0 is the least saturated. • bri: Set the brightness of the light, 255 is the maximum brightness, 1 is the minimum, 0 will turn the light on to previous state • transitiontime: Duration of the transition from the light’s current state to the new state. The default is 4 representing 0.4 seconds. • bri_inc: Increase or decrease the brightness with a specified value
3.1.5 Firmware upgrade
You can upgrade the firmware very easily by saving the binary file from Arduino to local disk and uploading it using /update page of the light web ui
3.2 IKEA Tradfri
There are two ways to interact with IKEA Tradfri devices, one method is to use the Tradfri Gateway and you will be able to control just the lights. The second method is to use the Raspbee module that offers the flowing advantages: • Add custom rules for sensors and switches • Tradfri Motion Sensors are emulated as Hue Motion Sensor giving the possibility to choose different scenes based on the time (ex: max brightness between 08:00 - 23:00 and Nightlight scene between 23:00 and 08:00) Also the light will be dimmed for 30 seconds before being turned off and you can configure from Hue application how much time the light will stay on after motion was triggered. • The Tradfri Remote can be emulated as a Hue Dimmer Switch or Hue Tap Switch that can apply color scenes.
3.2.1 Import Trafri Gateway Lights
Open http://{bridgeIP}/tradfri Type in the Ikea bridge IP and security key and click “Save”. You should then see all the lights paired with Tradfri bridge in Hue application. Important: You must make sure you are using the correct coap-client-linux binary for your system architecture or this will fail.
3.2.2 Raspbee Module Setup
For instructions on controlling Ikea Tradfri lights with the Raspbee module, see the Raspbee module page.
3.3 MiLight Hub
With the circuit from here you will be able to control MiLight bulbs that work using a proprietary 2.4 GHz protocol. The linked project provides a REST API that was integrated into diyHue.
3.3.1 Import MiLight lights
Open http://{bridgeIP}/milight, complete the form and click Save. You need to repeat this step for every light as there is no way to retrieve the list of lights from the MiLight hub.
14 Chapter 3. Lights diyHue Documentation, Release 1.0
3.3.2 Convert MiLight bulbs to Wi-Fi
It is also possible to convert MiLight bulbs to WiFi using any ESP8266 module. I have successfully converted one RGB-CCT bulb with an ESP-12S module (picture available) in less than 30 minutes. From original circuit board you will just need the 3.3V regulator (not recommended because of low power), the led drivers (NPN transistors for colored leds, MOSFET for white leds) and any nearby resistors that are connected to the transistors base/gate, other components can be disconnected/removed. You must remove the IC that controls the LED’s or it will conflict with the ESP8266 module. I connected GPIO12/13/14 to the resistors that point to the base of RGB transistors and GPIO4/5 directly to the MOSFET gates (not through the resistors because these are connected to ground). For stability an extra capacitor is required on the power line.
3.4 Hue Bridge Lights
To import the lights from your genuine Phillips Hue bridge, first open http://{bridgeIP}/hue and enter the IP of your genuine bridge. You can find the IP of your genuine bridge in the Hue app. Before clicking “Save” press the link button on your genuine Hue Bridge. The total number of lights copied to Bridge Emulator will be displayed. These lights will now be available in the app to add to a room. Note: Room configuration is not imported from the genuine Hue Bridge, only the lights.
3.5 ESPHome
ESPHome currently only works with one light per ESPHome device. This protocol will even work with switches that are mapped as lights in ESPHome, making it very flexible and ideal for a large variety of devices. Supported modes of operation are: • RGBW •CT • RGB • Dimmable • Toggle To add the device to diyHue, simply configure it using the information below and search for lights. The devices should be automatically imported into diyHue with the correct information.
3.5.1 General Configuration
All devices must have a text sensor: text_sensor: - platform: template name:"light_id" id: light_id lambda: |- char response[100]; memset( response, 0, 100 ); strcat( response, "esphome_diyhue_light;"); strcat( response, WiFi.macAddress().c_str()); strcat( response, ";"); (continues on next page)
3.4. Hue Bridge Lights 15 diyHue Documentation, Release 1.0
(continued from previous page) strcat( response, App.get_name().c_str()); strcat( response, ";CT_BOOST;RGB_BOOST" ); // ;CT_BOOST;RGB_BOOST values go
˓→here; Replace with 0 to disable return { response }; update_interval: 24h
Configurable options: • CT_BOOST: this value is utilized by diyHue to increase/decrease the default brightness of the CT light. Set this value to 0 to disable the feature. Must be an integer. • RGB_BOOST: same as CT_BOOST except will apply for the RGB component of the light. Important: CT_BOOST and RGB_BOOST must have a numeral value regardless of the bulb’s capabilities. For bulbs that are dimmable and toggle, simply set these values to 0. The alert switch will be called when the bulb is requested to be located. As it stands now, it is not ideal as it does not return the light to the original state.
3.5.2 Entertainment Mode
The configuration for entertainment mode differs from the configuration here which does not include entertainment mode. The full code can be found in the Lights repository. The primary differences are:
includes: - diyhueasyncudp.h libraries: - ESPAsyncUDP@697c75a025 custom_component: - lambda: |- auto diyhue = new diyhueudp(); return {diyhue};
These lines install the required library, the entertainment component, and initializes it. Additionally, be sure to copy the AsyncUDP component to the ESPHome directory.
3.5.3 RGBW
Including a white_led and a color_led light in the configuration will allow diyHue to automatically detect the devices as an RGBW device.
3.5.4CT
Include a white_led light to mark the light as a CT light.
3.5.5 RGB
Include a color_led light to mark the light as a RGB light.
16 Chapter 3. Lights diyHue Documentation, Release 1.0
3.5.6 Dimmable
Include a dimmable_led light to mark the light as a Dimmable light.
3.5.7 Toggle
Include a toggle_led light to mark the light as a Toggle light.
3.5.8 Sample Configuration
This is a sample configuration for a RGBW light, namely the Feit Electric Smart Bulb. This configuration can be modified using the above information to integrate practically any type of light ESPHome supports with diyHue. esphome: name: light1 platform: ESP8266 board: esp01_1m ota: password:"redacted" wifi: ssid:"redacted" password:"redacted"
ap: ssid:"ESPhome light1"
# Enable logging logger: level: DEBUG
# Enable Home Assistant API api: password:"redacted" power_supply: - id:'fast_led_pwr' pin: GPIO13 output: - platform: esp8266_pwm pin: GPIO5 id: cold_white_gpio frequency: 4000 Hz inverted: False min_power: 0 max_power: 1
- platform: esp8266_pwm pin: GPIO12 id: warm_white_gpio frequency: 4000 Hz inverted: False min_power: 0 (continues on next page)
3.5. ESPHome 17 diyHue Documentation, Release 1.0
(continued from previous page) max_power: 1 light: - platform: cwww id: white_led name:"white_led" cold_white: cold_white_gpio warm_white: warm_white_gpio cold_white_color_temperature: 6500 K warm_white_color_temperature: 2000 K gamma_correct: 0.8 default_transition_length: 0.4s
- platform: fastled_spi id: color_led chipset: SM16716 data_pin: GPIO14 clock_pin: GPIO4 power_supply: fast_led_pwr num_leds: 1 rgb_order: BGR name:"color_led" default_transition_length: 0.4s gamma_correct: 0.8 effects: - random: name: Random Effect With Custom Values transition_length: 5s update_interval: 3s text_sensor: - platform: template name:"light_id" id: light_id lambda: |- char response[100]; memset( response, 0, 100 ); strcat( response, "esphome_diyhue_light;"); strcat( response, WiFi.macAddress().c_str()); strcat( response, ";"); strcat( response, App.get_name().c_str()); strcat( response, ";CT_BOOST;RGB_BOOST" ); // ;CT_BOOST;RGB_BOOST values go
˓→here; Replace with 0 to disable return { response }; update_interval: 24h switch: - platform: template name: alert id: alert optimistic: true turn_on_action: - light.turn_off: color_led - light.turn_on: id: white_led brightness: 100% color_temperature: 4000 K (continues on next page)
18 Chapter 3. Lights diyHue Documentation, Release 1.0
(continued from previous page) - delay: 1s - light.turn_on: id: white_led brightness: 10% color_temperature: 4000 K - delay: 1s - light.turn_on: id: white_led brightness: 100% color_temperature: 4000 K - delay: 1s - light.turn_on: id: white_led brightness: 10% color_temperature: 4000 K - delay: 1s - light.turn_on: id: white_led brightness: 100% color_temperature: 4000 K - switch.turn_off: alert web_server: port: 80
3.6 YeeLight
Yeelight bulbs are automatically discovered and added to hue emulator on light search performed from Hue app. The light must be first connected to the local WiFi network and LAN control must be enabled from the YeeLight app. This can be done from the eject icon located in bottom right corner of the app. If light IP address changes, you need to perform a new light search in order to update the IP address for all the lights. To avoid this, you can give each light a static IP address in your routers settings.
3.7 Raspbee
The Raspbee module is used with Deconz, the software dedicated for this module that provides an API similar to the Hue API
3.7.1 ZigBee Devices With Built In Support
• Trandri Remote • Tradfri Wireless Dimmer • Tradfri Motion Sensor • Tradfri On/Off Switch • Xiaomi Aquara Motion Sensor *Other devices can still be manually configured to perform actions with custom Hue rules
3.6. YeeLight 19 diyHue Documentation, Release 1.0
3.7.2 Deconz installation
• Execute raspi-config and turn off the serial login as this will enter in conflict with deconz (do not disable also the hardware serial port) • Follow the steps from here: https://github.com/dresden-elektronik/deconz-rest-plugin for the deconz.deb pack- age download and installation (no need to install dev package or compile the code) • Override bind port of Deconz service to port 8080 in systemd unit file: – run sudo systemctl edit deconz.service – in opened editor put following file content and save file:
[Service] ExecStart= ExecStart=/usr/bin/deCONZ -platform minimal --http-port=8080 --upnp=0 --
˓→ws-port=8081
Docker: • If you are using docker, you can run the container with the following command:
docker run -d \ --name=deconz \ --net=host \ --restart=always \ -e DECONZ_WEB_PORT=8080 \ -e DECONZ_WS_PORT=8081 \ -v /etc/localtime:/etc/localtime:ro \ -v /opt/deconz:/root/.local/share/dresden-elektronik/deCONZ \ --device=/dev/ttyAMA0 \ marthoc/deconz
• To swap Bluetooth to /dev/S0 (moving RaspBee to /dev/ttyAMA0), run the following command and then reboot:
echo 'dtoverlay=pi3-miniuart-bt' | sudo tee -a /boot/config.txt
• Start the Deconz service, browse to http://{hue emulator ip}:8080 and add all zigbee devices. This is done by clicking “Open network” in settings and then reset the devices. Don’t configure any device in deconz. • Start hue emulator (you should see in the logs the import of all zigbee devices) • Click “Unlock Gateway” in the Deconz settings to allow hue emulator to register, then open http://{hue emulator ip}/deconz to automatically register the bridge emulator with Deconz. In order to configure IKEA switches you must first configure the rooms. Updates to the Deconz service made in your OS for any reason will most likely overwrite the changes made to the deconz systemctl service file. To prevent that from happening, you can divert updates to that file. If installing in Raspian/Ubuntu/Debian, use the following command to divert updates to that file to another location: sudo dpkg-divert –package deconz –add –rename –divert /home/
20 Chapter 3. Lights diyHue Documentation, Release 1.0
3.7.3 Sensors and Switches Configuration
• Tradfri Motion Sensors will be added as Hue Motion Sensors and must be configured from the Hue application. With the original rules in place it will work like a Hue Motion Sensor (ex: dim the light with 30 second before turning off) • Tradfri Dimmers and Tradfri Remotes must be configured from http://{hue emulator ip}/deconz Tradfri Remotes can be configured to work on a specified room (the same as it was developed to) or to act as if it is a Hue Dimmer Switch or Hue Tap Switch, where they must be configured from the Hue application. When this happens the Tradfri Remote will not be displayed anymore in the Deconz configuration page and can be added back only by removing it from Hue application. The Tradfri Remote has 5 buttons, while both hue switches have only 4 so for the Tap Switch the top button doesn’t perform any action. For the Dimming Switch, the center button is “On”, up/down are brightness up/down and both left/right buttons will turn of the light. The reason I added the feature to transform the Tradfri Remote into a Hue Switch is because it can then switch scenes where color lights are used, while the Tradfri Remote was designed just to change the brightness and color temperature.
3.8 MQTT - zigbee2mqtt
diyHue has support for lights that are controlled over mqtt. It uses the auto discovery feature described here. This emulator connects directly to mqtt (after you set the correct parameters), and subscribes to the defined auto discovery prefix. You’ll still need to look for lights (in the app), but any lights that emit an auto discovery message are added once you search for lights. For this to work you’ll need to setup a mqtt server, that is out of the scope of this documentation.
3.8.1 Configuration
You will need to start the bridge once (this will generate/update the config) and then you’ll need to edit the config. json file. If you’re using docker to run diyHue, make sure you stop the container before changing the config file. This is only a small portion of the config, but you should look for the emulator => mqtt section. It should look like this:
{ "emulator":{ "alarm":{ "email":"", "lasttriggered": 100000, "on": false }, "mqtt":{ "discoveryPrefix": "homeassistant", "enabled": false, "mqttPassword":"", "mqttPort": 1883, "mqttServer": "mqtt", "mqttUser":"" } }, }
3.8. MQTT - zigbee2mqtt 21 diyHue Documentation, Release 1.0
Now fill in the correct values: • discoveryprefix: don’t change • enabled: “true” (if mqttServer isn’t set correctly, hue-emulator will not be reachable) • mqttUser, mqttPassword and mqttPort: Match the setting on the mqtt server. Default values are already filled in. • mqttServer: Enter the server IP, eg. “127.0.0.1” or “localhost” if the server runs on the same machine.
3.8.2 Zigbee2mqtt
Zigbee2mqtt is a really nice application that uses a (pretty) cheap zigbee device and lets you control it from a mqtt server. To use zigbee2mqtt with diyHue, you’ll need to make sure the you turned on homeassistant in the configuration. This will make zigbee2mqtt start sending the auto discovery messages.
homeassistant: true
By using zigbee2mqtt and a compatible zigbee device together with diyHue you could replace the original bridges for zigbee lights. Hue bridge and/or TradFri.
3.8.3 Other mqtt lights
We have only tested it with zigbee2mqtt, but other lights that are controlled by mqtt can maybe also work. You have to publish the correct auto discovery message to mqtt for diyhue to be able to pick it up.
3.8.4 Protocol
Auto discovery messages look like this. Topic homeassistant/light/{light-id}/light/config
{ "brightness" : true, "xy" : true, "schema" : "json", "command_topic" : "zigbee2mqtt/naam-van-lamp/set", "state_topic" : "zigbee2mqtt/naam-van-lamp", "json_attributes_topic" : "zigbee2mqtt/naam-van-lamp", "name" : "naam-van-lamp_light", "unique_id" : "0x0017xxxec5e_light_zigbee2mqtt", "device" :{ "identifiers" :[ "zigbee2mqtt_0x0017xxxec5e"], "name" : "naam-van-lamp", "sw_version" : "Zigbee2mqtt 1.11.0", "model" : "Hue Bloom (7299760PH)", "manufacturer" : "Philips" }, "availability_topic" : "zigbee2mqtt/bridge/state" }
diyHue subscribes to {discoveryPrefix}/light/+/light/config and uses the brightness, ct and xy values to determine the light type. The state_topic is used to get data from the light and the command_topic is used to send a new state to the light. Sample state message, topic: zigbee2mqtt/naam-van-lamp
22 Chapter 3. Lights diyHue Documentation, Release 1.0
{ "state" : "ON", "brightness" : 200, "color" :{ "x" : 0.7006, "y" : 0.2993 } }
The light is controlled by sending a message like the state message to the command_topic like zigbee2mqtt/ naam-van-lamp/set.
{ "state" : "ON", "brightness" : 200, "ct": 200, "color" :{ "x" : 0.7006, "y" : 0.2993 } }
MQTT lights are only available since this pr, so no support for sensors yet. But you can always contribute to this feature.
3.9 Home Assistant
diyHue has support for lights that are controlled via Home Assistant. You setup the lights you wish to include/exclude in Home Assistant. You then search for lights (in the app) and thelights will be added. For this to work you need to have a working Home Assistant setup with the Rest API enabled. This is out of scope of this documentation - please check the Home Assistant documentation.
3.9.1 Configuration
Note: Once you have completed the setup below you will need to search for lights in Hue Essentials/Hue App or you can navigate to http://diyhue_ip/scan
You will need to start the bridge once (this will generate/update the config) and then you’ll need to edit the config. json file. If you’re using docker to run diyHue, make sure you stop the container before changing the config file. This is only a small portion of the config, but you should look for the emulator => homeassistant section. It should look like this:
{ "emulator":{ "homeassistant":{ "enabled": false, "homeAssistantIp": "127.0.0.1", (continues on next page)
3.9. Home Assistant 23 diyHue Documentation, Release 1.0
(continued from previous page) "homeAssistantPort": 8123, "homeAssistantToken":"", "homeAssistantIncludeByDefault": true }, } }
Now fill in the correct values: • enabled: “true” • homeAssistantIp: set to the IP address of your Home Assistant install • homeAssistantPort: By default this is 8123 but change it here if you are running on a different port. • homeAssistantToken: This is a Home Assistant long lived access token - details are on the Home Assistant website on how to create one • homeAssistantIncludeByDefault: If set to “true” all lights from Hoem Assistant will be included unless you explicity exclude them. If you don’t want all the lights in Home Assistant to be included then set this to “false” and explicity include the lights you want to use in diyhue Most of the other lights that diyhue supports could also be added directly to Home Assistant. If you are using the Home Assistant integration you may wish to disable the other integrations so that they don’t appear in diyHue directly (e.g. Shelly, Tasmota) if you plan to expose these devices by Home Assistant. This can be done by editing the config.json file. Look for the emulator section and set any you wish to disable to “false”
{ "emulator":{ "esphome":{ "enabled": false }, "hyperion":{ "enabled": false }, "network_scan":{ "enabled": false }, "shelly":{ "enabled": false }, "tasmota":{ "enabled": false }, "yeelight":{ "enabled": false } } }
3.9.2 Including/Excluding Lights in Home Assistant
To include or exclude individual lights you do this in Home Assistant by customizing the entity. You can do this in several ways - one way is to use the UI using the customize entities page :
24 Chapter 3. Lights diyHue Documentation, Release 1.0
You need to add an attribute called diyhue and set it to include to include the light and exclude to exclude the light. Another way is to enter it manually into the Home Assistant config files:
light.my_light_1: diyhue: include light.my_light_2: diyhue: exclude
3.9.3 Configure Rooms/Zones/Groups in Home Assistant
You can set Home Assistant lights to go into a Room/Zone/Group by customizing entities. Which will reduce the requirment to set these up via the apps. In the same way as you Include/Exclude lights you do this by customizing the entity in Home Assistant. You can add the following key and the value is the name you want to use: • diyhue_room • diyhue_zone • diyhue_group The integration will add it to a room with exactly the same name, if one doesn’t exist then it will create one. Whilst a light can be added to multiple zones/groups using the Hue App or Hue Essentials when the configuration is done in Home Assistant it only supports a single group/zone/room for each light. However this doesn’t stop you using the apps to add the light to additional Groups/Zones. You can also set the icon if a room is created by setting diyhue_class. If the room already exists then this will be ignored. It won’t change an existing icon. The class has to be a valid icon string otherwise the Hue app will continually crash so be careful. To find valid icon strings set an icon on a room and look in the Hue Essentials app for the group and look at it’s “class”. If the room already exists then this will be ignored. It won’t change an existing icon. Some valid examples: • “Attic” • “Barbecue” • “Bathroom” • “Bedroom” • “Garden” • “Hallway” • “Kids bedroom” • “Kitchen” • “Living room” • “Lounge” • “Nursery” • “Staircase”
3.9. Home Assistant 25 diyHue Documentation, Release 1.0
• “Storage” • “Studio” • “Terrace” Full example of adding a light to a room with an icon in Home Assistant using the customize.yaml light.shower_room_spot_lights diyhue: include diyhue_class:"Bathroom" diyhue_room:"Shower Room"
26 Chapter 3. Lights CHAPTER 4
Additional Functions
4.1 Alexa
Follow the instructions below to pair diyHue with Alexa. The Original Alexa Hue Skill is not required. 1. open “devices” in the amazon Alexa app 2. press “add device” 3. select “other” 4. go to http://{IP_ADDRESS}/hue/linkbutton and press “activate” 5. press “Discover devices” in amazon Alexa app Alexa will find your lights shortly.
4.2 Sensors
For ZigBee sensors and switches check Raspbee module
4.2.1 Switches
The Dimmer Switch and Tap Switch are almost identical, the only difference is that dimmer switch can control the lights without the bridge (for this reason bridgeIp is declared as an array to setup more IP’s), and the button codes are different.
Circuit diagram
Device Prototype
27 diyHue Documentation, Release 1.0
How it works
When the switch powers on, a GET request will be sent to the bridge , ex: http://{bridgeIP}/switch? mac=xx:xx:xx:xx:xx:xx&devicetype=ZLLSwitch The bridge will then check based on MAC address if the switch is already registered or not. If not, it will register making it available for configuration in the Hue ap- plication. After 3-5 seconds the ESP8266 will enter deep sleep mode and will consume less than 20uA. On every button press there will be a short negative pulse on ESP8266 RST pin that will wake up the device. It will then read the input pins to check what button was pressed and send a request like this: http://{bridgeIP}/switch? mac=xx:xx:xx:xx:xx:xx&button=1000 The bridge will then process all rules and perform the action con- figured for this button.
4.2.2 Motion Sensor
Circuit diagram
Device prototype
How is working
Exactly like the switches, the sensor will be registered on power on with a GET request: http://{bridgeIP}/ switch?mac=xx:xx:xx:xx:xx:xx&devicetype=ZLLPresence and configuration can then be done from the Hue application. The ESP8266 will wake up from deep sleep on every PIR positive signal on the GPIO5 pin and every 20 minutes to send the light sensor data. Request example: http://{bridgeIP}/switch? mac=xx:xx:xx:xx:xx:xx&lightlevel=46900&dark=false&daylight=true&presence=true It is important to choose a low power PIR that can run on batteries for many months. The PIR used in my example is an HC-SR501, that is very common in DIY projects. To increase the battery life I removed the 3.3V voltage regulator as this is not needed with batteries. GPIO4 will output +3V only when the light level is measured in order to lower the power consumption.
4.3 Hue Entertainment
The DTLS server used by Hue Entertainment is a 3rd party service build in C. Precompiled binaries are provided for x86_64, i686 (x86), aarch64, arm64 (e.g. Rock Pi) and arm (e.g. Raspberry Pi) architectures. For any other
28 Chapter 4. Additional Functions diyHue Documentation, Release 1.0
4.3. Hue Entertainment 29 diyHue Documentation, Release 1.0
30 Chapter 4. Additional Functions diyHue Documentation, Release 1.0 architecture the service must be compiled from source. It would be good if the compiled executable could be uploaded with a pull request for other architectures.
4.3.1 Compilation Commands wget https://github.com/ARMmbed/mbedtls/archive/
˓→1ab9b5714852c6810c0a0bfd8c3b5c60a9a15482.zip unzip1ab9b5714852c6810c0a0bfd8c3b5c60a9a15482.zip cd mbedtls-1ab9b5714852c6810c0a0bfd8c3b5c60a9a15482/ wget https://raw.githubusercontent.com/diyhue/diyHue/master/BridgeEmulator/ssl_
˓→server2_diyhue.c make no_test gcc-I./include ssl_server2_diyhue.c-o ssl_server2_diyhue-L./library-lmbedtls-
˓→lmbedx509-lmbedcrypto
4.4 Enable debug mode
4.4.1 Host install
1. Stop the hue-emulator service:
sudo systemctl stop hue-emulator
2. Change directory to the application home directory:
cd/opt/hue-emulator
3. Start the script with sudo ./HueEmulator3.py --debug Try to avoid unnecessary debugging output generated by other devices that you know work correctly fine such as home assistant, and working lights. The easiest method to prevent this is by temporally turning the working devices off. It is important to save a backup of your config file before entering debug mode and if any changes to your config are made while in debug mode to save the config manually before issuing the keyboard interrupt to stop debug mode. You can do this by issuing an HTTP request from your browser to http://IP.OF.DIY.HUE/save. This will save your configuration file to the DIYHue working directory (/opt/hue-emulator/ if using the easy-install method).
4.4.2 Docker install
Add the following environment variable to your docker run command. This can be set to true or false to turn debug on or off.
-e"DEBUG=true"
4.4.3 HTTPS certificate check
To test the https certificate you can use this command from the terminal of the device running diyHue: curl https://127.0.0.1/api/nouser/config-v-k
Sample output:
4.4. Enable debug mode 31 diyHue Documentation, Release 1.0
pi@raspberrypi:~ $ curl https://127.0.0.1/api/nouser/config -v -k * Trying 127.0.0.1... * TCP_NODELAY set * Connected to 127.0.0.1 (127.0.0.1) port 443 (#0) * ALPN, offering h2 * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: /etc/ssl/certs/ca-certificates.crt CApath: /etc/ssl/certs * TLSv1.2 (OUT), TLS header, Certificate Status (22): * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-ECDSA-AES128-GCM-SHA256 * ALPN, server did not agree to a protocol * Server certificate: * subject: C=NL; O=Philips Hue; CN=b827ebfffec8991c * start date: Jul 22 17:40:03 2018 GMT * expire date: Jul 19 17:40:03 2028 GMT * issuer: C=NL; O=Philips Hue; CN=b827ebfffec8991c * SSL certificate verify result: unable to get local issuer certificate (20), ˓→continuing anyway. > GET /api/nouser/config HTTP/1.1 > Host: 127.0.0.1 > User-Agent: curl/7.52.1 > Accept: */* > < HTTP/1.1 200 OK < Server: nginx < Date: Tue, 11 Sep 2018 12:43:26 GMT < Content-type: application/json < Content-Length: 227 < * Curl_http_done: called premature == 0 * Connection #0 to host 127.0.0.1 left intact {"name":"Philips hue","factorynew":false,"mac":"b8:27:eb:c8:99:1c","datastoreversion
˓→":70,"bridgeid":"B827EBFFFEC8991C","modelid":"BSB002","swversion":"1806051111",
˓→"replacesbridgeid":null,"starterkitid":"","apiversion":"1.24.0"}
Here are the important lines: issuer: C=NL; O=Philips Hue; CN=b827ebfffec8991c and
{"name":"Philips hue","factorynew":false,"mac":"b8:27:eb:c8:99:1c","datastoreversion
˓→":70,"bridgeid":"B827EBFFFEC8991C","modelid":"BSB002","swversion":"1806051111",
˓→"replacesbridgeid":null,"starterkitid":"","apiversion":"1.24.0"}
The CN value of the certificate must be the same as the bridgeid key from the json output. This must also represent
32 Chapter 4. Additional Functions diyHue Documentation, Release 1.0 the mac address of the main interface with fffe in the middle.
4.5 Home Kit
Follow the below instuctions to setup diyHue to work with Home Kit 1. Install homebridge 2. Install homebridge-hue 3. Prepare config.json for homebridge with an intial homebridge-hue plugin setup (need to be modified after the first run, see next step):
config.json initial: { "bridge":{ "name":"HB_Diy_Hue", "username":"mac-address homebridge", "port": 51838, "pin":"whatyouwant" }, "accessories": [], "platforms":[ { "platform":"Hue", "users":{ "":"" }, "hosts":"put_here_the_ip_diyhue_bridge", "sensors": false, "nativeHomeKitSensors": true, "nativeHomeKitLights": false, "excludeSensorTypes":["Daylight","CLIP","Geofence"], "lights": true } ] }
4. Run home bridge for the first time (not via service). Run sudo homebridge -U /
sudo homebridge-U/home/pi/.homediyhue
[2/3/2019,9:24:33 AM] [Hue] RpiHue: HA-Bridge v1810251352, api v1.24.0 [2/3/2019,9:24:33 AM] [Hue] RpiHue: bridge request2: post/{"devicetype":
˓→"homebridge-hue#raspberrypi"} [2/3/2019,9:24:33 AM] [Hue] RpiHue: bridge error 101: link button not pressed [2/3/2019,9:24:33 AM] [Hue] RpiHue: press link button on the bridge to create a
˓→user
5. Go to diyhue webpage and simulate the link button pressed (http://{IP_ADDRESS}/hue/linkbutton):
[2/3/2019,9:24:48 AM] [Hue] RpiHue: created user- please edit config.json and
˓→restart homebridge "platforms":[ { "platform":"Hue", (continues on next page)
4.5. Home Kit 33 diyHue Documentation, Release 1.0
(continued from previous page) "users":{ "B827EBFFFE959284":"470a0c52e89555f73b11904c84af6192" } } ]
6. Stop homebridge 7. Edit config.json with this user 8. Start homebridge (via service or manually):
[2/3/2019,9:24:48 AM] [Hue] RpiHue:5 accessories [2/3/2019,9:24:48 AM] [Hue] masked debug info dumped to/home/pi/.homediyhue/
˓→homebridge-hue.json.gz [2/3/2019,9:24:48 AM] [Hue] Initializing platform accessory'RpiHue'... [2/3/2019,9:24:48 AM] [Hue] RpiHue:2 services [2/3/2019,9:24:48 AM] [Hue] Initializing platform accessory'Hue bulb Plug 01'... [2/3/2019,9:24:48 AM] [Hue] Initializing platform accessory'Hue bulb Plug 01 2'.
˓→.. [2/3/2019,9:24:48 AM] [Hue] Initializing platform accessory'Hue bulb Plug 01 3'.
˓→.. [2/3/2019,9:24:48 AM] [Hue] Initializing platform accessory'Hue bulb Plug 01 4'.
˓→..
4.6 Domoticz diy-hue includes native support for Domoticz lights/switches. As there is no discover process provided by domotics, they must be added manually into ‘’config.json”.
4.6.1 Add a new light(s)
1. Stop the hue-emulator service sudo systemctl stop hue-emulator 2. Save ‘’config.json” sudo cp /opt/hue-emulator/config.json /opt/hue-emulator/config.json.bak 3. Edit config.json sudo nano /opt/hue-emulator/config.json • Add light adress
{ "lights_address":{ "3":{ "ip": "192.168.1.100:8080", "light_id": "281", "protocol": "domoticz" }, }, }
34 Chapter 4. Additional Functions diyHue Documentation, Release 1.0 ip is the Domoticz host light_id is the light/switch IDX "protocol": "domoticz" allow diyhue to format the correct request • Add light details for hue app
{ "lights":{ "3":{ "manufacturername": "domoticz", "name": "Eettafel", "state":{ "alert": "none", "on": true, "reachable": true }, "swversion": "V1.04.12", "type": "On/Off plug-in unit", "uniqueid": "xx:xx:xx:xx:xx:xx:xx:xx-xx" }, } }
4. Restart the hue-emulator service sudo systemctl start hue-emulator
4.7 Command Line Arguments diyHue has several options that can be passed in at run time. These options allow easy, and more complex configuration of diyHue.
4.7.1IP
The IP argument can be used to provide the IP address of the host machine running diyHue. If you use this argument, you must also provide a value for the MAC argument. This argument is typically only used with docker. If you are running diyHue directly on the host (easy install), then use the following format:
--ip XX.XX.XX.XX
If you are running diyHue with our docker image, then add the following environment variable to your docker run command:
-e"IP=XX.XX.XX.XX"
4.7.2 MAC
The MAC argument can be used to provide the MAC address of the host machine running diyHue. If you use this argument, you must also provide a value for the IP argument. This argument is typically only used with docker. If you are running diyHue directly on the host (easy install), then use the following format:
4.7. Command Line Arguments 35 diyHue Documentation, Release 1.0
--mac XX:XX:XX:XX
If you are running diyHue with our docker image, then add the following environment variable to your docker run command:
-e"MAC=XX:XX:XX:XX"
4.7.3 IP Range
The IP Range argument can be used to set the IP range for light discovery. The default range is 0 to 255. If you are running diyHue directly on the host (easy install), then use the following format:
--ip_range
If you are running diyHue with our docker image, then add the following environment variable to your docker run command:
-e"IP_RANGE=
4.7.4 Deconz
The Deconz argument can be used to provide the IP address of your Deconz instance if it is not hosted on the same device as diyHue. If you are running diyHue directly on the host (easy install), then use the following format:
--deconz XX:XX:XX:XX
If you are running diyHue with our docker image, then add the following environment variable to your docker run command:
-e"DECONZ=XX:XX:XX:XX"
4.7.5 Debug
For instructions on the debug argument please see Enable debug mode
4.8 Alarm
It is possible to receive email notifications when a motion sensor is triggered while the alarm is active. At this moment the alarm can be configured manually by editing the file /opt/hue-emulator/config.json while the service is stopped. You need to set just your email address and to switch the “on” value between true or false to enable / disable the alarm. ‘‘‘ “emulator”: { “alarm”: { “email”: “[email protected]”, “lasttriggered”: 1585935069, “on”: false } } ‘‘‘
36 Chapter 4. Additional Functions CHAPTER 5
Uninstall
Why on earth would you want to uninstall diyHue! All joking aside, uninstall is super easy if you need a fresh install, your moving over to new hardware or maybe diyHue just isnt for you.
5.1 Docker Uninstall
You can easily remove the diyHue docker container and image with one command: sudo docker rm diyHue&& sudo docker rmi diyhue/core
5.2 Host Uninstall
5.2.1 Automatic Uninstall
If you used the automatic install method, just run the following command to uninstall: curl-s https://raw.githubusercontent.com/diyhue/diyHue/master/BridgeEmulator/easy_
˓→uninstall.sh| sudo bash/dev/stdin
This will stop diyHue, remove the astral python library, remove the diyHue files and remove the diyHue service. It will leave the packages installed by diyHue in case they are used by other services. These packages are: • unzip • nmap • python3 • python3-requests • python3-ws4py • python3-setuptools
37 diyHue Documentation, Release 1.0
Remove these at your own discression.
38 Chapter 5. Uninstall CHAPTER 6
FAQ
6.1 What lights can I use with this project?
• MiLight • Yeelight • LYT8266 • Phillips Hue • Ikea Tradfri The following can be controlled with an ESP8266 or ESP32: • WS2812B and SK6812 smart led strips • Pwm RGB-CCT LEDs • Pwm RGBW LEDs • Pwm RGB LEDs • Pwm CCT LEDs • Pwm Dimming (up to 6 lights for every esp8266) • On/Off plugs/lights (up to 6 lights for every esp8266) • On/Off 433Mhz devices (multiple devices for every esp8266)
6.2 Do I need a Phillips Hue Bridge to control genuine Phillips Hue bulbs with diyHue?
Hue bulbs use the zigbee radios to comunicate so you either need a genuine Phillips Hue Bridge or a raspbee module.
39 diyHue Documentation, Release 1.0
6.3 Unable to Connect - diyHue Bridge is detected but i can´t pair!
In order to connect with diyHue, you need to pair the APP with the Bridge Emulator. Press Activate Button of diyHue found here http://{IP_ADDRESS}/hue/linkbutton with default credentials Hue:Hue If Hue Essentials app (or other 3rd party hue apps) can pair with the bridge emulator but official Hue app not most likely you have a [bad https certificate](https://diyhue.readthedocs.io/en/latest/AddFuncts/debug.html# https-certificate-check) For further Info see the Configuration page
6.4 My Phillips TV detects diyHue Bridge but I am unable establish a connection
Follow the instructions for pairing. In addition it can help to disconnect your Internet for a short period to make sure the TV performs a local Network search instead of using remote API of Phillips.
6.5 What do I need to use IKEA Tradfri devices?
IKEA Tradfri bulbs can be controlled when paired with an IKEA hub. If you wish to use IKEA switches then you must use the Raspbee module. This will enable you to control both the IKEA lights and switches without an IKEA hub.
6.6 App XYZ doesn’t work!
Not all apps for Phillips Hue work out of the box with diyHue. If you are unable to pair the app with diyHue automatically, try looking for a manual pair option in the app. If that fails then open an issue here on GitHub. We will try our best to to get your app to work but due to the lack of support for the remote API with diyHue, some apps will never work.
6.7 My Google Home / Google Assistant doesn’t find diyHue!
Google Assistant uses the remote API to find your Hue bridge. The remote API is not supported by diyHue. At the moment it looks like it never will. However, don’t despair. There is an option to get it to work. [Home Assistant](https: //www.home-assistant.io/) is software used to provide a unified hub for all your smart devices. It has support for diyHue and Google Assistant, so you can import your diyHue lights into Home Assistant and use Google Assistant to control them via Home Assistant. There are plenty of instructions on the Home Assistant website however details on Phillips Hue with home assistant can be found [here](https://www.home-assistant.io/components/hue/) and details on Google Assistant [here](https://www.home-assistant.io/components/google_assistant/) If you need more help, ask on our Slack chat or on the Home Assistant forums.
6.8 Philips Hue App complains about Bridge v1 detected and not supported anymore
The most common reason for this is because your diyHue Installation hasn’t go created a valid certificate.
40 Chapter 6. FAQ diyHue Documentation, Release 1.0
How to check this? Just type curl https://
6.8. Philips Hue App complains about Bridge v1 detected and not supported anymore 41 diyHue Documentation, Release 1.0
42 Chapter 6. FAQ CHAPTER 7
diyHue - Development
diyHue is an application written in python 3. To do any development you’ll need some basic programming knowledge. First you create a fork of diyhue on github. Create diyhue fork. If you already had a fork, make sure it’s in sync with the master branch.
# Add the remote, call it "upstream": (only once) git remote add upstream https://github.com/diyHue/diyHue.git
# Fetch all the branches of that remote into remote-tracking branches, # such as upstream/master: git fetch upstream
# Make sure that you're on your master branch: git checkout master
# Rewrite your master branch so that any commits of yours that # aren't already in upstream/master are replayed on top of that # other branch: git rebase upstream/master
7.1 Repository content
• .build/ - build requirements – select.sh - Script to move the correct coap client and entertainment service for the target platform, used in docker. • .github/ - github specific files (workflows / issue templates) • BridgeEmulator/ - The actual bridge emulator – functions/ - functions used in the bridge – protocols/ - Light connections (mqtt, esphome, tasmota,. . . )
43 diyHue Documentation, Release 1.0
– web-ui-src/ - The webinterface (unpackaged) – web-ui/ - Webinterface packaged – HueEmulator3.py - The main executable – coap-client-* - Pre-compiled coap client for connection with Ikea Tradfri bridge – entertainment-* - pre-compiled entertainment service. Used to setup the entertainment service for the hue bridge. – ssl_server2_diyhue.c - Source of entertainment service. • RemoteApi/ - Server used to create a remote connection.
7.2 Docker development
If you don’t want to install python or the diyhue emulator on your machine, you can use these steps to setup your local development environment with the help of docker. Docker is the recommended way to develop and test your changes to diyhue.
7.3 Requirements
• Docker (desktop), windows Docker desktop with linux containers • Editor like VSCode • A folder to put the configuration • You cannot have the bridge running on this PC, because of the required ports
7.4 Build docker image
The docker image for diyHue can be build for multiple architectures. Recently we added a Dockerfile that works for all (supported) architectures. • Linux 64-bit amd64 • Arm (raspberry pi 3 eg.) arm/v7 • Arm 64-bit (raspberry pi 3b/4 eg.) arm64 Run the following command from the root of the repository to build the image docker build -t diyhue:development -f ./.build/Dockerfile --build-args
˓→TARGETPLATFORM=amd64 .
# Or the following if you enabled buildx for multi architecture images docker build -t diyhue:development -f ./.build/Dockerfile --load .
7.5 Start docker image
Once you made your changes and build the image, you’ll need to run the following command to run your new image in debug mode. Before running change the values to your needs, so make sure you set the MAC variable to your used
44 Chapter 7. diyHue - Development diyHue Documentation, Release 1.0 network card and the IP to the IP of your machine. Also change the folder /Users/you/diyhue/export to your own configuration folder.
# Stop and remove current dev container docker stop diyhue-dev&& docker rm diyhue-dev
# Create new container docker run -d --name "diyhue-dev" --restart="unless-stopped" --network="bridge" \ -v '/Users/you/diyhue/export':'/opt/hue-emulator/export/':'rw' \ -e MAC='f4:0f:05:01:01:01' \ -eIP='192.168.x.x' \ -e disable-online-discover='true' \ -e DEBUG='true' \ -p 80:80/tcp -p 443:443/tcp -p 1900:1900/udp -p 2100:2100/udp -p 1982:1982/udp \ diyhue:development
# Open logging docker logs -f diyhue-dev
7.6 Publishing the docker image
If you want to publish the multiarchitecture image of diyHue, you’ll need to setup [Docker buildx](https://docs.docker. com/buildx/working-with-buildx/). Once setup it’s a one line command to publish this image to the docker hub for multiple architectures. Caution, the first time it has to download a lot of packages for 3 platforms. This will take some time. After the first time the requirements are cached and building should be a lot faster. docker buildx build \ --platform linux/amd64,linux/arm64,linux/arm/v7 \ -t diyhue/core:development \ -f .build/Dockerfile \ --push .
7.6. Publishing the docker image 45 diyHue Documentation, Release 1.0
46 Chapter 7. diyHue - Development CHAPTER 8
Indices and tables
• genindex • modindex • search
47