[nrf52, zigbee] zigbee binary_sensor, switch and time #7340

tomaszduda23 · 2024-08-22T14:41:20Z

What does this implement/fix?

Note: for adafruit bootloader check:

bootloader: adafruit_nrf52_sd140_v6 # for nice nano

This requires #7049. It adds zigbee switch and binary_sensor. Tested with zigbee2mqtt 1.40.0. Up to 8 components is supported due to endpoint limit on nrf52840. Endpoints could be reused but it requires extra implementation. Entities names are auto discovered by home assistant.

zigbee_demo.mp4

Types of changes

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Other

Related issue or feature (if applicable): fixes
esphome/feature-requests#1397

Pull request in esphome-docs with documentation (if applicable): esphome/esphome-docs#

Test Environment

Example entry for `config.yaml`:

Alternative config: #7340 (comment)

---
# based on adafruit bootloader
external_components:
  - source: github://pr#7049
    components: [ logger, nrf52, time, zephyr ]
    refresh: always
  - source: github://pr#7340
    components: [ zigbee_ctx, zigbee ]
    refresh: always

nrf52:
  board: adafruit_itsybitsy_nrf52840
  bootloader: adafruit_nrf52_sd140_v6 # for nice nano

esphome:
  name: nrf52-test-nrf

logger:
  level: DEBUG

switch:
  - platform: zigbee
    output: output_template
    id: zigbee_switch_1
  - platform: zigbee
    output: output_template
    id: zigbee_switch_2

output:
  - platform: template
    id: output_template
    type: binary
    write_action:
      - binary_sensor.zigbee.publish:
          id: zigbee_binary_sensor_1
          state: ON
      - binary_sensor.zigbee.publish:
          id: zigbee_binary_sensor_1
          state: OFF
  - platform: template
    id: output_factory
    type: binary
    write_action:
      - zigbee.factory_reset

binary_sensor:
  - platform: zigbee
    id: zigbee_binary_sensor_1
  - platform: zigbee
    id: zigbee_binary_sensor_2
    lambda: return true;

zigbee:
  on_join:
    - switch.zigbee.publish:
        id: zigbee_switch_1
        state: OFF
    - switch.zigbee.publish:
        id: zigbee_switch_1
        state: ON

time:
  - platform: zigbee
    id: test_time
---
# based on mcuboot bootloader
external_components:
  - source: github://pr#7049
    components: [ logger, nrf52, time, zephyr ]
    refresh: always
  - source: github://pr#7340
    components: [ zigbee_ctx, zigbee ]
    refresh: always

nrf52:
  board: adafruit_feather_nrf52840

esphome:
  name: nrf52-test-nrf

logger:
  level: DEBUG

switch:
  - platform: zigbee
    output: output_template
    id: zigbee_switch_1
  - platform: zigbee
    output: output_template
    id: zigbee_switch_2

output:
  - platform: template
    id: output_template
    type: binary
    write_action:
      - binary_sensor.zigbee.publish:
          id: zigbee_binary_sensor_1
          state: ON
      - binary_sensor.zigbee.publish:
          id: zigbee_binary_sensor_1
          state: OFF
  - platform: template
    id: output_factory
    type: binary
    write_action:
      - zigbee.factory_reset

binary_sensor:
  - platform: zigbee
    id: zigbee_binary_sensor_1
  - platform: zigbee
    id: zigbee_binary_sensor_2
    lambda: return true;

zigbee:
  on_join:
    - switch.zigbee.publish:
        id: zigbee_switch_1
        state: OFF
    - switch.zigbee.publish:
        id: zigbee_switch_1
        state: ON

time:
  - platform: zigbee
    id: test_time

Checklist:

The code change is tested and works locally.
Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated in esphome-docs.

probot-esphome · 2024-08-22T14:41:33Z

Hey there @tomaszduda23,
Thanks for submitting this pull request! Can you add yourself as a codeowner for this integration? This way we can notify you if a bug report for this integration is reported.
In __init__.py of the integration, please add:

CODEOWNERS = ["@tomaszduda23"]

And run script/build_codeowners.py

