Skip to content

Implement ZCL countdown timer (on_with_timed_off) - #540

Closed
mrmaximas wants to merge 2 commits into
romasku:mainfrom
mrmaximas:feat/on-with-timed-off-timer
Closed

mrmaximas wants to merge 2 commits into
romasku:mainfrom
mrmaximas:feat/on-with-timed-off-timer

Conversation

@mrmaximas

@mrmaximas mrmaximas commented Oct 20, 2026 •

Copy link
Copy Markdown

Summary

Implements the ZCL on_with_timed_off countdown (command 0x42) for relay endpoints. The command was already accepted by the Telink stack but ignored by the cluster callback, so the relay stayed on indefinitely. Zigbee2MQTT, Home Assistant and any other controller can now schedule an auto-off without a wall-clock timer on the device side.

Also removes the unsolicited periodic attributeReport that heartbeat polling emitted — the auto-off is now visible over the air as exactly one report, OnOff=0, at on_time.

Two bugs fixed

1. hal_millis() wraparound. clock_time() is a 32-bit register at 16 MHz, so hal_millis() wraps every ~268 s. A uint32_t deadline silently stops matching after the first wrap: a timer armed at t=270 s is compared against a now that has already wrapped back to 6.4 s, and the signed difference reads as ~263 s in the future. The timer then never fires for the rest of the uptime.

Added hal_millis_64(), which accumulates wraparounds in a high-word counter, and store the deadline as uint64_t. The comparison uses unsigned >= — tc32-gcc miscompiles the signed (int64_t)(now - deadline) >= 0 form into a subcs pattern that misfires the carry flag when a < b, firing the timer on the first poll (~80 ms) instead of at on_time.

2. Arm/cancel race. relay_on() fires the on_change callback, which cancels any pending auto-off. Arming the timer before driving the relay meant the same handler cancelled the timer it had just installed — the relay turned on, reported OnOff=1, and never turned off. The fix is to drive the relay first and install the deadline after, so the callback can only ever clear a previous timer.

Polling rather than ev_timer

The deadline is polled from app_task() via a new relay_cluster_task(). On end-device builds the core sleeps between wakeups and long delays do not fire reliably, so a scheduled ev_timer cannot carry a multi-second countdown; a polled deadline read from hal_millis_64() survives that because the hardware counter ticks whether or not the CPU is awake.

A consequence worth calling out: on end devices on_with_timed_off turns the relay on but arms no timer. The payload is still acknowledged normally, so this is a silent no-op rather than a malformed-command error.

Notes for review

  • Endianness. The 5-byte payload is parsed byte-by-byte (p[1] | (p[2] << 8)), not via a struct cast. zcl_onoff_onWithTimeOffCmd_t embeds a union over a bitfield; the x86_64 host ABI gives that bitfield 4 bytes while tc32 gives it 1, so the struct is 8 bytes on the host and 5 on the device. The struct cast reads from the wrong offset in the stub tests and cannot be made correct for both with __attribute__((packed)).
  • Scope. The timer is armed only on router builds. Behaviour is otherwise identical across boards — the feature lives entirely in relay_cluster.c and is not board-specific.

Tests

tests/test_relay_cluster_on_with_timed_off.py, 19 cases: LE payload decoding for a range of on_time/off_wait_time, the arm/cancel ordering, multi-endpoint dispatch, deadline evaluation across wraparound boundaries, and cancellation by a subsequent ZCL command. Full suite: 250 passed.

Verified on hardware

LZWSM16-2 (_TZ3000_ljhbw1c9), router build. On a packet capture, onWithTimedOff with ontime=50 produces defaultRsp status=0, then OnOff=1, then a single attributeReport OnOff=0 at exactly 5.0 s with nothing in between.

ZWSM16-2 (_TZ3000_mtnpt6ws) builds and installs, but has not been exercised on hardware yet.

The On/Off cluster already accepted the standard `on_with_timed_off`
command (0x42) at the stack level, but the callback ignored it — the
relay stayed on forever. This adds a working countdown.

