Creating an MQTT Battery Sensor in Home Assistant

Home Assistant provides battery readings for devices with the official companion app installed. We can replicate this functionality for other devices using the MQTT integration.

Prerequisites

File Editor or some other way to edit your configuration.yaml
The MQTT Integration installed
An MQTT broker server (can use mosquitto broker addon if you wish to host locally)

Creating the Sensor(s)

Assuming you already have the MQTT integration configured with an MQTT broker server, you can add the following straight into your config.

You can add everything directly under the mqtt section of configuration.yaml. Alternatively you can import your MQTT config from a separate yaml file to keep everything isolated and easier to manage. Here’s how to include such a file in your config.

mqtt: !include mqtt.yaml

You can then add any mqtt configuration inside mqtt.yaml.

🛈 Note: There should only be 1 sensor: entry in your mqtt config. Additional sensors should be added as another list item. Starting you sensor definition with - name: "Sensor Name" can make them easier to distinguish.

Battery Level

sensor:
  - name: "Battery Level"
    unique_id: deviceuuid_battery_level
    state_topic: "stat/deviceuuid/battery"
    device_class: battery
    unit_of_measurement: "%"
    value_template: "{{ value_json.battery_level }}"

Thanks to the battery sensor device class, the sensor icon and colour will automatically update to reflect the current charge level of the battery. Just like the ones from companion app devices!

Battery State

We can also add another sensor to track the current state of the battery (charging, discharging, full). To do this we add another item to the sensor: entry.

This part is very much a work in progress and does not yet have full parity with the official Home Assistant companion apps.

- name: "Battery State"
    unique_id: deviceuuid_battery_state
    state_topic: "stat/device_uuid/battery"
    device_class: enum
    value_template: "{{ value_json.battery_state }}"

Unlike the other sensor this will not automatically update the sensor icon, however, you can still use it to trigger automation actions based on the battery charging state. e.g. Sending push notifications when a device has finished charging or if a device with battery backup has switched fallen back to battery power.

Sensor Device Grouping

If you have multiple sensors associated with a device you can group them together like so.

device:
      identifiers: ["deviceuuid"]
      name: "Device Name"
      manufacturer: "Maker"
      model: "Model"

Combined example with the Battery Level sensor from earlier.

- name: "Battery Level"
    unique_id: deviceuuid_battery_level
    state_topic: "stat/deviceuuid/battery"
    device_class: battery
    unit_of_measurement: "%"
    value_template: "{{ value_json.battery_level }}"
    device:
      identifiers: ["deviceuuid"]
      name: "Device"
      manufacturer: "Maker"
      model: "Model"

For consistency it is a good idea to use the same deviceuuid value for the device unique_id and as part of the sensor unique id as well as the MQTT topics.

Linux Machine Example Sensor Script

If we have a battery powered Linux device we want to monitor in Home Assistant, we can setup a simple script to send us the data.

Simple MQTT Publisher using curl

Thanks to a relatively recent addition in early 2020, curl can now act as a basic MQTT client for us!

#! /bin/bash

HOME_ASSISTANT_BROKER_URL="homeassistant.local"
MQTT_USER=<username>; MQTT_PASSWD=<password>;
DEVICE_TOPIC="stat/device"

mqtt_pub() {
    curl -d "$2" mqtt://$MQTT_USER:$MQTT_PASSWD@$HOME_ASSISTANT_BROKER_URL/$1
}

battery_info=$(upower -i $(upower -e | grep 'BAT'))
battery_level=$(echo "$battery_info" | grep -E "percentage" | grep -E -o "[0-9]+")
battery_state=$(echo $battery_info | grep -P -o '(?<=state:\s)\w+')

mqtt_pub $DEVICE_TOPIC/battery "{ \"battery_level\": $battery_level, \"battery_state\": \"$battery_state\" }"

🛈 Note: Remember to set your MQTT username and Password if using authenticated MQTT. For a locally hosted supervised broker this can be a Home Assistant login.

You can also Python and the paho-mqtt package to create a client for more advanced configurations or integration with any existing embedded code you might be running on device.

Creating a crontab job

In order to automatically update the sensor data at regular intervals, we can setup a cron job. You can edit your crontab file on Linux by running crontab -e and adding the script like shown bellow.

*/15 * * * * ~/home-assistant-mqtt-sensors

This will run the script to update the sensors every 15 min (default sensor update frequency in Home Assistant). You can alter this as you see fit to update more or less often to meet your needs and devices.