Skip to content

WWST: add Zemismart ZM25Z window treatment support - #3280

Open
zemismart-dev wants to merge 4 commits into
SmartThingsCommunity:mainfrom
zemismart-dev:codex/zm25z-wwst-certification
Open

zemismart-dev wants to merge 4 commits into
SmartThingsCommunity:mainfrom
zemismart-dev:codex/zm25z-wwst-certification

Conversation

@zemismart-dev

@zemismart-dev zemismart-dev commented Oct 16, 2026 •

Copy link
Copy Markdown

Type of Change

  • WWST Certification Request
    • I have reviewed the README.md file
    • I have reviewed the CODE_OF_CONDUCT.md file
    • I have signed the CLA
    • I plan on entering a WWST Certification Request or have entered a request through the WWST Certification console at developer.smartthings.com
  • Bug fix
  • New feature
  • Refactor

Checklist

  • I have performed a self-review of my code
  • I have commented my code in hard-to-understand areas
  • I have verified my changes by testing with a device or have communicated a plan for testing
  • I am adding new behavior, such as adding a sub-driver, and have added and run new unit tests to cover the new behavior

Description of Change

Add support for _TZE200_cirjrpxe / TS0301 using the existing window-treatment-battery profile. The AC ZM25Z and a historical battery-powered unit share this fingerprint and firmware value (00000049); no reliable automatic discriminator has been established. The shared profile retains battery support for matching battery devices, while the AC sample may display its firmware-reported battery percentage. The manufacturer will not change the existing firmware. Acceptance of this compatibility approach remains open for review.

Normal commands use the SDK shade handlers. The revision removes movement-command blocking, init reads, and routine Unknown transitions after restart, pause, or completion. A narrow recovery handler checks an isolated zero position report with one read and a two-second fallback. It does not guarantee correction when the read is delayed or lost, and it is not a firmware fix.

The revision also removes the old position-confirmation module, retains relative-step target cleanup and timer cleanup on removal, and replaces the battery no-op handlers with capability-gated standard battery handlers. The parent driver's refresh capability remains declared. The device advertises manufacturer-specific cluster 0xEF00; this implementation does not use it.

The fingerprint selects this behavior for every matching device, not uniquely for the AC ZM25Z. The shared profile and the two remaining Full Integration failures below require review before certification/catalog release. This code-review update does not update the certification submission.

Summary of Completed Tests

Compatibility candidate

  • Current focused local validation: API 19 target tests 72/72 passed; Lua 5.3 syntax and Luacheck passed for the six checked Lua files with zero errors or warnings.
  • Physical compatibility validation on 2026-10-21 used production source ef6307972af07dbbbb9bfa99e617f08d6f035421 and installed package 2026-10-21T05:45:44.174386656. The AC sample selected window-treatment-battery during fresh onboarding. The subsequent fingerprint formatting change removes only two surrounding blank lines.
  • Full Integration YSCUOV1PTV: FAILED, 24/26 passed. The unresolved cases are the Unknown event and battery-percentage change on the AC sample. The battery case is recorded as USER_SKIPPED internally but counted as FAILED in the official summary; neither failure is treated as waived.
  • The separate recovery check corrected the transient zero report, but operator/camera observations showed a brief power-on jog followed by stopping. This is not a claim of stationary restoration or a firmware fix.
  • This failed report has not been linked to the product or used to update the certification submission. The earlier 23/23 result is not reused for this candidate. Detailed physical results.

Historical validation — previous no-battery package

The results below apply only to the earlier package explicitly identified in those results. They do not validate the shared-battery-profile candidate.

  • SmartThings Test Suite Full Integration XXEUAAMJBV, 2026-10-16: 23/23 passed; zero failures, skips, user exclusions, or errors. Duration: 00:14:15. Tested production revision: 8d4f448895ab89f53610cf650e0d5da3fe5db2c2; installed package version: 2026-10-16T03:24:03.230350782. Fresh onboarding selected window-treatment-profile without battery. Control, 0/50/100 positions, relative steps, preset, the required refresh-capability presence check, firmware checks, Unknown, and formal offboarding completed. Functional refresh/read behavior was additionally exercised in the separate real protocol and power-cut checks below.
  • Formal Unknown case: one ordinary standard pause caused the production driver's pending static-confirmation state to become unknown; two subsequent position reads of 43 restored partially open. This case did not include a power cut.
  • Separate real power-cut/recovery check, same package and physical sample: three read requests received no position response and produced unknown while retaining 43%. After power was restored, unsolicited 0/43 reports did not produce a false 0%, closed, or moving state. Two successful reads of 43 restored the static state. This recovery check sent no motion commands; sampled camera evidence showed the output remaining stationary.
  • The final-version Full Integration exercised 50 → step +10 = 60 → absolute 50 → step −10 = 40. Camera observations supported visible movement/stop and the manual preset checks; percentages are protocol readbacks, not independent mechanical position measurements.
  • Driver integration tests: API 19: 307/307; API 21: 303/307. The four API 21 failures are the existing VIVIDSTORM upper/lower Setlimit cases (Too many args for Mode.setMode), also reproduced on unmodified upstream. The final 49 feedback tests pass on both SDKs, including the strengthened real removed → SDK deleted callback case. That final test-only strengthening was rerun as the 49-case focused suite; production source was unchanged from the full-suite run. Lua 5.3 syntax, Luacheck, and whitespace checks passed.
  • Final test applicability update (test files only): 70 target tests pass on API 15, 19 and 21. Thirteen cases exercise the stock step helper’s API 15 named-argument command-injection dependency and now declare the same min_api_version = 15 as upstream step tests. The unfiltered API 14 harness reports 57/70 because it ignores this metadata; its 13 failures match those 13 API-15-only cases exactly. All 57 applicable cases pass. Additional independent preset, zero-step and non-step removal cases preserve API 14 coverage. Production driver, configuration, profiles, fingerprints and the installed/tested package are unchanged; only test applicability and coverage changed after the full integration run.

