Configuration & CLI

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

Configuration

Configuration is done through config.yml The parent folder of the file can be specified with -c PATH or --config PATH. If nothing is specified the file config.yml is searched in the subdirectory sml2mqtt in

the current working directory
the venv directory
the user home

If the config 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)

mqtt:
  connection:
    client id: sml2mqtt
    host: localhost
    port: 1883
    user: ''
    password: ''
    tls: false
    tls insecure: false

  # MQTT default configuration
  # All other topics use these values if no other values for qos/retain are set
  # It's possible to override
  #  - topic        (fragment that is used to build the full mqtt topic)
  #  - full_topic   (will not build the topic from the fragments but rather use the configured value)
  #  - qos
  #  - retain
  # for each (!) mqtt-topic entry
  defaults:
    qos: 0
    retain: false
  topic prefix: sml2mqtt

  last will:
    topic: status

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

# Serial port configurations for the sml readers
ports:
- url: COM1
  timeout: 3
- url: /dev/ttyS0
  timeout: 3


devices:
  # Device configuration by OBIS value 0100000009ff or by url if the device does not report OBIS 0100000009ff
  11111111111111111111:
    mqtt:
      topic: DEVICE_TOPIC

    # OBIS IDs that will not be processed (optional)
    skip:
    - OBIS
    - values
    - to skip

    # Configuration how each OBIS value is reported. Create as many OBIS IDs (e.g. 0100010800ff as you like).
    # Each sub entry (mqtt, workarounds, transformations, filters) is optional and can be omitted
    values:

      OBIS:
        # Sub topic how this value is reported.
        mqtt:
          topic: OBIS

        # Workarounds allow the enabling workarounds (e.g. if the device has strange behaviour)
        # These are the available workarounds
        workarounds:
        - negative on energy meter status: true   # activate this workaround

        # Transformations allow mathematical calculations on the obis value
        # They are applied in order how they are defined
        transformations:
        - factor: 3     # multiply with factor
        - offset: 100   # add offset
        - round: 2      # round on two digits

        # Filters control how often a value is published over mqtt.
        # If one filter is true the value will be published
        filters:
        - diff: 10      # report if value difference is >= 10
        - perc: 10      # report if percentage change is >= 10%
        - every: 120    # report at least every 120 secs (overrides the value from general)

Example devices

One energy meter is connected to the serial port. The serial meter reports OBIS 0100000009ff as 11111111111111111111.

For this device

the mqtt topic fragment is set to light
the value 0100010801ff will not be published
The following values of the device are specially configured:
- Energy value (OBIS 0100010800ff)
  - Will be rounded to one digit
  - Will be published on change or at least every hour
  - The mqtt topic used is sml2mqtt/light/energy. (Built through topic prefix + device mqtt + value mqtt)
- Power value (OBIS 0100100700ff)
  - Will be rounded to one digit
  - Will be published if at least a 5% power change occurred or at least every 2 mins (default from general -> republish after)
  - The mqtt topic used is sml2mqtt/light/power

devices:
  11111111111111111111:
    mqtt:
      topic: light
    skip:
    - 0100010801ff
    values:
      0100010800ff:
        mqtt:
          topic: energy
        transformations:
        - round: 1
        filters:
        - every: 3600
      0100100700ff:
        mqtt:
          topic: power
        filters:
        - perc: 5

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 ports: List[PortSettings] = []

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

logging

settings LoggingSettings

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

field file: Path = 'sml2mqtt.log': Log file path (absolute or relative to config file)

set_log_level()

Return type:: int

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[StrictStr] = ['0100000009ff']: Additional OBIS fields for the serial number, default is 0100000009ff

ports

settings PortSettings

field url: ConstrainedStrValue [Required]

Device path

Constraints:

minLength = 1

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

field baudrate: int = 9600

field parity: str = 'None'

field stop bits: Union[StrictInt, StrictFloat] = 1

field byte size: int = 8

mqtt

settings MqttConfig

field connection: MqttConnection [Optional]

field topic prefix: ConstrainedStrValue = 'sml2mqtt'

Constraints:

minLength = 1

field defaults: MqttDefaultPublishConfig [Optional]

field last will: OptionalMqttPublishConfig [Optional]

settings MqttConnection

field client id: ConstrainedStrValue = 'sml2mqtt'

field host: ConstrainedStrValue = 'localhost'

field port: ConstrainedIntValue = 1883

Constraints:

exclusiveMinimum = 0

field user: ConstrainedStrValue = ''

field password: ConstrainedStrValue = ''

field tls: StrictBool = False

Constraints:

type = boolean

field tls insecure: StrictBool = False

Constraints:

type = boolean

settings OptionalMqttPublishConfig

field topic: ConstrainedStrValue = None

Topic fragment for building this topic with the parent topic

Constraints:

minLength = 1

field full topic: ConstrainedStrValue = None

Full topic - will ignore the parent topic parts

Constraints:

minLength = 1

field qos: ConstrainedIntValue = None

QoS for publishing this value (if set - otherwise use parent)

Constraints:

minimum = 0
maximum = 2

field retain: StrictBool = None

Retain for publishing this value (if set - otherwise use parent)

Constraints:

type = boolean

settings MqttDefaultPublishConfig

field qos: ConstrainedIntValue = 0

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

Constraints:

minimum = 0
maximum = 2

field retain: StrictBool = False

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

Constraints:

type = boolean

devices

settings SmlDeviceConfig

Configuration for a sml device

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

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

field skip: Optional[Set[StrictStr]] = None: OBIS codes (HEX) of values that will not be published (optional)

field values: Dict[StrictStr, SmlValueConfig] = {}: Special configurations for each of the values (optional)

settings SmlValueConfig

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

field workarounds: Optional[List[Dict[WorkaroundOptionEnum, Union[StrictBool, StrictInt, StrictFloat, StrictStr]]]] = None: Workarounds for the value (optional)

field transformations: Optional[List[Dict[TransformOptionEnum, Union[StrictInt, StrictFloat]]]] = None: Mathematical transformations for the value (optional)

field filters: Optional[List[Dict[FilterOptionEnum, Union[StrictInt, StrictFloat]]]] = None: Refresh options for the value (optional)

class WorkaroundOptionEnum(value): An enumeration.

class TransformOptionEnum(value)

An enumeration.

factor = 'factor': Use the value as a factor

offset = 'offset': Use the value as an offset

round = 'round': Round the result to the digits

class FilterOptionEnum(value)

An enumeration.

diff = 'diff': Report when difference is greater equal than the value

perc = 'perc': Report when percentual change is greater equal the value

every = 'every': Report every x seconds