.

docs/operations.rst

@@ -83,21 +83,21 @@ Example
     min %: 10
 
 
-Heartbeat Filter
+Throttle Filter
 --------------------------------------
 
-.. autopydantic_model:: HeartbeatFilter
+.. autopydantic_model:: ThrottleFilter
    :inherited-members: BaseModel
 
 
 Example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ..
-    YamlModel: HeartbeatFilter
+    YamlModel: ThrottleFilter
 
 .. code-block:: yaml
 
-    heartbeat filter: 60
+    throttle filter: 60
 
 
 Actions
@@ -121,21 +121,21 @@ Example
     refresh action: 01:30:00
 
 
-Throttle Action
+Heartbeat Action
 --------------------------------------
 
-.. autopydantic_model:: ThrottleAction
+.. autopydantic_model:: HeartbeatAction
    :inherited-members: BaseModel
 
 
 Example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ..
-    YamlModel: ThrottleAction
+    YamlModel: HeartbeatAction
 
 .. code-block:: yaml
 
-    throttle action: 30
+    heartbeat action: 30
 
 Math
 ======================================
@@ -366,7 +366,7 @@ Example
 
     or:
       - type: change filter
-      - heartbeat filter: 60
+      - heartbeat action: 60
 
 
 Sequence
@@ -398,7 +398,8 @@ These are some examples for sml value configurations
 Energy consumption today
 --------------------------------------
 
-This will report the power consumption of 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.
 
 ..
     YamlModel: SmlValueConfig
@@ -416,3 +417,27 @@ This will report the power consumption of today
     - 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.
+
+..
+    YamlModel: SmlValueConfig
+
+.. code-block:: yaml
+
+    obis: '0100100700ff'    # Obis code for the energy meter
+    mqtt:
+      topic: power   # MQTT topic for the meter
+    operations:
+    - type: mean interval
+      interval: 30
+      wait for data: False
+    - throttle filter: 30     # Let a value pass every 30s
+    - round: 1
+    - type: change filter      # Only report on changes
+    - refresh action: 01:00    # ... but refresh every hour

requirements.txt

@@ -7,4 +7,4 @@ pytest-asyncio  == 0.23.6
 aioresponses    == 0.7.6
 
 # Linter
-ruff == 0.3.7
+ruff == 0.4.1

requirements_setup.txt

@@ -3,4 +3,4 @@ pyserial-asyncio == 0.6
 easyconfig       == 0.3.2
 pydantic         == 2.7.0
 smllib           == 1.4
-aiohttp          == 3.9.4
+aiohttp          == 3.9.5

src/sml2mqtt/config/operations.py

@@ -68,13 +68,11 @@ def _check_set(self) -> DeltaFilter:
         return self
 
 
-class HeartbeatFilter(BaseModel):
-    """A filter which lets a value pass periodically every specified interval."""
-
-    every: DurationType = Field(
-        alias='heartbeat filter',
-        description='Interval'
-    )
+class ThrottleFilter(BaseModel):
+    """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.
+    """
+    period: DurationType = Field(alias='throttle filter', description='Throttle period')
 
 
 # -------------------------------------------------------------------------------------------------
@@ -87,12 +85,16 @@ class RefreshAction(BaseModel):
     every: DurationType = Field(alias='refresh action', description='Refresh interval')
 
 
