M-bus Library from FreeSCADA: libmbus

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 only supports access to the M-bus via M-bus gateways with TCP interface. However, to use libmbus with serial-based M-bus gateways would only require minimal changes in the applications that use the libmbus library, and changes in the library itself should not be necessary.

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:

Open source C-library for communicating with M-bus slaves and for encoding/decoding the M-bus protocol.
Demo applications for scanning the M-bus for slaves, and for reading out user data (meter readings) from M-bus slaves.
Presentation of the M-Bus meter data in an intuitive and easily processed XML format. This feature greatly simplifies the handing of meter data in other applications.
Support for TCP/IP M-bus gateways.

Download

You can browse the libmbus source code here, or download the latest tarball.

Build and install

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

$ ./configure
$ make
$ make install

Examples

The libmbus library comes with several example applications.

mbus_scan

The mbus_scan application can be used for scanning an M-bus for slaves. 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_request_data program below).

rob@bergen$ mbus_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$

mbus_request_data

The mbus_request_data application 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_request_data
usage: mbus_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>

License

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