The smartmeter-datacollector
tool is a Python3 software which allows you to continuously retrieve data from supported smart meters (listed below).
The acquired values can be forwarded to one or more data sinks like a MQTT broker or logger.
This tool is an open source software funded by EKZ (Elektrizitätswerke des Kantons Zürich) and developed by Supercomputing Systems AG. The goal of this voluntary initiative is to create a tool that can read, decode and decrypt data (if necessary) from the local interface of various smart meters and convert it into human-readable and simple formats. This should eliminate the complexity of decoding DLMS and similar protocols for the user. The user has the data in a format, which he can easily use in various use-cases ranging from simple visualization (see Method 1: Raspberry Pi image with demo) to integration into energy management algorithms or into custom home automation software.
The following smart meters are supported (see Wiki/Home for detailed information).
Note: All smart meters integrated so far push binary data encoded with HDLC (IEC 62056-46) and DLMS/COSEM. Both unencrypted and encrypted DLMS messages are accepted by the software.
The following data sinks are implemented:
stdout
smartmeter-datacollector
is fully configurable through a .ini
configuration file. The smartmeter-datacollector-configurator
webinterface can help to create and modify the configuration.
There are different methods how to use smartmeter-datacollector
.
For a very easy first time usage of smartmeter-datacollector
we provide a Raspberry Pi image (based on Raspberry Pi OS) which contains the following parts:
smartmeter-datacollector
as a systemd servicesmartmeter-datacollector-configurator
webinterfacesmartmeter-datacollector
smartmeter-datacollector
over MQTT and store them in InfluxDBSee Wiki/Demo for detailed setup instructions.
smartmeter-datacollector
can be installed as a Python3 package either from PyPi or manually using a released wheel.
The Python3 package does not contain any infrastructure to run smartmeter-datacollector
in the background or to automatically start it during a boot sequence. If such infrastructure is required either see Method 3: Debian package or provide it yourself.
Install the package either as global Python package or in a virtualenv with
python3 -m pip install smartmeter-datacollector
Similarly the smartmeter-datacollector-configurator
webinterface can be installed with
python3 -m pip install smartmeter-datacollector-configurator
smartmeter-datacollector
is also available as a Debian (.deb
) package from the releases which installs it system wide. The Debian package includes a systemd service file which enables smartmeter-datacollector
to automatically start after booting the system.
Download the Debian package from releases and install it with
sudo apt install ./python3-smartmeter-datacollector_*.deb
Similarly the smartmeter-datacollector-configurator
webinterface can be installed with a Debian package from its releases with
sudo apt install ./python3-smartmeter-datacollector-configurator_*.deb
The usage of smartmeter-datacollector
depends on the installation method. Independent of the installation method a .ini
configuration file is required to properly run smartmeter-datacollector
.
See Wiki/Configuration for more details on the available configuration options.
To simplify the process of generating a valid .ini
configuration for smartmeter-datacollector
the companion smartmeter-datacollector-configurator
webinterface can be used. It supports
smartmeter-datacollector
(only if installed as a Debian package)See Wiki/smartmeter-datacollector-configurator for more details on the webinterface and the configuration possibilities.
Run smartmeter-datacollector
with the following command:
smartmeter-datacollector --config datacollector.ini
The following command line arguments are supported:
-h, --help
: Shows the help output of smartmeter-datacollector
.-c, --config CONFIG
: Path to the .ini
configuration file.-s,--saveconfig
: Create a default .ini
configuration file.-d, --dev
: Enable development mode.The configuration file can be located anywhere and use any filename. If no .ini
configuration file is specified a default configuration with the following options is used:
/dev/ttyUSB0
LOGGER
sinkMQTT
sink connected to a local broker without encryption or authenticationWhen smartmeter-datacollector
has been installed as a Debian package it provides a systemd .service file named python3-smartmeter-datacollector.service
. Therefore the service can be managed using the systemctl
command. See Run as a systemd service for possible commands.
Help from the community for the smartmeter-datacollector
project is always welcome. Please follow the next few chapters to setup a working development environment.
pipenv
To install the listed minimal requirements run the following command:
sudo apt install git python3 pipenv
To install the optional requirements also run the following command:
sudo apt install python3-all debhelper dh-python
Use git
to clone / checkout smartmeter-datacollector
from GitHub using
git clone https://github.com/scs/smartmeter-datacollector.git
smartmeter-datacollector
uses pipenv
to manage its dependencies and setup a virtual environment. Run the following command to setup the initial development environment:
pipenv install --dev
This will install all runtime and development dependencies for smartmeter-datacollector
in a new virtual environment. Now you are ready to start working on smartmeter-datacollector
.
smartmeter-datacollector
offers a few custom pipenv run
commands to simplify certain development workflows:
build_check
uses twine
to check if the built Python package will be accepted by PiPI
.build_deb
builds a Debian package for the current development platform.build_srcdeb
builds a Debian source package which can be used to build a Debian (binary) package for any platform (e.g. using pbuilder
)build
builds a Python package which can be uploaded to PyPI
using twine
.debianize
creates a debian/
directory used to build Debian source / binary packages.format_check
checks if the code follows the autopep8
code formatting rules.format
automatically adjusts the code to follow the autopep8
code formatting rules.isort_check
checks if the order of the import statements is correct using isort
.isort
automatically re-orders the import statements using isort
.license
makes sure every Python (*.py
) file contains the proper license header.lint_check
checks if the code follows the pylint
rules defined in pyproject.toml
.lint
automatically adjust the code to follow the pylint
rules defined in pyproject.toml
.setup_check
checks whether the dependencies defined in Pipfile
/ Pipfile.lock
are in sync with setup.py
.setup
synchronizes the dependencies defined in Pipfile
/ Pipfile.lock
with setup.py
.Make sure to run format_check
/ format
, isort_check
/ isort
, lint_check
/ lint
, license
, setup_check
/ setup
before committing changes to the repository to avoid unnecessary development cycles. smartmeter-datacollector
uses GitHub Actions to check if these rules apply.
smartmeter-datacollector
and its companion project smartmeter-datacollector-configurator
have been developed by Supercomputing Systems AG on behalf of and funded by EKZ.