Files
file	zcl_time.h
	Header for implementation of ZigBee Time Cluster (ZCL Spec section 3.12).

file	zcl_time.c
	Client and server code to implement the ZigBee Time Cluster.

Macros
#define	zcl_gmtime(tm, timestamp) xbee_gmtime( tm, timestamp)

#define	zcl_mktime(tm) xbee_mktime( tm)

#define	ZCL_CLUST_ENTRY_TIME_BOTH
	Macro for inserting a standard Time Server (and Client) into an endpoint's cluster list. More...

#define	ZCL_CLUST_ENTRY_TIME_SERVER
	Macro for inserting a standard Time Server (no Client) into an endpoint's cluster list. More...

#define	ZCL_CLUST_ENTRY_TIME_CLIENT
	Macro for inserting a standard Time Client (no Server) into an endpoint's cluster list. More...

#define	_zcl_time_debug

Functions
zcl_utctime_t	zcl_time_now (void)
	Returns the current date/time, using the ZCL epoch of January 1, 2000. More...

int	zcl_time_client (const wpan_envelope_t FAR envelope, void FAR context)
	Handle Read Attribute Responses to requests sent as part of the zcl_time_find_servers() process. More...

int	zcl_time_find_servers (wpan_dev_t *dev, uint16_t profile_id)
	Find Time Servers on the network, query them for the current time and then synchronize this device's clock to that time. More...

int	_zcl_time_time_set (const zcl_attribute_full_t FAR attribute, zcl_attribute_write_rec_t rec)
	Function registered to ZCL_TIME_ATTR_TIME attribute of Time Cluster and called to modify the attribute. Also called internally to update the zcl_time_skew global. More...

uint_fast8_t	_zcl_time_time_get (const zcl_attribute_full_t FAR *attribute)
	Function registered to ZCL_TIME_ATTR_TIME attribute of Time Cluster and called to refresh the Time attribute (global zcl_time_time). More...

int	_zcl_time_timestatus_set (const zcl_attribute_full_t FAR attribute, zcl_attribute_write_rec_t rec)
	Special code for setting bitfield of TimeStatus attribute. More...

Variables
const zcl_attribute_tree_t	zcl_time_attribute_tree []

zcl_utctime_t	zcl_time_time
	Current value of Time Attribute (ZCL_TIME_ATTR_TIME), start value doesn't matter since it is set by _zcl_time_time_get(). More...

uint8_t	zcl_time_timestatus = 0
	Current value of TimeStatus Attribute (ZCL_TIME_ATTR_TIME_STATUS)

int32_t	zcl_time_skew = 0
	difference between xbee_seconds_timer() and actual calendar time

struct {
zcl_attribute_full_t time

zcl_attribute_full_t time_status

uint16_t end_of_list

}	zcl_time_attr
	Global attribute list used in ZCL_CLUST_ENTRY_TIME_SERVER and for adding a Time Cluster Server to an endpoint. More...

const zcl_attribute_tree_t	zcl_time_attribute_tree []

Attributes of ZCL Time Cluster
#define	ZCL_TIME_ATTR_TIME 0x0000
	3.12.2.2.1 Time Attribute

#define	ZCL_TIME_ATTR_TIME_STATUS 0x0001
	3.12.2.2.2 TimeStatus Attribute

#define	ZCL_TIME_ATTR_TIME_ZONE 0x0002
	3.12.2.2.3 TimeZone Attribute

#define	ZCL_TIME_ATTR_DST_START 0x0003
	3.12.2.2.4 DstStart Attribute

#define	ZCL_TIME_ATTR_DST_END 0x0004
	3.12.2.2.5 DstEnd Attribute

#define	ZCL_TIME_ATTR_DST_SHIFT 0x0005
	3.12.2.2.6 DstShift Attribute

#define	ZCL_TIME_ATTR_STANDARD_TIME 0x0006
	3.12.2.2.7 StandardTime Attribute

#define	ZCL_TIME_ATTR_LOCAL_TIME 0x0007
	3.12.2.2.8 LocalTime Attribute

Bitfields for attribute ZCL_TIME_ATTR_TIME, TimeStatus. Bits 3-7 are reserved. Per Section 3.12.2.2.2 of the ZCL spec: If the Master bit is 1, the value of [the Synchronized bit] is 0. If both the Master and Synchronized bits are 0, the real time clock has no defined relationship to the time standard.
#define	ZCL_TIME_STATUS_MASTER 0x01
	The RTC corresponding to the Time attribute is internally set to the time standard. More...

#define	ZCL_TIME_STATUS_SYNCHRONIZED 0x02
	The Synchronized bit specifies whether Time has been set over the [ZigBee] network to synchronize it (as close as may be practical) to the time standard (see 3.12.1). More...

