docs(zigbee2mqtt): correct the WS90 debounce rationale #560

2026-08-23T20:33:32Z

claude-bot commented

2026-08-23 20:33:32 +00:00

Comment-only follow-up to #559. debounce: 2 and the device stanza are byte-identical; only the justification changes.

What was wrong

#559 justified the value from the device's ZCL reporting configuration, reading minRepIntval 10 as "no attribute repeats inside 10s, so the window must stay well under that" — i.e. treating it as the station's update cadence.

minRepIntval is not a cadence. For a configuration of minRepIntval 10 / maxRepIntval 3600 with a reportable change set, the ZCL reporting model gives:

periodic reports at the maximum interval — once an hour
change-driven reports, each held back so it lands no sooner than 10s after the previous

"In some scenarios it is useful to limit amount of on-change reports to certain minimum time interval. This can be done using minimum report interval parameter. In such case if the difference in attribute value exceeds the reportable change, stack will hold on the transmission of the attribute report to ensure that the report is sent after the minimum report interval."
— AT08550 §2.1.2

So it is a hold-off on change-triggered reports. It sets no schedule, and says nothing about the gap between reports of different attributes — which is precisely what a debounce window sees.

What the bound actually is

The WS90's documented reporting interval: 8.8 seconds (Ecowitt WS90 manual). Z2M's documented rule for this option is not to set it above the sensor's update interval, since a window that never sees silence never flushes. 2 sits well under 8.8.

Also removed

The claim that the window had to exceed 1s because "the recovery burst straddles a second boundary". That was inferred from log lines stamped 11:42:11 and 11:42:12 — second-resolution timestamps, which cannot distinguish 10ms from 900ms. No lower bound is established, and the comment now says so instead of implying one; the burst span is a property of this device on this network and isn't documented anywhere.

The gap-distribution and run-length figures go with it. They measured that the current arrival pattern happens to suit the value — not that the configuration guarantees it. Keeping them presented an accident as a bound.

Verification

Checked before writing, on the live instance post-debounce:

20:30:05  20:30:09  20:30:15  20:30:26  20:30:36  20:30:46  20:30:56  20:31:06
        4s        6s        11s       10s       10s       10s       10s

All eight frames complete — 22 fields each, no partials, no mid-burst flush. precipitation holding at 33.3 rather than dipping.

Note for whoever reviews: 2.13.0 added capacitor_voltage and voltage to the payload. Both read null until the battery cluster reports (minRepIntval 3600), so two new HA entities will sit unknown for up to an hour after rollout. Expected, not a regression.

The wiki note ws90-zigbee-reporting-configuration was written from the same inverted reading and is being corrected separately.

🤖 Generated with Claude Code

Comment-only follow-up to #559. `debounce: 2` and the device stanza are byte-identical; only the justification changes. ## What was wrong #559 justified the value from the device's ZCL reporting configuration, reading `minRepIntval 10` as *"no attribute repeats inside 10s, so the window must stay well under that"* — i.e. treating it as the station's update cadence. `minRepIntval` is not a cadence. For a configuration of `minRepIntval 10` / `maxRepIntval 3600` with a reportable change set, the ZCL reporting model gives: - **periodic** reports at the **maximum** interval — once an hour - **change-driven** reports, each held back so it lands no sooner than 10s after the previous > *"In some scenarios it is useful to limit amount of on-change reports to certain minimum time interval. This can be done using minimum report interval parameter. In such case if the difference in attribute value exceeds the reportable change, stack will hold on the transmission of the attribute report to ensure that the report is sent after the minimum report interval."* > — AT08550 §2.1.2 So it is a hold-off on change-triggered reports. It sets no schedule, and says nothing about the gap between reports of *different* attributes — which is precisely what a debounce window sees. ## What the bound actually is The WS90's **documented** reporting interval: **8.8 seconds** (Ecowitt WS90 manual). Z2M's documented rule for this option is not to set it above the sensor's update interval, since a window that never sees silence never flushes. `2` sits well under 8.8. ## Also removed The claim that the window had to exceed 1s because *"the recovery burst straddles a second boundary"*. That was inferred from log lines stamped `11:42:11` and `11:42:12` — second-resolution timestamps, which cannot distinguish 10ms from 900ms. No lower bound is established, and the comment now says so instead of implying one; the burst span is a property of this device on this network and isn't documented anywhere. The gap-distribution and run-length figures go with it. They measured that the current arrival pattern happens to suit the value — not that the configuration guarantees it. Keeping them presented an accident as a bound. ## Verification Checked before writing, on the live instance post-debounce: ``` 20:30:05 20:30:09 20:30:15 20:30:26 20:30:36 20:30:46 20:30:56 20:31:06 4s 6s 11s 10s 10s 10s 10s ``` All eight frames complete — 22 fields each, no partials, no mid-burst flush. `precipitation` holding at 33.3 rather than dipping. Note for whoever reviews: 2.13.0 added `capacitor_voltage` and `voltage` to the payload. Both read `null` until the battery cluster reports (`minRepIntval 3600`), so two new HA entities will sit `unknown` for up to an hour after rollout. Expected, not a regression. The wiki note `ws90-zigbee-reporting-configuration` was written from the same inverted reading and is being corrected separately. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

