Time-Synchronization of Devices

The devices in a ZigBee PRO network may need to be time-synchronized (so that they all refer to the same time). In this case, the Time cluster is used and one device acts as the Time cluster server and time-master from which the other devices set their time.

Note: Synchronization with a time-master is not required in all networks. In such cases, it is sufficient to use the ZCL time without synchronization between devices, as described in Section 18.4.

There are two times on a device that should be maintained during the synchronisation process:

  • Time attribute of the Time cluster (utctTime field of tsCLD_Time structure)

  • ZCL time

On the time-master, these times are initialized by the local application using an external master time and are subsequently maintained using a local one-second timer (see Section 18.5.1), as well as occasional re-synchronizations with external master time.

On all other devices, these times are initialized by the local application by synchronizing with the time-master (see Section 18.5.2). The ZCL time is subsequently maintained using a local one-second timer and both times are occasionally re-synchronized with the time-master (see Section 18.5.3).

synchronization with the time-master is normally performed via the Time cluster.

CAUTION:

If there is more than one Time cluster server in the network, devices should only attempt to synchronize to one server in order to prevent their clocks from repeatedly jittering backwards and forwards.

The figure below provides an overview of the time initialization and synchronization processes described in the sub-sections that follow.

Time Initialization and Synchronization

Time Initialization and Synchronization

Initialising and Maintaining Master Time

The time-master must initially obtain a master time from an external source. The application on the time-master must use this time to set its ZCL time by calling the function vZCL_SetUTCTime() and to set the value of the Time cluster attribute utctTime in the local tsCLD_Time structure within the shared device structure (securing access with a mutex). The application must also set (to ‘1’) the ‘Master’ bit of the u8TimeStatus attribute of the tsCLD_Time structure, to indicate that this device is the time-master and that the time has been set.

Note: The ‘Synchronised’ bit of the u8TimeStatus attribute should always be zero on the time-master, as this device does not synchronise to any other device within the ZigBee network.

If the time-master has also obtained time-zone and daylight saving information (or has been pre-programmed with this information), its application must set (to ‘1’) the ‘Master for Time Zone and DST’ bit of the u8TimeStatus attribute and write the relevant optional attributes. These optional attributes can then be used to provide time-zone and daylight saving information to other devices (see Section 18.3).

Note: The time-master can prevent other devices from attempting to read its Time cluster attributes before the time has been set - the initialization of the master time should be done after registering the endpoint for the device and before starting the ZigBee PRO stack.

The ZCL time and the utctTime attribute are subsequently incremented from a local one-second timer, as follows. On expiration of the timer, an event is generated (from the hardware/software timer that drives the one-second timer), which causes a ZCL user task to be activated. The event is initially handled by this task as described in Section 3.2, resulting in an E_ZCL_CBET_TIMER event being passed to the ZCL via the function vZCL_EventHandler(). The following actions should then be performed:

  1. The ZCL automatically increments the ZCL time and may run cluster-specific schedulers (e.g. for maintaining a price list).

  2. The user task updates the value of the utctTime attribute of the tsCLD_Time structure within the shared device structure (securing access with a mutex).

  3. The user task resumes the one-second timer.

Both the ZCL time and the utctTime attribute must also be updated by the application when an update of the master time is received.

Parent topic:Time-Synchronization of Devices

Initial Synchronisation of Devices

It is the responsibility of the application on a ZigBee PRO device to perform time-synchronisation with the time-master. The application can remotely read the Time cluster attributes from the time-master by calling the function eZCL_SendReadAttributesRequest(), which will result in a ‘read attributes’ response containing the Time cluster data. On receiving this response, a ‘data indication’ stack event is generated on the local device, which causes a ZCL user task to be activated. The event is initially handled by this task as described in Section 3.2, resulting in an E_ZCL_ZIGBEE_EVENT event being passed to the ZCL via the function vZCL_EventHandler(). Provided that the event contains a message incorporating a ‘read attributes’ response, the ZCL:

  1. automatically sets the utctTime field of the tsCLD_Time structure to the value of the same attribute in the ‘read attributes’ response (and also sets other Time cluster attributes, if requested)

  2. invokes the relevant user-defined callback function (see Chapter 3), which must read the local utctTime attribute (securing access with a mutex) and use this value to set the ZCL time by calling the function vZCL_SetUTCTime()

Note: When a device attempts to time-synchronise with the time-master, it should check the u8TimeStatus attribute in the ‘read attributes’ response. If the ‘Master’ bit of this attribute is not equal to ‘1’, the obtained time should not be trusted and the time should not be set. The device should wait and try to synchronise again later.

It may also be possible to obtain time-zone and daylight saving information from the time-master. If available, this information will be returned in the ‘read attributes’ response. However, before using these optional Time cluster attributes from the response, the application should first check that the ‘Master for Time Zone and DST’ bit of the u8TimeStatus attribute is set (to ‘1’) in the response.

The ZCL time and utctTime attribute value on the local device are subsequently maintained as described in Section 18.5.3.

Parent topic:Time-Synchronization of Devices

Re-synchronisation of Devices

After the initialization described in Section 18.5.2, the ZCL time must be updated by the application on each one-second tick of the local timer. The ZCL time is updated from the timer in the same way as described in Section 18.4.

Due to the inaccuracy of the local one-second timer, the ZCL time is likely to lose synchronisation with the time on the time-master. It will therefore be necessary to occasionally re-synchronise the local ZCL time with the time-master - the utctTime attribute value is also updated at the same time. A device can re-synchronise with the time-master by first remotely reading the utctTime attribute using the function eZCL_SendReadAttributesRequest(). On receiving the ‘read attributes’ response from the time-master, the operations performed are the same as those described for initial synchronisation in Section 18.5.2.

Parent topic:Time-Synchronization of Devices

Parent topic:Time Cluster and ZCL Time