_{^{(message by NeedsCodeownersLabel)}}

codecov-commenter · 2024-08-22T14:43:14Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 59.94%. Comparing base (5b3d61b) to head (c96d576).
Report is 69 commits behind head on dev.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev    #7340   +/-   ##
=======================================
  Coverage   59.94%   59.94%           
=======================================
  Files          50       50           
  Lines       10293    10294    +1     
  Branches     1381     1381           
=======================================
+ Hits         6170     6171    +1     
  Misses       3762     3762           
  Partials      361      361

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

randybb · 2024-08-22T15:46:56Z

Nice! And what about ZHA? Will it work by default?

tomaszduda23 · 2024-08-22T15:58:11Z

It implements binaryinput/binaryoutput from https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf. It might work. I've not tested it with ZHA.
I was surprised that it doesn't work with zigbee2mqtt by default since it uses standard clusters (unless I'm missing something).

tomaszduda23 · 2024-08-22T19:08:08Z

There is some implementation in ZHA https://www.home-assistant.io/integrations/binary_sensor/. Both clusters seems to be implemented in zigpy https://github.com/zigpy/zigpy/blob/f1dddb45d6e7e0cc8a6fb4a0098a9b33149cf024/zigpy/zcl/clusters/general.py#L1539 https://github.com/zigpy/zigpy/blob/f1dddb45d6e7e0cc8a6fb4a0098a9b33149cf024/zigpy/zcl/clusters/general.py#L1572. If someone has setup it would be worth to take a shot.

randybb · 2024-08-22T19:13:03Z

I have ZHA and many Xiaomi/Aqara zigbee sensors. Have bunch of unused nrf5240 modules, just have no clue how to setup this whole nrf52 thing. Probably I have to wait until it is fully merged...

Hedda · 2024-08-27T10:03:55Z

@tomaszduda23 are you following this related "zigbee_esphome" (Zigbee component) project by @luar123 for ESPHome here?

https://github.com/luar123/zigbee_esphome/

Hedda · 2024-08-27T10:07:34Z

Oh, and i addition to that, FYI, be aware Espressif developer P-R-O-C-H-Y is now working on a new Zigbee Wrapper library with a simpler API in Arduino (for arduino-esp32) and he wrote that other developers can post additional feature request related to that in the same issue there for tracking. Maybe you could make use of the same Zigbee API?

Implement Zigbee in Arduino espressif/arduino-esp32#10135

tomaszduda23 · 2024-08-27T17:53:53Z

https://github.com/luar123/zigbee_esphome/

I've seen that. You can do more with it. It seems to be lower level implementation since it requires defining clusters in yaml. My goal was to make it easy to use. Most users don't want to understand what is the difference between cluster, attribute etc.

Maybe you could make use of the same Zigbee API?

Looking on provided examples Espressif API looks different from Nordic. From user point of view it could be the same. c++ implementation would have to be done twice.

Hedda · 2024-08-27T18:37:53Z

It implements binaryinput/binaryoutput from https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf. It might work. I've not tested it with ZHA.

FYI, while ZHA does expose much by default I believe that the ZHA integration does not expose all that zigpy supports, especially not for binary sensors, but instead generally only exposes the bare essentials for each supported platform in order to try to not overwhelmn the end user, however if something is not exposed then you can expand the sensors that it exposes by default in the main zha library which contain their Zigbee Gateway implementation, check out:

https://github.com/zigpy/zha

and

https://github.com/zigpy/zha/tree/dev/zha/application/platforms/binary_sensor

If most of it is exposed there then it is possible to finetune device quirks by writting a custom ZHA Device Handler using the unique device signature to identify specific devices:

https://github.com/zigpy/zha-device-handlers

PS: I think Zigbee2MQTT works very differently in that it instead does not expose anything by default so you more less always need to write a custom sevice handler which they call converters (see zigbee-herdsman-converters):

https://www.zigbee2mqtt.io/advanced/support-new-devices/01_support_new_devices.html

tomaszduda23 · 2024-08-27T18:55:23Z

