Zigbee Implementation: ZCL Time Client (ZigBee Time Extension) support + Zigbee Time Client examples

[Hedda]

Related area

Zigbee

Hardware specification

ESP32-C6

Is your feature request related to a problem?

Related to #10135 (Implement Zigbee in Arduino) and feature requests posted there about Time Client in Zigbee devices.405

ZCL Time Client looks to be missing, and Zigbee Time Client is needed to make a smart thermostat or HVAC with local timer.

Note that Time cluster shuld be in UTC, see -> espressif/esp-zigbee-sdk#446

Describe the solution you'd like

ZCL Time Client support + Zigbee example of HVAC or thermostat and similar using Time Client for local timers on ESP32-C6?

Describe alternatives you've considered

Stumbled on these PRs for OpenHAB's ZigBee Binding and the com.zsmartsystems.zigbee library/framework it depends on which just made me a little curious if you happen to know if this ZigBeeTimeExtension and ZigbeeUtcTime class / Zigbee Time Cluster + time client/server (ZCL time server) support is used and required by any Zigbee (3.0) devices in the available real-world consumer products and not just commercial products for Zigbee Smart Energy (Zigbee SE) devices like those used by energy utility companies (such as in the electricity meter they install in your house)? See:

openhab/org.openhab.binding.zigbee#791

and

zsmartsystems/com.zsmartsystems.zigbee#1371

Silicon Labs have an sample Zigbee application example of a such device with "Zigbee RTC Time Synchronization":

https://github.com/SiliconLabs/zigbee_applications/tree/master/zigbee_rtc_time_sync

"In a common Zigbee network, the gateway normally has the capability of connecting to the internet, so it can get the date and time through NTP. Therefore, the gateway can act as the time server to provide the time source for the other Zigbee devices. This example demonstrates how we synchronize the date and time in the Zigbee network. On the device side, the local date and time will be kept by the plugin Simple Clock."

I do not have any such device however searching a little online a found some references that Zigbee Time Cluster is probably used in some Zigbee thermostats(?) as well as the more obviously smart energy (electricity and water consumption management devices that act as DLMS/COSEM bridges) such as for example smart reader products for the "HAN" (Home Area Network) ports that are common in electricity meters in Scandinavia and P1 port in Holland.

https://www.digi.com/resources/documentation/digidocs/90001931/general_operation/general_operation.html

https://community.silabs.com/s/question/0D51M00007xeTqISAU/zigbee-time-cluster?language=en_US

https://e2e.ti.com/support/wireless-connectivity/zigbee-thread-group/zigbee-and-thread/f/zigbee-thread-forum/759125/cc2530-zstack-3-linux-gateway---add-support-for-coordinator-time-cluster

https://digidotcom.github.io/xbee_ansic_library/group__zcl__time.html

https://community.nxp.com/t5/Wireless-Connectivity/JN5179-ZigBee-3-0-Time-Cluster/m-p/613616

https://developer.nordicsemi.com/nRF_Connect_SDK/doc/zboss/3.11.1.177/group___z_b___z_c_l___t_i_m_e___a_t_t_r_s.html

https://developer.nordicsemi.com/nRF_Connect_SDK/doc/zboss/3.12.1.0/group___z_b___z_c_l___t_i_m_e___c_o_m_m_a_n_d_s.html

This creates a ZigBeeUtcTime class for managing time on a remote device. It then supports a ZigBeeTimeExtension which in turn can provide a local ZclTimeClient or ZclTimeServer to manage the time on the remote device.

The ZclTimeServer is relatively simple in that it just responds to requests from the device.

The ZclTimeClient is in itself also simple in that it provides methods to set the time on the remote.

The ZigBeeTimeExtension tries to automate the time management by working out drift rates, and setting the clock proactively if the time has drifted outside spec and the device didn't update the time through a request to the ZclTimeServer.

There is also a ZigBeeConsoleTimeCommand console command to get or set the time, and display the various information.

This is potentially a breaking change if people are using time at the moment since this changes some interfaces from Calendar to ZigBeeUtcTime.

Additional context

FYI, noticed that zha-toolkit has a feature for misc_settime for setting attributes of a Time Cluster from HA's current time and timezone:

https://github.com/mdeweerd/zha-toolkit/blob/main/README.md#misc_settime-set-attributes-of-a-time-cluster

misc_settime: Set attributes of a Time Cluster

Sets the time and DST configuration for a Time Cluster from HA's current time and default timezone.

The TimeStatus attribute is not set. You likely need to set it to 2 (synchronized).

Before and after writing, the attributes are read from the cluster and available in the event data, unless options disable these reads.

service: zha_toolkit.misc_settime
data:
  ieee: 5c:02:72:ff:fe:92:c2:5d
  # The endpoint is optional - by default the endpoint containing the Time Cluster
  endpoint: 11
  # You can set the next events to use as a trigger.
  # The event data has the result of the command (currently attr_read, attr_write)
  event_success: my_read_success_trigger_event
  event_fail: my_read_fail_trigger_event
  event_done: my_read_done_trigger_event
  # Settings for attr_write
  # Read attribute before writing it (defaults to True)
  read_before_write: true
  # Read attribute after writing it (defaults to True)
  read_after_write: true

I have checked existing list of Feature requests and the Contribution Guide

• I confirm I have checked existing list of Feature requests and Contribution Guide.

[P-R-O-C-H-Y]

Hi @Hedda, as the time cluster have been fixed in esp-zigbee-sdk 1.6.0 which is currently used I will start working on implementing that soon :)