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. For older Hats this requires some configuration on the Pi. However, for newer Hats (v1.7d onwards) the Pi should detect the Hat and configure the serial port automatically. If you have a newer Hat, skip this section.

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 raspi-gpio installed, install it now:

sudo apt install raspi-gpio

To enable the M-Bus you need to make GPIO 26 high.

raspi-gpio set 26 op # Set pin 26 as output
raspi-gpio set 26 dh # dh = drive high

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:

raspi-gpio set 26 dl # dl = drive low

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

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 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 milliCelsius 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.