Skip to content

Countdown timers (ZCL On With Timed Off) for relay endpoints - #556

Open
mrmaximas wants to merge 3 commits into
romasku:mainfrom
mrmaximas:feature/countdown-timer
Open

mrmaximas wants to merge 3 commits into
romasku:mainfrom
mrmaximas:feature/countdown-timer

Conversation

@mrmaximas

@mrmaximas mrmaximas commented Nov 16, 2026 •

Copy link
Copy Markdown

Countdown timers (ZCL On With Timed Off) for relay endpoints

What

The ZCL On With Timed Off command (0x42) was already accepted by the Zigbee stack, but the OnOff cluster callback ignored it, so the relay stayed on indefinitely. This PR implements it.

  • on_time and off_wait_time are honoured, in units of 100 ms as the spec defines them.
  • A timer is armed per relay endpoint, so two relays count down independently.
  • Any local change cancels a pending countdown: a button press, or a plain on / off / toggle / level command. The relay then stays where the user put it.
  • A repeated on_with_timed_off re-arms the countdown instead of cancelling it.
  • The timer fires from app_task(), so no extra traffic is sent: the firmware only reports an attribute change when the relay actually switches.

zigbee2mqtt/countdown_timer_example.js is an example external converter that exposes the on_time field. The generated converters do not expose it, so it cannot be set from the UI without it. It covers all four AVATTO variants: TS0012-avatto, TS0012-AVB1, TS0002-AVB and TS0001-AVB.

The millisecond counter bug

Two bugs had to be fixed before a countdown could work at all.

clock_time() on the Telink TLSR8258 is a 32-bit counter at 16 MHz, so it wraps every 268.435456 s. The old hal_millis() divided that raw tick by 16000 and tracked the wrap of the derived value. The derived value only spans 0..268435 ms, so the wrap counter was shifted left by 32 bits: every hardware wrap added ~49.7 days instead of the ~268 s that really elapsed. The result was not a millisecond timeline.

The consequence was that a countdown was compared against a counter that jumped forward by 49.7 days at every wrap, so any timer longer than ~268 s fired at the wrap boundary instead of at its deadline. Observed on real hardware:

command 11:16:58.852 -> OFF 11:18:06.884   (68 s instead of 300 s)
command 10:42:22.138 -> OFF 10:46:47       (265 s instead of 300 s)

Both timestamps land exactly on a hardware-wrap boundary.

hal/tick64.h replaces that with a counter that advances by the elapsed tick delta. The delta is a plain uint32 subtraction, so it is the true elapsed tick count across the wrap. The sub-millisecond remainder is carried over, because a tick period is 268435.456 ms rather than a whole number of milliseconds.

hal_millis() now returns the low 32 bits of the true millisecond timeline, so it wraps every ~49.7 days instead of every ~268 s. The countdown itself is compared against hal_millis_64(), which is monotonic.

Only 32-bit division is used: the tc32 toolchain has no __udivdi3.

Platform coverage

This is implemented for Telink router builds only.

HAL_HAS_TIMER_64 gates the whole feature. It is defined for Telink router builds and for the host stub, and not for end device builds and not for Silabs.

End device builds sleep between polls, and the system clock stops while they do, so a deadline could never be reached on time there. The feature is therefore excluded rather than shipped with a broken timer.

Silabs is not covered by this PR. We have no Silabs hardware to test on, so we did not want to ship an untested time source there. A Silabs build is unaffected and still compiles.

The Silabs side is not a hard problem, though: it needs the same monotonic 64-bit millisecond counter, and the rest of the cluster logic is shared code and applies as is. src/silabs/hal/timer.c would need its own counter implementation, the same way src/telink/hal/timer.c has one now.

If you have Silabs hardware and are willing to test it, please say so. The implementation for Silabs can be provided on request - the approach is already worked out and the shared part of the code is already in this PR. It just needs a Silabs timer implementation and someone to flash it and check that the countdown behaves.

