sml2mqtt

https://sml2mqtt.readthedocs.io/en/latest/
Admin
sml2mqtt is an asyncio application that reads Smart Message Language (SML) streams from energy...
Tokens:13,095
Snippets:138
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create and Navigate to Installation Directory

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to prepare the filesystem for the virtual environment.

```bash
cd /opt/sml2mqtt
```

```bash
mkdir /opt/sml2mqtt
```

--------------------------------

### YAML Configuration Example

Source: https://sml2mqtt.readthedocs.io/en/latest/configuration.html

A complete example of a configuration file including logging, MQTT, general settings, input definitions, and device-specific value processing.

```yaml
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
```

--------------------------------

### Install and Run sml2mqtt

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to update dependencies, install the package, and execute the application.

```bash
python3 -m pip install --upgrade pip setuptools
```

```bash
python3 -m pip install sml2mqtt
```

```bash
sml2mqtt --config PATH_TO_CONFIGURATION_FILE
```

--------------------------------

### Configure HTTP source input

Source: https://sml2mqtt.readthedocs.io/en/latest/configuration.html

Minimal configuration example for an HTTP data source.

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

--------------------------------

### Configure MQTT topics

Source: https://sml2mqtt.readthedocs.io/en/latest/configuration.html

Example configuration for MQTT topics, supporting full paths or fragments.

```yaml
full topic: my/full/topic
qos: 1
```

--------------------------------

### Configure serial source input

Source: https://sml2mqtt.readthedocs.io/en/latest/configuration.html

Minimal configuration example for a serial data source.

```yaml
type: serial
url: COM3
```

--------------------------------

### Docker Lifecycle Management

Source: https://sml2mqtt.readthedocs.io/en/latest/installation.html

Commands to start, stop, and update the sml2mqtt Docker container.

```bash
docker compose up -d sml2mqtt
```

```bash
docker compose run -e SML2MQTT_ANALYZE=1 --rm sml2mqtt
```

```bash
docker compose down
```

```bash
docker compose pull
```

--------------------------------

### Docker Compose Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/installation.html

Example compose.yml file for running sml2mqtt in a Docker container.

```yaml
---
services:
  sml2mqtt:
    image: spacemanspiff2007/sml2mqtt
    container_name: sml2mqtt
    init: true
    restart: unless-stopped
    # drop root privileges and permit access to serial device
    user: "1000:dialout"
    volumes:
      # Subdirectory ./data contains config.yml and log files
      - "./data:/sml2mqtt"
    devices:
      #
      # Add your serial device here.
      #
      # The `/dev/serial/by-id/` path is recommended because it is stable.
      #
      # It is possible to simply use
      #   `/dev/ttyUSB0`
      # instead, although this might change over time
      # when multiple devices are connected.
      - /dev/serial/by-id/<ID-OF-SERIAL-DEVICE-TO-METER>
```

--------------------------------

### Manage Systemd Service

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to enable, start, stop, and check the status of the service.

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

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

--------------------------------

### Analyze Command Output

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/getting_started.rst.txt

Example output from the analyze command showing the resulting MQTT topics and values.

```text
...
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)
...
```

--------------------------------

### Define Device Inputs and Value Processing

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/getting_started.rst.txt

Full configuration example showing serial input definitions and complex value processing pipelines for specific devices.

```yaml
# ...

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
```

--------------------------------

### Energy Consumption Today Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Example configuration for reporting daily energy consumption with meter resets.

```yaml
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
```

--------------------------------

### Configure Tibber bridge input

Source: https://sml2mqtt.readthedocs.io/en/latest/configuration.html

Example configuration for polling data from a Tibber bridge via HTTP.

```yaml
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"
```

--------------------------------

### Downsample Current Power Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Example configuration for downsampling power values using mean intervals and filters.

```yaml
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
```

--------------------------------

### Analyze SML meter data output

Source: https://sml2mqtt.readthedocs.io/en/latest/getting_started.html

Example output generated when running sml2mqtt with the analyze flag to inspect meter data structures.

```text
 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
```

--------------------------------

### Initialize Virtual Environment

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Create and enter the virtual environment directory.

```bash
python3 -m venv venv
```

```bash
cd venv
```

--------------------------------

### View CLI help and options

Source: https://sml2mqtt.readthedocs.io/en/latest/cli.html

Displays the usage instructions and available command line arguments for the SML to MQTT bridge.