#define	ZCL_TIME_STATUS_MASTERZONEDST 0x04
	The MasterZoneDst bit specifies whether the TimeZone, DstStart, DstEnd and DstShift attributes are set internally to correct values for the location of the clock. More...

Detailed Description

Macro Definition Documentation

#define ZCL_CLUST_ENTRY_TIME_BOTH

Value:

{ ZCL_CLUST_TIME,                \
         &zcl_time_client,             \
         zcl_time_attribute_tree,      \
         WPAN_CLUST_FLAG_INOUT | WPAN_CLUST_FLAG_ENCRYPT }

Macro for inserting a standard Time Server (and Client) into an endpoint's cluster list.

#define ZCL_CLUST_ENTRY_TIME_CLIENT

Value:

{ ZCL_CLUST_TIME,                \
         &zcl_time_client,             \
         zcl_attributes_none,          \
         WPAN_CLUST_FLAG_CLIENT | WPAN_CLUST_FLAG_ENCRYPT }

Macro for inserting a standard Time Client (no Server) into an endpoint's cluster list.

#define ZCL_CLUST_ENTRY_TIME_SERVER

Value:

{ ZCL_CLUST_TIME,                \
         &zcl_general_command,         \
         zcl_time_attribute_tree,      \
         WPAN_CLUST_FLAG_SERVER | WPAN_CLUST_FLAG_ENCRYPT }

Macro for inserting a standard Time Server (no Client) into an endpoint's cluster list.

#define ZCL_TIME_STATUS_MASTER 0x01

The RTC corresponding to the Time attribute is internally set to the time standard.

This bit should only be set if the host has reliably set its RTC.

Referenced by _zcl_time_time_set(), _zcl_time_timestatus_set(), zcl_time_client(), and zcl_time_now().

#define ZCL_TIME_STATUS_MASTERZONEDST 0x04

The MasterZoneDst bit specifies whether the TimeZone, DstStart, DstEnd and DstShift attributes are set internally to correct values for the location of the clock.

#define ZCL_TIME_STATUS_SYNCHRONIZED 0x02

The Synchronized bit specifies whether Time has been set over the [ZigBee] network to synchronize it (as close as may be practical) to the time standard (see 3.12.1).

Referenced by _zcl_time_timestatus_set(), zcl_time_client(), and zcl_time_now().

Function Documentation

uint_fast8_t _zcl_time_time_get ( const zcl_attribute_full_t FAR * attribute )

Function registered to ZCL_TIME_ATTR_TIME attribute of Time Cluster and called to refresh the Time attribute (global zcl_time_time).

See zcl_attribute_update_fn() for calling convention.

References PRIx32, XBEE_UNUSED_PARAMETER, zcl_time_skew, and zcl_time_time.

Referenced by _zcl_time_timestatus_set(), and zcl_time_now().

int _zcl_time_time_set	(	const zcl_attribute_full_t FAR *	attribute,
		zcl_attribute_write_rec_t *	rec
	)

Function registered to ZCL_TIME_ATTR_TIME attribute of Time Cluster and called to modify the attribute. Also called internally to update the zcl_time_skew global.

Parameters

[in]	attribute	ignored; assumed to point to zcl_time_time
[in,out]	rec	if NULL, function was called internally to update zcl_time_skew only

See zcl_attribute_write_fn() for calling convention.

References zcl_attribute_write_rec_t::buffer, zcl_attribute_write_rec_t::flags, PRId32, PRIx32, zcl_attribute_write_rec_t::status, ZCL_ATTR_WRITE_FLAG_ASSIGN, zcl_decode_attribute(), zcl_time_skew, ZCL_TIME_STATUS_MASTER, zcl_time_time, and zcl_time_timestatus.

Referenced by _zcl_time_timestatus_set(), and zcl_time_client().

int _zcl_time_timestatus_set	(	const zcl_attribute_full_t FAR *	attribute,
		zcl_attribute_write_rec_t *	rec
	)

Special code for setting bitfield of TimeStatus attribute.

See ZCL Spec section 3.12.2.2.2 for rules on setting values in this field.

Only used if device has a Time Server.

References _zcl_time_time_get(), _zcl_time_time_set(), zcl_attribute_write_rec_t::buffer, zcl_attribute_write_rec_t::flags, XBEE_UNUSED_PARAMETER, ZCL_ATTR_WRITE_FLAG_ASSIGN, ZCL_ATTRIB_FLAG_FULL, ZCL_ATTRIBUTE_END_OF_LIST, zcl_time_attr, ZCL_TIME_ATTR_TIME, ZCL_TIME_ATTR_TIME_STATUS, ZCL_TIME_STATUS_MASTER, ZCL_TIME_STATUS_SYNCHRONIZED, zcl_time_time, zcl_time_timestatus, and ZCL_TYPE_TIME_UTCTIME.

