Collect Zigbee cluster definitions

[luar123]

The correct setup of clusters is not always trivial and requires careful reading of the Zigbee cluster library
So lets collect endpoint/cluster/attribute definitions that are know to work. With this we can help each other to get working setups and it would help me to finally implement an automated setup of the definitions.

Device types have two purposes:

1. Let other zigbee devices find an endpoint that implements a certain functionality. Example: A thermostat could search for endpoints that have device type = HA_TEMPERATURE_SENSOR_DEVICE in oder to bind and read the temperature cluster.
2. Automatically setup mandatory clusters, so you don't need to define them manually.

Available device types can be found here, clusters that are included here and the full definitions are in the ZigBee Home Automation Application Profile

In the end it is up to you how you want to implement multiple devices. You can add all to one endpoint or setup many endpoints. If no device type is fitting you can always use TEST or CUSTOM_ATTR. (SIMPLE_SENSOR should only be used for a binary switch.)

[luar123]

Sensors:

(value is always the default value and could be different from what is shown here)

• Temperature

 endpoints:
    - device_type: TEMPERATURE_SENSOR
      num: 1
      clusters:
        - id: TEMP_MEASUREMENT
          attributes:
            - attribute_id: 0x0
              type: S16
              value: 100
              device: temp_id
              scale: 100

• Pressure:
  No fitting device type, often added to temperature endpoint

      clusters:
        - id: PRESSURE_MEASUREMENT
          attributes:
            - attribute_id: 0x0
              type: S16
              report: true
              value: 0x8000
              device: press_id

• Particular matter
  No fitting device type, often added to temperature endpoint

      clusters:
        - id: PM2_5_MEASUREMENT
          attributes:
            - attribute_id: 0x0
              type: single
              report: true
              value: 0
              device: pm25
            - attribute_id: 0x2 # maximum value is needed!
              type: single
              value: 999

• Humidity
  No fitting device type, often added to temperature endpoint

      clusters:
        - id: REL_HUMIDITY_MEASUREMENT
          attributes:
            - attribute_id: 0
              type: U16
              report: true
              value: 200
              device: hum_id
              scale: 100

• illuminance

 endpoints:
    - device_type: LIGHT_SENSOR
      num: 1
      clusters:
        - id: ILLUMINANCE_MEASUREMENT
          attributes:
            - attribute_id: 0
              type: U16
              report: true
              value: 0
              lambda: !lambda "return log10(x)*10000 + 1;"
              device: illum_id

[luar123]

Outputs

• Color dimmable light:
  (dimmable light and on_off light work the same, just use the correct device type and remove unneeded clusters.)

globals:
   - id: color_x
     type: float
     restore_value: no
     initial_value: '0'
   - id: color_y
     type: float
     restore_value: no
     initial_value: '0'

zigbee:
  endpoints:
    - num: 1
      device_type: COLOR_DIMMABLE_LIGHT
      clusters:
        - id: ON_OFF
          attributes:
            - attribute_id: 0
              type: bool
              on_value:
                then:
                  - light.control:
                      id: light_1
                      state: !lambda "return x;"
        - id: LEVEL_CONTROL
          attributes:
            - attribute_id: 0
              type: U8
              value: 255
              on_value:
                then:
                  - light.control:
                      id: light_1
                      brightness: !lambda "return (float)x/255;"
        - id: COLOR_CONTROL
          attributes:
            - attribute_id: 3
              type: U16
              on_value:
                then:
                  - lambda: id(color_x) = (float)x/65536;
                  - light.control:
                      id: light_1
                      red: !lambda "return zigbee::get_r_from_xy(id(color_x), id(color_y));"
                      green: !lambda "return zigbee::get_g_from_xy(id(color_x), id(color_y));"
                      blue: !lambda "return zigbee::get_b_from_xy(id(color_x), id(color_y));"
            - attribute_id: 4
              type: U16
              on_value:
                then:
                  - lambda: id(color_y) = (float)x/65536;
                  - light.control:
                      id: light_1
                      red: !lambda "return zigbee::get_r_from_xy(id(color_x), id(color_y));"
                      green: !lambda "return zigbee::get_g_from_xy(id(color_x), id(color_y));"
                      blue: !lambda "return zigbee::get_b_from_xy(id(color_x), id(color_y));"

[baal86]

• Fan control (0 = off; 1,2,3 = fan speeds)

        - id: FAN_CONTROL
          attributes:
            - attribute_id: 0x0000
              id: fan_mode_attr
              type: 8BIT_ENUM
              report: true
              on_value:
                then:
                  logger.log: 
                    format: "Received state %d" 
                    args: [!lambda "x"]

[baal86]

Simple sensor device with analog input cluster and all mandatory attributes except for the description string working. Assuming that support for strings is still broken on the zigbee_esphome side and not investigating this any further.

  endpoints:
    - device_type: SIMPLE_SENSOR
      num: 1
      clusters:
        - id: ANALOG_INPUT
          attributes:
            - attribute_id: 0x0051
              type: BOOL
              value: False
            - attribute_id: 0x0055
              type: SINGLE
              report: true
              value: 100
            - attribute_id: 0x006F
              type: 8BITMAP
              value: 0