```text
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
```

--------------------------------

### Configure Systemd Autostart

Source: https://sml2mqtt.readthedocs.io/en/latest/installation.html

Commands and service file content to manage sml2mqtt as a systemd service.

```bash
nano /etc/systemd/system/sml2mqtt.service
```

```ini
[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
```

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

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

--------------------------------

### Create and Activate Virtual Environment

Source: https://sml2mqtt.readthedocs.io/en/latest/installation.html

Commands to initialize a virtual environment and activate it based on the operating system.

```bash
python3 -m venv venv
```

```bash
cd venv
```

```bash
source bin/activate
```

```bash
Scripts\activate
```

--------------------------------

### Display help information via CLI

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/cli.rst.txt

Invokes the command line argument parser with the help flag to display available options.

```python
import sml2mqtt.__args__
sml2mqtt.__args__.get_command_line_args(['-h'])
```

--------------------------------

### Configure sml2mqtt settings

Source: https://sml2mqtt.readthedocs.io/en/latest/getting_started.html

Configuration file template for defining logging, MQTT broker connection, input sources, and device-specific value processing.

```yaml
 1 logging:
 2   level: INFO         # Log level
 3   file: sml2mqtt.log  # Log file path (absolute or relative to config file) or stdout
 4
 5 mqtt:
 6   connection:
 7     identifier: sml2mqtt-ZqlFvhSBdDGvJ
 8     host: localhost
 9     port: 1883
10     user: ''
11     password: ''
12   topic prefix: sml2mqtt
13   defaults:
14     qos: 0         # Default value for QOS if no other QOS value in the config entry is set
15     retain: false  # Default value for retain if no other retain value in the config entry is set
16   last will:
17     topic: status   # Topic fragment for building this topic with the parent topic
18
19 general:
20   Wh in kWh: true       # Automatically convert Wh to kWh
21   republish after: 120  # Republish automatically after this time (if no other filter configured)
22
23 inputs:
24 - type: serial
25   url: COM1   # Device path
26   timeout: 3  # Seconds after which a timeout will be detected (default=3)
27 - type: serial
28   url: /dev/ttyS0   # Device path
29   timeout: 3        # Seconds after which a timeout will be detected (default=3)
30
31 devices:
32   # Device configuration by reported id
33   device_id_hex:
34
35     mqtt:                           # Optional MQTT configuration for this meter.
36       topic: DEVICE_BASE_TOPIC      # Topic fragment for building this topic with the parent topic
37
38     status:                         # Optional MQTT status topic configuration for this meter
39       topic: status                 # Topic fragment for building this topic with the parent topic
40
41     skip:                           # OBIS codes (HEX) of values that will not be published (optional)
42     - '00112233445566'
43
44     # Configurations for each of the values (optional)
45     values:
46
47     - obis: '00112233445566'        # Obis code for this value
48       mqtt:                         # Mqtt config for this value (optional)
49         topic: OBIS_VALUE_TOPIC     # Topic fragment for building this topic with the topic prefix
50       # A sequence of operations that will be evaluated one after another.
51       # If one operation blocks nothing will be reported for this frame
52       operations:
53       - 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
54       - factor: 3               # Factor with which the value gets multiplied
55       - offset: 100             # Offset that gets added on the value
56       - round: 2                # Round to the specified digits
57       - refresh action: 300     # Republish value every 300s
```

--------------------------------

### Configure openHAB Things

Source: https://sml2mqtt.readthedocs.io/en/latest/smart_home_systems.html

Defines the MQTT broker bridge and channels for power and energy sensors in an openHAB .things file.

```text
Thing mqtt:topic:stromzaehler "Stromzähler" (mqtt:broker:localhost) [
        availabilityTopic="stromzaehler/status", payloadAvailable="ONLINE", payloadNotAvailable="OFFLINE"
    ]
{
    Channels:

    Type number : leistung          [stateTopic="stromzaehler/leistung",   unit="W"]
    Type number : energie           [stateTopic="stromzaehler/energie",   unit="kWh"]
    ...


    Type string : status            [stateTopic="stromzaehler/status"]
}
```

--------------------------------

### Configure device settings in YAML

Source: https://sml2mqtt.readthedocs.io/en/latest/getting_started.html

Define serial inputs, MQTT topics, and value-specific operations in the configuration file. Ensure the device ID matches the reported ID from the analyze command.

