libmbus2mqtt

M-Bus to MQTT bridge with Home Assistant integration.

Read your wired M-Bus meters (water, heat, gas, electricity) and send the data to Home Assistant or any MQTT broker.

Disclaimer: This software is provided 'as-is' without any guarantees.

Features

Reading M-Bus devices via serial M-Bus Master connected over:
- TTL (UART)
- USB
- IPv4 TCP (using for example ser2net)
Automatic discovery of connected M-Bus meters
Publishing meter data to MQTT
Home Assistant MQTT Discovery integration:
- Automatic device and entity creation
- Device availability reporting
- Bridge device entity with controls (rescan, log level, poll interval)
Template system to support different M-Bus device types
Docker support with pre-compiled libmbus
Systemd service for native Linux installation

Requirements
⚡Quick Start with Docker (recommended)
Native Installation
Configuration
Running libmbus2mqtt
Home Assistant Integration
Device Templates
Hardware Setup
Troubleshooting
Supported Devices

Requirements

M-Bus Master adapter - converts TTL/USB signals to M-Bus protocol
- TTL to M-Bus converter (example from AliExpress)
- USB to M-Bus adapter (example from AliExpress)
Any Linux host device with access to M-Bus Master via:
- UART (TTL)
- USB
- IPv4 TCP
Docker / Docker Compose
Python 3.11+ for native installation

Quick Start with Docker (recommended)

Docker is the easiest way to get started - libmbus is pre-compiled in the image.

Step 1: Create the project directory

mkdir libmbus2mqtt
cd libmbus2mqtt

Step 2: Create docker-compose.yml

nano docker-compose.yml

Paste the following content:

services:
  libmbus2mqtt:
    image: nilvanis/libmbus2mqtt:latest
    container_name: libmbus2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/data
    devices:
      # Change this to match your M-Bus adapter
      - /dev/ttyUSB0:/dev/ttyUSB0
    environment:
      TZ: Europe/London

Save and exit (Ctrl+O, Ctrl+X).

Step 3: Create configuration

mkdir -p data/config
nano data/config/config.yaml

Paste the following content and edit to match your setup:

mbus:
  device: /dev/ttyUSB0          # Your M-Bus adapter device (or IPv4:port for TCP masters)

mqtt:
  host: 192.168.1.100           # Your MQTT broker IP address
  # username: user              # Uncomment if authentication required
  # password: secret

homeassistant:
  enabled: true                 # Set to true for Home Assistant integration

Save and exit (Ctrl+O, Ctrl+X).

[!NOTE] Full config options are described here.

Step 4: Start the container

docker compose up -d

Step 5: Check the logs

docker compose logs -f

You should see your M-Bus devices being discovered and data published to MQTT.

Native Installation

For running directly on Linux without Docker.

Step 1: Install libmbus

libmbus2mqtt can install libmbus for you:

# Install dependencies first (Debian/Ubuntu)
sudo apt-get install git build-essential libtool autoconf automake

# Clone and install libmbus2mqtt
git clone https://github.com/nilvanis/libmbus2mqtt
cd libmbus2mqtt
pip install .

# Install libmbus
sudo libmbus2mqtt libmbus install

Or install libmbus manually - see libmbus on GitHub.

Step 2: Create configuration

# Create config directory
sudo mkdir -p /data/config

# Generate example configuration
libmbus2mqtt config init --config /data/config/config.yaml

# Edit the configuration
sudo nano /data/config/config.yaml

Step 3: Test the connection

# Check if your M-Bus device is accessible
libmbus2mqtt device-info

# Scan for connected meters
libmbus2mqtt scan

Step 4: Run the daemon

libmbus2mqtt run

Step 5: Install as a service (optional)

To run libmbus2mqtt automatically at startup:

sudo libmbus2mqtt install

This creates a systemd service that starts on boot. To manage the service:

# Check status
sudo systemctl status libmbus2mqtt

# View logs
sudo journalctl -u libmbus2mqtt -f

# Stop the service
sudo systemctl stop libmbus2mqtt

# Remove the service
sudo libmbus2mqtt uninstall

Configuration

Configuration is stored in a YAML file. By default, libmbus2mqtt looks for /data/config/config.yaml.

Minimal Configuration

Only two settings are required:

mbus:
  device: /dev/ttyUSB0

mqtt:
  host: 192.168.1.100

Full Configuration Reference

# M-Bus Interface
mbus:
  device: /dev/ttyUSB0          # REQUIRED - Serial device path OR IPv4:port (TCP master)
                                # Serial examples: /dev/ttyUSB0, /dev/ttyACM0, /dev/ttyAMA0
                                # TCP example: 192.168.1.50:9999 (IPv4 only, no hostnames)
  baudrate: 2400                # M-Bus baudrate (300, 2400, or 9600) - ignored for TCP
  poll_interval: 60             # Seconds between polling cycles
  startup_delay: 5              # Seconds to wait before first poll/scan
  timeout: 5                    # Seconds to wait for device response
  retry_count: 3                # Number of retries on failure
  retry_delay: 1                # Seconds between retries
  autoscan: true                # Scan for devices on startup

