ThirdReality Smart Color Bulb ZL1 (3RCB01057Z)

[ekobres]

Proposed change

Add quirk for ThirdReality Smart Color Bulb ZL1 (3RCB01057Z)

Additional information

This is a new quirk. No breaking changes.

This quirk fixes a few problems with the ZL1 Bulb:

1. Correct logical color temperature presentation (device reports 142-454
   mireds but is actually 154-370). Map between logical and device ranges.
2. Provide perceptual brightness mapping so very low but non-off levels
   (raw 1..) are reachable and high end is slightly compressed.
3. Snap XY and Hue/Sat commands to the nearest CT in u'v' when close,
   emitting MoveToColorTemp with default transition; expose logical CT
   154–370 while mapping to device 142–454. (So "Hey Siri, set the
   lights to X" will work if you previously asked what color a light was
   while it was in CT mode and want to set it back to that temperature.)

Device diagnostics

zha-1c4d17a122adeb322c60c77f5939f0ee-Third Reality, Inc 3RCB01057Z-563d149f0a3ab26a9bc0e2d9f377fe39.json

Checklist

• The changes are tested and work correctly
• pre-commit checks pass / the code has been formatted using Black
• Tests have been added to verify that the new code works
• Device diagnostics data has been attached

[codecov]

Codecov Report

❌ Patch coverage is 93.22034% with 44 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.18%. Comparing base (2e2bbd9) to head (ba12737).
⚠️ Report is 5 commits behind head on dev.

Files with missing lines	Patch %	Lines
zhaquirks/thirdreality/smart_color_bulb_zl1.py	93.22%	44 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #4335      +/-   ##
==========================================
+ Coverage   92.13%   92.18%   +0.05%     
==========================================
  Files         358      359       +1     
  Lines       11919    12568     +649     
==========================================
+ Hits        10981    11586     +605     
- Misses        938      982      +44     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[puddly]

Interesting PR! Superifically, these look like firmware problems.

@3reality-support are these issues you can address?

[ekobres]

Interesting PR! Superifically, these look like firmware problems.

@3reality-support are these issues you can address?

They are firmware issues to be sure. Firmware fixes would be preferable, but I haven't gotten any traction on their support forums. In the meantime, this quirk has my lights behaving properly. If they are listening and respond, I have suggestions...

To add - if they do patch these changes in firmware it's likely to pretty badly break scenes people have already created since their brightness and CT levels will be noticeably (albeit correctly) changed from whatever they have been living with.

[ekobres]

Hi maintainers,