I've not look into ZHA integration much. I don't have HW to setup another coordinator to test how it works. I could flash nrf52840 with coordinator firmware. The setup looks time consuming though. I hope it gets merged at some point zigpy/zigpy#394.

PS: I think Zigbee2MQTT works very differently in that it instead does not expose anything by default so you more less always need to write a custom sevice handler which they call converters (see zigbee-herdsman-converters):

There is auto generation which works e.g. with genOnOff. I might add auto discovery for other types Koenkk/zigbee2mqtt#23708.
In general genOnOff has better support. The thing which I don't like is missing description which could be used to display name of sensor in HA.

Hedda · 2024-08-28T10:37:24Z

I don't have HW to setup another coordinator to test how it works. I could flash nrf52840 with coordinator firmware. The setup looks time consuming though. I hope it gets merged at some point zigpy/zigpy#394.

FYI, the zigpy-zboss (ZBOSS radio library for zigpy) project which enable using ZBOSS NCP firmware as Zigbee Coordinator in zha is actually quite far along now so the setup should not be as time consuming description in the old issue you linked to, instead check out this repo:

https://github.com/kardia-as/zigpy-zboss

The latest release should be fully usable:

https://github.com/kardia-as/zigpy-zboss/releases

Though because zigpy-zboss is still experimental and not yet included by default in ZHA you do however need to add it to the zha library (ZHA’s Zigbee Gateway implementation) and then manually make Home Assistant core use that patched version instead:

https://github.com/zigpy/zha

PS: I have keep up with that zigpy-zboss project myself and have ongoing progress summeries if interested in the longer back-story of that project here, which also contains user discussion on how to setup:

https://community.home-assistant.io/t/nordic-semi-nrf52840-chips-with-zboss-zigbee-stack-now-usable-as-zigbee-coordinator-for-the-zha-integration-via-new-radio-library-for-zigpy/570196

tomaszduda23 · 2024-08-28T14:48:19Z

It would be great to install experimental version by HACS. Patching core is not for average user 😄 I might take a look later on.

tomaszduda23 · 2024-08-28T18:36:30Z

If Koenkk/zigbee-herdsman-converters#7913 gets merge it would be discover without external converters.

Hedda · 2024-08-28T20:23:46Z

It would be great to install experimental version by HACS. Patching core is not for average user 😄 I might take a look later on.

I agree and that and other related ideas was requested and discussed in these:

zigpy-zboss radio library for ZHA installable as custom component for Home Assistant via HACS? kardia-as/zigpy-zboss#2
How to get started with zigpy-zboss and Home Assistant? kardia-as/zigpy-zboss#20

luar123 · 2024-08-28T20:46:47Z

https://github.com/luar123/zigbee_esphome/

I've seen that. You can do more with it. It seems to be lower level implementation since it requires defining clusters in yaml. My goal was to make it easy to use. Most users don't want to understand what is the difference between cluster, attribute etc.

For me the ideal zigbee implementation would be like api or mqtt. Just define sensors/lights/etc and the translation to zigbee clusters is handled automatically. That is of course a lot of work to implement and I am lacking time and esphome knowledge to do that. So my approach is more flexible but not user friendly, whereas you are targeting a few use-cases that are easy to use. I hope that my approach will lead to a full mqtt-like implementation at some point.

Looking on provided examples Espressif API looks different from Nordic. From user point of view it could be the same. c++ implementation would have to be done twice.

Although low level apis are similar because both use zboss, details are different, so I don't think a common low level code base is easy to do. But what we should consider is that there will be multiple hardware implementations for zigbee. For example we both use zigbee as a component name.

Hedda · 2024-08-29T04:25:20Z

For me the ideal zigbee implementation would be like api or mqtt. Just define sensors/lights/etc and the translation to zigbee clusters is handled automatically.

That sounds like what @ffenix113 is trying to achieve with his ESPHome inspired non-esphome project (which is also for nRF52):

https://github.com/ffenix113/zigbee_home

tomaszduda23 · 2024-08-29T19:07:22Z

For me the ideal zigbee implementation would be like api or mqtt. Just define sensors/lights/etc and the translation to zigbee clusters is handled automatically.