# MQTT Broker
mqtt:
  host: 192.168.1.100           # REQUIRED - Broker IP or hostname
  port: 1883                    # Broker port
  username:                     # Username (if required)
  password:                     # Password (if required)
  client_id:                    # Client ID (auto-generated if empty)
  keepalive: 60                 # Connection keepalive in seconds
  qos: 1                        # Message quality of service (0, 1, or 2)
  base_topic: libmbus2mqtt      # Base MQTT topic

# Home Assistant Integration
homeassistant:
  enabled: false                # Enable Home Assistant MQTT Discovery
  discovery_prefix: homeassistant

# Devices (optional)
# Must be defined if 'mbus' -> 'autoscan' is set to 'false')
# Can be also used as override for specific devices
devices:
  - id: 1                       # M-Bus address (0-254)
    name: "Water Meter Kitchen" # Friendly name
    enabled: true               # Set false to ignore this device
    template:                   # Template name (auto-detect if empty)

# Device Availability
availability:
  timeout_polls: 3              # Consecutive failures before marking offline

# Logging
logs:
  level: INFO                   # Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
  save_to_file: false           # Enable file logging
  file: data/log/libmbus2mqtt.log  # Log file path
  max_size_mb: 10               # Max file size before rotation (1-1000 MB)
  backup_count: 5               # Number of rotated backup files (0-100)

Environment Variables

Environment variables can be used to provide config values (handy in Docker). When both the YAML file and an environment variable set the same field, the environment variable takes precedence and the override is logged.
Env var naming convention is based on config.yaml: LIBMBUS2MQTT_SECTION_OPTION. Below is complete list:

LIBMBUS2MQTT_MBUS_DEVICE
LIBMBUS2MQTT_MBUS_BAUDRATE
LIBMBUS2MQTT_MBUS_POLL_INTERVAL
LIBMBUS2MQTT_MBUS_STARTUP_DELAY
LIBMBUS2MQTT_MBUS_TIMEOUT
LIBMBUS2MQTT_MBUS_RETRY_COUNT
LIBMBUS2MQTT_MBUS_RETRY_DELAY
LIBMBUS2MQTT_MBUS_AUTOSCAN
LIBMBUS2MQTT_MQTT_HOST
LIBMBUS2MQTT_MQTT_PORT
LIBMBUS2MQTT_MQTT_USERNAME
LIBMBUS2MQTT_MQTT_PASSWORD
LIBMBUS2MQTT_MQTT_CLIENT_ID
LIBMBUS2MQTT_MQTT_KEEPALIVE
LIBMBUS2MQTT_MQTT_QOS
LIBMBUS2MQTT_MQTT_BASE_TOPIC
LIBMBUS2MQTT_HOMEASSISTANT_ENABLED
LIBMBUS2MQTT_HOMEASSISTANT_DISCOVERY_PREFIX
LIBMBUS2MQTT_AVAILABILITY_TIMEOUT_POLLS
LIBMBUS2MQTT_LOGS_LEVEL
LIBMBUS2MQTT_LOGS_SAVE_TO_FILE
LIBMBUS2MQTT_LOGS_FILE
LIBMBUS2MQTT_LOGS_MAX_SIZE_MB
LIBMBUS2MQTT_LOGS_BACKUP_COUNT

Docker Compose example with environment variables:

services:
  libmbus2mqtt:
    image: nilvanis/libmbus2mqtt:latest
    environment:
      LIBMBUS2MQTT_MBUS_DEVICE: /dev/ttyUSB0
      LIBMBUS2MQTT_MQTT_HOST: 192.168.1.100
      LIBMBUS2MQTT_MQTT_USERNAME: user
      LIBMBUS2MQTT_MQTT_PASSWORD: secret
      LIBMBUS2MQTT_HOMEASSISTANT_ENABLED: "true"
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    volumes:
      - ./data:/data

Running libmbus2mqtt

CLI Commands

# Start the main daemon
libmbus2mqtt run

# Scan for M-Bus devices (one-time)
libmbus2mqtt scan

# Show M-Bus adapter information
libmbus2mqtt device-info

# Show version
libmbus2mqtt version
# or
libmbus2mqtt --version

# Validate configuration file
libmbus2mqtt config validate

# Generate example configuration
libmbus2mqtt config init

# Install/uninstall systemd service
libmbus2mqtt install
libmbus2mqtt uninstall

# Install libmbus (native installation only)
libmbus2mqtt libmbus install

Using a Custom Config File

libmbus2mqtt run --config /path/to/config.yaml
libmbus2mqtt scan --config /path/to/config.yaml

Home Assistant Integration

When homeassistant.enabled is set to true, libmbus2mqtt automatically creates devices and entities in Home Assistant using MQTT Discovery.

Libmbus2mqtt

Install / Use

README