Python package to read data from Energomera energy meter (possibly supporting others similar) and send over to HomeAssistant using MQTT.
The package has been developed with CE301BY three-phase meter.
- Pending PR to
iec62056_21
for transport improvements: pwitab/iec62056-21#29
Since there are direct dependencies no package is published on PyPI and you'll need to install it directly from Github:
pip install git+https://github.com/hostcc/energomera-hass-mqtt@master
usage: energomera-hass-mqtt [-h] [-c CONFIG_FILE] optional arguments: -h, --help show this help message and exit -c CONFIG_FILE, --config-file CONFIG_FILE Path to configuration file (default: '/etc/energomera/config.yaml')
Configuration file is in YAML format and supports following elements:
# (optional) General parameters
general:
# (bool) default ``false``: perform single processing cycle and
# exit
oneshot:
# (number) default ``30``: delay in seconds between processing
# cycles. Is also used as MQTT keepalive interval upon which the
# broker will consider the client disconnected if no response
intercycle_delay:
# (string) default ``error``: logging level, one of ``critical``,
# ``error``, ``warning``, ``info`` or ``debug``
logging_level:
# (bool) default ``false``: if enabled makes parameters a
# combination of default ones plus those defined in the
# configuration file, no check for duplicates is performed!
include_default_parameters:
# Energy meter parameters
meter:
# (string) Serial port (e.g. /dev/ttyUSB0)
port:
# (string) Password to meter for administrative session, manufacturer's
# default is '777777'
password:
# (number) default ``30``: Timeout for meter communications
timeout:
# MQTT parameters
mqtt:
# (string) Hostname or IP address of MQTT broker
host:
# (number) default ``1883``: Port of MQTT broker
port:
# (string) optional: MQTT user name
user:
# (string) optional: MQTT user password
password:
# (string) default ``homeassistant``: Preffix to MQTT topic names,
# should correspond to one set in HomeAssistant for auto-discovery
hass_discovery_prefix:
# (bool) default ``true``: Whether to enable TLS with MQTT broker
tls:
# (list of mappings) - optional: Energy meter parameters to process and
# properties of corresponding HASS sensor
parameters:
- # (string) IEC address (e.g. ``POWEP``)
address:
# (string or list) HASS Sensor name for the entry. If IEC address
# provides multi-value reponse, this could be a list with the
# number of entries equals to number of values in response
name:
# (string) Device class of the HASS sensor
device_class:
# (string) State class of the HASS sensor
state_class:
# (string) Unit of measurement for the HASS sensor
unit:
# (string) - optional: Additional data to read the parameter with
# (argument to parameter's address)
additional_data:
# (string) - optional: Entity name for the HASS sensor, will be
# used to generate its unique ID. If omitted the ``address`` is
# used instead. Use of this option might be needed if your
# configuration contains several entries of meter's parameters
# of same address, but with different ``additional_data``
entity_name:
# (number) - optional: Zero-based index to pick an entry from
# multi-value response to meter's parameter
response_idx:
parameters
section supports following expressions:
{{ energomera_prev_month }}
: Previous month in meter's format, defaults to one month back{{ energomera_prev_day }}
: Previous day in meter's format, default to one day back
All expressions support passing optional argument as (...)
to specify how far
interpolated result should go in the past. Whitespaces around the brackets,
both inner and outer, are ignored. Specifying empty argument results in
using a default value as per interpolation specification above.
For example, {{ energomera_prev_day (5) }}
will result in meter-specific
timestamp returned for the date being 5 days ago. An use case for that might be
intermittent connectivity to the meter where the readings aren't sent to
collecting system on cadence thus have gaps in data points.
Following environment variables might be provided overriding corresponding configuration file entries:
MQTT_HOST
: Host or IP address of MQTT brokerMQTT_PORT
: Same but for the portMQTT_USER
: User name to connect to MQTT broker withMQTT_PASSWORD
: Same but for the password
Sample service definition for systemd
is provided under
systemd/
directory.
There are Docker images available if you would like to run it as Docker container - you could use
ghcr.io/hostcc/energomera-hass-mqtt:latest
or
ghcr.io/hostcc/energomera-hass-mqtt:<release version>
.
As of writing, the images are built to ARM v6/v7 and ARM64 platforms.
Note
For ARMv6 you might need to specify image variant explicitly, in case the
container engine detects it incorrectly and resulting image doesn't run as
expected. To do that just add --variant v6
to pull
command
To run the program as container you will need to create a directory on the host
and put config.yaml
relevant to your setup there.
Then, assuming the directory is called config
and resides relative to
current directory, and the serial port the meter is connected to is
/dev/ttyUSB0
the following command will run it
$ docker run --device /dev/ttyUSB0 -v `pwd`/config:/etc/energomera/ \ ghcr.io/hostcc/energomera-hass-mqtt:latest
Please see online documentation for details on the API package provides.