[GUIDE] Using the Hue App with Home Assistant (via DiyHue)

I wanted to use the Hue App to control Home Assistant lights as some members of the family prefer the Hue App to the Home Assistant interface.

So I set out to add Home Assistant integration into diyHue (https://diyhue.org/) and as luck would have it at the same time @MaxBec92 created the DiyHue Addon that has now been included in the diyhue project (https://github.com/diyhue/hassio-addon) here is how to configure everything you need to get the Hue App working to control Home Assistant lights…

Before we start one limitation of this setup is that the Hue App will only work when your phone is on the same local network as your Home Assistant installation - it isn’t a solution for remote access.

You will also need to setup your own home network dns so that my.domain.com points to your home assistant server. This is out of scope of this guide as all networks are different.

This setup will then mean that from now on when on your home network if you enter

Install Diy Hue Addon

  1. First are you using port 80 or 443 on your home assistant install? E.g. if you are using the “NGINX Configurable Home Assistant SSL proxy” addon. If so you need to stop the services running on these ports to start with. If you are using NGINX add on there is an alternative later in this guide.

  2. Install the DiyHue Add on (but don’t start it!) from here: https://github.com/diyhue/hassio-addon

  3. Once installed you need to configure the add on it as follows setting the MAC address is very important before the first run - this is the MAC address of your server.

(debug isn’t strictly necessary but does make it easier to check issues - if you are running on a pi or similar you should disable debug once it is working to preserve the SD card)

  1. Start the add on.

  2. Navigate to http://

  3. Open up either the Hue Essentials or normal Hue App on your phone and add a new hub.

E.g. in the Hue App click settings “Add Hue Bridge”, it will search but if you don’t want to wait you can click “help” and enter the IP address of your server. It will ask you to push the “Hue Link Button” to do this on diyHue you need to go to the web UI we opened in Step (4) and click “Link Device”. The default username and password are Hue/Hue. Then click the “Activate” button.

  1. If everything is successful the Hue App should connect - however at this stage it may not have any lights setup we will do this in the next step.

Setup DiyHue to connect to Home Assistant

  1. Stop the diyHue add on

  2. Find diyHue’s config.json file. If you have access to the server and configured the add on as above then it will be in /usr/share/hassio/homeassistant/diyhue

  3. Check the diyHue docs on how to configure diyHue’s connection to Home Assistant here: Home Assistant — diyHue 1.0 documentation

  4. Start the DiyHue Add on and check the logs to ensure there are no errors.

  5. In the Hue App / Hue Essentials search for lights - it might say it didn’t find any but this is ok. Once you enter out of the search screen you should see the lights.

  6. Toggle a light to make sure it is working

Re-enable port 443 / 80

If you were using the “NGINX Configurable Home Assistant SSL proxy” on port 443/80 to access the Home Assistant lovelace UI then this addon isn’t compatible with running diyHue however I have created a modified add on here: https://github.com/foxy82/ha-addons. Unfortunately if you are using port 443/80 for something else then I can’t easily help but comment and we can see what we can do.

  1. Stop the diyhue addon

  2. Open the Hue App or Hue Essentials app and delete the hub you added in the first test.

  3. Go to the diyHue add on configuration page and change it so it doesn’t use port 443/80 by changing these settings, here i’ve used 41443 and 41080. Once changed save and restart the addon.

  1. Install my modified NGINX add on from: https://github.com/foxy82/ha-addons

  2. Set the config up like this being sure to enter your own domain. The fallback_certfile and fallback_keyfile were created by diyHue when you first started the diyHue addon.

  1. On your server go to /usr/share/hassio/share and create a directoy called nginx_proxy

  2. In /usr/share/hassio/share/nginx_proxy create a file called diyhue.conf which contains the details below changing <your ip address> for your home assistant IP address e.g.

    server {
        server_name <your ip address>;
        ssl_certificate  /config/diyhue/cert.pem;
        ssl_certificate_key  /config/diyhue/cert.pem;

        listen 443 ssl http2;

        location / {
            proxy_pass http://<your ip address>:41080;
            proxy_set_header Host $host;
            proxy_http_version 1.1;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    server {
        server_name <your ip address>;

        listen 80;
        proxy_buffering off;

        location / {
            proxy_pass http://<your ip address>:41080;
            proxy_set_header Host $host;
            proxy_http_version 1.1;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  1. Start my modified NGINX add on

  2. Navigate to http:// :41080

  3. Open Hue Essentials or Hue App on your phone and it should successfully connect. Try toggling a light to make sure it is working.

E.g. in the Hue App click settings “Add Hue Bridge”, it will search but if you don’t want to wait you can click “help” and enter the IP address of your server. It will ask you to push the “Hue Link Button” to do this on diyHue you need to go to the web UI we opened in Step (21) and click “Link Device”. The default username and password are Hue/Hue. Then click the “Activate” button.

There we have it - a lot of hard work went into making this work from both myself, @MaxBec92, @Mevel, and Mauris Moteta. It has included submissions to diyHue and creating the addons in use so if you are using this and it is working please let us know. Any comments please add them below.


UPDATE 01 July 2022

So this add on has now been picked up by the diyhue team. I’ve updated the documentation above.

However as of today please note there is an outstanding issue where the Hue app doesn’t work: https://github.com/diyhue/diyHue/issues/840 this is due to changes made by Hue that the diyHue team try to keep up with.

The Hue Essentials app does work though.

Moved to community guides.

Thank you very much for the guide, @foxy82. Will add this to the add-on if you are ok with it! :slight_smile:

Fine by me - although maybe we should wait a bit to see what feedback arrives as we might find this only works for me :slight_smile:

1 Like


I am trying to use DiyHue with Zigbee2mqtt add-on on HomeAssistant. The goal is to connect to Mosquito Broker from DiyHue and then discover all the lights from it. But the MQTT integration is not working. The DiyHue add on is not able to talk with Mosquito Broker. Mosquito Broker is running properly and I am able to use Zigbee2mqtt properly.

My configuration is

"emulator": {
        "alarm": {
            "email": "",
            "lasttriggered": 100000,
            "on": false
        "esphome": {
            "enabled": false
        "homeassistant": {
            "enabled": false,
            "homeAssistantIncludeByDefault": true,
            "homeAssistantIp": "",
            "homeAssistantPort": 8123,
            "homeAssistantToken": "",
            "homeAssistantUseHttps": false
        "hyperion": {
            "enabled": false
        "lights": {},
        "mqtt": {
            "discoveryPrefix": "homeassistant",
            "enabled": true,
            "mqttPassword": "mqtt_pass",
            "mqttPort": 1883,
            "mqttServer": "",
            "mqttUser": "mqtt_user"
        "network_scan": {
            "enabled": true
        "sensors": {},
        "shelly": {
            "enabled": false
        "tasmota": {
            "enabled": true
        "wled": {
            "enabled": false
        "yeelight": {
            "enabled": false

I am getting the following error on log

[cont-init.d] 00-banner.sh: exited 0.
[cont-init.d] 01-log-level.sh: executing... 
[cont-init.d] 01-log-level.sh: exited 0.
[cont-init.d] done.
[services.d] starting services
[services.d] done.
/config/diyhue exists.
Your Architecture is = amd64
2021-08-02 12:46:29,111 - root - INFO - Using Host
2021-08-02 12:46:29,111 - root - INFO - XXXXXXXXXXXX
Docker Setup Initiated
SSL certificate found
Config file found
Docker Setup Complete
2021-08-02 12:46:29,111 - root - INFO - IP range for light discovery: 0-255
2021-08-02 12:46:29,111 - root - INFO -
2021-08-02 12:46:29,111 - root - INFO - Online Discovery/Remote API Enabled!
2021-08-02 12:46:29,112 - root - INFO - Config loaded
Traceback (most recent call last):
  File "/opt/hue-emulator/HueEmulator3.py", line 2000, in <module>
    mqtt.mqttServer(bridge_config["emulator"]["mqtt"], bridge_config["lights"], bridge_config["lights_address"], bridge_config["sensors"])
  File "/opt/hue-emulator/protocols/mqtt.py", line 246, in mqttServer
    client.connect(config["mqttServer"], config["mqttPort"])
  File "/usr/local/lib/python3.8/site-packages/paho/mqtt/client.py", line 937, in connect
    return self.reconnect()
  File "/usr/local/lib/python3.8/site-packages/paho/mqtt/client.py", line 1071, in reconnect
    sock = self._create_socket_connection()
  File "/usr/local/lib/python3.8/site-packages/paho/mqtt/client.py", line 3522, in _create_socket_connection
    return socket.create_connection(addr, source_address=source, timeout=self._keepalive)
  File "/usr/local/lib/python3.8/socket.py", line 808, in create_connection
    raise err
  File "/usr/local/lib/python3.8/socket.py", line 796, in create_connection
ConnectionRefusedError: [Errno 111] Connection refused

When connecting the Hue app to your addon it says that a mandatory firmware update must be applied to the bridge . It won’t connect unless you click ‘update Hue bridge’ and that option gives a fail followed by try again later. So you can’t discover any lights…

Just tried Hue Essentials and that works though…

Recently Hue has updated the Firmware (swversion) of their Bridge.
A new Software Version is introduced.
In general diyhue does not use the swversion. It is only used for emulation.

However: Changing swversion can also imply changes to how things are handled on genuine hardware.

That being said it is possible that updating swversion without changes to diyhue could cause bugs.

In order to Update your swversion follow these steps:

Stop Emulator or Docker Container
edit config.json
in key “config” change “swversion”:“XXXXXXX” to “swversion”:“1945091050”
Note: do not change version in Lights!
restart Service or Docker Container
Update Message should be gone.

Dev Note: you can set “swversion”:“1999999999” to eliminate any future update requests but be advised as this may cause unkown error. try and error :slightly_smiling_face:

Source: APP requires Update of Hue Bridge - Update Fails - Hue Emulator - diyHue

One of the new features of the latest firmware is that the hub is capable of pushing the update events to clients that support the feature. It is no longer necessary to poll the hub. HomeAssistant supports this now.

Is this a feature that you hope to include in DIYHue?

BTW I have it all working I think from above. Only thing being that Hue Essentials keeps complaining it has lost connection - or can’t locate the DIYHue hub. But then a few seconds later it seems to work OK.

I think it may be more appropriate if I post this question in the DIYHue community…

As far as I can see, this currently is not working with App 4.x and API v2

In any case, I could not get any of this to work, neither via HASS add-on (stable and beta), nor with a direct install of beta on a separate server.

Hi there, got almost everything working,
expect that icant find my lights in the hue app. The ligths are tuya based and already configured in HA. Technically it should be possible or not ?
Further, is it possible to add the non hue lights to a hue entertainement area?
Reason: iwant to adress them via Hyperion ng. Thanks :slight_smile:

I’m trying to install the Add-on but i get the following error message:

Failed to install add-on

The command ‘/bin/bash -o pipefail -c mv /diyhue/BridgeEmulator/web-ui/ ./web-ui/’ returned a non-zero code: 1
How do I resolve this error?

I get the same error. This issue goes away when installing from the Beta branch, but I can’t get that version to discover any devices. The logs appear to have properly found all my lights but they just don’t show up in diyhue.

Even if I push forward I’m realizing the above port configurations don’t work with the beta version, diyhue ignores the port customizations and binds to 443 anyways (which fails since nginx is using it) so I can’t get both diyhue and nginx running simultaneously.

It’s also worth noting that the directory /usr/share/hassio doesn’t exist on supervised installs. I’m assuming this correlates with /share/ and glancing through the source seems to confirm that assumption, but I did spin my wheels here a bit.

I think we are strange place at the moment with diyhue/home assistant.

I wrote the original diyhue home assistant integration but not long after diyhue started quite a big rewrite. I’m not sure if they migrated the home assistant part to the rewrite (the beta branch) and at the moment I don’t have time to go back and investigate. Sorry.

DIYHue itself have launched a ha addon 2 Days ago… take a look at: GitHub - diyhue/hassio-addon

I’ve helped fix up the diyhue home assistant code as well as the diyhue addon and it works better now.

I’ve updated the instructions at the top of this post as well.

There are still a few outstanding issues… the ability to define rooms that are created in Home Assistant customizations isn’t working yet so you will need to sort your lights into rooms yourself.

Also I want to try and make it more responsive - if there is a change in a lights state the Hue Essential / Hue app won’t show them until DiyHue has polled for that update (I think this is every 60 seconds or so).

Great work updating the add on, however I seem to get stuck on step 5/6.

It seems that I may partly pair the Hue essential app with the bridge, but only if I manually write the IP-address even though the bridge shows up in the app without manually adding it, but still not correctly.

1)If I try to add the DiyHue bridge “the normal way” by pressing the device within the app and then clicking the “Link APP” in the browser the app says
“Unable to connect to the bridge, check the internet connection”, but I have connection.

  1. If I in the other way add the bridge the manual way , writing the IP address and port 80 and then press “Link APP” in the browser it connects. But if I press anywhere within the app the app refresh and says that the DiyHue Bridge is disconnected and if i press connect I get
    “Unable to connect. Couldn’t connect to the bridge, verify the internet connection”, but I have connection.
    I never get a request to use a password either, if I know should get that within Hue essentials too?

3)If I instead try to pair it with the Hue app, it just won’t pair I press the pair button within the browser but nothing happens.

The only program I know that may conflict with the add-on is the duckdns installation I have, which I have disabled and taken away the redirection in the router for.

I don’t know what may the problem be? any ideas what to look into?