Press "Enter" to skip to content

M-Bus Master Hat Instructions

This page provides instructions for installing and using the M-Bus Master Hat for the Raspberry Pi. For more details about the M-Bus Master Hat see here.

Installation

The following picture shows the M-Bus Master Hat mounted on a Raspberry Pi Model 3 A+. To mount the hat:

  • First fit the supplied standoffs to the Raspberry Pi.
  • Then carefully slide the Hat down the standoffs and mate the 40-pin female connector on the Hat with the male connector on the Pi.
  • Once you’re sure the connectors are aligned press the Hat firmly onto the Pi so the pins make a good connection.
  • Finally use the 4 nuts provided to secure the Hat to the standoffs.

Be careful throughout the process not to damage any components on either the Pi or the Hat. In particular, avoid the Pi’s SD card area – it is easy to snap an SD card by putting too much pressure on it.

If you are installing the M-Bus Master Hat on a Pi Zero, only 2 standoffs can be used. In this case be careful not to put pressure on the unsupported parts of the Hat or you may damage the Hat or the Pi.

Removal

Removal is the opposite of installation. The Hat can be very firmly held to the Pi by the connectors and standoffs. Be careful when sliding the Hat off not to damage any components or bend any pins. In particular avoid holding the Pi anywhere near the SD card to avoid damaging the SD card or the Pi.

Powering On

Power on the Pi as usual. The Hat’s green “PI” LED should be illuminated. (Depending the revision of your M-Bus Master the “BUS” LED may be faintly illuminated.)

If using Raspbian the Pi should automatically detect the the Hat at boot. To confirm this from a terminal session run:

cat /proc/device-tree/hat/product

You should see:

M-Bus Master

All further instructions below assume you are using Raspbian.

Enabling Serial Access

The Pi communicates with the M-Bus Master Hat using the serial port. This requires some configuration on the Pi.

From a terminal run:

sudo raspi-config

Select

Interfacing Options

Then

Serial

Answer

Would you like a login shell to be accessible over serial?
=> <No>

Answer

Would you like the serial port hardware to be enabled?
=> <Yes>

Now select

=> <Ok>
=> <Finish>

Do not reboot the Pi yet. If you have a Bluetooth-capable Raspberry Pi you need to reconfigure the Bluetooth port to avoid it using the serial port that will be used by the M-Bus Master Hat. To do this, edit /boot/config.txt with your favourite text editor. For example:

sudo nano /boot/config.txt

At the end of that file add the line:

dtoverlay=pi3-miniuart-bt

Save /boot/config.txt and then reboot:

sudo reboot now

Serial device /dev/ttyAMA0 will now be connected to the M-Bus Master Hat. This is the PL011 UART on the Pi’s Broadcom CPU. See this post for more information about the Raspberry Pi Serial ports.

Running with mbus-httpd

mbus-httpd is a web server providing RESTful APIs to perform common M-Bus operations. It is fully integrated with the M-Bus Master Hat. The easiest way to use the M-Bus Master Hat is to follow the Quickstart instructions in the mbus-httpd README.

If you want to control the M-Bus Master Hat manually, read on…

Enable M-Bus

By default the M-Bus will be disabled – there will be no power on the bus. Before communicating on the bus you need to power the bus on. If you don’t have wiringPi installed, install it now:

sudo apt install wiringpi

To enable the M-Bus you need to make GPIO 26 high. WiringPi (confusingly) calls this GPIO 25, so run:

gpio write 25 1

The Hat’s “BUS” LED should now be illuminated brightly. This confirms bus power is present. Depending on the revision of your M-Bus Master Hat, the “BUS” LED may glow faintly when there is no bus power present.

To disable the M-Bus again run:

gpio write 25 0

After a reboot the bus power will automatically be off by default.

If you have a Raspberry Pi 4, you need to follow some additional instructions, because as of writing this page the version of wiringPi included with Raspbian doesn’t support the Pi 4. To upgrade wiringPi to support the Pi4:

cd /tmp
wget https://project-downloads.drogon.net/wiringpi-latest.deb
sudo dpkg -i wiringpi-latest.deb

Then re-run:

gpio write 25 1

