Add hold_off_send_last to @time_active

[dmamelin]

The existing hold_off drops all triggers during the hold-off window, which is useful for rate limiting but can lose the latest data.
With hold_off_send_last enabled, it still suppresses intermediate triggers, but runs once after the hold-off expires using the most recent suppressed trigger data.

[ALERTua]

As a dyslexic, I would want to have an example for this kwarg, as, after reading the description thrice, I could not grasp its functionality. You may disregard my comment.

[dmamelin]

Example: if sensor.power changes to 10, then 20, then 30 within 60 seconds:

• With @time_active(hold_off=60), the function runs immediately for 10, and 20/30 are dropped.
• With @time_active(hold_off=60, hold_off_send_last=True), the function runs immediately for 10, suppresses 20, and then runs once more after 60 seconds with 30.

This is useful for noisy and unstable sensors that spam updates: decorator can ignore the intermediate churn while still processing the latest value once the hold-off period ends.

[ALERTua]

So hold_off_send_last holds for hold_off seconds after the first trigger, but then triggers again for the last trigger that was within those hold_off seconds?

[dmamelin]

hold_off_send_last controls what happens to data dropped during hold_off.

With hold_off_send_last=True, the dropped data will be sent after hold_off seconds from the last send.
With hold_off_send_last=False (default), the dropped data will be ignored completely, as before.

There is no double send.

[ALERTua]

So if my power voltage sensor trigger is voltage >= 180 with hold_off=60 and hold_off_send_last=True, the voltage was 220, triggered on 0, then, after a second, turned unavailable, then, after 15 seconds, back to 220, the triggers would be 0, and then, after the hold_off period, 220 (unavailable being skipped)?

[dmamelin]

With @state_trigger("voltage >= 180"), if voltage=0 or voltage=unavailable, execution will not even reach @time_active, because @state_trigger will not fire.

With @state_trigger("voltage >= 0") and @time_active(hold_off=60, hold_off_send_last=True), it will behave as you described: 0 will be sent, unavailable will be dropped, and 220 will be delivered after hold_off.

[ALERTua]

Crap, you are right. I made up a bad example.

[dmamelin]

@ALERTua, i corrected my comment above.

If it's still unclear, I'm happy to walk through more examples.

It seems I didn't phrase the comment in reference.rst clearly enough. Let's try to find the right wording together - any suggestions?