```yaml
 1 # ...
 2
 3 inputs:
 4 - type: serial
 5   url: COM1   # Device path
 6   timeout: 3  # Seconds after which a timeout will be detected (default=3)
 7 - type: serial
 8   url: /dev/ttyS0   # Device path
 9   timeout: 3        # Seconds after which a timeout will be detected (default=3)
10
11 devices:
12   # Device configuration by reported id
13   '11111111111111111111':
14
15     mqtt:                           # Optional MQTT configuration for this meter.
16       topic: meter_light            # Topic fragment for building this topic with the parent topic
17
18     status:                         # Optional MQTT status topic configuration for this meter
19       topic: status                 # Topic fragment for building this topic with the parent topic
20
21     skip:                           # OBIS codes (HEX) of values that will not be published (optional)
22     - '8181c78205ff'
23
24     # Configurations for each of the values (optional)
25     values:
26
27     - obis: '00112233445566'        # Obis code for this value
28       mqtt:                         # Mqtt config for this value (optional)
29         topic: OBIS_VALUE_TOPIC     # Topic fragment for building this topic with the topic prefix
30       # A sequence of operations that will be evaluated one after another.
31       # If one operation blocks nothing will be reported for this frame
32       operations:
33       - 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
34       - factor: 3               # Factor with which the value gets multiplied
35       - offset: 100             # Offset that gets added on the value
36       - round: 2                # Round to the specified digits
37       - refresh action: 300     # Republish value every 300s
```

--------------------------------

### Activate Virtual Environment

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Platform-specific commands to activate the environment.

```bash
source bin/activate
```

```bash
Scripts\activate
```

--------------------------------

### Configure Virtual Meter

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Sets up a virtual meter with reset times and days.

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

--------------------------------

### Upgrade sml2mqtt in Virtual Environment

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Command to upgrade the package within an active environment.

```bash
python3 -m pip install --upgrade sml2mqtt
```

--------------------------------

### Configure openHAB Items

Source: https://sml2mqtt.readthedocs.io/en/latest/smart_home_systems.html

Maps openHAB channels to items for display and persistence in an openHAB .items file.

```text
String          Zuhause_Status     "Status [%s]"         {channel="mqtt:topic:stromzaehler:status"}
Number:Power    Zuhause_Leistung   "Leistung [%d W]"     {channel="mqtt:topic:stromzaehler:leistung",  unit="W", expire="5m"}
Number:Energy   Zuhause_Energie    "Energie [%.2f kWh]"  {channel="mqtt:topic:stromzaehler:leistung",  unit="kWh"}
```

--------------------------------

### Default YAML configuration structure

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/getting_started.rst.txt

The default configuration file defines logging, MQTT connection settings, general processing options, and input device definitions.

```yaml
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
```

```yaml
    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
```

--------------------------------

### Configure Systemd Service

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Service file definition for managing sml2mqtt as a background process.

```ini
nano /etc/systemd/system/sml2mqtt.service
```

```ini
[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
```

--------------------------------

### Configure device settings in YAML

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/getting_started.rst.txt

Define serial input sources and device-specific configurations using the YAML format. Use the emphasized lines to identify where to specify device IDs and connection parameters.

```yaml
# ...

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':
```

--------------------------------

### Configure Home Assistant MQTT Sensors

Source: https://sml2mqtt.readthedocs.io/en/latest/smart_home_systems.html

Defines MQTT sensors for energy and power in the Home Assistant configuration file.

```yaml
mqtt:
  sensor:
    - name: "sml2mqtt_energy_total"
      unique_id: f955b69a-828b-4cad-bafd-7563a909153e
      state_topic: "sml2mqtt/meter1/energy_total"
      icon: mdi:transmission-tower
      unit_of_measurement: kWh
      state_class: total
      device_class: energy
      availability:
        topic: "sml2mqtt/status"
        payload_available: "ONLINE"
        payload_not_available: "OFFLINE"

    - name: "sml2mqtt_momentary_power"
      unique_id: 6ddc1f63-bd73-4d9b-86a1-3e7dfeccee1e
      state_topic: "sml2mqtt/meter1/momentary_power"
      unit_of_measurement: W
      state_class: measurement
      device_class: power
      availability:
        topic: "sml2mqtt/status"
        payload_available: "ONLINE"
        payload_not_available: "OFFLINE"

    ...
```

