mbus-httpd

An HTTP microservice exposing (wired) M-Bus functionality, allowing you to scan an M-Bus and query M-Bus slaves.

You'll need a serial - M-Bus device to connect your server to an M-Bus.

If you want to use a Raspberry Pi and want an M-Bus Master Hat, see here. Alternatively

• buy a USB M-Bus Master device from ebay or aliexpress
• build your own using widely available schematics.

Quickstart

The easiest way to run mbus-httpd is to use a pre-built container, using docker. An mbus-httpd docker manifest is available which supports:

• x86_64
• ARMv6 & ARMv7 (which together cover all Raspberry Pi models).

If you need docker the easiest way to get it is to run:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Once docker is installed (and you may need to logout and back in after installing) you can run mbus-httpd using the following (replacing ttyAMA0 with your serial device):

docker run --name mbus \
          -d -p 8080:8080 \
          -e RUST_LOG=INFO \
          --device /dev/ttyAMA0:/dev/ttyAMA0 \
          packom/mbus-release

This will start the mbus-httpd web server listening on port 8080.

If you're using an M-Bus Master Hat run the container like this instead:

docker run --name mbus \
           -d -p 8080:8080 \
           -e RUST_LOG=INFO \
           --device /dev/ttyAMA0:/dev/ttyAMA0 \
           -v /proc/device-tree/hat:/proc/device-tree/hat \
           --privileged \
           packom/mbus-release

To check whether it is working, from another shell run:

curl -v -X GET http://localhost:8080/mbus/api

Or, modify this as appropriate and stick in a browser:

http://<your_host_name>:8080/mbus/mbus_api 

The YAML API document should be returned.

Using

If you're using an M-Bus Master Hat you can check that it is physically installed corrected by running:

curl -v -X GET http://localhost:8080/mbus/hat

You should be a response like:

{
  "product":"M-Bus Master",
  "productId":"0x0001",
  "productVer":"0x0002",
  "uuid":"abcdef12-abcd-abcd-abcd-123456abcdef",
  "vendor":"packom.net"
}

You need to power on the M-Bus if using an M-Bus Master Hat using:

curl -v -X POST http://localhost:8080/mbus/hat/on

To scan the M-Bus connected to device /dev/ttyAMA0 at 2400 baud:

curl -v -X POST http://localhost:8080/mbus/scan/ttyAMA0/2400

To get info from a device address 48 (0x30):

curl -v -X POST http://localhost:8080/mbus/get/ttyAMA0/2400/48

Building

To build you'll need Rust installed. If you don't want to go to the effort of installing Rust, you can use a build container supporting Rust such as this one, which works on x86_64, ARMv6 and ARMv7 (so all flavours of Raspberry Pis):

docker run --rm -ti -v some_local_dir:/home/build/builds piersfinlayson/build

Once Rust is installed run:

cd ~
git clone https://github.com/packom/mbus-httpd
cd mbus-httpd
cargo build

You also need libmbus. On Ubuntu you can install like this:

sudo apt install libtool autoconf
cd ~
git clone https://github.com/rscada/libmbus
cd libmbus
./build.sh
sudo make install

Running

To run:

cd ~/mbus-httpd
cargo run

As mbus-httpd is designed to run in a container, all configuration is done by environment variables. You'll almost certainly want:

LIBMBUS_PATH=<limbus binary path e.g. ~/libmbus/bin>
LD_LIBRARY_PATH<path libmbus.so is installed to e.g. /usr/local/lib>

You may also want:

SERVER_IP=<IP to listen on>
SERVER_PORT=<port to listen on>
RUST_LOG=<log level, e.g. INFO>

So for example:

cd ~/mbus-httpd
env SERVER_IP=localhost \
env SERVER_PORT=8080 \
env LIBMBUS_PATH=~/libmbus/bin \
env LD_LIBRARY_PATH=/usr/local/lib \
env RUST_LOG=INFO \
cargo run

Clients

A sample mbus-httpd client implemented in Rust is provided. To build and run:

cargo run --example hat-tester

This is designed to do functional and burn-in testing of the M-Bus Master Hat, and is fairly self-explanatory.

To run, doing a full suite of tests on an M-Bus Master Hat:

cargo run --example hat-tester -- \
          --host localhost \
          --port 8080 \
          --address 48 \
          --baudrate 2400 \
          --device ttyAMA0 \
          --reps 10 \
          --get-reps 100 \
          --hat \
          --scan \
          --check-scan \
          --product-ver 0x0002 \
          --uuid=148f8981-033b-407a-a13f-72405d08e0fe

To run on another type of M-Bus Master, connected at device /dev/ttyUSB0 use like this:

cargo run --example hat-tester -- \
          --host localhost \
          --port 8080 \
          --address 48 \
          --baudrate 2400 \
          --device ttyUSB0 \
          --scan \
          --check-scan

To get help on and see other command-line options:

cargo run --example hat-tester -- --help

Debugging

To view logs, make sure RUST_LOG is set to INFO or DEBUG (see above). If running in a shell the logs will be output to stdout. If running within docker you can view the logs using:

docker logs -f mbus

License

mbus-httpd is licensed under the GPL v3.0 or later.

libmbus is licensed under the BSD.