[wryandginger]

To elaborate on this, description seems to be working with this endpoint. Also, and more amazingly, you can specify the unit of measurement by using BACNet Enumerations (see here)

Here's a working example of an LD2410 showing the target distance:

    - device_type: SIMPLE_SENSOR
      num: 1
      clusters:
        - id:  ANALOG_INPUT
          attributes:
            - attribute_id: 0x001C
              type: CHAR_STRING
              max_length: 11    #  This needs to match character count of value below
              report: true
              value: Target Dist    #  Custom name for the sensor
            - attribute_id: 0x0051
              type: bool
              value: false
            - attribute_id: 0x0055
              type: single
              report: true
              value: 0
              device: ddistance    #  Sensor ID defined earlier in your ESPHome config
            - attribute_id: 0x0075
              type: 16BIT_ENUM
              value: 118     # BACNet Engineering Unit 118 = centimeters
              report: true
            - attribute_id: 0x006F
              type: 8BITMAP
              value: 0

So, instead of writing quirks/zigbee custom cluster handlers, it might be easier to manually define your sensors this way.

For example, you can specify PM2_5_MEASUREMENT directly, but you should be able to attach this analog input to that same device to get PM10. (Just use 219 as your value for the engineering unit and name it PM10).

[luar123]

Yes that is the best approach for now and string attributes are also supported.
With ZHA it will be auto-discovered if unit or application type is set. Z2m needs an external definition to make it work. See Koenkk/zigbee2mqtt#27926

There is one very small drawback: you can have only one analog input cluster on each endpoint. Normally you would combine pm1, pm2.5, pm10 on the same endpoint. But for adding the device to home assistant that doesn't hurt.

[cameroncros]

Water flow meter:

    - device_type: SIMPLE_SENSOR
      num: 1
      clusters:
        - id: FLOW_MEASUREMENT
          attributes:
            - attribute_id: 0x0 # Actual value, m^3/h
              type: U16
              report: true
              value: 100
              device: water_meter_total
              scale: 100
            - attribute_id: 0x1 # MinMeasuredValue, required
              type: U16
              value: 0xffff # == Not specified
            - attribute_id: 0x2 # MaxMeasuredValue, required
              type: U16
              value: 0xffff # == Not specified

Have gotten it to appear once, but my esp32-c6 boards dont seem to like to reconnect on reboot, so cant be sure it works correctly.

[zipavlin]

Occupancy sensor that I attached to SIMPLE_SENSOR device:

        - id: OCCUPANCY_SENSING
          attributes:
            - id: zb_occupancy # actual state as bit. 0 -> empty; 1 -> occupied 
              attribute_id: 0x000
              type: 8BITMAP
              report: true
              value: 0
              device: sensor_occupancy
              lambda: !lambda "return x ? 1 : 0;" # perhaps not needed
            - attribute_id: 0x0001
              type: 8BIT_ENUM
              report: true
              value: 0x02 #0x00 -> PIR; 0x01 -> sonic; 0x02 -> PIR & sonic

Attribute definitions as well as optional attributes can be found here [page 4-19]

[wryandginger]

Honestly, a custom converter might be the easiest way to go since you are working with a custom template sensor. I think the issue is with your lambda, but it's beyond my knowledge. Without any logs, I can't be much more help. I had similar issues where Zigbee wanted the template data passed as an integer but the lambda is giving a string. Something like that might be happening with your template sensor. You can also try to force update the zigbee attribute. Here's an example of how I am doing it for an air quality sensor:

sensor:
  - platform: template
    id: qualnum1
    lambda: |-
      return static_cast<int>(std::atoi(id(qualnum).state.c_str()));
    update_interval: 120s
    on_value:
      then:
        - zigbee.setAttr:
            id: setqual
            value: !lambda "return x;"
        - zigbee.report: zb

Obviously, you'd want to customize that sensor for your use case and remove the update_Interval.

If you need it to work natively with Z2M, you could try IAS_Zone. It's in 8-3 of the ZCL, page 524. Here's an untested guess. You'll probably have to adjust your template sensor to fit this format:

      clusters:
        - id: IAS_ZONE
          attributes: 
            - attribute_id: 0x0000
              type: 8BIT_ENUM
              value: 0x01
            - attribute_id: 0x0001
              type: 16BIT_ENUM
              value: 0x000d
            - attribute_id: 0x0002
              type: 16BITMAP
              device: combined_presence
              value: 0
              report: true

Sorry I couldn't be more helpful.

[zipavlin]

@steppel sorry, I didn't notice this message. I am doing exactly what you are trying: I combine PIR sensor and mmWave sensor into one template binary sensor. Note that my mmWave sensor is a 'dumb' on/off one, but that should not matter: here is my full config (gist).

What I did notice is that when adding or changing zigbee endpoints/clusters I need to (at least sometimes) force-remove device from zigbee2mqtt, restart Home Assistant and add device once again.

[steppel]