--------------------------------

### Configure sml2mqtt device and value settings

Source: https://sml2mqtt.readthedocs.io/en/latest/getting_started.html

Defines serial inputs, MQTT topics, and value-specific operations such as virtual meters, rounding, and change filters.

```yaml
 1 # ...
 2
 3 inputs:
 4 - type: serial
 5   url: COM1   # Device path
 6   timeout: 3  # Seconds after which a timeout will be detected (default=3)
 7 - type: serial
 8   url: /dev/ttyS0   # Device path
 9   timeout: 3        # Seconds after which a timeout will be detected (default=3)
10
11 devices:
12   # Device configuration by reported id
13   '11111111111111111111':
14
15     mqtt:                           # Optional MQTT configuration for this meter.
16       topic: meter_light            # Topic fragment for building this topic with the parent topic
17
18     status:                         # Optional MQTT status topic configuration for this meter
19       topic: status                 # Topic fragment for building this topic with the parent topic
20
21     skip:                           # OBIS codes (HEX) of values that will not be published (optional)
22     - '8181c78205ff'
23
24     # Configurations for each of the values (optional)
25     values:
26
27     -  obis: '0100010800ff'    # Obis code for the energy value
28        mqtt:
29          topic: energy_today
30        operations:
31        - type: meter           # A virtual meter
32          start now: true       # Start immediately
33          reset times:          # Reset at midnight
34            - 00:00
35        - round: 1
36        - type: change filter      # Only report on changes
37        - refresh action: 01:00    # ... but refresh every hour
38
39     -  obis: '0100010800ff'  # Obis code for the energy value
40        mqtt:
41          topic: energy_total
42        operations:
43        - round: 1
44        - type: change filter
45        - refresh action: 01:00
46
47     -  obis: '0100100700ff'  # Obis code for the power value
48        mqtt:
49          topic: power
50        operations:
51        - type: delta filter
52          min: 10
53          min %: 5
54        - refresh action: 01:00
```

--------------------------------

### Configure Min Value

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Tracks the minimum value with a reset time.

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

--------------------------------

### Configure Negative On Energy Meter Status Workaround

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Enables the workaround for negative energy meter status.

```yaml
negative on energy meter status: true
```

--------------------------------

### Docker Compose Operations

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to manage the application lifecycle using Docker.

```bash
docker compose up -d sml2mqtt
```

```bash
docker compose run -e SML2MQTT_ANALYZE=1 --rm sml2mqtt
```

```bash
docker compose down
```

```bash
docker compose pull
```

```bash
docker compose up -d
```

--------------------------------

### Configure sml2mqtt YAML

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/getting_started.rst.txt

Define status topics, filter OBIS codes, and apply data transformations like scaling, rounding, and periodic refreshing.

```yaml
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
```

--------------------------------

### Min Interval Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines a minimum interval operation in YAML.

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

--------------------------------

### Configure Heartbeat Action

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Sets the heartbeat interval in seconds.

```yaml
heartbeat action: 30
```

--------------------------------

### Configure Throttle Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Sets a throttle interval in seconds.

```yaml
throttle filter: 60
```

--------------------------------

### Configure Max Value

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Tracks the maximum value with a reset time.

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

--------------------------------

### Configure Value Operations in YAML

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/getting_started.rst.txt

Defines MQTT topics and a sequence of operations for processing SML values, such as applying factors, offsets, and rounding.

```yaml
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
```

--------------------------------

### Configure Offset Math

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Applies an additive offset to the value.

```yaml
offset: 10
```

--------------------------------

### Sequence Operation Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines a sequence of operations in YAML.

```yaml
sequence:
  - factor: 0.1
  - offset: -50
```

--------------------------------

### Configure Factor Math

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Applies a multiplication factor to the value.

```yaml
factor: -1
```

--------------------------------

### Configure Refresh Action

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Sets the refresh interval for the action.

```yaml
refresh action: 01:30:00
```

--------------------------------

### Configure Change Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines a filter that triggers on value changes.

```yaml
type: change filter
```

--------------------------------

### Mean Interval Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines a mean interval operation in YAML.

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

--------------------------------

### Max Interval Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines a maximum interval operation in YAML.

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

--------------------------------

### Or Operation Configuration

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines an OR logical operation in YAML.

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

--------------------------------

### Configure Range Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines a filter with a minimum value constraint.