Two independent bugs had to be fixed:

1. The Telink `clock_time()` register is 32 bits at 16 MHz, so
   `hal_millis()` wraps every ~268 s. A `uint32_t` deadline therefore
   stops matching after the first wrap: a timer set at t=270 s is
   compared against a `now` that has already wrapped back to 6.4 s and
   is then reported as ~263 s in the future. Added `hal_millis_64()`,
   which tracks wraparounds in a high-word counter, and store the
   deadline as `uint64_t`. Compare with unsigned `>=` — tc32-gcc
   miscompiles the signed `(int64_t)(now - deadline) >= 0` form and
   fires the timer on the first poll (~80 ms) instead of at on_time.

2. `relay_on()` fires the `on_change` callback, which cancels any
   pending auto-OFF. Arming the timer before driving the relay meant
   the same handler cancelled the timer it had just installed. Drive
   the relay first, install the deadline after, so the callback can
   only ever clear a *previous* timer.

The timer is polled from `app_task()` via `relay_cluster_task()`
rather than scheduled as an `ev_timer`: on end-device builds the core
sleeps between wakeups and long delays do not fire reliably. As a
consequence `on_with_timed_off` turns the relay on but arms no timer
on end devices — the payload is still acknowledged, so this is a silent
no-op rather than a malformed-command error.

This also removes the unsolicited periodic `attributeReport` that
heartbeat polling used to emit; the auto-OFF now shows up over the air
as exactly one report, `OnOff=0`, at on_time.

Covered by tests/test_relay_cluster_on_with_timed_off.py (19 cases):
LE payload decoding, the arm/cancel race, multi-endpoint dispatch, and
deadline evaluation across wraparound boundaries.
The file's own header asks for work-in-progress entries to go under
'## Upcoming', and that section did not exist yet. Records the new
on_with_timed_off behaviour and links PR #540 for the implementation
detail rather than restating it here.
@mrmaximas

Copy link
Copy Markdown
Author

@andrei-lazarov please pay attention 🙏🏻

@mrmaximas mrmaximas closed this by deleting the head repository Nov 2, 2026
@hawaltie

hawaltie commented Nov 16, 2026 •

Copy link
Copy Markdown

A pity that this is not implemented. Would like to see this function, to use together with the Ikea zigbee motion controllers properly.

@mrmaximas

mrmaximas commented Nov 16, 2026 •

Copy link
Copy Markdown
Author

A pity that this is not implemented. Would like to see this function, to use together with the Ikea zigbee motion controllers properly.

@hawaltie hi!
I already have a second, tested, and working version (router only; my goal was to create firmware for ED relays without a neutral wire that would flood their parents with messages at a frequency of 5 Hz).
No one even looked at the first version, so I deleted the first PR.
Overall, it seems to me that, unfortunately, this project is already dead.

@falkenhawk

Copy link
Copy Markdown

@mrmaximas will you share the "second, tested" version with us, please?

@mrmaximas

Copy link
Copy Markdown
Author

@falkenhawk I was editing some code for Telink, but I don't have any Silabs devices to test it on. What devices do you have?

@hawaltie

hawaltie commented Nov 16, 2026 •

Copy link
Copy Markdown

@mrmaximas: hi!

I have a AVATTO ZWSM16-1-Zigbee switch, so almost the same switch you are using, but with a neutral. Already running the current custom switch firmware.

@mrmaximas

mrmaximas commented Nov 16, 2026 •

Copy link
Copy Markdown
Author

@hawaltie I've modified two versions of the AVATTO LZWSM16-2 _TZ3000_ljhbw1c9 & _TZ3000_kpatq5pq (both w/o neutral), it's works good.
I'm sure it will work on a single-channel devices as well. I'll try to get something done today—at least a .diff

@hawaltie

Copy link
Copy Markdown

Thanks. And take it easy

@mrmaximas

Copy link
Copy Markdown
Author

FYI @hawaltie @falkenhawk @romasku
#556

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.

4 participants