I got it to run with a combined entity. Still seeing 0x406 error in logs even though, but it works. Now I'm wondering if there is a way to control the mmWave sensor settings (sensitive, cool down, distance etc).

[luar123]

You mean like sending settings over zigbee to esphome? Can you even change the settings of this sensor dynamically?
If yes, there are multiple ways to achieve this: 1. Add analog output (float) or binary output (boolean) clusters with on_value trigger. You will need multiple endpoints if you need more than one of each cluster. 2. You could add a custom cluster with exactly the attributes and data types you need. Of course this needs a custom converter in z2m.

[steppel]

You mean like sending settings over zigbee to esphome? Can you even change the settings of this sensor dynamically?

If yes, there are multiple ways to achieve this: 1. Add analog output (float) or binary output (boolean) clusters with on_value trigger. You will need multiple endpoints if you need more than one of each cluster. 2. You could add a custom cluster with exactly the attributes and data types you need. Of course this needs a custom converter in z2m.

Yes exactly. I have entities defined to change mmWave sensor settings via UART commands, works well with just ESPHome. I have to trigger the config change with a separate defined button ("Apply settings").

[gurg1e]

Hacked this together to create an on/off sensor from a photodiode (led_input). In HA i just hide the non-working temperature sensor.

endpoints:
    - num: 1
      device_type: TEMPERATURE_SENSOR
      clusters:
        - id: BINARY_INPUT
          attributes:
            - attribute_id: 0x0055
              id: led_attr
              type: bool
              report: true          
              device: led_input     

[luar123]

Switch from temperature sensor to simple sensor. And you should add the other mandatory attributes 0x51 and 0x6F, like for the analog input cluster a few posts above.

[Hedda]

@luar123 Probably overkill but have you looked it could repurpoe "ZAP" (ZCL Advanced Platform) to generate/setup the clusters needed?

• https://github.com/project-chip/zap

"The ZCL Advanced Platform (ZAP) is a tool used to configure endpoints for Zigbee and Matter. When you open ZAP, it launches in a new tab next to the .slcp tab. A Zigbee or Matter application can have multiple endpoints. Each endpoint contains a device configuration made up of Clusters on that end-point. The cluster groups differ depending on whether you re configuring a Zigbee or a Matter project, and the interface differs slightly."

• https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/zigbee-cluster-configurator

Based on Zigbee Cluster Library; "It is used to configure clusters, attributes and other entities for Matter and Zigbee Pro applications"

• https://docs.silabs.com/zap-tool/1.1.0/zap-fundamentals/

• https://docs.silabs.com/zap-tool/1.1.0/zap-users-guide/

• https://github.com/project-chip/zap/blob/master/README.md

ZCL Advanced Platform

ZCL Advanced Platform

What is ZAP?

ZAP is a generic generation engine and user interface for applications and libraries based on Zigbee Cluster Library, the specification developed by the Connectivity Standards Alliance.

ZAP allows you to perform the following:

• perform SDK-specific customized generation of all global artifacts (constants, types, IDs, etc) based on the ZCL specification
• provide UI for the end-user to select specific application configuration (clusters, attributes, commands, etc.)
• perform SDK-specific customized generation of all user selected configuration artifacts (application configuration, endpoint configuration, etc) based on ZCL specification and customer-provided application configuration.

ZAP is a generic templating engine. Examples are provided for how to generate artifacts for the C language environment, but one could easily add new templates for other language environments, such as C++, java, node.js, python or any other.

Quick setup

Refer to Setup Instructions

Source code

Refer to development instructions for more details.

License

This software is licensed under Apache 2.0 license.

Usage Documentation

• ZAP Fundamentals
• ZAP User's Guide

Detailed Developer Documentation

• ZAP Template Helpers
• ZAP External Template Helpers
• ZAP file Extensions
• Upgrading ZAP files with GSDK upgrades
• FAQ/Developer dependencies
• Release instructions
• Development Instructions
• Design
• Template tutorial
• SDK integration guideline
• Custom ZCL entities design
• API
• Coding standard

[luar123]

Yes it is probably overkill. And I have no idea how to integrate it with esp SDK.

[Hedda]

FYI, for reference, Nerivec is using ZAP for the reverse thing to check if Zigbee devices follow the ZCL spec:

• fix!: enhance ZCL specification Koenkk/zigbee-herdsman#1503

• "zspec/zcl/definition/datatypes.ts is auto-generated from ZAP (we can deprecated some of the manually defined stuff eventually)"

• "This would have been much easier if we could have used ZAP directly to generate the spec (instead of manually scripting to edit current), but with so many name mismatches that would be created, it would end up being a very big cross-repo update... Something to keep in mind for next Z2M major though."

• "ZAP could technically be used to generate the whole ZCL Clusters object for ZH, that's one of its purposes, but the problem is backwards compat with name changes (& customs), that would create a massive amount of changes needed in ZHC (& external converters). So, had to build a script to merge data instead."

As I understand it he linked the ZAP reto and automatically updates the clusters with ZAP data, (checking clusters against the ZCL specs).

• https://github.com/project-chip/zap/tree/master/zcl-builtin/dotdot