Welcome to sml2mqtt’s documentation!

sml2mqtt is a asyncio application that can read multiple sml (Smart Message Language) streams from energy meters and report the values through mqtt. The meters can be read through serial ports or through http (e.g. Tibber) and the values that will be reported can be processed in various ways with operations.

Installation

Virtual environment

Installation

Hint

On Windows use the python command instead of python3

Navigate to the folder in which the virtual environment shall be created (e.g.):

cd /opt/sml2mqtt

If the folder does not exist yet you can create it with the mkdir command:

mkdir /opt/sml2mqtt

Create virtual environment (this will create a new subfolder “venv”):

python3 -m venv venv

Go into folder of virtual environment:

cd venv

Activate the virtual environment

Linux:
```
source bin/activate
```
Windows:
```
Scripts\activate
```

Upgrade pip and setuptools:

python3 -m pip install --upgrade pip setuptools

Install sml2mqtt:

python3 -m pip install sml2mqtt

Run sml2mqtt:

sml2mqtt --config PATH_TO_CONFIGURATION_FILE

Upgrading

Stop sml2mqtt
Activate the virtual environment
Navigate to the folder where sml2mqtt is installed:
cd /opt/sml2mqtt
Activate the virtual environment

Linux:
source bin/activate
Windows:
Scripts\activate
Run the following command in your activated virtual environment:
```
python3 -m pip install --upgrade sml2mqtt
```
Start sml2mqtt
Observe the log for errors in case there were changes

Autostart after reboot

To automatically start the sml2mqtt from the virtual environment after a reboot call:

nano /etc/systemd/system/sml2mqtt.service

and copy paste the following contents. If the user/group which is running sml2mqtt is not “openhab” replace accordingly. If your installation is not done in “/opt/sml2mqtt/venv/bin” replace accordingly as well:

[Unit]
Description=sml2mqtt
Documentation=https://github.com/spacemanspiff2007/sml2mqtt
After=network-online.target

[Service]
Type=simple
User=openhab
Group=openhab
Restart=on-failure
RestartSec=10min
ExecStart=/opt/sml2mqtt/venv/bin/sml2mqtt -c PATH_TO_CONFIGURATION_FILE

[Install]
WantedBy=multi-user.target

Now execute the following commands to enable autostart:

sudo systemctl --system daemon-reload
sudo systemctl enable sml2mqtt.service

It is now possible to start, stop, restart and check the status of sml2mqtt with:

sudo systemctl start sml2mqtt.service
sudo systemctl stop sml2mqtt.service
sudo systemctl restart sml2mqtt.service
sudo systemctl status sml2mqtt.service

Docker

Installation through docker is available:

docker pull spacemanspiff2007/sml2mqtt:latest

The docker image has one volume /sml2mqtt which has to be mounted. There the config.yml will be used or a new config.yml will be created

The analyze option can also be set through an environment variable (see command line interface).

Configuration

Configuration of sml2mqtt is done through a yaml file. The path to the file can be specified with -c PATH or --config PATH. If nothing is specified a file with the name config.yml is searched in the subdirectory sml2mqtt in

the current working directory
the venv directory
the user home

If a config file is specified and it does not yet exist a default configuration file will be created.

Example

logging:
  level: INFO         # Log level
  file: sml2mqtt.log  # Log file path (absolute or relative to config file) or stdout

mqtt:
  connection:
    identifier: sml2mqtt-ZqlFvhSBdDGvJ
    host: localhost
    port: 1883
    user: ''
    password: ''
  topic prefix: sml2mqtt
  defaults:
    qos: 0         # Default value for QOS if no other QOS value in the config entry is set
    retain: false  # Default value for retain if no other retain value in the config entry is set
  last will:
    topic: status   # Topic fragment for building this topic with the parent topic

general:
  Wh in kWh: true       # Automatically convert Wh to kWh
  republish after: 120  # Republish automatically after this time (if no other filter configured)