int zcl_time_client	(	const wpan_envelope_t FAR *	envelope,
		void FAR *	context
	)

Handle Read Attribute Responses to requests sent as part of the zcl_time_find_servers() process.

This function expects to receive "read attribute response" packets ONLY for reads of Time and TimeStatus.

If responding device is a master or is synchronized with one, use it's Time value to update a "skew" global used to track the offset between system time (which may just be "seconds of uptime") and calendar time.

Parameters

[in]	envelope	envelope from received message
[in]	context	pointer to attribute list for cluster (typically passed in via endpoint dispatcher)

Return values

0	Command was processed and default response (with either success or error status) was sent.
!0	Error sending default response; time may or may not have been set.

References _zcl_time_time_set(), zcl_command_t::command, FAR, zcl_command_t::frame_control, hex_dump(), HEX_DUMP_FLAG_TAB, le16toh, le32toh, PRIu32, ZCL_CMD_MATCH, ZCL_CMD_READ_ATTRIB_RESP, zcl_command_build(), zcl_default_response(), zcl_general_command(), ZCL_TIME_ATTR_TIME, ZCL_TIME_ATTR_TIME_STATUS, ZCL_TIME_STATUS_MASTER, ZCL_TIME_STATUS_SYNCHRONIZED, zcl_time_time, zcl_time_timestatus, and ZCL_TYPE_TIME_UTCTIME.

int zcl_time_find_servers	(	wpan_dev_t *	dev,
		uint16_t	profile_id
	)

Find Time Servers on the network, query them for the current time and then synchronize this device's clock to that time.

Note: This function uses a static buffer to hold context information for the ZDO responder that generates the ZCL Read Attributes request. Wait at least 60 seconds between calls to allow for earlier requests to time out.; This function will only work correctly if the Time Cluster Client in your endpoint table is using the zcl_time_client() function as its callback handler. If you use the ZCL_CLUST_ENTRY_TIME_CLIENT or ZCL_CLUST_ENTRY_TIME_BOTH macro, the client cluster is set up correctly.

Parameters

[in]	dev	device to send query on
[in]	profile_id	profile ID to match in endpoint table or #WPAN_APS_PROFILE_ANY to use the first endpoint with a Time Cluster Client

Return values

0	Successfully issued ZDO Match Descriptor Request to find Time Cluster Servers on the network. No guarantee that we'll get a response.
!0	Some sort of error occurred in generating or sending the ZDO Match Descriptor Request.
-EINVAL	Couldn't find a Time Cluster Client with `profile_id` in the endpoint table of `dev`.

References EINVAL, WPAN_CLUST_FLAG_CLIENT, WPAN_CLUSTER_END_OF_LIST, wpan_endpoint_of_cluster(), ZCL_ATTRIBUTE_END_OF_LIST, zcl_find_and_read_attributes(), ZCL_TIME_ATTR_TIME, and ZCL_TIME_ATTR_TIME_STATUS.

zcl_utctime_t zcl_time_now ( void )

Returns the current date/time, using the ZCL epoch of January 1, 2000.

Assumes that device has connected to a time server and updated its clock accordingly. Returns ZCL_UTCTIME_INVALID if the device has not synchronized its clock.

Do not use this value for tracking elapsed time – use xbee_seconds_timer() or xbee_millisecond_timer() instead. The value may jump forward (or even backward) when the device decides to synchronize with a time server.

Return values

ZCL_UTCTIME_INVALID	Clock not synchronized to a time source.
0-0xFFFFFFFE	Number of elapsed seconds since midnight UTC on January 1, 2000.

See also: xbee_seconds_timer, xbee_millisecond_timer

References _zcl_time_time_get(), ZCL_TIME_STATUS_MASTER, ZCL_TIME_STATUS_SYNCHRONIZED, zcl_time_time, and zcl_time_timestatus.

Variable Documentation

const { ... } zcl_time_attr

Initial value:

=
{
   { { ZCL_TIME_ATTR_TIME,
      ZCL_ATTRIB_FLAG_FULL,
      ZCL_TYPE_TIME_UTCTIME,
      &zcl_time_time },
      { 0 }, { 0 },
      &_zcl_time_time_get, &_zcl_time_time_set },
   { { ZCL_TIME_ATTR_TIME_STATUS,
      ZCL_ATTRIB_FLAG_FULL,
      ZCL_TYPE_BITMAP_8BIT,
      &zcl_time_timestatus },
      { 0 }, { 0 },
      NULL, &_zcl_time_timestatus_set },
   ZCL_ATTRIBUTE_END_OF_LIST
}