Connecting Slaves

Slaves or a bus of slaves can be connected to the M-Bus Master Hat using the labelled M-Bus +/- connectors. It doesn’t matter which way around you connect the bus/slave cables. Note that the M-Bus Master Hat is only rated for connection to up to 3 slave devices simultaneously and up to 100m cable runs.

Using libmbus

No software is provided with the M-Bus Master Hat, but you can use the open source libmbus to drive it.

To install libmbus, from a terminal run:

sudo apt install git libtool autoconf cmake build-essential
git clone https://github.com/rscada/libmbus
cd libmbus
./build.sh
sudo make install

A number of utilities are provided with libmbus – see the documentation for more details.

Once you have connected the M-Bus to the M-Bus Master Hat, a good first step is to scan the bus for connected devices. Note that while the default M-Bus speed is 2400 baud, your device may have a different baud rate configured – so experiment with different speed settings if you don’t immediately find your device.

build/bin/mbus-serial-scan -b 2400 /dev/ttyAMA0

You should see output like this (with your slave’s address likely being different):

Found a M-Bus device at address 48

Now you know your M-Bus slave’s address, you can query its data:

build/bin/mbus-serial-request-data -b 2400 /dev/ttyAMA0 48

The output from this command will the data your slave provided, encoded as XML. The precise data and format will depend upon the slave type. See example output here.

If you get an error message when running libmbus commands like this:

/home/pi/libmbus/bin/.libs/lt-mbus-serial-request-data: error while loading
shared libraries: libmbus.so.0: cannot open shared object file: No such file
or directory

Run

export LD_LIBRARY_PATH=/usr/local/lib

Then try running the command again.

Using Python

If you’d like to use Python to control your M-Bus Master Hat see pyMbusHat.

M-Bus Master Hat DS

Connect any desired external DS18B20 devices to the 3 pin connector. The pins are labelled on the underside:

  • 3V3 – connect to DS18B20 power
  • 1W – connect to DS18B20 1-wire (data)
  • GND – connect to DS18B20 ground

Enable one-wire bus on the Raspberry Pi:

pi@pi:~ $ raspi-config
-> 5 Interfacing Options
-> P7 1-Wire
-> Yes
-> Ok
-> Finish

Now reboot your Pi.

Check the Pi has detected your DS18B20(s):

pi@pi:~ $ ls /sys/bus/w1/devices/
28-0115715163ff  w1_bus_master1

Here there is a single DS18B20 device: 28-0115715163ff. Read it by postpending the DS18B20 device’s filename with w1_slave as follows:

pi@pi:~ $ cat /sys/bus/w1/devices/28-0115715163ff/w1_slave
83 01 4b 01 7f ff 0c 10 1a : crc=1a YES
83 01 4b 01 7f ff 0c 10 1a t=24187

The temperature in milliCelcius is shown after “t=”. Here the temperature is 24.187C.

The number of DS18B20 devices which can be supported will vary based on the length of the one-wire bus, and the value of the pull-up resistor used on the one-wire bus. The M-Bus Master Hat DS ships with a 3K3 pull-up resistor (R22).

Problems and Troubleshooting

If you have any problems with your M-Bus Master Hat first check out our Troubleshooting page.

If you continue to have problems please contact us and supply details of your problem.

Please note that we do not provide support for any software, but will provide best effort assistance if you are having trouble to get it to work with your M-Bus Master Hat.

Optional GPIO Header

We may supply an M-Bus Master Hat with the GPIO header populated. This is a feature available as an add-on to later (v1.2+) boards. If the GPIO header (a 1×14 pin header, next to the standard 2×20 pin Raspberry Pi header) is populated, there should be 2 jumpers:

  • One should be placed on the “HAT” pins, on the right hand side, to enable the Hat EEPROM (to allow the Pi to detect the Hat).
  • The other should be used to jumper a numbered pin to an “EN” pin. By default 26 should be connected to EN with this jumper. This signifies that GPIO pin (in this case 26) is used to control the M-Bus.

For more details on using this header, see the mods page.

libmbus License

BSD 3-Clause License

Copyright (c) 2010-2012, Raditex Control AB All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.