inputs:
- type: serial
  url: COM1   # Device path
  timeout: 3  # Seconds after which a timeout will be detected (default=3)
- type: serial
  url: /dev/ttyS0   # Device path
  timeout: 3        # Seconds after which a timeout will be detected (default=3)

devices:
  # Device configuration by reported id
  device_id_hex:

    mqtt:                           # Optional MQTT configuration for this meter.
      topic: DEVICE_BASE_TOPIC      # Topic fragment for building this topic with the parent topic

    status:                         # Optional MQTT status topic configuration for this meter
      topic: status                 # Topic fragment for building this topic with the parent topic

    skip:                           # OBIS codes (HEX) of values that will not be published (optional)
    - '00112233445566'

    # Configurations for each of the values (optional)
    values:

    - obis: '00112233445566'        # Obis code for this value
      mqtt:                         # Mqtt config for this value (optional)
        topic: OBIS_VALUE_TOPIC     # Topic fragment for building this topic with the topic prefix
      # A sequence of operations that will be evaluated one after another.
      # If one operation blocks nothing will be reported for this frame
      operations:
      - negative on energy meter status: true   # Make value negative based on an energy meter status. Set to "true" to enable or to "false" to disable workaround. If the default obis code for the energy meter is wrong set to the appropriate meter obis code instead
      - factor: 3               # Factor with which the value gets multiplied
      - offset: 100             # Offset that gets added on the value
      - round: 2                # Round to the specified digits
      - refresh action: 300     # Republish value every 300s

Example input Tibber bridge

These input settings can be used to poll data from a Tibber bridge:

inputs:
 - type: http
   url: http://IP_OR_HOSTNAME_OF_TIBBER_BRIDGE/data.json?node_id=1
   interval: 3   # Poll interval secs
   timeout: 10   # After which time the input will change to TIMEOUT
   user: "admin"
   password: "printed on bridge socket"

Example mqtt config

MQTT topics can be configured either by providing a full topic or a topic fragment. With a topic fragment the resulting topic is build with the parent topic. The structure is topic prefix / device / value. Providing a full topic will ignore the fragments. The entries for qos and retain are optional.

full topic: my/full/topic
qos: 1

Configuration Reference

All possible configuration options are described here. Not all entries are created by default in the config file and one should take extra care when changing those entries.

settings Settings

field logging: LoggingSettings [Optional]

field mqtt: MqttConfig [Optional]

field general: GeneralSettings [Optional]

field inputs: list[HttpSourceSettings | SerialSourceSettings] = []

field devices: dict[Annotated[str], SmlDeviceConfig] = {}: Device configuration by ID or url

logging

settings LoggingSettings

field level: str = 'INFO': Log level

field file: str = 'sml2mqtt.log': Log file path (absolute or relative to config file) or “stdout”

general

settings GeneralSettings

field Wh in kWh: bool = True: Automatically convert Wh to kWh

field republish after: int = 120: Republish automatically after this time (if no other filter configured)

field report blank energy meters: bool = False: Report blank energy meters (where the value is 0kwh)

field report device id: bool = False: Report the device id even though it does never change

field device id obis: list[Annotated[str]] = ['0100000009ff', '0100600100ff']: Additional OBIS fields for the serial number to configuration matching

inputs

settings SerialSourceSettings

field type: Literal['serial'] [Required]

field url: Annotated[str] [Required]

Device path

Constraints:

strip_whitespace = True
strict = True
min_length = 1

field timeout: Union[Annotated[int], Annotated[float]] = 6: Seconds after which a timeout will be detected (default=6)

field baudrate: int = 9600

field parity: str = 'None'

field stop bits: Union[Annotated[int], Annotated[float]] = 1

field byte size: int = 8

Example:

type: serial
url: COM3

settings HttpSourceSettings

field type: Literal['http'] [Required]

field url: Annotated[Url] [Required]

Url

Constraints:

allowed_schemes = [‘http’, ‘https’]

field timeout: Union[Annotated[int], Annotated[float]] = 6: Seconds after which a timeout will be detected (default=6)