The failing test (test_xiaomi_eu_plug_binding[PlugMAEU01] in tests/test_xiaomi.py) is not related to the changes in this PR. It appears to be failing in CI for unrelated reasons (see job: https://github.com/zigpy/zha-device-handlers/actions/runs/17599529930/job/49998865778?pr=4335).

Could you please:

Confirm this test failure is unrelated to my changes, and/or
Rerun the workflow, or
Allow merging despite this unrelated failure?
Thank you!

[3reality-support]

Interesting PR! Superifically, these look like firmware problems.
@3reality-support are these issues you can address?

They are firmware issues to be sure. Firmware fixes would be preferable, but I haven't gotten any traction on their support forums. In the meantime, this quirk has my lights behaving properly. If they are listening and respond, I have suggestions...

To add - if they do patch these changes in firmware it's likely to pretty badly break scenes people have already created since their brightness and CT levels will be noticeably (albeit correctly) changed from whatever they have been living with.

@ekobres 1. Regarding (device reports 142-454mireds but actually 154-370). The report is indeed 142-454, but how did you obtain 154-370? Is it the device interface?
2. Is it not dark enough when the brightness is 1%?
3. At present, we have achieved that when setting xy or hs, if it approaches the range of color temperature, it will transition to color temperature

[ekobres]

@ekobres 1. Regarding (device reports 142-454mireds but actually 154-370). The report is indeed 142-454, but how did you obtain 154-370? Is it the device interface?

@3reality-support Thank you for responding!

1. I got 154-370 (2700K-6500K) from your web site, your user manual,

your product packaging:...

and the bulb itself:

Also, empirical testing next to 4 other smart and dumb bulbs that match at 2700K. When I set your CT to 454 mired, it is a perfect match for 2700K. When I set it at 143 mired, it matches 6500K. So it was a pretty safe bet I could map your 311 mired range into the normal 216 mired range of 2700K-6500K. That part works beautifully and with my quirk, your bulbs behave just exactly like my other tunable CT bulbs from 154-370.

2. Is it not dark enough when the brightness is 1%?

I did some informal testing with a lux meter held to the diffuser of your bulb, and a Hue ambience bulb. I know you don't have the hardware to match Hue's very dim settings, and that is okay. But it also does not appear that you build a perceptual curve into your brightness. Human brightness perception is logarithmic - everyone can immediately see the difference between 10-20 lux. It's much harder to tell the difference between 1,000 and 2,000 lux. It's even harder still to tell 10,000 from 20,000 lux - and so on. So I did my best to squash your low-end brightness and stay idempotent on the round trip between brightness percentage and raw brightness settings (1-255). There is only so much correction I can do in a quirk since I am locked into your 255 possible values - but by flattening the bottom 50% of the HomeAssistant 1-255 range and then compressing on a curve to meet at 254 - it's a crude approximation of a perceptual curve, but it's far better than the default in the firmware.

I'm sure you could do much, much better in firmware by programming a true brightness perceptual curve into a 255-element level table.

3. At present, we have achieved that when setting xy or hs, if it approaches the range of color temperature, it will transition to color temperature.

I would love to test this. I borrowed the math from the internet, so I can't take credit, but I am very happy with my quirk's .015 epsilon u'v' distance snap to the blackbody curve. This matches several Apple colors exactly the same as Hue - including a perfect 370 mired "Topaz" color and a nice 360 mired "Desert Sand" color - and "Ivory", and a few others. It would be very handy to have a manufacturer cluster attribute to set the epsilon so that the snap could be tuned.

Another request: Please add your color gamut RGB x/y/intensity and primary driver 1-5 x/y/intensity attributes in 0x0300: 0x11 - 0x3B. This can help a lot with calibrating colors with real objects and with other types of lights. Also, it would be nice if your bulb would clamp XY at the actual CIE 1931 XY area of your bulb. It would also be amazing if you could publicly share the true color gamut chart and the photo spectrograph information for your bulbs. Even if you decide not to clamp or populate the RGB X/Y/I and primary XY/I, having the real gamut would allow us to achieve these things with quirks.

Last thing - is it possible to share what was changed in the 1.00.74 firmware that was released recently?

I really do hope you can fix all of this in firmware!

Please let me know if you have any questions, or let me know how I can help!

Off topic:

I really like your products, and I know the community is excited for you to continue developing new lights and other products.
I pre-ordered your dual-receptacle energy-monitoring plug, and I am looking forward to the things I can do with it!

[ekobres]

Had to rebase - looks like the Tuya tests are no longer blocking. (Thanks!)
In the meantime I pruned some unnecessary code and added additional tests to hit the coverage target.

This PR is ready for review.

[Copilot]

Pull Request Overview

This PR adds a comprehensive quirk for the ThirdReality Smart Color Bulb ZL1 (3RCB01057Z) to fix color temperature mapping, brightness perception, and color command handling. The quirk addresses device limitations to improve user experience with voice assistants and Home Assistant controls.

Key changes:

• Custom Color cluster with logical color temperature mapping (154-370 mireds) over device range (142-454 mireds)
• Perceptual brightness mapping using Hermite interpolation for better low-level control and natural brightness progression
• Intelligent color command snapping that routes XY/HS commands to color temperature when near the Planckian locus

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
zhaquirks/thirdreality/smart_color_bulb_zl1.py	Complete quirk implementation with custom Color and LevelControl clusters, color temperature mapping, brightness curves, and CT snapping logic
tests/test_thirdreality_zl1.py	Comprehensive test suite covering all quirk functionality including edge cases, error handling, and fallback behaviors

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}