2024.12.5
Home ▸ Integrations ▸

MQTT room presence

The mqtt_room sensor integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to detect the indoor location of devices using MQTT clients.

Configuration

To use this device tracker in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.

# Example configuration.yaml entry
sensor:
  - platform: mqtt_room
    device_id: 123testid
    state_topic: "espresense/devices/123testid"

Configuration Variables

Looking for your configuration file?
away_timeout integer (Optional, default: 0)

The time in seconds after which the state should be set to not_home if there were no updates. 0 disables the check.

device_id string Required

The device id to track for this sensor.

name string (Optional, default: Room Sensor)

The name of the sensor.

state_topic string Required

The topic that contains all subtopics for the rooms.

timeout integer (Optional, default: 5)

The time in seconds after which a room presence state is considered old. An example: device1 is reported at scanner1 with a distance of 1. No further updates are sent from scanner1. After 5 seconds scanner2 reports device1 with a distance of 2. The old location info is discarded in favor of the new scanner2 information as the timeout has passed.

unique_id string (Optional)

An ID that uniquely identifies this room sensor. If two sensors have the same unique ID, Home Assistant will raise an exception.

Usage

Example JSON that should be published to the room topics:

{
  "id": "123testid",
  "name": "Test Device",
  "distance": 5.678
}

Setting up clients

This integration works with any software that is sending data in the given format. Each client should post the discovered devices in its own subtopic of the configured topic. Instead of developing your own application, you can also use any of these already existing clients:

  • ESPresense: Fork of ESP32-MQTT-room w/ fingerprinting, tile support, Kalman filter, based on C++/Platformio
  • ESP-32-BLE-Scanner for Home Assistant: ESP32 based BLE presence detection for Home Assistant with web GUI
  • room-assistant: looks for Bluetooth LE beacons, based on Node.js
  • Happy Bubbles Presence Server: presence detection server for Happy Bubbles BLE-scanning devices, based on Go
  • ESP32-MQTT-room: runs on an ESP32, and looks for Bluetooth LE devices, based on C++/Arduino
  • OpenMQTTGateway: uses ESP32 Bluetooth Low Energy to scan BLE Broadcaster like smart watches/bands and much more to get sensor values

Related topics