field interval: Union[Annotated[int], Annotated[float]] = 2

Delay between requests

Constraints:

ge = 0.1

field user: str = '': User (if needed)

field password: str = '': Password (if needed)

field request timeout: Union[Annotated[int], Annotated[float], None] = None: Dedicated timeout for the http request

Example:

type: http
url: http://localhost:8080/sml
interval: 3
timeout: 10

mqtt

settings MqttConfig

field connection: MqttConnection [Optional]

field topic prefix: Annotated[str] = 'sml2mqtt'

Prefix for all topics. Set to empty string to disable

Constraints:

strict = True
strip_whitespace = True

field defaults: MqttDefaultPublishConfig [Optional]

field last will: OptionalMqttPublishConfig [Optional]

settings MqttConnection

field identifier: Annotated[str] = 'sml2mqtt-tNeMNZrhuwjSQ'

Constraints:

strict = True
strip_whitespace = True

field host: Annotated[str] = 'localhost'

Constraints:

strict = True
strip_whitespace = True

field port: int = 1883

Constraints:

ge = 0

field user: Annotated[str] = ''

Constraints:

strict = True
strip_whitespace = True

field password: Annotated[str] = ''

Constraints:

strict = True
strip_whitespace = True

field tls: MqttTlsOptions | None = None

settings OptionalMqttPublishConfig

field topic: Optional[Annotated[str]] = None: Topic fragment for building this topic with the parent topic

field full topic: Optional[Annotated[str]] = None: Full topic - will ignore the parent topic parts

field qos: Optional[Literal[0, 1, 2]] = None: QoS for publishing this value (if set - otherwise use parent)

field retain: Optional[Annotated[bool]] = None: Retain for publishing this value (if set - otherwise use parent)

settings MqttDefaultPublishConfig

field qos: Literal[0, 1, 2] = 0: Default value for QoS if no other QoS value in the config entry is set

field retain: Annotated[bool] = False

Default value for retain if no other retain value in the config entry is set

Constraints:

strict = True

settings MqttTlsOptions

field insecure: bool | None = None: Enable/disable server hostname verification when using SSL/TLS.

field ca certificates: str | None = None: Path to Certificate Authority (CA) certificate file in PEM or DER format

field cert file: str | None = None: Path to PEM encoded client certificate file

field key file: str | None = None: Path to PEM encoded private keys file

field file password: str | None = None: Password to encrypt the cert file or the key file if needed

field certificate requirement: Optional[Literal['NONE', 'OPTIONAL', 'REQUIRED']] = None: Certificate requirement that the client imposes on the broker.

field tls version: Optional[Literal['SSLv23', 'TLS', 'TLS_CLIENT', 'TLS_SERVER', 'TLSv1', 'TLSv1_1', 'TLSv1_2']] = None: The version of the SSL/TLS protocol to be used.

field ciphers: str | None = None: Which encryption ciphers are allowable for the connection

devices

settings SmlDeviceConfig

Configuration for a sml device

field mqtt: OptionalMqttPublishConfig | None = None: Optional MQTT configuration for this meter.

field status: OptionalMqttPublishConfig = OptionalMqttPublishConfig(topic='status', full_topic=None, qos=None, retain=None): Optional MQTT status topic configuration for this meter

field skip: set[Annotated[str]] [Optional]: OBIS codes (HEX) of values that will not be published (optional)

field values: list[SmlValueConfig] = []: Configurations for each of the values (optional)

settings SmlValueConfig

field obis: Annotated[str] [Required]

Obis code for this value

Constraints:

strip_whitespace = True
to_lower = True
strict = True
pattern = [0-9a-fA-F]{12}

field mqtt: OptionalMqttPublishConfig | None = None: Mqtt config for this value (optional)