That was my idea too at the beginning. How would you like to do so? I can see two possibilities:

use ZCL which is standardized but not fully supported by z2m. Probably similar thing in zha. There are also limitation e.g. genOnOff do not support description which could be used to set name.
implement completely custom clusters just for esphome and add implementation to z2m and zha.
Are there others possibilities?

Although low level apis are similar because both use zboss, details are different, so I don't think a common low level code base is easy to do. But what we should consider is that there will be multiple hardware implementations for zigbee. For example we both use zigbee as a component name.

Mine could be done on top of yours as long as you allow to define ZCL clusters. I was thinking about generating everything in python similar to yours but it was just easier to use things which are already defined in nrf-sdk.

luar123 · 2024-08-29T19:46:23Z

That was my idea too at the beginning. How would you like to do so? I can see two possibilities:
1. use ZCL which is standardized but not fully supported by z2m. Probably similar thing in zha. There are also limitation e.g. genOnOff do not support description which could be used to set name.
2. implement completely custom clusters just for esphome and add implementation to z2m and zha.
3. Are there others possibilities?

I would stick to standard ZCL clusters wherever possible and add custom clusters for not supported functions. With this also binding to other devices would work. I think it is even possible to add custom attributes to default clusters, but then you still need a converter for z2m. For z2m converters could be added upstream or esphome could generate custom files for each device.

Mine could be done on top of yours as long as you allow to define ZCL clusters. I was thinking about generating everything in python similar to yours but it was just easier to use things which are already defined in nrf-sdk.

At the moment my implementation depends on esp, I don't think there is much to share. Basically an intermediate abstraction layer would be needed. (But don't expect much development from my side, I am not working at this at the moment, just sharing ideas)

Hedda · 2024-08-29T21:26:35Z

That was my idea too at the beginning. How would you like to do so? I can see two possibilities:

use ZCL which is standardized but not fully supported by z2m. Probably similar thing in zha. There are also limitation e.g. genOnOff do not support description which could be used to set name.

implement completely custom clusters just for esphome and add implementation to z2m and zha.

Are there others possibilities?

I would stick to standard ZCL clusters wherever possible and add custom clusters for not supported functions. With this also binding to other devices would work. I think it is even possible to add custom attributes to default clusters, but then you still need a converter for z2m. For z2m converters could be added upstream or esphome could generate custom files for each device.

What sounds like a good compromise would be to use standard ZCL clusters as much as possible and create a set of custom clusters for not supported functions that is standardized for ESPHome so can reuse the same converter in Zigbee2MQTT and same for ZHA Device Handler (zha-quirk) for translation without having to new converter or device handler for each new device created. Also note that ZHA recently added support for ZHA Device Handlers version 2 (ZHA-Quirks V2) architectural design which enable writing dynamic device handlers for ZHA:

https://community.home-assistant.io/t/zha-device-handlers-version-2-zha-quirks-v2-architectural-design-developer-discussion/666460

Hedda · 2024-09-02T13:08:59Z

FYI; ZHA developers are working on AnalogInput and MultistateInput clusters for their "zha" Zigbee Gateway implementation:

@prairiesnpr do you happen to know if zha will dynamically support both BinaryInput and BinaryOutput clusters this way?

github-actions · 2025-07-17T19:43:13Z

To use the changes from this PR as an external component, add the following to your ESPHome configuration YAML file:

external_components:
  - source: github://pr#7340
    components: [zigbee, zigbee_ctx]
    refresh: 1h

(Added by the PR bot)

github-actions · 2025-07-17T19:55:19Z

To use the changes from this PR as an external component, add the following to your ESPHome configuration YAML file:

external_components:
  - source: github://pr#7340
    components: [zigbee, zigbee_ctx]
    refresh: 1h

(Added by the PR bot)

github-actions · 2025-07-17T20:07:26Z

To use the changes in this PR:

# Clone the repository:
git clone https://github.com/esphome/esphome
cd esphome

# Checkout the PR branch:
git fetch origin pull/7340/head:nrf52_zigbee
git checkout nrf52_zigbee

# Install the development version:
script/setup

# Activate the development version:
source venv/bin/activate