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:
- 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 and serialport M-bus gateways.
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:
- 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 Raditex Control AB 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 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.