field operations: Annotated[list[Annotated[Union[Annotated[OnChangeFilter], Annotated[DeltaFilter], Annotated[HeartbeatAction], Annotated[RangeFilter], Annotated[RefreshAction], Annotated[ThrottleFilter], Annotated[Factor], Annotated[Offset], Annotated[Round], Annotated[NegativeOnEnergyMeterWorkaround], Annotated[Or], Annotated[Sequence], Annotated[VirtualMeter], Annotated[MaxValue], Annotated[MinValue], Annotated[MaxOfInterval], Annotated[MinOfInterval], Annotated[MeanOfInterval]]]]] = []

A sequence of operations that will be evaluated one after another. If one operation blocks this will return nothing.

Constraints:

min_length = 1

Command Line Interface

usage: -c [-h] [-c CONFIG] [-a]

SML to MQTT bridge

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Path to configuration file
  -a, --analyze         Process exactly one sml message, shows the values of
                        the message and what will be reported. Can also be set
                        by setting the environment variable "SML2MQTT_ANALYZE"
                        to an arbitrary value

Getting started

1. Installation

First install sml2mqtt e.g in a virtual environment.

2. Create default configuration

Run sml2mqtt with a path to a configuration file. A new default configuration file will be created.

logging:
  level: INFO         # Log level
  file: sml2mqtt.log  # Log file path (absolute or relative to config file) or stdout

mqtt:
  connection:
    identifier: sml2mqtt-ZqlFvhSBdDGvJ
    host: localhost
    port: 1883
    user: ''
    password: ''
  topic prefix: sml2mqtt
  defaults:
    qos: 0         # Default value for QOS if no other QOS value in the config entry is set
    retain: false  # Default value for retain if no other retain value in the config entry is set
  last will:
    topic: status   # Topic fragment for building this topic with the parent topic

general:
  Wh in kWh: true       # Automatically convert Wh to kWh
  republish after: 120  # Republish automatically after this time (if no other filter configured)

inputs:
- type: serial
  url: COM1   # Device path
  timeout: 3  # Seconds after which a timeout will be detected (default=3)
- type: serial
  url: /dev/ttyS0   # Device path
  timeout: 3        # Seconds after which a timeout will be detected (default=3)

devices:
  # Device configuration by reported id
  device_id_hex:

    mqtt:                           # Optional MQTT configuration for this meter.
      topic: DEVICE_BASE_TOPIC      # Topic fragment for building this topic with the parent topic

    status:                         # Optional MQTT status topic configuration for this meter
      topic: status                 # Topic fragment for building this topic with the parent topic

    skip:                           # OBIS codes (HEX) of values that will not be published (optional)
    - '00112233445566'

    # Configurations for each of the values (optional)
    values:

    - obis: '00112233445566'        # Obis code for this value
      mqtt:                         # Mqtt config for this value (optional)
        topic: OBIS_VALUE_TOPIC     # Topic fragment for building this topic with the topic prefix
      # A sequence of operations that will be evaluated one after another.
      # If one operation blocks nothing will be reported for this frame
      operations:
      - negative on energy meter status: true   # Make value negative based on an energy meter status. Set to "true" to enable or to "false" to disable workaround. If the default obis code for the energy meter is wrong set to the appropriate meter obis code instead
      - factor: 3               # Factor with which the value gets multiplied
      - offset: 100             # Offset that gets added on the value
      - round: 2                # Round to the specified digits
      - refresh action: 300     # Republish value every 300s

3. Edit inputs and mqtt

