Home Assistant Add-on: M-Bus Meter Reader

This Home Assistant add-on reads an M-Bus meter via a USB serial adapter using libmbus and publishes the meter value to MQTT.

It is designed for Home Assistant OS and Home Assistant Supervised installations and runs as a local add-on.

---

Features

• Reads M-Bus meters via mbus-serial-request-data-multi-reply
• Configurable serial device, baud rate, and polling interval
• Publishes meter value to MQTT
• Lightweight single-process container (init: false)
• Compiles libmbus from official source
• Works with MQTT auto-discovery (optional)

---

Requirements

• Home Assistant OS or Supervised
• MQTT broker (e.g. Mosquitto add-on)
• USB M-Bus serial adapter
• Serial device available under /dev/serial/by-id/

---

Installation (Local Add-on)

1. Copy the Add-on to the Local Add-ons Folder

On your Home Assistant host, copy this repository to:

/mnt/data/supervisor/addons/local/mbus_meter

The directory structure must look like this:

mbus_meter/
├── config.yaml
├── Dockerfile
├── run.sh
└── README.md

---

2. Reload the Supervisor

Run:

ha supervisor reload

Or reboot Home Assistant.

---

3. Install the Add-on

Go to:

Settings → Add-ons → Add-on Store

Scroll down to:

Local add-ons

Install M-Bus Meter Reader.

---

Configuration

Example configuration:

device: "/dev/serial/by-id/usb-Prolific_Technology_Inc._USB-Serial_Controller_D-if00-port0"
baudrate: 2400
interval: 60
mqtt_topic: "homeassistant/sensor/mbus_meter/state"

Configuration Options

Option	Description
device	Serial device path
baudrate	M-Bus baud rate (usually 2400)
interval	Read interval in seconds
mqtt_topic	MQTT topic used to publish the meter value

---

MQTT Sensor Setup

You have two options.

---

Option 1 (Recommended): MQTT Auto-Discovery

If MQTT discovery is enabled in your add-on, the sensor will appear automatically.

Go to:

Settings → Devices & Services → MQTT

You should see a new device:

M-Bus Meter

No YAML configuration required.

---

Option 2: Manual MQTT Sensor

Add the following to configuration.yaml:

mqtt:
  sensor:
    - name: "M-Bus Meter"
      state_topic: "homeassistant/sensor/mbus_meter/state"
      unit_of_measurement: "m³"
      state_class: total_increasing
      device_class: water

Restart Home Assistant afterwards.

---

How It Works

The add-on performs the following steps:

1. Executes:

   mbus-serial-request-data-multi-reply
   

2. Extracts the first <Value> element from the XML response.

3. Publishes the extracted value to the configured MQTT topic.

4. Waits for the configured interval.

5. Repeats.

---

Build Details

The add-on:

• Uses ghcr.io/home-assistant/base:aarch64
• Installs required build dependencies
• Compiles libmbus from source
• Runs as a single foreground process
• Does not use s6-overlay (init: false)

---

Troubleshooting

Add-on Fails to Start

Check logs:

Settings → Add-ons → M-Bus Meter Reader → Logs

---

Serial Device Not Found

Check that your device exists:

ls /dev/serial/by-id

Ensure:

• The USB adapter is connected
• The device path matches your configuration
• The add-on has device access configured

---

No MQTT Updates

Verify the MQTT broker is running.

In Home Assistant:

Settings → Devices & Services → MQTT → Listen to topic

Subscribe to:

homeassistant/sensor/mbus_meter/#

If nothing appears, check add-on logs.

---

Permission Issues on Serial Device

Ensure your config.yaml includes:

devices:
  - /dev/serial/by-id:/dev/serial/by-id

---

Security Notes

• The add-on requires direct access to serial hardware.
• Meter values are published to MQTT without additional encryption inside the HA network.
• Secure your MQTT broker properly if exposed externally.