```yaml
type: range filter
min: 0
```

--------------------------------

### Offset

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Adds an offset to the input value.

```APIDOC
## Offset

### Description
Adds an offset to the value.

### Parameters
- **offset** (Number) - Required - Offset that gets added on the value

### Example
```
offset: 10
```
```

--------------------------------

### Configure Round To Multiple Math

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Rounds the value to the nearest multiple.

```yaml
type: round to multiple
value: 20
round: down
```

--------------------------------

### Configure Round Math

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Rounds the value to the specified number of decimal places.

```yaml
round: 2
```

--------------------------------

### Configure Delta Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/_sources/operations.rst.txt

Defines filters based on absolute or percentage changes.

```yaml
type: delta filter
min: 5
min %: 10
```

```yaml
type: delta filter
min: 5
```

```yaml
type: delta filter
min %: 10
```

--------------------------------

### Refresh Action

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

An action that lets every value pass. If no value is received, it produces the last received value every specified interval.

```APIDOC
## Refresh Action

### Description
Lets every value pass. When no value is received, this action produces the last received value every interval.

### Parameters
- **refresh action** (DurationType) - Required - Refresh interval

### Example
```
refresh action: 01:30:00
```
```

--------------------------------

### Heartbeat Action

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

An action that lets a value pass periodically every specified interval.

```APIDOC
## Heartbeat Action

### Description
Lets a value pass periodically every specified interval. When no value is received, this action produces the last received value every interval.

### Parameters
- **heartbeat action** (DurationType) - Required - Interval

### Example
```
heartbeat action: 30
```
```

--------------------------------

### Factor

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Multiplies the input value by a specified factor.

```APIDOC
## Factor

### Description
Multiplies the value by the specified factor.

### Parameters
- **factor** (Number) - Required - Factor with which the value gets multiplied

### Example
```
factor: -1
```
```

--------------------------------

### Round To Multiple

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Rounds the value to the nearest multiple of a given value.

```APIDOC
## Round To Multiple

### Description
Rounds to the multiple of a given value.

### Parameters
- **type** (Literal['round to multiple']) - Required
- **value** (int) - Required - Round to the multiple of the given value
- **round** (Literal['up', 'down', 'nearest']) - Required - Round up, down or to the nearest multiple

### Example
```
type: round to multiple
value: 20
round: down
```
```

--------------------------------

### Throttle Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Limits the frequency of value passing based on a defined time period.

```APIDOC
## Throttle Filter

### Description
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.

### Parameters
- **throttle filter** (DurationType) - Required - Throttle period.

### Example
```
throttle filter: 60
```
```

--------------------------------

### Range Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Filters or limits values to a specific range.

```APIDOC
## Range Filter

### Description
Filters or limits values to those within a certain range.

### Parameters
- **min** (float) - Optional - Minimum value that will pass.
- **max** (float) - Optional - Maximum value that will pass.
- **limit** (bool) - Optional - If true, values are limited to min/max instead of being ignored.

### Example
```
type: range filter
min: 0
```
```

--------------------------------

### Round

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Rounds the value to a specified number of digits.

```APIDOC
## Round

### Description
Round to the specified digits, negative for tens.

### Parameters
- **round** (int) - Required - Round to the specified digits (Constraints: -4 to 6)

### Example
```
round: 2
```
```

--------------------------------

### Change Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

A filter that only allows a value to pass if it is different from the previously passed value.

```APIDOC
## Change Filter

### Description
A filter which lets the value only pass when it is different from the value that was passed the last time.

### Parameters
- **type** (Literal['change filter']) - Required - Filter type identifier.

### Example
```
type: change filter
```
```

--------------------------------

### Delta Filter

Source: https://sml2mqtt.readthedocs.io/en/latest/operations.html

Allows values to pass if they differ from the last passed value by a specified absolute amount or percentage.

```APIDOC
## Delta Filter

### Description
A filter which lets the value only pass if the incoming value is different enough from the value that was passed the last time. The delta can be an absolute value or a percentage.

### Parameters
- **type** (Literal['delta filter']) - Required - Filter type identifier.
- **min** (StrictInt | StrictFloat) - Optional - Absolute delta threshold.
- **min %** (StrictInt | StrictFloat) - Optional - Percentage delta threshold.

### Example
```
type: delta filter
min: 5
min %: 10
```
```
Tokens:
Raw