Edit the configuration file and configure the appropriate inputs for serial or http (e.g. for tibber) and edit the mqtt settings.

 logging:
   level: INFO         # Log level
   file: sml2mqtt.log  # Log file path (absolute or relative to config file) or stdout

 mqtt:
   connection:
     identifier: sml2mqtt-ZqlFvhSBdDGvJ
     host: localhost
     port: 1883
     user: ''
     password: ''
   topic prefix: sml2mqtt
   defaults:
     qos: 0         # Default value for QOS if no other QOS value in the config entry is set
     retain: false  # Default value for retain if no other retain value in the config entry is set
   last will:
     topic: status   # Topic fragment for building this topic with the parent topic

 general:
   Wh in kWh: true       # Automatically convert Wh to kWh
   republish after: 120  # Republish automatically after this time (if no other filter configured)

 inputs:
 - type: serial
   url: COM1   # Device path
   timeout: 3  # Seconds after which a timeout will be detected (default=3)
 - type: serial
   url: /dev/ttyS0   # Device path
   timeout: 3        # Seconds after which a timeout will be detected (default=3)

 devices:
   # Device configuration by reported id
   device_id_hex:

     mqtt:                           # Optional MQTT configuration for this meter.
       topic: DEVICE_BASE_TOPIC      # Topic fragment for building this topic with the parent topic

     status:                         # Optional MQTT status topic configuration for this meter
       topic: status                 # Topic fragment for building this topic with the parent topic

     skip:                           # OBIS codes (HEX) of values that will not be published (optional)
     - '00112233445566'

     # Configurations for each of the values (optional)
     values:

     - obis: '00112233445566'        # Obis code for this value
       mqtt:                         # Mqtt config for this value (optional)
         topic: OBIS_VALUE_TOPIC     # Topic fragment for building this topic with the topic prefix
       # A sequence of operations that will be evaluated one after another.
       # If one operation blocks nothing will be reported for this frame
       operations:
       - negative on energy meter status: true   # Make value negative based on an energy meter status. Set to "true" to enable or to "false" to disable workaround. If the default obis code for the energy meter is wrong set to the appropriate meter obis code instead
       - factor: 3               # Factor with which the value gets multiplied
       - offset: 100             # Offset that gets added on the value
       - round: 2                # Round to the specified digits
       - refresh action: 300     # Republish value every 300s

4. Run with analyze

Now run sml2mqtt with the path to the configuration file and the --analyze option. (see command line interface). This will process one sml frame from the meter and report the output. It’s a convenient way to check what values will be reported. It will also show how the configuration changes the reported values when you add an operation.

Check if the meter reports the serial number unter obis 0100000009ff. Example output for the meter data:

 SmlMessage
     transaction_id: 17c77d6b
     group_no      : 0
     abort_on_error: 0
     message_body <SmlOpenResponse>
         codepage   : None
         client_id  : None
         req_file_id: 07ed29cd
         server_id  : 11111111111111111111
         ref_time   : None
         sml_version: None
     crc16         : 25375
 SmlMessage
     transaction_id: 17c77d6c
     group_no      : 0
     abort_on_error: 0
     message_body <SmlGetListResponse>
         client_id       : None
         sever_id        : 11111111111111111111
         list_name       : 0100620affff
         act_sensor_time : 226361515
         val_list: list
             <SmlListEntry>
                 obis           : 8181c78203ff
                 status         : None
                 val_time       : None
                 unit           : None
                 scaler         : None
                 value          : ISK
                 value_signature: None
                 -> (Hersteller-Identifikation)
             <SmlListEntry>
                 obis           : 0100000009ff
                 status         : None
                 val_time       : None
                 unit           : None
                 scaler         : None
                 value          : 11111111111111111111
                 value_signature: None
                 -> (Geräteeinzelidentifikation)
             <SmlListEntry>
                 obis           : 0100010800ff
                 status         : 386
                 val_time       : None
                 unit           : 30
                 scaler         : -1
                 value          : 123456789
                 value_signature: None
                 -> 12345678.9Wh (Zählerstand Total)
             <SmlListEntry>
                 obis           : 0100010801ff
                 status         : None
                 val_time       : None
                 unit           : 30
                 scaler         : -1
                 value          : 123456789
                 value_signature: None
                 -> 12345678.9Wh (Zählerstand Tarif 1)
             <SmlListEntry>
                 obis           : 0100010802ff
                 status         : None
                 val_time       : None
                 unit           : 30
                 scaler         : -1
                 value          : 0
                 value_signature: None
                 -> 0.0Wh (Zählerstand Tarif 2)
             <SmlListEntry>
                 obis           : 0100100700ff
                 status         : None
                 val_time       : None
                 unit           : 27
                 scaler         : 0
                 value          : 555
                 value_signature: None
                 -> 555W (aktuelle Wirkleistung)
             <SmlListEntry>
                 obis           : 8181c78205ff
                 status         : None
                 val_time       : None
                 unit           : None
                 scaler         : None
                 value          : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                 value_signature: None
                 -> (Öffentlicher Schlüssel)
         list_signature  : None
         act_gateway_time: None
     crc16         : 22117
 SmlMessage
     transaction_id: 17c77d6d
     group_no      : 0
     abort_on_error: 0
     message_body <SmlCloseResponse>
         global_signature: None
     crc16         : 56696

