Nimly lock, with Zigbee module

uvnikita · October 24, 2024, 12:46pm

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

uvnikita · October 25, 2024, 9:39am

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

uvnikita · October 25, 2024, 9:40am

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.

linust · October 25, 2024, 6:31pm

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

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.

uvnikita · October 26, 2024, 8:46pm

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.

Eriond · October 26, 2024, 9:16pm

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!

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.

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.

uvnikita · October 27, 2024, 10:23am

Thanks for the kind words

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.

Eriond · October 27, 2024, 11:06am

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%.

uvnikita · October 27, 2024, 11:10am

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

Eriond · October 27, 2024, 11:22am

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?

uvnikita · October 27, 2024, 11:34am

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.

Eriond · October 27, 2024, 11:45am

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

gustavostmo · November 18, 2024, 9:14am

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

uvnikita · November 21, 2024, 2:30pm

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.