Physical testing used an unloaded sample with temporary travel limits. It does not establish rated-load endurance or full production travel coverage. The two-read policy provides bounded consistency checking, not proof of radio freshness or mechanical truth; repeated identical incorrect responses remain a protocol limitation. Passing these tests is evidence for review, not a claim of completed WWST certification.

Use the standard profile without battery and confirm position feedback before
allowing motion after startup or inconsistent reports. Preserve step targets
and invalidate stale callbacks safely across device removal.
Match the stock step helper minimum API 15 for the thirteen tests that
exercise named-argument command injection. Retain API 14 coverage for
non-step removal callbacks, pure preset and zero-step behavior.

No production driver, profile, fingerprint or installed package changes.
@cjswedes

Copy link
Copy Markdown
Contributor

Fingerprint scope requiring review: a separate historical unit recorded as ZM15B uses the same manufacturer/model and firmware value (00000049). No reliable product-variant discriminator has been established. This exact fingerprint therefore also selects the profile without battery when another matching unit is newly paired. Tests preserving an already assigned battery profile do not protect fresh pairing of such units. This request covers ZM25Z only; the mapping's effect on other matching products needs an agreed resolution before merge/catalog release. We do not claim that the fingerprint uniquely identifies the tested power variant.

Is there any distinguishing attribute, such as the endpoint/cluster list, or the battery attributes returning unsupported, that we could use? Otherwise we'd prefer a profile that works for both. We can leave the existing fingerprint to assign the proper profile to the old device, but do a profile switch during doConfigure if there is something in the device record to differentiate the devices.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This adds a lot of complexity and changes UX in ways we wouldn't accept for other shades. Dropping open, close and level commands while the state is 'unknown', and showing 'unknown' after every hub restart, pause or completed move, are both regressions compared with the default handlers. What specific device misbehaviour does this fix? The description mentions spurious 0/43 reports after power is restored. If that's the problem, please handle it narrowly, for example by ignoring that report pattern or doing one refresh after a rejoin. Commands should never be blocked. Please also don't send Zigbee reads from init; use doConfigure or added.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The concrete device issue was an unsolicited CurrentPositionLiftPercentage report of 0 after power restoration while the motor was stationary. In the captured run, a read sent after that report returned the prior value 43 about 0.654 seconds after the zero report, and a subsequent report repeated 43 about 2.521 seconds after the zero. I found no usable rejoin/DeviceAnnce marker in the captured Edge log, so I cannot rely on a rejoin-only hook. I agree that the previous general trust gate was too broad. The local rewrite removes command blocking, init reads, and Unknown transitions on restart/pause/completion. It delegates normal commands to the SDK handlers and uses the existing position-delta/two-second-settling pattern, with a bounded one-read correction only for an isolated zero report when the cached level is nonzero and the cached shade state is neither opening nor closing. A genuine zero read is accepted; no reply releases the original zero report after a two-second bound. That bound is a fallback choice, not a guarantee that every restoration anomaly is corrected: a delayed or lost read can still allow a transient zero to be published. This rewrite is still under local tests and has not been pushed or physically revalidated yet.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Push your changes so we can review them.

When responding to PR comments, be concise.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pushed the simplified implementation and shared battery profile for review. Commands use the SDK handlers; the broad Unknown/command gate and init reads are removed. Recovery is limited to one corrective read for an isolated zero report. The firmware is unchanged.

API 19 target tests pass (72/72). The compatibility Full Integration run YSCUOV1PTV remains FAILED: 24/26 passed; Unknown and AC battery-percentage-change failed. Neither failure is treated as waived, and the certification submission is unchanged. Please advise on acceptance of the shared profile and the required handling of those two cases.

