Home Assistant Integration

Integrating an ESPurna switch into Home Assistant is very easy since both talk MQTT. You don't need any special addon in ESPurna but you will need to properly configure the MQTT connection.

Once the ESPurna powered device is connected to your MQTT broker of choice, its time to configure the link from the configuration.yaml file of your Home Assistant instance.

Note: I'm assuming here you already have Home Assistant installed somewhere. Head over to their getting started page to do it if you have not.

Note: Integration with Home Assistant is done using "MQTT platform", not "MQTT-JSON platform". Each message is sent to its own topic. This means you should disable "JSON payload" in the ESPurna MQTT tab to make it work.

Note: If Discovery integration is configured and Alexa emulation is enabled on the device, Home Assistant will discover ESPurna as WeMo switch / light.

Basic configuration

Build settings

Build flag	Description	Default value
HOMEASSISTANT_SUPPORT	Enable Home Assistant module	MQTT_SUPPORT
HOMEASSISTANT_ENABLED	Send MQTT discovery message	0 (off)
HOMEASSISTANT_PREFIX	MQTT topic prefix for the configuration messages	homeassistant
HOMEASSISTANT_RETAIN	Perist configuration message in the broker	1 (on)

Home Assistant

First make sure your Home Assistant instance connects to the same broker you connected the ESPurna device. You can read the Home Assistant MQTT page for a full explanation of the process but you will basically have to add these lines to your configuration.yaml file:

mqtt:
  broker: <your broker ip>
  username: "<username for the MQTT connection>"
  password: "<password for the MQTT connection>"

This is the bare minimum (username and password are optional, but you really should use them). If your broker setup is not standard check all the configuration options in the Home Assistant MQTT page.

MQTT Discovery

Instead of manually editing configuration.yaml you can use MQTT Discovery to allow ESPurna device to configure itself automatically.

To enable, add this to the mqtt component configuration:

mqtt:
  discovery: true
  discovery_prefix: homeassistant

Configuration

Key	Description	Possible values	Default value
haEnabled	MQTT Discovery	0 (no) or 1 (yes)	1 (yes)
haPrefix	MQTT Prefix	A string	homeassistant
haRetain	MQTT retain flag	0 (no) or 1 (yes)	1 (yes)
haBirthTopic	MQTT birth topic	MQTT topic string	homeassistant/status
haBirthPayload	MQTT birth topic payload	payload for the birth topic	online

To supplement retain option, device would subcribe to a special 'birth' topic which is used by the HA MQTT client. When HA instance connects to the broker and publishes the specified payload string, device would publush discovery message(s).

Terminal commands

Command	Description
ha	Shows configuration options
ha.send	Publish MQTT Discovery for Home Assistant (as if it is enabled)
ha.clear	Clear messages(s), possibly retained by the broker, by publishing an empty string

Troubleshooting

Discovery topic has the following format:

{haPrefix}/{switch or light}/{hostname}_{switch or light index}/config

For example:

homeassistant/switch/espurna_820501_relay_0/config

If discovery message is sent to the MQTT broker with the retained flag enabled, the subscriber will receive the message even when the ESPurna device is offline. To disable discovery manually, simply send an empty message with retained flag to the discovery topic.

Home Assistant will keep discovered devices that were configured with using an entity registry.

Manual configuration

Relays

Home Assistant has a special type of device called "switch". You can configure this switch to use MQTT connection. Basically you will have to define the command (write) and status (read) topics and payloads.

Configuration sample:

switch:
  - platform: mqtt
    name: "Test Switch"
    state_topic: "test/switch/D1MINI/relay/0"
    command_topic: "test/switch/D1MINI/relay/0/set"
    payload_on: 1
    payload_off: 0
    optimistic: false
    qos: 0
    retain: true

As you can see we are setting the "platform" to "mqtt" to use the connection be have previously configured. We can use the same topic for command and status. The topic you have to use is the "MQTT Root Topic" you configure in the MQTT page in your ESPurna device web interface ("test/switch/D1MINI" in the example), plus "/relay/" plus the number of the relay (if your board has only one relay that would be number 0). Also note the payloads for both of them, these are required by ESPurna (1 for on, 0 for off).

Lights

Since version 1.15.0 lights should be automatically configured using light.mqtt JSON schema and MQTT discovery. See https://www.home-assistant.io/integrations/light.mqtt/#json-schema and https://github.com/xoseperez/espurna/issues/2539 for more information.

Base configuration should contain availability and json topics. Feature set available for the device depends on the number of configured channels.

light:
  - platform: mqtt
    name: "Test JSON light"
    schema: "json"
    availability_topic: "test/light/status"
    payload_available: "1"
    payload_not_available: "0"
    state_topic: "test/light/light_json"
    command_topic: "test/light/light_json/set"

ESPurna supports color, brightness, temperature color and individual channels for light devices (dimmers, my9192-based light bulbs,...).

Configuration sample for older version, based on individual topics and relays

light:
  - platform: mqtt
    name: 'Test RGBW Light'
    state_topic: 'test/light/relay/0'
    command_topic: 'test/light/relay/0/set'
    payload_on: 1
    payload_off: 0
    rgb_state_topic: 'test/light/color'
# the next line is only required if you have css style enabled in espurna "lights" settings
#    rgb_value_template: "{{ '%s,%s,%s' | format(value[1:3] | int(value[1:3], 16), value[3:5] | int(value[3:5], 16), value[5:7] | int(value[5:7], 16)) }}"
    rgb_command_topic: 'test/light/color/set'
    rgb: true
    optimistic: false
    color_temp: true
    color_temp_command_topic: 'test/light/mired/set'
    brightness: true
    brightness_scale: 255
    brightness_command_topic:  'test/light/brightness/set'
    brightness_state_topic: 'test/light/brightness'
    white_value: true
    white_value_command_topic: 'test/light/channel/3/set'
    white_value_state_topic: 'test/light/channel/3'