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.
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 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.
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:
You should see:
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:
Would you like a login shell to be accessible over serial? => <No>
Would you like the serial port hardware to be enabled? => <Yes>
=> <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:
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…
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
gpio write 25 1
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.
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 cmake --build build --target 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
Then try running the command again.
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.
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.