Connecting a DHT-Sensor to WLED with Home Assistant integration

I've recently installed Home Assistant on my Raspberry Pi and ever since I have been looking at every piece of electronic equipment in my house and going "How can I integrate this thing into my HA-Instance?". People like me are probably why fridges now have remote code execution vulnerabilities and your toaster needs an active internet connection to function.

Anyway, the first targets were my two ESP32s running WLED, connected to some WS2812B LED-Strips in my kitchen and behind my desk. To my dismay, the setup of these two was as easy as just launching Home Assistant, since they were automatically detected at boot, so I had no opportunity to mess with and break things.

But then I remembered I could connect additional devices to the ESPs and try to integrate those instead. So I started digging around in my fun box of random chips, devices and wires (every person that cares about electronics but doesn't care about organizing them has a box like this), and found a couple of DHT11 humidity and temperate sensors, which were perfect for trying to integrate into Home Assistant, while serving no actual purpose when I'm done.

The Problem

Now if you've ever played around with WLED on an ESP, you will know that you install it by flashing the provided compiled binary and that's it. There is no obvious way to run additional custom code on the ESP alongside WLED itself. Luckily the developers thought of that and included a sort of compiled plug-in system called usermods.

DHT Usermod

Even more conveniently, someone already did the hard work of creating a plug in that can read DHT-Sensors and reports the temperature and humidity values in the info section of the WLED instance, which is already half of what I want it to do.

Since the documentation for installing and using usermods is pretty spread out and sparse, I will give a rundown here.

Software Setup

Since usermods have to be compiled with WLED and can't be loaded after the fact, we first have to set up compiling WLED from source. Detailed instructions for that can be found here. Compiling with PlatformIO worked well for me, so that's what I'm using.

After completing the steps in the official compilation guide and getting a successful compile, it's time to include our usermod. The one we're looking for can be found under ./WLED/usermods/DHT/. To install it, follow these steps:

1. Copy the platformio_override.ini file from ./WLED/usermods/DHT/ to the projects root directory.
2. Inside platformio_override.ini, add the following configuration block:

                   [env:esp32dev_usermod_dht_C]
   extends = env:esp32dev
   build_flags = ${env:esp32dev.build_flags}
                       -D WLED_RELEASE_NAME=ESP32
                       -D USERMOD_DHT
                       -D USERMOD_DHT_CELSIUS
                       -D USERMOD_DHT_DHTTYPE=11
                       -D USERMOD_DHT_PIN=4
   lib_deps = ${esp32.lib_deps}
              https://github.com/alwynallan/DHT_nonblocking
              makuna/NeoPixelBus@^2.6.7
                   
               

   You can set up a couple of things here, for example the type of DHT sensor and the pin you want to use. Im using a DHT11 and pin GPIO4 in my setup. If you want to use fahrenheit instead of celsius, remove the line -D USERMOD_DHT_CELSIUS.
3. After setting up Visual Studio Code with PlatformIO according to the compilation guide, click the alien-looking icon on the left-hand side and select esp32dev_usermod_dht_C -> General -> Build from the task-list. You may have to click the refresh button at the top for it to show up.

Now VSCode should be building a new WLED release with our DHT-Usermod included. The finished binary can be found at:

./WLED/build_output/firmware/esp32dev_usermod_dht_C.bin

You can flash this file to an esp32 using esptool.py:

esptool.py write_flash 0x10000 esp32dev_usermod_dht_C.bin

Side note: I had an issue with my ESP32, where I could flash new firmware successfully, but the changes never actually applied properly. I had to erase my entire flash and then reflash the bootloader and WLED-Binary:

esptool.py erase_flash
esptool.py write_flash 0x0 esp32_bootloader_v2.bin
esptool.py write_flash 0x10000 esp32dev_usermod_dht_C.bin

Hardware Setup

Now that we have the base usermod set up it's time to test if we did it right and connect the actual DHT-Sensor to our ESP32. This is fairly simple, just connect VCC of the DHT to either the 5V or 3.3V output of the ESP (my DHT11 can operate on either voltage, check if yours can too before connecting it), GND to any ground pin on the ESP and the Data pin to GPIO4.

Now we can test our setup by connecting to the WLED instance, opening the info panel in the navigation bar and looking for the temperature and humidity entries.

Modifying the Usermod

So now that we have WLED polling the sensor for data, it's time to get it to send that data to a Home Assistant instance. For that we're going to be using MQTT since it is already integrated into WLED and can be easily used in usermods. There already exists a usermod ("sensors_to_mqtt") that uses the integrated MQTT capabilities to report sensor statistics for a different sensor, so we will just be taking some of that code to modify our mod. We just need a few functions to initialize the necessary MQTT topics and register them with the broker. The full modified code can be found here. Save this file at ./WLED/usermods/DHT/usemod_dht.h and recompile.

Configuring MQTT

The final part of the setup is configuring a way to communicate using MQTT on all relevant devices.

Message Broker

The MQTT Message broker is basically the hub that receives and routes messages between clients. In my case I'm using the same Raspberry Pi that is running the Home Assistant instance. To install it on a standard Raspbian Image, run:

sudo apt install mosquitto

Any configuration settings like protecting your broker with username and password can be done in the mosquitto configuration file at /etc/mosquitto/mosquitto.conf.
In my case, the default configuration was sufficient, so we can go ahead and start and enable the mosquitto service with:

sudo systemctl enable mosquitto.service --now

Clients

Now we just have to set up our two clients, the WLED ESP32 and our Home Assistant instance, to communicate with each other. We did the hard part of modifying WLEDs source code to include MQTT in the DHT usermod, now we just need to configure which MQTT broker it should connect to. The settings can be found in the webinterface for your WLED instance at Config -> Sync Interfaces -> MQTT. Just enter the brokers IP-address and credentials if necessary. You can even give it a nice name in the Client ID field. Save your changes and then reboot the ESP32.

To connect the Home Assistant instance to the MQTT broker, you need to install the MQTT integration. Then, in the integrations dashboard, again configure the brokers IP and credentials and watch in awe as Home Assistant should auto-discover the new sensors.