local AUTO_RECOVERY = "_zemismartAutoRecovery"
local PARTIAL_GENERATION = "_zemismartPartialGeneration"
local PARTIAL_TIMER = "partial_open_timer"
-- Engineering consistency policy; these are not certification or travel-time limits.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this mean?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That comment referred to locally chosen communication/settling timeouts, not values required by WWST or the motor's travel specification. The wording is unclear and the broader policy is unnecessary. I am removing that confirmation module in the local draft; the remaining short timeout only bounds how long a possible transient zero report can be deferred before accepting it when the single corrective read has no response. The new implementation still needs validation.

@cjswedes

cjswedes commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

This driver should be rewritten using existing patterns for handling window shades. Zigbee and matter both have been made somewhat more robust in the last few months, and have examples.

@zemismart-dev

Copy link
Copy Markdown
Author

Thanks for the review. I rechecked the captured protocol responses from both physical units. The AC-powered ZM25Z returns PowerConfiguration BatteryPercentageRemaining (0x0021) with SUCCESS and value 0xC8; the historical unit recorded as ZM15B also returns SUCCESS (0x5E/0x60). Both recorded firmware 00000049. These are reported battery-percentage values, not reliable product identifiers; the AC ZM25Z reading does not establish a physical battery. I do not have comparable physical endpoint descriptors or BatteryVoltage (0x0020) responses for both units, so I cannot justify a doConfigure profile switch from the current evidence. The fresh-pairing profile remains unresolved, and I agree that an existing battery device retaining its profile is not sufficient coverage. I am reviewing the compatibility-profile choice with the product owner before updating that mapping. In parallel I am rewriting the movement handling around the standard shade handlers. Before updating the certification package, I will physically validate the final driver/Profile and rerun Full Integration; the existing 23/23 report belongs to the previously submitted package only.

@zemismart-dev

Copy link
Copy Markdown
Author

The product owner has agreed to the shared-fingerprint compatibility approach. The local candidate now maps _TZE200_cirjrpxe / TS0301 to the existing window-treatment-battery profile, with the generic label Zemismart Roller Shade Motor. It retains the seven existing capabilities and the reported battery values; there is no SKU discriminator or synthesized percentage. Local tests are now 72/72 on API15 and API21, and 312/312 for the complete driver on the officially published API19 / 0.60.x beta SDK. These are local simulated results; the candidate has not been pushed, installed or physically revalidated yet.

Two test-applicability questions remain before the new Full Integration result can be used for certification:

  1. The AC ZM25Z has no physical battery, but returns 0x0021 SUCCESS / 0xC8. Its historical STTS plan requested a percentage change away from 100%. We can retain and verify real reports, but cannot produce a real battery-discharge event on this AC sample. Does the compatibility recommendation require any additional battery-variant physical evidence, and which WWST review route should confirm whether that AC-specific test can be explained as inapplicable?
  2. The rewrite reports Unknown from an invalid position report, while keeping commands available. Our saved physical captures have not shown such a value; the recorded power-off tests produced no device replies. We have removed the old pause/init/completion Unknown behavior and have not added an arbitrary refresh timeout to recreate it. Is protocol-derived Unknown the intended driver behavior here, with the currently unverified physical trigger addressed separately with the WWST team?

The Test Suite documentation provides a route for explaining necessary exclusions in Notes, but we are not treating that as an approved waiver. We will preserve the actual outcomes and request a product-specific decision. The old 23/23 report remains evidence for the previous package only.

@zemismart-dev

zemismart-dev commented Oct 21, 2026 •

Copy link
Copy Markdown
Author

A fresh hardware validation run of the compatibility candidate has completed. The original AC ZM25Z sample automatically selected the existing seven-capability window-treatment-battery profile during Scan nearby onboarding in 78 seconds. The tested local source is ef6307972af07dbbbb9bfa99e617f08d6f035421, installed package version 2026-10-21T05:45:44.174386656.

Full Integration YSCUOV1PTV completed in 23m10s with all 26 items selected: 24 passed, 2 failed, 0 skipped/excluded/errors. Open, close, pause, position targets, preset, relative steps, onboarding and offboarding passed. The two remaining cases correspond to the applicability questions above:

  • windowShade/attribute_windowShade/4: no Unknown event during the 120-second window; the final value remained partially open. We did not reinstate routine pause/init/completion Unknown or a command gate.
  • battery/attribute_battery/3: the AC sample continued reporting the actual 0xC8 value (100%). We selected Skip because there is no physical battery to discharge; the raw log says USER_SKIPPED, but the official summary counts this as FAILED, not as an approved exclusion. Optional battery quantity/type were answered No and passed.