review-bot reviewed

2026-08-23 20:35:21 +00:00

review-bot left a comment

🤖 Automated review — model claude-haiku-4-5-20251001 (complexity: trivial), commit c73dc40f9c599f0ac274d8b98ffa64739e96ff61.

Advisory review by the review-bot pipeline. It never approves; a human merges. Push new commits to get a fresh review.

Summary

This PR corrects the technical justification in comments for the WS90 weather station's debounce: 2 configuration value. The actual configuration remains unchanged — only the comments explaining why that value was chosen are updated. The new explanation corrects a misreading of ZCL reporting configuration and properly grounds the bound in the device's documented 8.8s reporting interval.

🔴 Blocking

No blocking issues.

🟡 Suggestions

None. The documentation correction is thorough and well-reasoned.

🟢 Nits

None.

Tests

This is a documentation-only change within a YAML configuration file marked as SEED-ONLY (read at initialization only; the running instance uses its PVC copy). Comments do not affect functionality. The device configuration value (debounce: 2) is unchanged, and the YAML structure is valid.

The PR body provides good context: the author corrected a misunderstanding about ZCL minRepIntval (it's a hold-off on change-triggered reports, not a schedule), and verified the 8.8s reporting interval claim with actual captured log intervals.

Recommendation

Looks reasonable — no blocking issues; the documentation correction is technically sound and well-grounded.

🤖 **Automated review** — model `claude-haiku-4-5-20251001` (complexity: trivial), commit `c73dc40f9c599f0ac274d8b98ffa64739e96ff61`. > Advisory review by the `review-bot` pipeline. It never approves; a human merges. Push new commits to get a fresh review. --- ## Summary This PR corrects the technical justification in comments for the WS90 weather station's `debounce: 2` configuration value. The actual configuration remains unchanged — only the comments explaining why that value was chosen are updated. The new explanation corrects a misreading of ZCL reporting configuration and properly grounds the bound in the device's documented 8.8s reporting interval. ## 🔴 Blocking No blocking issues. ## 🟡 Suggestions None. The documentation correction is thorough and well-reasoned. ## 🟢 Nits None. ## Tests This is a documentation-only change within a YAML configuration file marked as SEED-ONLY (read at initialization only; the running instance uses its PVC copy). Comments do not affect functionality. The device configuration value (`debounce: 2`) is unchanged, and the YAML structure is valid. The PR body provides good context: the author corrected a misunderstanding about ZCL `minRepIntval` (it's a hold-off on change-triggered reports, not a schedule), and verified the 8.8s reporting interval claim with actual captured log intervals. ## Recommendation Looks reasonable — no blocking issues; the documentation correction is technically sound and well-grounded.

claude-bot force-pushed fix-ws90-debounce-rationale from c73dc40f9c to 9b63e15678

2026-08-23 20:36:12 +00:00

Compare

claude-bot force-pushed fix-ws90-debounce-rationale from 9b63e15678 to 2c45841ea6

2026-08-23 20:38:21 +00:00

Compare

review-bot reviewed

2026-08-23 20:38:34 +00:00

review-bot left a comment

🤖 Automated review — model claude-haiku-4-5-20251001 (complexity: trivial), commit 9b63e15678014c497d623981730210508958e8f7.

Advisory review by the review-bot pipeline. It never approves; a human merges. Push new commits to get a fresh review.

Summary

This PR corrects the documentation for the Ecowitt WS90 weather station's debounce: 2 configuration in the Zigbee2mqtt config. It replaces an incorrect technical rationale (based on a misunderstanding of ZCL minRepIntval) with an accurate explanation grounded in the device's documented reporting interval and proper ZCL semantics. The actual configuration value remains unchanged.

🟢 Nits

Lines 196-200: The comment mentions Shelly's KB stating "readings are taken every 2s and data is reported every 9s" — the 9s figure aligns with Z2M's rule to not exceed the sensor's update interval. The PR body separately notes Ecowitt's manual documents 8.8s, and the subsequent paragraph (lines 202-205) clarifies this refers to a different variant (915MHz Ecowitt vs Zigbee/BLE Shelly). This is correct but could potentially confuse someone who only reads the diff without the PR body. The comment itself handles the distinction well by explicitly calling out the source ("SHELLY's documentation, not Ecowitt's") and explaining the variant difference.

Tests

Not applicable — this is a documentation-only change with no code logic or configuration values altered.

Recommendation

Looks reasonable — no blocking issues. The documentation correction is technically sound and improves clarity for future maintainers.

🤖 **Automated review** — model `claude-haiku-4-5-20251001` (complexity: trivial), commit `9b63e15678014c497d623981730210508958e8f7`. > Advisory review by the `review-bot` pipeline. It never approves; a human merges. Push new commits to get a fresh review. --- ## Summary This PR corrects the documentation for the Ecowitt WS90 weather station's `debounce: 2` configuration in the Zigbee2mqtt config. It replaces an incorrect technical rationale (based on a misunderstanding of ZCL `minRepIntval`) with an accurate explanation grounded in the device's documented reporting interval and proper ZCL semantics. The actual configuration value remains unchanged. ## 🟢 Nits - Lines 196-200: The comment mentions Shelly's KB stating "readings are taken every 2s and data is reported every 9s" — the 9s figure aligns with Z2M's rule to not exceed the sensor's update interval. The PR body separately notes Ecowitt's manual documents 8.8s, and the subsequent paragraph (lines 202-205) clarifies this refers to a different variant (915MHz Ecowitt vs Zigbee/BLE Shelly). This is correct but could potentially confuse someone who only reads the diff without the PR body. The comment itself handles the distinction well by explicitly calling out the source ("SHELLY's documentation, not Ecowitt's") and explaining the variant difference. ## Tests Not applicable — this is a documentation-only change with no code logic or configuration values altered. ## Recommendation Looks reasonable — no blocking issues. The documentation correction is technically sound and improves clarity for future maintainers.

claude-bot force-pushed fix-ws90-debounce-rationale from 2c45841ea6 to 87c6f1235c

2026-08-23 20:39:28 +00:00

Compare

review-bot reviewed

2026-08-23 20:41:34 +00:00

review-bot left a comment

🤖 Automated review — model claude-haiku-4-5-20251001 (complexity: trivial), commit 87c6f1235cb6fe44aa256ab641ff316cb22e2379.

Advisory review by the review-bot pipeline. It never approves; a human merges. Push new commits to get a fresh review.

Summary

This PR corrects the technical justification for the WS90 weather station's debounce configuration. The actual value (2) and behavior remain unchanged; only the comment explaining why the value is correct is updated. The change replaces an incorrect rationale based on ZCL minRepIntval with an accurate one based on the device's documented 8.8s transmit interval.

🔴 Blocking

None.

🟡 Suggestions

The PR description excellently documents why the old rationale was wrong and provides verification data. Consider linking the PR or a summary of this analysis into the code comment if the technical reasoning is likely to be questioned again — for instance, a one-line note like # Bound by device's 8.8s transmit interval (Ecowitt manual), not ZCL minRepIntval. would anchor future readers.

🟢 Nits

Minor note: The old version included empirical statistics from 6 hours of observation (run-length distributions, typical/max deferral). While the PR correctly explains these are not actual bounds, preserving a single sentence like "verified under typical network conditions" might help future readers understand that the value has been tested, not just theoretically justified. Not essential, as the PR body provides this context.

Tests

No test changes needed — this is configuration documentation for an existing value, not a new feature or logic change.

Recommendation

Looks reasonable — no blocking issues; the change improves technical accuracy with clear justification.

🤖 **Automated review** — model `claude-haiku-4-5-20251001` (complexity: trivial), commit `87c6f1235cb6fe44aa256ab641ff316cb22e2379`. > Advisory review by the `review-bot` pipeline. It never approves; a human merges. Push new commits to get a fresh review. --- ## Summary This PR corrects the technical justification for the WS90 weather station's debounce configuration. The actual value (2) and behavior remain unchanged; only the comment explaining *why* the value is correct is updated. The change replaces an incorrect rationale based on ZCL `minRepIntval` with an accurate one based on the device's documented 8.8s transmit interval. ## 🔴 Blocking None. ## 🟡 Suggestions The PR description excellently documents why the old rationale was wrong and provides verification data. Consider linking the PR or a summary of this analysis into the code comment if the technical reasoning is likely to be questioned again — for instance, a one-line note like `# Bound by device's 8.8s transmit interval (Ecowitt manual), not ZCL minRepIntval.` would anchor future readers. ## 🟢 Nits Minor note: The old version included empirical statistics from 6 hours of observation (run-length distributions, typical/max deferral). While the PR correctly explains these are not actual bounds, preserving a single sentence like "verified under typical network conditions" might help future readers understand that the value has been tested, not just theoretically justified. Not essential, as the PR body provides this context. ## Tests No test changes needed — this is configuration documentation for an existing value, not a new feature or logic change. ## Recommendation Looks reasonable — no blocking issues; the change improves technical accuracy with clear justification.

k.renner merged commit 96a51f1337 into master

2026-08-23 20:57:52 +00:00

k.renner referenced this issue from a commit

2026-08-23 20:57:54 +00:00

Merge pull request 'docs(zigbee2mqtt): correct the WS90 debounce rationale' (#560) from fix-ws90-debounce-rationale into master

claude-bot referenced this issue from a commit

2026-08-24 04:41:22 +00:00

docs(zigbee2mqtt): the WS90 merge does not make the glitch detectable

claude-bot referenced this pull request

2026-08-24 04:41:36 +00:00

docs(zigbee2mqtt): the WS90 merge does not make the glitch detectable #561

Sign in to join this conversation.