Yeah, the ZHA support for Nimly is poor to say the least.
What is even more annoying, is that ZHA can apparently read out a whole bunch of interesting values from the lock, but for some reason, chose not to. See this picture from my setup, where I chose “Configure device” in the three dots menu next to reconfigure
and then select the “Power configuration” cluster, and quite a long bit down the list of attributes, chose “battery_percentage_remaining”
(there is a bunch of other batteries named 1, 2, 3 etc. but if you scroll down even further, you’ll find the right one)
Finally, click “READ ATTRIBUTE” and you’ll get the sought after value.
What bothers me is why the ZHA developers chose to omit such an important value from the UI? I guess they can’t keep track of every device in the world, but reading out the battery status ought to be one of the most prioritized values in all battery operated devices, right?
I think the reason why ZHA is not showing battery percentage is because Nimly lock incorrectly presents itself as a Mains powered device. See Basic → power_source attribute.
My guess is that adding a simple quirk to zigpy/zha-device-handlers repository that changes it to a battery powered device should fix this issue.
I spent the entire evening yesterday, at first with high hopes and a “how hard can it be, actually?” -attitude. It turns out that it’s far from trivial. I am a hardware developer, and besides that, have been writing simple code for my own use for the last 40 years. But I must admit that I’m having trouble with the level of abstraction that modern coding techniques has brought us.
I have no issues grasping the concept of translating the output of one device (Zigbee) into a structure readable by another device (HA), but I just can’t wrap my head around the how. All these class calls everywhere, overloads and substitutions just got the better of me.
If there was a step-by-step instruction, I’d stand a chance, but writing my own device handler in Python - a language I’m not familiar with - is more than I can do.
I will just have to patiently wait until someone skilled in the art, decides it’s worth his or her time to do it. Or, hope that one day, the ZHA developers make a user-friendly helper that allows to turn any arbitrary Zigbee cluster from any Zigbee device, into a HA device entity that is accessible from the UI as well as from automations and the rest of the HA environment.
I know that is a hell of a task to accomplish, but in the end it could relieve the ZHA devs from this endless flood of quirk requests from lesser users like me.
I finally got around making the custom quirk that changes the Power Source for nimly lock. I’ll submit PR to the upstream zha-device-handlers repo, but in the meantime you can just create a quirk file with the following code:
Interestingly, ZHA reports that my lock has 20% remaining battery after applying this quirk while battery_percentage_remaining reports as 40%. Not sure which number is correct.
TheJulianJES explained in the PR that the battery_percentage_remaining attribute should be from 0 to 200 according to the standard. So unless nimly violates the standard, the value reported by ZHA should be correct.
Looks like it’s time for me to replace the batteries I’ll do that and if it will show 50% on the new batteries, I’ll open another PR to fix this.
In any case, PR has been merged so after home assistant will pull the changes there should be no need for custom quirk.
I’ll also see if I’ll manage to add other features from Z2M (like last user) into ZHA.
Thank you so much for those two links, especially the latter one. I thought I had sifted through every piece of documentation, but apparently not.
Now the pieces come together nicely, even for an old chap like me. Things are always so much easier once you understand what you’re actually doing!
Anyways, excellent work, @uvnikita and thank you for taking your time to elaborate on what you have done. That’s really helpful, and an excellent example of good will towards others.
I’m not sure yet if we need to fix this battery levels. Apparently, battery_percentage_remaining should go from 0 to 200 where 200 actually means 100%, so ZHA just automatically recalculates this number (see comment here: Fix Nimly smart lock mains-powered capability by uvNikita · Pull Request #3457 · zigpy/zha-device-handlers · GitHub).
So, if Nimly is doing everything according to zigbee standard, we should see 200 in that attribute when we replace the batteries. If not, then we can use “doubling power configuration cluster” mentioned by TheJulianJES to fix it.
Here is new code for a custom quirk (make sure to read value from the battery_percentage_remaining attribute to update the reported battery level by ZHA):
Hmm… I replaced the previous quirk code with the new one from above, but I still only get 50% battery status. First I reloaded the ZHA integration, but when that didn’t improve, I restarted the whole box. Still the same 50%. Is there a quirk cache I need to purge somewhere to get the new code into play?
Did you try to re-read the value from Manage Zigbee device → DoublingPowerConfigurationCluster → battery_percentage_remaining.
Might also need to click on “Reconfigure” button for the device.
Btw, I highly encourage everyone interested in better support (via ZHA or Z2M) of Nimly smart locks to send a message to their contact email asking to publish Zigbee Specs Documentation. This makes it much easier to add the integration for it.
We managed to get a hold of zigbee specs for some Schneider Electric / Wiser / Elko devices and adding support for them to ZHA was a breeze.
Installed the nimly touch pro a few months back with a Zigbee module. Just got HA setup via proxmox on a N100 mini pc and had a few issues with nimly, adding with skyconnect.
First ZHA paired nice but I only had lock/unlock functionality. So then I switched from ZHA to Z2M. First pairing failed, had to play a bit with the batteries in and out to get it to link. 2nd pairing went fine and I saw alot of new options, but, everything was greyed out and with “unavailable” status… Third time pairing went fine. I see the same options and I can click on them in the dashboard and they do stuff.
However… I’m not getting any status from the device, no logs, when family members come home and unlock the door. I was hoping to do some notifications based on unlocking the door, but since the nimly isn’t telling HA the door had been unlocked, and nothing is showing up in the logs, I can’t do that. I can only control the device it seems, and not get anything from it.
Is this normal? Or do I need to relink the device for a 4th time?
Firmware for the skyconnect is from 2024 April, 17th if I remember right. 20140417 or something.