A separate power-cut check after the formal Unknown step ended sent three refreshes (six position/battery reads) with no replies. On restoration, the transient zero triggered one position read returning 43; no false 0/closed/opening capability events or movement commands were emitted in that recovery window. The operator and camera observations nevertheless showed a brief power-on jog/rotation followed by stopping, so we are not claiming completely stationary restoration or a firmware fix. The product owner has since confirmed that the manufacturer considers this brief power-on action normal design behavior; this does not resolve the two WWST test-applicability questions.

The final Stop was acknowledged and reported 43, and the device was offboarded. The original report and detailed Notes are preserved in STTS. The Notes were verified in a second official export; this report has not been linked to the product or used to resubmit the certification request. This is a FAILED result, not a claim of certification compliance; the previous 23/23 report is not reused. The compatibility source has not been pushed while the product-specific Unknown and AC battery-test expectations remain unresolved. We await guidance on those two cases before updating the certification request.

Comment on lines +121 to +124
[PowerConfiguration.ID] = {
[PowerConfiguration.attributes.BatteryVoltage.ID] = ignore_battery_report,
[PowerConfiguration.attributes.BatteryPercentageRemaining.ID] = ignore_battery_report,
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since window-treatment-profile that is used by this device doesn't support battery, then battery events will not be propagated anyway.
If this is externally powered device. Doesn't it need a fix in FW to not send battery reports ?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The manufacturer has confirmed that they will not change the existing firmware. The battery-powered and AC variants share the same manufacturer/model fingerprint, and we currently have no validated way to distinguish them automatically.

The existing compatibility candidate uses the shared window-treatment-battery profile. Its Full Integration result is YSCUOV1PTV: 24 passed, 2 failed. The unresolved cases are battery-percentage change on the AC sample and the Unknown event, as documented in #3280 (comment).

Could you please clarify which compatibility approach is acceptable and what validation is required?

  1. Can the shared battery-profile approach be accepted, and how should the AC battery-percentage-change and Unknown test cases be handled?
  2. If that approach is not acceptable, would an explicit user preference selecting battery or AC power, with the corresponding profile selected by the driver, be acceptable? What testing would be required for that approach?

We will wait for clarification of the accepted approach and test scope before changing the implementation, so we can consolidate the necessary changes and validation rather than repeatedly rerunning hardware tests. Neither failed case is being treated as waived, and the compatibility source and failed report have not been used to update the certification submission.

Comment on lines +72 to +73
-- This externally powered profile has no battery, despite unsolicited battery reports.
local function ignore_battery_report() end

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since window-treatment-profile that is used by this device doesn't support battery, then battery events will not be propagated anyway.
If this is externally powered device. Doesn't it need a fix in FW to not send battery reports ?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed that the old profile in the current PR does not expose battery, so the no-op handler is unnecessary for suppressing capability events. I have consolidated the firmware/shared-fingerprint question and our actual test results in this reply: #3280 (comment) .

The manufacturer has confirmed that they will not change the existing firmware. The shared-battery-profile candidate is still unpublished, pending agreement on the acceptable approach and test scope. Neither failed test is being treated as waived.

Comment on lines +157 to +162
- id: "_TZE200_cirjrpxe/TS0301"
deviceLabel: Zemismart ZM25Z Roller Shade Motor
manufacturer: _TZE200_cirjrpxe
model: TS0301
deviceProfileName: window-treatment-profile

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove those empty lines (before & after the fingerprint)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed both surrounding blank lines in the local follow-up change. All nonblank content is unchanged, and git diff --check passes. This formatting change has not been pushed; it will be included in the consolidated revision after the outstanding compatibility and test-scope questions are settled.

@github-actions

Copy link
Copy Markdown

@github-actions

Copy link
Copy Markdown

zigbee-window-treatment_coverage.xml

File Coverage
All files 97% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/aqara/aqara_utils.lua 93% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/aqara/init.lua 90% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/hanssem/init.lua 91% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/sombra/init.lua 95% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/axis/axis_version/init.lua 97% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/yoolax/init.lua 97% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/lazy_load_subdriver.lua 57% ❌
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/window_shade_utils.lua 96% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/VIVIDSTORM/init.lua 93% ✅
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/aqara/version/can_handle.lua 83% ❌
/home/runner/work/SmartThingsEdgeDrivers/SmartThingsEdgeDrivers/drivers/SmartThings/zigbee-window-treatment/src/aqara/curtain-driver-e1/init.lua 92% ✅

Minimum allowed coverage is 90%

Generated by 🐒 cobertura-action against c081c63

@github-actions

Copy link
Copy Markdown

Test Results

   73 files    546 suites   0s ⏱️
3 375 tests 3 375 ✅ 0 💤 0 ❌
5 368 runs  5 368 ✅ 0 💤 0 ❌

Results for commit c081c63.

@CLAassistant

CLAassistant commented Nov 4, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

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