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