Skip to content

Home Assistant

The Home Assistant integration consists of two parts:

  1. node sensors: each ESP32 appears as a device automatically through MQTT discovery, with the entities listed below
  2. beacons: define each beacon in configuration.yaml (using mqtt_room integration)

Once the ESP32 is running, it is important to configure Home Assistant to use the information from the MQTT topic to determine what devices to track. You can read the full documentation on the Home Assistant website. It is critical that you configure your device IDs to match the device fingerprint found by ESPresence (e.g. apple:1007:11-12).

The easiest way to find the fingerprint is to connect the usb cable and monitor the serial port (115200 baud) while bringing a device close to the ESP32. To monitor the serial port you can use the ESPresense terminal. Alternatives: e.g. Arduino monitor function, the PlatformIO VSCode extension or via platform io pio run --target monitor.

You should see output similar to the following:

--- Miniterm on /dev/cu.usbserial-39522517AB 115200,8,N,1 ---
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
0 New | MAC: 67dc0c979510, ID: apple:0c0e:26
0 New | MAC: 14dc290e58f2, ID: apple:0a01:5
1 Close | MAC: 4277f2521053, ID: apple:1007:11-12

The Close message will show which devices are under half a meter away. Once you move the device > 1m you will see a Left message.

Alternatively, you can monitor the MQTT topics using e.g. MQTT Explorer or the monitoring built into the Home Assistant MQTT integration (Configure -> Listen to topic -> espresense/# -> Start listening will give you all taffic from all nodes). Connect to the Home Assistant MQTT broker (same configuration as used for the ESPresence sensor setup). This groups + shows the rooms and devices.

ESPresense supports MQTT auto discovery, which is enabled by default in Home Assistant. This means a device + entities for each ESP32 sensor will automatically be created.

The following inventory describes current firmware. Optional sensors, inputs, outputs, and lights only appear when the relevant hardware and configuration are present; names of configured inputs and outputs are chosen by the user. Lights use the name LED <number> and are discovered when configured for MQTT control. A node does not have every entity in this table.

Entity nameHome Assistant typeAvailability
AbsorptionnumberStandard node
AHTX0 HumiditysensorWhen the relevant hardware or feature is configured
AHTX0 TemperaturesensorWhen the relevant hardware or feature is configured
Arduino OTAswitchStandard node
Auto UpdateswitchStandard node
BatterysensorWhen the relevant hardware or feature is configured
Battery VoltagesensorWhen the relevant hardware or feature is configured
BH1750 LuxsensorWhen the relevant hardware or feature is configured
BME280 HumiditysensorWhen the relevant hardware or feature is configured
BME280 PressuresensorWhen the relevant hardware or feature is configured
BME280 TemperaturesensorWhen the relevant hardware or feature is configured
BMP180 PressuresensorWhen the relevant hardware or feature is configured
BMP180 TemperaturesensorWhen the relevant hardware or feature is configured
BMP280 PressuresensorWhen the relevant hardware or feature is configured
BMP280 TemperaturesensorWhen the relevant hardware or feature is configured
Chargingbinary sensorWhen the relevant hardware or feature is configured
Co2sensorWhen the relevant hardware or feature is configured
Configured input namebinary sensorWhen the relevant hardware or feature is configured
Configured output nameswitchWhen the relevant hardware or feature is configured
Connectivitybinary sensorStandard node
CountsensorWhen count filters are configured
CurrentsensorWhen the relevant hardware or feature is configured
DS18B20 Temperature <number>sensorWhen the relevant hardware or feature is configured
EnergysensorWhen the relevant hardware or feature is configured
EnrollbuttonStandard node
Free MemsensorStandard node
HumiditysensorWhen the relevant hardware or feature is configured
LED <number>lightWhen an LED is configured for MQTT control
Max DistancenumberStandard node
PowersensorWhen the relevant hardware or feature is configured
PrereleaseswitchStandard node
Raw WeightsensorWhen the relevant hardware or feature is configured
RestartbuttonStandard node
TemperaturesensorWhen the relevant hardware or feature is configured
TSL2561 LuxsensorWhen the relevant hardware or feature is configured
TVOCsensorWhen the relevant hardware or feature is configured
UpdatebuttonStandard node
UptimesensorStandard node
VoltagesensorWhen the relevant hardware or feature is configured

They appear as device + entities in Mosquitto broker card on the integrations page.

Open your Home Assistant instance and show your integrations.

And available in the devices overview.

Open your Home Assistant instance and show your devices.

Each beacon that should be monitored in Home Assistant needs to be added to the configuration.yaml file.

sensor:
# One entry for each beacon you want to track
- platform: mqtt_room
device_id: "iTrack:xxxxxxxxxxxx"
name: 'ESP Keys'
state_topic: 'espresense/devices/iTrack:xxxxxxxxxxxx'
timeout: 10
away_timeout: 120
- platform: mqtt_room
device_id: "iBeacon:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-3-58241"
name: 'ESP Chipolo'
state_topic: 'espresense/devices/iBeacon:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-3-58241'
timeout: 10
away_timeout: 120

If you have enrolled a device with a specific name that becomes the device_id to track.

PNG image

beacon: MQTT room sensor in the lovelace UI

Section titled “beacon: MQTT room sensor in the lovelace UI”

Mqtt Room sensor

ESP32 sensor: binary sensor with telemetry in the lovelace UI

Section titled “ESP32 sensor: binary sensor with telemetry in the lovelace UI”

Binary sensor with telemetry

Normally not needed, but in case MQTT auto discovery is disabled, it is possible to manually add a binary_sensor for the ESP32 sensor. Note: this does not add the other controls and diagnostics listed under MQTT auto discovery above.

mqtt:
binary_sensor:
# One entry per sensor node
- unique_id: 'kitchen'
name: 'Kitchen'
state_topic: espresense/rooms/kitchen/status
json_attributes_topic: espresense/rooms/kitchen/telemetry
payload_on: online
payload_off: offline
device_class: connectivity
- unique_id: 'living_room'
name: 'Living Room'
state_topic: espresense/rooms/living_room/status
json_attributes_topic: espresense/rooms/living_room/telemetry
payload_on: online
payload_off: offline
device_class: connectivity
- unique_id: 'kid_room'
name: 'Kid Room'
state_topic: espresense/rooms/kid_room/status
json_attributes_topic: espresense/rooms/kid_room/telemetry
payload_on: online
payload_off: offline
device_class: connectivity
- unique_id: 'master_bedroom'
name: 'Master Bedroom'
state_topic: espresense/rooms/master_bedroom/status
json_attributes_topic: espresense/rooms/master_bedroom/telemetry
payload_on: online
payload_off: offline
device_class: connectivity