libmbus: M-bus Library from Raditex Control

libmbus is an open source M-bus (Meter-Bus) library. The Meter-Bus is a standard for reading out meter data from electricity meters, heat meters, gas meters, etc. The M-bus standard deals with both the electrical signals on the M-Bus, and the protocol and data format used in transmissions on the M-Bus. Here we are only concerned with the data format, and the role of the libmbus library is to decode/encode M-bus data, and to handle the communication with M-Bus devices.

There are several different hardware solutions (M-bus gateways) for interconnecting PCs and M-Buses. They typically provide access to the M-Bus via a serial RS-232, a TCP/IP server, etc. At the moment libmbus supports access to M-bus via M-bus gateways with TCP and serial (RS232) interface.

See, e.g., the Wiki page for M-Bus or the M-Bus home page for more information.

Features

The libmbus library is under active development, and the feature list is expected to be expanded in the near future.

The main characteristics of libmbus currently are:

Source code

The latest development code is available at our github repository: rscada/libmbus.

Download releases

You can browse the libmbus source code online here, or download the tarballs and Ubuntu binary packages for official relases:

Version Release date Source Binary
0.8.0 2012-06-18 libmbus-0.8.0.tar.gz Ubuntu:
libmbus1_0.8.0_amd64.deb, libmbus-dev_0.8.0_amd64.deb
0.7.0 2012-02-07 libmbus-0.7.0.tar.gz Ubuntu:
libmbus1_0.7.0-1_i386.deb, libmbus-dev_0.7.0-1_i386.deb,
libmbus1_0.7.0-1_amd64.deb, libmbus-dev_0.7.0-1_amd64.deb
0.6.1 2011-11-07 libmbus-0.6.1.tar.gz Ubuntu:
libmbus1_0.6.1-1_i386.deb, libmbus-dev_0.6.1-1_i386.deb,
libmbus1_0.6.1-1_amd64.deb, libmbus-dev_0.6.1-1_amd64.deb
0.6 2011-11-06 libmbus-0.6.tar.gz Ubuntu:
libmbus1_0.6-1_i386.deb, libmbus-dev_0.6-1_i386.deb,
libmbus1_0.6-1_amd64.deb, libmbus-dev_0.6-1_amd64.deb
0.5 2011-08-06 libmbus-0.5.tar.gz Ubuntu:
libmbus1_0.5-1_i386.deb, libmbus-dev_0.5-1_i386.deb,
libmbus1_0.5-1_amd64.deb, libmbus-dev_0.5-1_amd64.deb
0.4 2011-03-21 libmbus-0.4.tar.gz Ubuntu:
libmbus1_0.4-1_i386.deb, libmbus-dev_0.4-1_i386.deb,
libmbus1_0.4-1_amd64.deb, libmbus-dev_0.4-1_amd64.deb
0.3 2010-11-23 libmbus-0.3.tar.gz
0.2 2010-08-07 libmbus-0.2.tar.gz

Build and install

The libmbus library use the GNU autobuild tools, and building the library therefore follows the standard procedures, i.e.,

$ ./configure
$ make
$ make install

On a Ubuntu system, install the binary packages like this:

$ sudo dpkg -i libmbus1_0.5-1_i386.deb libmbus-dev_0.5-1_i386.deb

Documentation

See the autogenerated API reference online or download the PDF.

Examples

The libmbus library comes with several example and utility applications, some of which are described here:

mbus-tcp-scan and mbus-serial-scan

The mbus-tcp-scan and mbus-serial-scan applications can be used for scanning an M-bus for slaves using the primary addressing method. In the M-Bus protocol the primary address of a slave is an integer between 1 and 250. It is this integer valued address that the mbus_scan application presents in the list of discovered slaves. This address is also used to address slaves e.g. when reading out data (see the mbus-tcp-request-data program below).

rob@bergen$ mbus-tcp-scan 192.168.0.100 10001
Found an M-Bus slave at physical address 1
Found an M-Bus slave at physical address 2
Found an M-Bus slave at physical address 8
rob@bergen$ 
rob@bergen$ mbus-serial-scan /dev/ttyS0
Found an M-Bus slave at physical address 1
Found an M-Bus slave at physical address 2
Found an M-Bus slave at physical address 8
rob@bergen$ 

mbus-tcp-scan-secondary and mbus-serial-scan-secondary

Like the scanning programs above, but scanning for devices that use the secondary addressing method.

rob@bergen$ mbus-tcp-scan-secondary 192.168.0.100 10001
Found a device on secondary address 1401020701010105 [using address mask 14010207FFFFFFFF]
Found a device on secondary address 1401020801010105 [using address mask 14010208FFFFFFFF]
Summary: Tried 210 address masks and found 2 devices.
rob@bergen$

