Nimly lock, with Zigbee module

Hardware
117

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

ZHA configue
ZHA configue810×1114 75.6 KB

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.
ZHA attributes
ZHA attributes1519×1096 123 KB

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?

118

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.

119

Could you elaborate more on this? Is it like in “simple for me”, or “easy for anyone” ? :smile:

120

As in it should be a quite easy contribution by someone familiar with zha quirks. Note that you can also add your own local quirk to achieve the same (see here Zigbee Guide: How-to add/setup local custom ZHA Device Handlers (also known as ”quirks”) in the ZHA integration).

I’m planning to do it at some point when having more time. I can post the instructions here if I’ll get around doing it.

121

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. :man_shrugging:
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.

122

That sounds like a rough experience, sorry to hear that. You might be interested in their new quirckv2 API which supposed to be much simpler: ZHA Device Handlers version 2 (ZHA-Quirks V2) architectural design developer discussion

Documentation draft can be found here: zha-device-handlers/quirks_v2.md at a97ee3baa790b13b7e468f5489233d6b1ed558c1 · zigpy/zha-device-handlers · GitHub

1 Like
123

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:

from zigpy.quirks.v2 import QuirkBuilder
from zigpy.zdo.types import NodeDescriptor

NIMLY = "Onesti Products AS"

NIMLY_LOCK_NODE_DESCRIPTOR = NodeDescriptor(
    logical_type=2,
    complex_descriptor_available=0,
    user_descriptor_available=0,
    reserved=0,
    aps_flags=0,
    frequency_band=8,
    manufacturer_code=4660,
    maximum_buffer_size=108,
    maximum_incoming_transfer_size=127,
    server_mask=11264,
    maximum_outgoing_transfer_size=127,
    descriptor_capability_field=0,
    mac_capability_flags=140 & ~NodeDescriptor.MACCapabilityFlags.MainsPowered
)


(
    QuirkBuilder(NIMLY, "NimlyPRO")
    .also_applies_to(NIMLY, "NimlyCode")
    .also_applies_to(NIMLY, "NimlyTouch")
    .also_applies_to(NIMLY, "NimlyIn")
    .also_applies_to(NIMLY, "EasyFingerTouch")
    .also_applies_to(NIMLY, "EasyCodeTouch")
    .node_descriptor(NIMLY_LOCK_NODE_DESCRIPTOR)
    .add_to_registry()
)

EDIT:

And here is submitted PR: Add Nimly smart lock quirk by uvNikita · Pull Request #3457 · zigpy/zha-device-handlers · GitHub

124

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.

125

I get a similar result. The battery entity reports 37 while the battery remaining percentage reports the double 74.

IMG_4872
IMG_48721179×1268 113 KB

I vaguely remember hearing about this doubling/halving for battery status on another forum perhaps Z2M.

Not sure how to adapt the quirk v2 for this though.

126

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 :sweat_smile: 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.

127

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! :sweat_smile:

Now I will have a go at that doubled battery percentage value. I know for instance it has already been solved for the IKEA remotes, as you can see on line 97 and 124 in the code: zha-device-handlers/zhaquirks/ikea/opencloseremote.py at 263e68c4877852d489688d4d23c1fe9e49795cd8 · zigpy/zha-device-handlers · GitHub
Unfortunately my limitations in Python won’t allow me to fully understand from where line 39 imports the code for “DoublingPowerConfig1CRCluster”. Maybe I’ll have to resort to ChatGPT for an explanation. :smile:

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.

1 Like
128

Thanks for the kind words :grinning:

DoublingPowerConfig1CRCluster is coming from __init__.py file from the ikea module, here: zha-device-handlers/zhaquirks/ikea/__init__.py at 263e68c4877852d489688d4d23c1fe9e49795cd8 · zigpy/zha-device-handlers · GitHub

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.

129

Unfortunately, I swapped out my batteries just the other day, and now I have a cluster reading of “100”, and hence a battery indicaton of only 50%.

130

You are right, unlike their old EachTouch/EasyFinger locks, new Nimly locks require this fix. There is more information over at Z2M here: Fix for showing 50% battery instead of 100% by newlund · Pull Request #6940 · Koenkk/zigbee-herdsman-converters · GitHub.

I created a new PR that should fix this: Add DoublingPowerConfigurationCluster for some nimly locks by uvNikita · Pull Request #3465 · zigpy/zha-device-handlers · GitHub.

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):

from zigpy.quirks.v2 import QuirkBuilder
from zigpy.zdo.types import NodeDescriptor

from zhaquirks import DoublingPowerConfigurationCluster

NIMLY = "Onesti Products AS"

NIMLY_LOCK_NODE_DESCRIPTOR = NodeDescriptor(
    logical_type=2,
    complex_descriptor_available=0,
    user_descriptor_available=0,
    reserved=0,
    aps_flags=0,
    frequency_band=8,
    manufacturer_code=4660,
    maximum_buffer_size=108,
    maximum_incoming_transfer_size=127,
    server_mask=11264,
    maximum_outgoing_transfer_size=127,
    descriptor_capability_field=0,
    mac_capability_flags=NodeDescriptor.MACCapabilityFlags.AllocateAddress|NodeDescriptor.MACCapabilityFlags.RxOnWhenIdle,
)


(
    QuirkBuilder(NIMLY, "EasyFingerTouch")
    .also_applies_to(NIMLY, "EasyCodeTouch")
    .node_descriptor(NIMLY_LOCK_NODE_DESCRIPTOR)
    .add_to_registry()
)

(
    QuirkBuilder(NIMLY, "NimlyPRO")
    .also_applies_to(NIMLY, "NimlyCode")
    .also_applies_to(NIMLY, "NimlyTouch")
    .also_applies_to(NIMLY, "NimlyIn")
    .node_descriptor(NIMLY_LOCK_NODE_DESCRIPTOR)
    .replaces(DoublingPowerConfigurationCluster, endpoint_id=11)
    .add_to_registry()
)
131

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?

132

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.

133

Re-reading the value from the DoublingPowerConfigurationCluster did the trick!
Thanks again; I wouldn’t have figured that out in a million years :slight_smile:

1 Like
134

Does anyone know how to wish ZHA to have the same entities as Z2M?

135

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.

136

Hi.

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? :joy:

Firmware for the skyconnect is from 2024 April, 17th if I remember right. 20140417 or something.