Skip to content

05 Home Assistant

Jump to bottom
Klaus Musch edited this page Sep 28, 2024 · 9 revisions

Integration in Home Assistant

Home Assistant is an open source home automation software.

The esp32 fan controller can automatically be detected via MQTT discovery. So with almost no effort you have a nice looking integration into HA.

Climate mode

In "climate mode", this is how the ESP32 fan controller looks like in the dashboard when the Thermostat Card is used.

Fan mode

In "fan mode", this is how the ESP32 fan controller looks like in the dashboard.

Requirements

  • working Home Assistant installation
  • working ESP32 fan controller with MQTT and Home Assistant discovery activated
  • running MQTT broker (a standalone one like Mosquitto or the one from Home Assistant)
  • working connection between Home Assistant and the MQTT broker. Working connection between ESP32 and the MQTT broker.

Integration

In file "config.h" you have to uncomment

  #define useHomeassistantMQTTDiscovery

Please also set up everything in "config.h" and "config_override.h" according to your environment so that WiFi and MQTT are running.

After flashing and rebooting the ESP32, please wait some seconds, then you should see in Home Assistant the following entities and device ("Settings" - "Devices & services"):

Climate mode

The new entity is a Climate Entity You can simply click on the entity to see an automatically generated Thermostat Card.

Via click on "history" you can see the history of the "current temperature" and "target temperature".

Fan mode

MQTT discovery

The ESP32 fan controller will automatically be integrated into your Home Assistant installation via MQTT discovery. Thanks a lot for the contribution from s4saken and Niklas.

If you are interested, here is the discovery message for the climate, please also see here.

Topic Payload
homeassistant/climate/
esp32_fan_controller/config		 
{
  "name":null,
  "unique_id":"esp32_fan_controller",
  "object_id":"esp32_fan_controller",
  "~": "esp32_fan_controller",
  "icon":"mdi:fan",
  "min_temp":10,
  "max_temp":50,
  "temp_step":1.0,
  "precision":0.1,
  "current_humidity_topic":"~/tele/STATE1",
  "current_humidity_template":"{{value_json.hum | round(0)}}",
  "current_temperature_topic":"~/stat/ACTUALTEMP",
  "temperature_command_topic":"~/cmnd/TARGETTEMP",
  "temperature_state_topic":"~/stat/TARGETTEMP",
  "modes":["off", "fan_only"],
  "mode_command_topic":"~/cmnd/MODE",
  "mode_state_topic":"~/stat/MODE",
  "availability_topic":"~/stat/STATUS",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}

Here is the discovery message for the fan, please also see here.

Topic Payload
homeassistant/fan/
esp32_fan_controller/config		 
{
  "name":null,
  "unique_id":"esp32_fan_controller",
  "object_id":"esp32_fan_controller",
  "~": "esp32_fan_controller",
  "icon":"mdi:fan",
  "command_topic":"~/cmnd/MODE",
  "state_topic":"~/stat/MODE",
  "payload_on": "fan_only",
  "payload_off": "off",
  "percentage_state_topic": "~/stat/FANPWM",
  "percentage_command_topic": "~/cmnd/FANPWM",
  "speed_range_min": 1,
  "speed_range_max": 255,
  "availability_topic":"~/stat/STATUS",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}

Here are the discovery messages for the sensors, please also see here.

Topic Payload
homeassistant/sensor/
esp32_fan_controller/humidity/config		 
{
  "name":"Humidity",
  "unique_id":"esp32_fan_controller_humidity",
  "object_id":"esp32_fan_controller_humidity",
  "~": "esp32_fan_controller",
  "state_topic":"~/tele/STATE1",
  "value_template":"{{ value_json.hum | round(0) }}",
  "device_class":"humidity",
  "unit_of_measurement":"%",
  "state_class":"measurement",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}
homeassistant/sensor/
esp32_fan_controller/temperature/config		 
{
  "name":"Temperature",
  "unique_id":"esp32_fan_controller_temperature",
  "object_id":"esp32_fan_controller_temperature",
  "~": "esp32_fan_controller",
  "state_topic":"~/tele/STATE1",
  "value_template":"{{ value_json.ActTemp | round(1) }}",
  "device_class":"temperature",
  "unit_of_measurement":"°C",
  "state_class":"measurement",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}