mbus-tcp-request-data and mbus-serial-request-data

The mbus-tcp-request-data and mbus-serial-request-data applications can be used for reading out meter data from an M-Bus slave. The meter data is presented in XML form, as in the following example:

rob@bergen$ mbus-tcp-request-data
usage: mbus-tcp-request-data ip-address ip-port mbus-address
rob@bergen$ mbus_request_data 192.168.0.100 10001 1
<MBusData>

    <SlaveInformation>
        <Id>9806388</Id>
        <Manufacturer>SAU</Manufacturer>
        <Version>2</Version>
        <Medium>Heat</Medium>
        <AccessNumber>47</AccessNumber>
        <Status>00</Status>
        <Signature>0000</Signature>
    </SlaveInformation>

    <DataRecord id="0">
        <Function>Instantaneous value</Function>
        <Unit>Energy (10 kWh)</Unit>
        <Value>288144</Value>
    </DataRecord>

    <DataRecord id="1">
        <Function>Instantaneous value</Function>
        <Unit>Volume (10^-1 m^3)</Unit>
        <Value>00498529</Value>
    </DataRecord>

    <DataRecord id="2">
        <Function>Instantaneous value</Function>
        <Unit>Power (10^2 W)</Unit>
        <Value>004970</Value>
    </DataRecord>

    <DataRecord id="3">
        <Function>Instantaneous value</Function>
        <Unit>Volume flow (10^-3 m^3/h)</Unit>
        <Value>008512</Value>
    </DataRecord>

    <DataRecord id="4">
        <Function>Instantaneous value</Function>
        <Unit>Flow temperature (10^-1 deg C)</Unit>
        <Value>0838</Value>
    </DataRecord>

    <DataRecord id="5">
        <Function>Instantaneous value</Function>
        <Unit>Return temperature (10^-1 deg C)</Unit>
        <Value>0333</Value>
    </DataRecord>

    <DataRecord id="6">
        <Function>Instantaneous value</Function>
        <Unit>Temperature Difference (10^-2 \xc2\xb0C)</Unit>
        <Value>005050</Value>
    </DataRecord>

    <DataRecord id="7">
        <Function>Instantaneous value</Function>
        <Unit>Time Point (date)</Unit>
        <Value>5202</Value>
    </DataRecord>

    <DataRecord id="8">
        <Function>Instantaneous value</Function>
        <Unit>Operating time (days)</Unit>
        <Value>162</Value>
    </DataRecord>

</MBusData>

The mbus-serial-request-data is used in a similar manner, but it takes one argument (serialport file) instead of two (host and port). The "mbus-address" can either be a primary address (integer 0-250) or a secondary address. The secondary address is a 16 character string, consisting of the devices ID, Manufacturer-ID, Version, Medium. Example: "1401020701010105".

License

The libmbus library is a component of RaditexSCADA that is published as open source, and it is free for anyone to use as long as due credit it given to RaditexSCADA and Raditex Control in derivative work based on the libmbus library.

Copyright (c) 2010-2011, 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:

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 PARTICULA R 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, PROCUREME NT 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 OTH ERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

libmbus News

2012-06-18:

libmbus 0.8 released

This release contains many improvements bug fixes, and major new features are support for float point numbers and support for multi-telegram communication, thanks to major contributions from Stefan Wahren. Also, thanks to Henry N. for contributing patches.

2012-02-07:

libmbus 0.7 released

Added support for variable-length VIF ASCII encoding. Added support for setting baud rates as command-line argument for the serial communication utilities. Thanks to Stefan Wahren for bug fixes and improvements.

2011-11-07:

libmbus 0.6.1 released

Minor update that fixes a problem with the autotools build system in version 0.6.0.

2011-11-06:

libmbus 0.6 released

Added support for decoding of more DIF and VIF types. Thanks to Pelle van der Heide for patches for imporoved support for ABB mbus devices. Several bug fixes, many of which provided by Tomas Menzl. Added a new auxillary API for simplifying development of custom mbus applications, and which contains a unified API for TCP and serial MBUS communication. Many thanks to Tomas Menzl for major contributions.

2011-08-06:

libmbus 0.5 released

Added serial transport layer. Removed unnecessary GLib dependency. Added support for secondary address selection and probing. Many thanks to Uwe Grohnwaldt for assisting with a test environment for devices using secondary addressing.

2011-03-21:

libmbus 0.4 released

Added unit tests. Some minor backwards-incompatible API changes (related to generation of XML representation). Support for dynamic number of records in variable-length data frames. Support for more medium and unit types. This release also includes several patches from Markus Bergkvist.

>> more news