If the meter does not report 0100000009ff it’s possible to configure another number (of even multiple ones) for configuration matching (see general under config).

5. Edit device settings

Replace device_id_hex in the dummy configuration with the reported number (here 11111111111111111111). Edit the mqtt settings or remove them to use the default. Add the obis code of values that should not be reported to the skip section. Run the analyze command again to see how the reported values change.

 # ...

 inputs:
 - type: serial
   url: COM1   # Device path
   timeout: 3  # Seconds after which a timeout will be detected (default=3)
 - type: serial
   url: /dev/ttyS0   # Device path
   timeout: 3        # Seconds after which a timeout will be detected (default=3)

 devices:
   # Device configuration by reported id
   '11111111111111111111':

     mqtt:                           # Optional MQTT configuration for this meter.
       topic: meter_light            # Topic fragment for building this topic with the parent topic

     status:                         # Optional MQTT status topic configuration for this meter
       topic: status                 # Topic fragment for building this topic with the parent topic

     skip:                           # OBIS codes (HEX) of values that will not be published (optional)
     - '8181c78205ff'

     # Configurations for each of the values (optional)
     values:

     - obis: '00112233445566'        # Obis code for this value
       mqtt:                         # Mqtt config for this value (optional)
         topic: OBIS_VALUE_TOPIC     # Topic fragment for building this topic with the topic prefix
       # A sequence of operations that will be evaluated one after another.
       # If one operation blocks nothing will be reported for this frame
       operations:
       - negative on energy meter status: true   # Make value negative based on an energy meter status. Set to "true" to enable or to "false" to disable workaround. If the default obis code for the energy meter is wrong set to the appropriate meter obis code instead
       - factor: 3               # Factor with which the value gets multiplied
       - offset: 100             # Offset that gets added on the value
       - round: 2                # Round to the specified digits
       - refresh action: 300     # Republish value every 300s

6. Edit value settings

It’s possible to further configure how values will be reported. For every value there are multiple operations that can be applied. Each sml value can also be processed multiple times.

Run the analyze command again to see how the reported values change.

 # ...

 inputs:
 - type: serial
   url: COM1   # Device path
   timeout: 3  # Seconds after which a timeout will be detected (default=3)
 - type: serial
   url: /dev/ttyS0   # Device path
   timeout: 3        # Seconds after which a timeout will be detected (default=3)

 devices:
   # Device configuration by reported id
   '11111111111111111111':

     mqtt:                           # Optional MQTT configuration for this meter.
       topic: meter_light            # Topic fragment for building this topic with the parent topic

     status:                         # Optional MQTT status topic configuration for this meter
       topic: status                 # Topic fragment for building this topic with the parent topic

     skip:                           # OBIS codes (HEX) of values that will not be published (optional)
     - '8181c78205ff'

     # Configurations for each of the values (optional)
     values:

     -  obis: '0100010800ff'    # Obis code for the energy value
        mqtt:
          topic: energy_today
        operations:
        - type: meter           # A virtual meter
          start now: true       # Start immediately
          reset times:          # Reset at midnight
            - 00:00
        - round: 1
        - type: change filter      # Only report on changes
        - refresh action: 01:00    # ... but refresh every hour

     -  obis: '0100010800ff'  # Obis code for the energy value
        mqtt:
          topic: energy_total
        operations:
        - round: 1
        - type: change filter
        - refresh action: 01:00

     -  obis: '0100100700ff'  # Obis code for the power value
        mqtt:
          topic: power
        operations:
        - type: delta filter
          min: 10
          min %: 5
        - refresh action: 01:00