Tested on

Live hardware, with the countdown exercised over Zigbee2MQTT. Both are running router firmware:

Device Manufacturer Model
AVATTO LZWSM16-2 _TZ3000_ljhbw1c9 TS0012-avatto
AVATTO LZWSM16-2 _TZ3000_kpatq5pq TS0012-AVB1

The firmware for the other two AVATTO variants is built from the same source, but was not tested on live hardware:

Device Manufacturer Model
AVATTO ZWSM16-1 _TZ3000_4rbqgcuv TS0001-AVB
AVATTO ZWSM16-2 _TZ3000_mtnpt6ws TS0002-AVB

Tests

126 new test cases in the host stub (73 test functions, several of them parameterised):

  • tests/test_relay_cluster_on_with_timed_off.py - the command itself: arming, firing, off_wait_time precedence, the (0,0) case, byte order, per-relay independence, and a countdown that spans a hardware tick wrap.
  • tests/test_relay_cluster_timer_reset.py - every path that cancels or replaces a pending countdown.
  • tests/test_relay_cluster_timer_matrix.py - the cross-product of timer length, device shape, endpoint and tick wrap.
  • tests/test_relay_cluster_button_pairing.py - which button cancels which relay's countdown, including a crossed wiring.
  • tests/test_tick64_timer.py - the counter itself, driven with a simulated tick so the code under test is the code that ships. The test also carries the old formula, so it fails if the fix is reverted.

The full suite passes: 357 tests.

make tests

Notes for the reviewer

  • relay_cluster_task() is called from app_task() and reads the clock once per loop iteration. It does not send anything on its own.
  • The countdown is not persisted. A reboot clears a pending timer.
  • The on_time / off_wait_time values are in 100 ms units on the wire, as the spec requires. Zigbee2MQTT takes seconds and converts.
  • device_db.yaml is not touched. Note that the upstream entries for these AVATTO boards currently say device_type: end_device, so a countdown needs a router build (BOARD=MODULE_AVATTO_TS0012 DEVICE_TYPE=router make board/build). The two devices listed above were tested on router firmware.

Related upstream work

PR #555 (opened 2026-11-15) fixes the same hal_millis() wrap on Telink, in the same files this PR touches. The two changes overlap in src/app.c and src/telink/hal/timer.c; the conflict is two lines of context and is resolved by keeping both.

If #555 lands first, this PR can be rebased on top of it and drop the hal_millis() change, keeping only hal_millis_64(), since the counter would then already be monotonic.

PR #170 also carries an "On with timed Off" implementation, but it is from October 2025 and was written against the old polling HAL; the review there asked for a rewrite in terms of tasks. This PR takes the task-based route already: relay_cluster_task() polls a deadline from app_task().

Issue #182 tracks the countdown timer request.

@hawaltie

Copy link
Copy Markdown

I want to try if this works, but how can i compile an image with this change?

@mrmaximas

Copy link
Copy Markdown
Author

@hawaltie I can compile it out—what is the exact Zigbee model of your relay?

@hawaltie

Copy link
Copy Markdown

From Zigbee2MQTT:

Zigbee model
TS0001-AVB
4rbqgcuv

Is this the information you require?

The example converter listed only the two 2-gang TS0012 variants. The
1-gang TS0001-AVB (ZWSM16-1) and the 2-gang TS0002-AVB (ZWSM16-2)
build from the same firmware and expose the timer the same way, so
add them to the example.

The endpoint layout follows the config_str in device_db.yaml: the
switch clusters come first, then the relay clusters.

Also drop a duplicated block of configuration attributes, which
registered the same three exposes twice per definition.
@mrmaximas

Copy link
Copy Markdown
Author

@hawaltie

hawaltie commented Nov 16, 2026 •

Copy link
Copy Markdown

Works! Excellent. I binded an Ikea motion detector to this device. It didn't work before, and now it just works. Nice!

Thanx.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants