{"id":13723668,"url":"https://github.com/volkszaehler/mbmd","last_synced_at":"2025-04-13T13:14:52.246Z","repository":{"id":38375395,"uuid":"189631891","full_name":"volkszaehler/mbmd","owner":"volkszaehler","description":"ModBus Measurement Daemon - simple reading of data from ModBus meters and grid inverters","archived":false,"fork":false,"pushed_at":"2025-04-11T15:24:41.000Z","size":7019,"stargazers_count":255,"open_issues_count":55,"forks_count":88,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-13T13:14:47.439Z","etag":null,"topics":["golang","grid-inverters","modbus","modbus-meters","openhab","smart-meter","sunspec","volkszaehler"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/volkszaehler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-05-31T17:17:13.000Z","updated_at":"2025-04-11T15:24:45.000Z","dependencies_parsed_at":"2023-09-21T19:22:18.035Z","dependency_job_id":"dee0fe69-fe36-4649-b63b-8fe6a14c873c","html_url":"https://github.com/volkszaehler/mbmd","commit_stats":{"total_commits":515,"total_committers":34,"mean_commits":"15.147058823529411","dds":0.3864077669902912,"last_synced_commit":"d50c56af82d25215afa785b4c411face04c97373"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volkszaehler%2Fmbmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volkszaehler%2Fmbmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volkszaehler%2Fmbmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volkszaehler%2Fmbmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volkszaehler","download_url":"https://codeload.github.com/volkszaehler/mbmd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717238,"owners_count":21150389,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","grid-inverters","modbus","modbus-meters","openhab","smart-meter","sunspec","volkszaehler"],"created_at":"2024-08-03T01:01:44.132Z","updated_at":"2025-04-13T13:14:52.219Z","avatar_url":"https://github.com/volkszaehler.png","language":"Go","funding_links":[],"categories":["Consumption"],"sub_categories":["Buildings and Heating"],"readme":"# ModBus Measurement Daemon\n\n[![Build Status](https://travis-ci.org/volkszaehler/mbmd.svg?branch=master)](https://travis-ci.org/volkszaehler/mbmd)\n\nA daemon for collecting measurement data from smart meters and grid inverters over modbus.\n\n`mbmd` provides an http interface to smart meters and grid inverters with modbus interface.\nMeter readings are made accessible through REST API and MQTT.\nModbus communication is possible over RS485 connections as well as TCP sockets.\n\n`mbmd` was originally developer by Mathias Dalheimer under the name of `gosdm`. Previous releases are still [available](https://github.com/gonium/gosdm630).\n\n# Table of Contents\n\n* [Requirements](#requirements)\n* [Installation](#installation)\n  * [Raspberry Pi](#raspberry-pi)\n  * [Detecting connected meters](#detecting-connected-meters)\n* [API](#api)\n  * [Rest API](#rest-api)\n  * [Websocket API](#websocket-api)\n  * [MQTT API](#mqtt-api)\n* [Supported Devices](#supported-devices)\n* [Releases](#releases)\n\n\n## Requirements\n\nYou'll need:\n* A supported Modbus/RTU smart meter OR an supported Modbus/TCP SunSpec-compatible grid inverter.\n* In case of Modbus/RTU: A USB RS485 adapter. See [USB-ISO-RS485 project](https://github.com/gonium/usb-iso-rs485) for a home-grown adapter.\n* Optionally an RS485 to Ethernet converter (see [SO discussion](https://stackoverflow.com/questions/59459877/is-rtu-over-tcp-a-spec-conforming-modbus-application))\n\n\n## Installation\n\n### Using the precompiled binaries\n\nPrecompiled release packages are [available](https://github.com/volkszaehler/mbmd/releases). Download the right package for the target platform and unzip.\n\n### Building from source\n\n`mbmd` is developed in [Go](http://golang.org) and requires ^1.16. To build from source two steps are needed:\n\n- use `make install` to install the build tools (make sure `$GOPATH/bin` is part of the path to make the installed tools accessible for the next step)\n- then run `make build` which creates the `./mbmd` binary\n\nTo cross-build for a different archtecture (e.g. Raspberry Pi), use\n\n    GOOS=linux GOARCH=arm GOARM=5 make build\n\n### Running\n\nTo get help on the various command line options run\n\n\tmbmd -h\n\nThe full documentation is available in the [docs](docs/mbmd.md) folder.\nA typical invocation looks like this:\n\n    $ ./bin/mbmd run -a /dev/ttyUSB0 -d janitza:26,sdm:1\n    2017/01/25 16:34:26 config: creating RTU connection via /dev/ttyUSB0 (9600baud, 8N1)\n    2017/01/25 16:34:26 httpd: starting api at :8080\n\nThis call queries a Janitza B23 meter with ID 26 and an Eastron SDM\nmeter at ID 1. Not all devices are by default configured to use ID 1.\nThe default device IDs depend on the meter type and documented in the meter's manual.\n\nTo use RTU devices with RS485/Ethernet adapters, add the `--rtu` switch to configure `mbmd` to use the TCP connection with RTU data format:\n\n\t❯ ./bin/mbmd run -a rs485.fritz.box:23 --rtu -d sdm:1\n\t2020/01/02 10:43:53 mbmd unknown version (unknown commit)\n\t2020/01/02 10:43:53 config: creating RTU over TCP connection for rs485.fritz.box:23\n\t2020/01/02 10:43:53 initialized device SDM1.1: {SDM Eastron SDM meters   }\n\t2020/01/02 10:43:53 httpd: starting api at :8080\n\nIf you use the ``-v`` commandline switch you can see\nmodbus traffic and the current readings on the command line.  At\n[http://localhost:8080](http://localhost:8080) you can see an embedded\nweb page that updates itself with the latest values:\n\n![realtime view of incoming measurements](img/realtimeview.png)\n\n\n### Run using Docker\n\nAlternatively run `mbmd` using the Docker image:\n\n\tdocker run -p 8080:8080 --device=/dev/ttyUSB0 volkszaehler/mbmd run -a /dev/ttyUSB0 -u 0.0.0.0:8080 -d sdm:1\n\nTo mount the config file into the docker container use `-v $(pwd)/mbmd.yaml:/etc/mbmd.yaml`.\n\n## Raspberry Pi\n\nDownload the ARM package for usage with Raspberry Pi and copy the binary\ninto `/usr/local/bin`. The following sytemd unit can be used to\nstart `mbmd` as service (put this into a new file ``/etc/systemd/system/mbmd.service``):\n\n    [Unit]\n    Description=mbmd\n    After=syslog.target\n    After=network-online.target\n    [Service]\n    ExecStart=/usr/local/bin/mbmd run -a /dev/ttyAMA0\n    Restart=always\n    [Install]\n    WantedBy=multi-user.target\n\nYou might need to adjust the ``-a`` parameter depending on where your\nRS485 adapter is connected. Then, use\n\n    systemctl start mbmd\n\nto test your installation. If you're satisfied use\n\n    systemctl enable mbmd\n\nto start the service at boot time automatically.\n\n*WARNING:* When using an FTDI-based USB-RS485 adaptor the\nRaspberry Pi might become unreachable after a while. This is most likely not\nan issue with the RS485-USB adaptor or this software, but because of [a\nbug in the Raspberry Pi kernel](https://github.com/raspberrypi/linux/issues/1187).\nTo fix switch the internal `dwc` USB hub of the Raspberry Pi to\nUSB1.1 by adding the following parameter to `/boot/cmdline.txt`:\n\n    dwc_otg.speed=1\n\n\n## Detecting connected meters\n\nMODBUS/RTU does not provide a mechanism to discover devices. There is no\nreliable way to detect all attached devices.\nAs workaround `mbmd scan` attempts to read the L1 voltage from all\ndevice IDs and reports which one replied correctly (i.e. 110/230V +/-10%):\n\n````\n./mbmd scan -a /dev/ttyUSB0\n2017/06/21 10:22:34 Starting bus scan\n2017/06/21 10:22:35 Device 1: n/a\n...\n2017/07/27 16:16:39 Device 21: SDM type device found, L1 voltage: 234.86\n2017/07/27 16:16:40 Device 22: n/a\n2017/07/27 16:16:40 Device 23: n/a\n2017/07/27 16:16:40 Device 24: n/a\n2017/07/27 16:16:40 Device 25: n/a\n2017/07/27 16:16:40 Device 26: Janitza type device found, L1 voltage: 235.10\n...\n2017/07/27 16:17:25 Device 247: n/a\n2017/07/27 16:17:25 Found 2 active devices:\n2017/07/27 16:17:25 * slave address 21: type SDM\n2017/07/27 16:17:25 * slave address 26: type JANITZA\n2017/07/27 16:17:25 WARNING: This lists only the devices that responded to a known L1 voltage request. Devices with different function code definitions might not be detected.\n````\n\n\n# API\n\n## Rest API\n\n`mbmd` provides a convenient REST API. Supported endpoints under `/api` are:\n\n* `/api/last/{ID}` latest data for device\n* `/api/avg/{ID}` averaged data over last minute\n* `/api/status` daemon status\n\nBoth device APIs can also be called without the device id to return data for all connected devices.\n\n\n### Monitoring\n\nThe `/api/status` endpoint provides the following information:\n\n    $ curl http://localhost:8080/api/status\n    {\n      \"StartTime\": \"2017-01-25T16:35:50.839829945+01:00\",\n      \"UpTime\": 65587.177092186,\n      \"Goroutines\": 11,\n      \"Memory\": {\n        \"Alloc\": 1568344,\n        \"HeapAlloc\": 1568344\n      },\n      \"Modbus\": {\n        \"TotalModbusRequests\": 1979122,\n        \"ModbusRequestRatePerMinute\": 1810.5264666764785,\n        \"TotalModbusErrors\": 738,\n        \"ModbusErrorRatePerMinute\": 0.6751319688261972\n      },\n      \"ConfiguredMeters\": [\n        {\n          \"Id\": 26,\n          \"Type\": \"JANITZA\",\n          \"Status\": \"available\"\n        }\n      ]\n    }\n\nThis is a snapshot of a process running over night, along with the error\nstatistics during that timeframe. The process queries continuously,\nthe cabling is not a shielded, twisted wire but something that I had laying\naround. With proper cabling the error rate should be lower, though.\n\n\n## Websocket API\n\nData read from the meters can be observed by clients in realtime using the Websocket API.\nAs soon as new readings are available, they are pushed to connected websocket clients.\n\nThe websocket API is available on `/ws`. All connected clients receive status and\nmeter updates for all connected meters without further subscription.\n\n\n## MQTT API\n\nAnother option for receiving client updates is by using the built-in MQTT publisher.\nBy default, readings are published at `/mbmd/\u003cunique id\u003e/\u003creading\u003e`. Rate limiting is possible.\n\n\n## Homie API\n\n[Homie](https://homieiot.github.io) is an MQTT convention for IoT/M2M. `mbmd` publishes all devices and readings using the Homie protocol. This allows systems like e.g. OpenHAB to auto-discover devices operated by `mbmd`:\n\n![auto-discovery of thinks in OpenHAB](img/openhab.png)\n\n## InfluxDB support\n\nThere is also the option to directly insert the data into an influxdb database by using the command-line options available. InfluxDB 1.8 and 2.0 are currently supported. to enable this, add the `--influx-database` and the `--influx-url` commandline parameter. More advanced configuration is available, to learn more checkout the [mbmd_run.md](docs/mbmd_run.md) documentation\n\n# Supported Devices\n\n`mbmd` supports a range of DIN rail meters and grid inverters.\n\n## Modbus RTU Meters\n\nThe meters have slightly different capabilities. The EASTRON SDM630 offers\na lot of features, while the smaller devices only support basic\nfeatures.  The table below gives an overview (please consult the\nmanuals for definitive guidance):\n\n| Meter | Phases | Voltage | Current | Power | Power Factor | Total Import | Total Export | Per-phase Import/Export | Line/Neutral THD |\n|---|---|---|---|---|---|---|---|---|---|\n| SDM54 | 3 | + | + | + | + | + | + | + | + |\n| SDM72 | 3 | - | - | + | - | + | + | - | - |\n| SDM120/220 | 1 | + | + | + | + | + | + | - | - |\n| SDM530 | 3 | + | + | + | + | + | + | - | - |\n| SDM630 | 3 | + | + | + | + | + | + | + | + |\n| Inepro PRO1/2 | 1 | + | + | + | + | + | + | - | - |\n| Inepro PRO380 | 3 | + | + | + | + | + | + | + | - |\n| Janitza B23-312 | 3 | + | + | + | + | + | + | - | - |\n| DZG DVH4013 | 3 | + | + | - | - | + | + | - | - |\n| SBC ALE3 | 3 | + | + | + | + | + | + | - | - |\n| ABB A/B-Series | 3 | + | + | + | + | + | + | + | + |\n| BE MPM3MP | 3 | + | + | + | + | + | + | - | - |\n| KOSTAL Smart Energy Meter | 3 | + | + | + | + | + | + | + | - |\n| ORNO WE-504/514/515 | 1 | + | + | + | + | + | - | - | - |\n| ORNO WE-516/517 | 3 | + | + | + | + | + | + | + | - |\n| iEM3000 Series | 3 | + | + | + | + | + | + | (+) | + |\n| B+G e-tech WS100 | 1 | + | + | + | - | + | + | - | - |\n\n- **SDM54**: Compact (3TE), 3P meter with a lot of features. Can be configured using the builtin display.\n- **SDM72**: Compact (4TE), 3P meter with bare minium of total measurements, no currents. Can be configured using the builtin display.\n- **SDM120**: Cheap and small (1TE), but communication parameters can only be set over MODBUS, which is currently not supported by this project.\nYou can use e.g. [SDM120C](https://github.com/gianfrdp/SDM120C) to change parameters.\n- **SDM220, SDM230**: More comfortable (2TE), can be configured using the builtin display.\n- **SDM530**: Very big (7TE) - takes up a lot of space, but all connections are\non the underside of the meter.\n- **SDM630**: v1 and v2, both MID and non-MID. Compact (4TE) and with lots\nof features. Can be configured for 1P2 (single phase with neutral), 3P3\n(three phase without neutral) and 3P4 (three phase with neutral) systems.\n- **Inepro PRO1/2**: Small (1TE) MID meter up to 100A (Pro2). External tariff input possible (2T versions).\n- **Inepro PRO380**: Compact (4TE) MID meter with extensive features.\nCan be connected 3P4W, 3P3W and 1P2W. Includes per-direction active/reactive energy consumption and supports two tariffs. Energy resolution is 2 digits per kWh.\n- **Janitza B23-312**: These meters have a higher update rate than the Eastron\ndevices, but they are more expensive. The -312 variant is the one with a MODBUS interface.\n- **DZG DVH4013**: This meter does not provide raw phase power measurements\nand only aggregated import/export measurements. The meter is only\npartially implemented and not recommended.\nBy default, the meter communicates using 9600 8E1. The meter ID\nis derived from the serial number taking the last two numbers of the\nserial number (top right of the device), e.g. 23, and add one (24).\nAssume this is a hexadecimal number and convert it to decimal (36). Use\nthis as the meter ID.\n- **SBC ALE3**: This compact Saia Burgess Controls meter is comparable to the SDM630.\nIt has two tariffs, both import and export depending on meter version and compact (4TE). It's often used with Viessmann heat pumps.\n- **BE MPM3PM**: Compact (4TE) three phase meter.\n- **KOSTAL Smart Energy Meter**: Slave device for Kostal grid inverters. Known [bug](https://github.com/volkszaehler/mbmd/pull/61#issuecomment-570081618) in inverter firmware with Total Export Energy.\n- **ORNO WE-504/514/515**: Low cost single phase meter\nBy default, the meter communicates using 9600 8E1. The meter ID is 1. Meter ID, bus speed and other parameters are configurable via  [Software(Windows only)](https://www.partner.orno.pl/grafiki2/PC%20softwre170621.rar)\nWE-515 has a lithium battery and multi-tariff support, WE-514 does not support tariff zones.\n- **ORNO WE-516/517**: Low cost three phase meter.\nBy default, the meter communicates using 9600 8E1. The meter ID is 1. Meter ID, bus speed and other parameters are configurable via  [Software(Windows only)](https://www.partner.orno.pl/grafiki2/PC%20softwre170621.rar)\nWE-517 has a lithium battery and multi-tariff support, WE-516 does not support tariff zones.\n- **Schneider Electric iEM3000 Series**: Professional meter with loads of configurable max/average measurements with timestamp functionality.\n- **B+G e-tech WS100**: Cheap and small (1TE), 1P MID meter.\n\n## Modbus TCP Grid Inverters\n\nApart from meters, SunSpec-compatible grid inverters connected over TCP\nare supported, too. SunSpec defines a default register layout for accessing\nthe devices.\n\nSupported inverters include popular devices from SolarEdge (SE3000, SE9000)\nand SMA (Sunny Boy and Sunny TriPower).\n\nIn case of TCP connection, the adapter parameter becomes the hostname and port:\n\n\t./mbmd run -a 192.168.0.44:502 -d SMA:23\n\nSunSpec devices can host multiple subdevices, e.g. to expose a meter attached to an inverter. To access a subdevice, append its id to the slave id:\n\n\t./mbmd run -a 192.168.0.44:502 -d FRONIUS:1.0 -d FRONIUS:1.1\n\n\n# Releases\n\nDownload the lastest release from [github.com/volkszaehler/mbmd/releases](https://github.com/volkszaehler/mbmd/releases).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolkszaehler%2Fmbmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolkszaehler%2Fmbmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolkszaehler%2Fmbmd/lists"}