Output from the analyze command that shows what values will be reported

...
sml2mqtt/meter_light/energy_today: 0 (QOS: 0, retain: False)
sml2mqtt/meter_light/energy_total: 12345.7 (QOS: 0, retain: False)
sml2mqtt/meter_light/power: 555 (QOS: 0, retain: False)
sml2mqtt/meter_light/status: OK (QOS: 0, retain: False)
...

Operations

It’s possible to define operations which are used to process the received value

Filters

Change Filter

settings OnChangeFilter

A filter which lets the value only pass when it’s different from the value that was passed the last time

field type: Literal['change filter'] [Required]: Filter which passes only changes

Example

type: change filter

Range filter

settings RangeFilter

Filters or limits to values that are in a certain range

field min: float | None = None: minimum value that will pass

field max: float | None = None: maximum value that will pass

field limit: bool = False: Instead of ignoring the values they will be limited to min/max

Example

type: range filter
min: 0

Delta Filter

settings DeltaFilter

A filter which lets the value only pass if the incoming value is different enough from value that was passed the last time. The delta can an absolute value or as a percentage. If multiple deltas are specified they are all checked.

field type: Literal['delta filter'] [Required]

field min: StrictInt | StrictFloat | None = None

field min %: StrictInt | StrictFloat | None = None

Example

type: delta filter
min: 5
min %: 10

type: delta filter
min: 5

type: delta filter
min %: 10

Throttle Filter

settings ThrottleFilter

Filter which only lets one value pass in the defined period. If the last passed value is not at least period old any new value will not be forwarded.

field throttle filter: DurationType [Required]: Throttle period

Example

throttle filter: 60

Actions

Refresh Action

settings RefreshAction

Action which lets every value pass. When no value is received (e.g. because an earlier filter blocks) this action will produce the last received value every interval.

field refresh action: DurationType [Required]: Refresh interval

Example

refresh action: 01:30:00

Heartbeat Action

settings HeartbeatAction

Action which lets a value pass periodically every specified interval. When no value is received (e.g. because an earlier filter blocks) this action will produce the last received value every interval.

field heartbeat action: DurationType [Required]: Interval

Example

heartbeat action: 30

Math

Factor

settings Factor

field factor: Number [Required]: Factor with which the value gets multiplied

Example

factor: -1

Offset

settings Offset

field offset: Number [Required]: Offset that gets added on the value

Example

offset: 10

Round

settings Round

field round: int [Required]

Round to the specified digits

Constraints:

ge = 0
le = 6

Example

round: 2

Workarounds

Negative On Energy Meter Status

settings NegativeOnEnergyMeterWorkaround

Make value negative based on an energy meter status.

field negative on energy meter status: StrictBool | ObisHex [Required]: Set to “true” to enable or to “false” to disable workaround. If the default obis code for the energy meter is wrong set to the appropriate meter obis code instead

Example

negative on energy meter status: true

Date time based

Virtual Meter

settings VirtualMeter

A virtual meter. It will output the difference from the last reset

field start now: bool [Required]: Immediately start instead of starting after the next reset

field reset times: list[time] = []: Time(s) of day when a reset will occur

field reset days: list[DayOfMonth | DayOfWeekStr] = []: Days of month or weekdays where the time(s) will be checked

Example

type: meter
start now: False
reset times:
  - 02:00
reset days:
  - 1
  - monday

Max Value

settings MaxValue

Maximum value since last reset

field start now: bool [Required]: Immediately start instead of starting after the next reset

field reset times: list[time] = []: Time(s) of day when a reset will occur

field reset days: list[DayOfMonth | DayOfWeekStr] = []: Days of month or weekdays where the time(s) will be checked

Example