homeassistant/sensor/
esp32_fan_controller/pressure/config		 
{
  "name":"Pressure",
  "unique_id":"esp32_fan_controller_pressure",
  "object_id":"esp32_fan_controller_pressure",
  "~": "esp32_fan_controller",
  "state_topic":"~/tele/STATE1",
  "value_template":"{{ value_json.pres | round(0) }}",
  "device_class":"atmospheric_pressure",
  "unit_of_measurement":"hPa",
  "state_class":"measurement",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}
homeassistant/sensor/
esp32_fan_controller/altitude/config		 
{
  "name":"Altitude",
  "unique_id":"esp32_fan_controller_altitude",
  "object_id":"esp32_fan_controller_altitude",
  "~": "esp32_fan_controller",
  "state_topic":"~/tele/STATE1",
  "value_template":"{{ value_json.alt | round(1) }}",
  "device_class":"distance",
  "unit_of_measurement":"m",
  "state_class":"measurement",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}
homeassistant/sensor/
esp32_fan_controller/pwm/config		 
{
  "name":"PWM",
  "unique_id":"esp32_fan_controller_PWM",
  "object_id":"esp32_fan_controller_PWM",
  "~": "esp32_fan_controller",
  "state_topic":"~/tele/STATE2",
  "value_template":"{{ value_json.pwm }}",
  "state_class":"measurement",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}
homeassistant/sensor/
esp32_fan_controller/rpm/config		 
{
  "name":"RPM",
  "unique_id":"esp32_fan_controller_RPM",
  "object_id":"esp32_fan_controller_RPM",
  "~": "esp32_fan_controller",
  "state_topic":"~/tele/STATE2",
  "value_template":"{{ value_json.rpm }}",
  "state_class":"measurement",
  "dev":{
      "name":"Fan Controller",
      "model":"esp32_fan_controller",
      "identifiers":["esp32_fan_controller"],
      "manufacturer":"KlausMu"}
}

The following table shows how subscriptions and messages are used to control the esp32 fan controller with Home Assistant.

Topic Payload Remark sent when fan controller boots or reconnects to the MQTT broker sent when HA reports "online" Retain
homeassistant/status {online,offline}
means: either "online" or "offline" is used as payload		 Home Assistant is sending its state in this topic. The fan controller subscribes to this topic. When "online" is received, the fan controller reacts accordingly, so that the device in HA gets available again. See below.
homeassistant/climate/
esp32_fan_controller/config
homeassistant/fan/
esp32_fan_controller/config
homeassistant/sensor/
esp32_fan_controller/humidity/config
homeassistant/sensor/
esp32_fan_controller/temperature/config
homeassistant/sensor/
esp32_fan_controller/pressure/config
homeassistant/sensor/
esp32_fan_controller/altitude/config
homeassistant/sensor/
esp32_fan_controller/rpm/config
homeassistant/sensor/
esp32_fan_controller/pwm/config
 see table above these are the actual discovery messages for the climate/fan and sensors x x
esp32_fan_controller/
stat/STATUS		 {online,offline}
means: either "online" or "offline" is used as payload		 x
(payload "online" is sent)		 x
(payload "online" is sent)		 "offline" will be sent as last will with retain flag set
esp32_fan_controller/
cmnd/MODE
esp32_fan_controller/
stat/MODE		 {fan_only,off}
means: either "fan_only" or "off" is used as payload		 HA is sending the "cmnd" topic.
Must be confirmed by the fan controller with the same payload to the "stat" topic.
esp32_fan_controller/
cmnd/TARGETTEMP
esp32_fan_controller/
stat/TARGETTEMP		 target temperature as floating point number
"." is used as decimal separator
example: 21.0		 HA is sending the "cmnd" topic.
Must be confirmed by the fan controller with the same payload to the "stat" topic.		 x
(topic "stat" is used)		 x
(topic "stat" is used)
esp32_fan_controller/
stat/ACTUALTEMP		 the fan controller is reporting the actual temperature as floating point
example: 25.43		 Only sent by the fan controller. Whenever the temperature changes, at most once per second
esp32_fan_controller/
tele/STATE1		 example:
{"ActTemp":21.46, "pres":998.14, "alt":115.50, "hum":67.65, "TargTemp":27.00}		 Sent every 10 seconds. Values are used in the climate ("hum") and in the sensors.
esp32_fan_controller/
tele/STATE2		 example:
{"rpm":1200, "pwm":120}		 Sent every 10 seconds. Values are used in the sensors.
Clone this wiki locally