-class ThrottleAction(BaseModel):
-    """Action 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.
+class HeartbeatAction(BaseModel):
+    """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.
     """
-    period: DurationType = Field(alias='throttle action', description='Throttle period')
 
+    every: DurationType = Field(
+        alias='heartbeat action',
+        description='Interval'
+    )
 
 # -------------------------------------------------------------------------------------------------
 # Math
@@ -259,8 +261,8 @@ class MeanOfInterval(HasIntervalFields):
 # -------------------------------------------------------------------------------------------------
 
 OperationsModels = (
-    OnChangeFilter, DeltaFilter, HeartbeatFilter, RangeFilter,
-    RefreshAction, ThrottleAction,
+    OnChangeFilter, DeltaFilter, HeartbeatAction, RangeFilter,
+    RefreshAction, ThrottleFilter,
     Factor, Offset, Round,
     NegativeOnEnergyMeterWorkaround,
     Or, Sequence,

src/sml2mqtt/sml_value/operations/__init__.py

@@ -1,11 +1,11 @@
-from .actions import RefreshActionOperation, ThrottleActionOperation
+from .actions import HeartbeatActionOperation, RefreshActionOperation
 from .date_time import DateTimeFinder, MaxValueOperation, MinValueOperation, VirtualMeterOperation
 from .filter import (
     DeltaFilterOperation,
-    HeartbeatFilterOperation,
     OnChangeFilterOperation,
     RangeFilterOperation,
     SkipZeroMeterOperation,
+    ThrottleFilterOperation,
 )
 from .math import FactorOperation, OffsetOperation, RoundOperation
 from .operations import OrOperation, SequenceOperation

src/sml2mqtt/sml_value/operations/actions.py

@@ -36,26 +36,26 @@ def describe(self, indent: str = '') -> Generator[str, None, None]:
         yield f'{indent:s}- Refresh Action: {format_period(self.every)}'
 
 
-class ThrottleActionOperation(ValueOperationBase):
-    def __init__(self, period: DurationType):
-        self.period: Final = get_duration(period)
+class HeartbeatActionOperation(ValueOperationBase):
+    def __init__(self, every: DurationType):
+        self.every: Final = get_duration(every)
         self.last_time: float = -1_000_000_000
+        self.last_value: float | None = None
 
     @override
     def process_value(self, value: float | None, info: SmlValueInfo) -> float | None:
-        if value is None:
-            return None
+        if value is not None:
+            self.last_value = value
 
-        now = monotonic()
-        if self.last_time + self.period > now:
+        if monotonic() - self.last_time < self.every:
             return None
 
-        self.last_time = now
-        return value
+        self.last_time = monotonic()
+        return self.last_value
 
     def __repr__(self):
-        return f'<ThrottleAction: {self.period}s at 0x{id(self):x}>'
+        return f'<HeartbeatAction: {self.every}s at 0x{id(self):x}>'
 
     @override
     def describe(self, indent: str = '') -> Generator[str, None, None]:
-        yield f'{indent:s}- Throttle Action: {format_period(self.period)}'
+        yield f'{indent:s}- Heartbeat Action: {format_period(self.every)}'

src/sml2mqtt/sml_value/operations/filter.py

@@ -5,7 +5,7 @@
 from typing_extensions import override
 
 from sml2mqtt.const import DurationType, get_duration
-from sml2mqtt.sml_value.base import SmlValueInfo, ValueOperationBase, ValueOperationWithStartupBase
+from sml2mqtt.sml_value.base import SmlValueInfo, ValueOperationBase
 from sml2mqtt.sml_value.operations._helper import format_period
 
 
@@ -123,26 +123,26 @@ def describe(self, indent: str = '') -> Generator[str, None, None]:
         yield f'{indent:s}- Zero Meter Filter'
 
 
-class HeartbeatFilterOperation(ValueOperationBase):
-    def __init__(self, every: DurationType):
-        self.every: Final = get_duration(every)
+class ThrottleFilterOperation(ValueOperationBase):
+    def __init__(self, period: DurationType):
+        self.period: Final = get_duration(period)
         self.last_time: float = -1_000_000_000
-        self.last_value: float | None = None
 
     @override
     def process_value(self, value: float | None, info: SmlValueInfo) -> float | None:
-        if value is not None:
-            self.last_value = value
+        if value is None:
+            return None
 
-        if monotonic() - self.last_time < self.every:
+        now = monotonic()
+        if self.last_time + self.period > now:
             return None
 
-        self.last_time = monotonic()
-        return self.last_value
+        self.last_time = now
+        return value
 
     def __repr__(self):
-        return f'<HeartbeatFilter: {self.every}s at 0x{id(self):x}>'
+        return f'<ThrottleFilter: {self.period}s at 0x{id(self):x}>'
 
     @override
     def describe(self, indent: str = '') -> Generator[str, None, None]:
-        yield f'{indent:s}- Heartbeat Filter: {format_period(self.every)}'
+        yield f'{indent:s}- Throttle Filter: {format_period(self.period)}'

src/sml2mqtt/sml_value/setup_operations.py

@@ -6,7 +6,7 @@
 from sml2mqtt.config.operations import (
     DeltaFilter,
     Factor,
-    HeartbeatFilter,
+    HeartbeatAction,
     MaxOfInterval,
     MaxValue,
     MeanOfInterval,
@@ -21,14 +21,14 @@
     RefreshAction,
     Round,
     Sequence,
-    ThrottleAction,
+    ThrottleFilter,
     VirtualMeter,
 )
 from sml2mqtt.sml_value.base import OperationContainerBase, ValueOperationBase
 from sml2mqtt.sml_value.operations import (
     DeltaFilterOperation,
     FactorOperation,
-    HeartbeatFilterOperation,
+    HeartbeatActionOperation,
     MaxOfIntervalOperation,
     MaxValueOperation,
     MeanOfIntervalOperation,
@@ -42,7 +42,7 @@
     RefreshActionOperation,
     RoundOperation,
     SequenceOperation,
-    ThrottleActionOperation,
+    ThrottleFilterOperation,
     VirtualMeterOperation,
 )
 
@@ -65,11 +65,11 @@ def create_sequence(operations: list[OperationsType]):
 
 MAPPING = {
     OnChangeFilter: OnChangeFilterOperation,
-    HeartbeatFilter: HeartbeatFilterOperation,
+    HeartbeatAction: HeartbeatActionOperation,
     DeltaFilter: DeltaFilterOperation,
 
     RefreshAction: RefreshActionOperation,
-    ThrottleAction: ThrottleActionOperation,
+    ThrottleFilter: ThrottleFilterOperation,
 
     Factor: FactorOperation,
     Offset: OffsetOperation,

tests/config/test_config.py

@@ -29,7 +29,7 @@ def test_error_message():
             'operations': [
                 {'negative on energy meter status': True},
                 {'factor': 3}, {'offset': 100}, {'round': 2},
-                {'or': [{'change filvter': True}, {'heartbeat filter': 120}]}
+                {'or': [{'change filvter': True}, {'heartbeat action': 120}]}
             ]
         })
 

tests/sml_values/test_operations/test_actions.py

@@ -1,6 +1,6 @@
 from tests.sml_values.test_operations.helper import check_description, check_operation_repr
 
-from sml2mqtt.sml_value.operations import RefreshActionOperation, ThrottleActionOperation
+from sml2mqtt.sml_value.operations import HeartbeatActionOperation, RefreshActionOperation
 from sml2mqtt.sml_value.operations._helper import format_period
 
 
@@ -33,20 +33,27 @@ def test_refresh_action(monotonic):
     assert f.process_value(None, None) == 2
 
 
-def test_throttle_action(monotonic):
-    f = ThrottleActionOperation(30)
+def test_heartbeat_action(monotonic):
+    f = HeartbeatActionOperation(30)
     check_operation_repr(f, '30s')
-    check_description(f, '- Throttle Action: 30 seconds')
 
-    assert f.process_value(None, None) is None
     assert f.process_value(1, None) == 1
 
-    monotonic.set(29.99)
-    assert f.process_value(1, None) is None
-    monotonic.set(30)
-    assert f.process_value(1, None) == 1
+    monotonic.add(15)
+    assert f.process_value(2, None) is None
 
-    monotonic.set(59.99)
-    assert f.process_value(1, None) is None
-    monotonic.set(60)
-    assert f.process_value(1, None) == 1
+    monotonic.add(14.99)
+    assert f.process_value(3, None) is None
+
+    monotonic.add(0.01)
+    assert f.process_value(None, None) == 3
+    assert f.process_value(2, None) is None
+
+    monotonic.add(30.01)
+    assert f.process_value(5, None) == 5
+    assert f.process_value(5, None) is None
+
+    check_description(
+        HeartbeatActionOperation(30),
+        '- Heartbeat Action: 30 seconds'
+    )