type: max value
start now: True
reset times:
  - 02:00

Min Value

settings MinValue

Minimum value since last reset

field start now: bool [Required]: Immediately start instead of starting after the next reset

field reset times: list[time] = []: Time(s) of day when a reset will occur

field reset days: list[DayOfMonth | DayOfWeekStr] = []: Days of month or weekdays where the time(s) will be checked

Example

type: min value
start now: True
reset times:
  - 02:00

Time series

Max Value

settings MaxOfInterval

Maximum value in a sliding interval

field interval: timedelta [Required]: Interval duration

field wait for data: bool [Required]: Only produce a value when data for the whole interval is available

field reset after value: bool = False: Clear all data as soon as a value has been produced

Example

type: max interval
interval: 3600
wait for data: False

Min Value

settings MinOfInterval

Minimum value in a sliding interval

field interval: timedelta [Required]: Interval duration

field wait for data: bool [Required]: Only produce a value when data for the whole interval is available

field reset after value: bool = False: Clear all data as soon as a value has been produced

Example

type: min interval
interval: 3600
wait for data: False

Mean Value

settings MeanOfInterval

Weighted mean in a sliding interval

field interval: timedelta [Required]: Interval duration

field wait for data: bool [Required]: Only produce a value when data for the whole interval is available

field reset after value: bool = False: Clear all data as soon as a value has been produced

Example

type: mean interval
interval: 3600
wait for data: False

Operations

Or

settings Or

A sequence of operations that will be evaluated one after another. The first value that gets returned by an operation will be used.

field or: OperationsListType [Required]

Constraints:

min_length = 1

Example

or:
  - type: change filter
  - heartbeat action: 60

Sequence

settings Sequence

A sequence of operations that will be evaluated one after another. If one operation blocks this will return nothing.

field sequence: OperationsListType [Required]

Constraints:

min_length = 1

Example

sequence:
  - factor: 0.1
  - offset: -50

Examples

These are some examples for sml value configurations

Energy consumption today

This will report the power consumption of today. The first reported value every day will be 0 and then it will increase for every day.

obis: '0100010800ff'    # Obis code for the energy meter
mqtt:
  topic: energy_today   # MQTT topic for the meter
operations:
- type: meter
  start now: true       # Start immediately
  reset times:          # Reset at midnight
    - 00:00
- round: 1
- type: change filter      # Only report on changes
- refresh action: 01:00    # ... but refresh every hour

Downsample current power

This will report a power value every max every 30s. The reported value will be the weighted mean value of the last 30s.

obis: '0100100700ff'    # Obis code for the energy meter
mqtt:
  topic: power   # MQTT topic for the meter
operations:
- type: mean interval     # Calculate weighted mean over 30s
  interval: 30
  wait for data: False
- throttle filter: 30     # Let a value pass every 30s
- round: 0                # Round the mean value to the full number
- type: delta filter      # Only report when the value changes at least 10W or 5%
  min: 10
  min %: 5
- refresh action: 01:00   # ... but refresh every hour

Welcome to sml2mqtt’s documentation!

Installation

Virtual environment

Installation

Upgrading

Autostart after reboot

Docker

Configuration

Example

Example input Tibber bridge

Example mqtt config

Configuration Reference

logging

general

inputs

mqtt

devices

Command Line Interface

Getting started

1. Installation

2. Create default configuration

3. Edit inputs and mqtt

4. Run with analyze

5. Edit device settings

6. Edit value settings

Operations

Filters

Change Filter

Example

Range filter

Example

Delta Filter

Example

Throttle Filter

Example

Actions

Refresh Action

Example

Heartbeat Action

Example

Math

Factor

Example

Offset

Example

Round

Example

Workarounds

Negative On Energy Meter Status

Example

Date time based

Virtual Meter

Example

Max Value

Example

Min Value

Example

Time series

Max Value

Example

Min Value

Example

Mean Value

Example

Operations

Or

Example

Sequence

Example

Examples

Energy consumption today

Downsample current power

Indices and tables