Link Search Menu Expand Document
Libertas Things Documentation

Device Descriptions - ZDO

At the end of the device joining process. The Hub (trust center) will wirelessly query device descriptions, primarily the device type and capabilities of the device.

Device Endpoints

A physical device may contain more than 1 endpoints.

Each endpoint can be viewed as a particular component within the physical device.

For example, a on/off light switch with 3 buttons may have a total of 4 endpoints,

  1. An on/off light device
  2. 3 extra buttons

In Hornet, we also call endpoint a “logical device”.

Each endpoint is uniquely assigned a number between 1 and 240. Note the endpoint number does NOT need to be consecutive. In the example above, the device with 4 endpoints numbered as 1, 10, 11, 12 is perfectly normal.

Cluster

Each endpoint shall have clusters. The clusters are devided into two sets, input clusters and output clusters, which may not be the same set.

Each cluster is assigned a 16bit ID. Zigbee defined many commonly used cluster ID. Hornet adopted the design of Zigbee Cluster Library. We also need to add our own clusters because the current standard is far from complete.

Cluster can be viewed as “device capability”. For example, an on/off light shall define a “ON_OFF” (value is 0x0006) cluster as both input and output.

This is a list of cluster ID defined in Libertas IoT OS.

For more information about cluster programming, read next chapter.

Descriptions

During device join process, the Hub will query descriptions from the remote device to get more information about it.

Physical Device Descriptions

Libertas Hub will query two descriptions below,

  • Node Descriptor - Such as the device is a router or end device? etc.
  • Power Descriptor - Is it using battery or mains power? etc.

Hornet stack implementation will automatically answer the query request. Developer don’t need to do anything.

Endpoint (Logical Device) Descriptions

Libertas Hub will query descriptions of each end point. Developer is responsible to implement the code to answer the queries.

Developers’ Responsibilities

Developers is responsible for implementing the API to answer queries for endpoint descriptions.

extern void zdo_get_active_ep_list(uint8_t *buffer, uint8_t *size);
extern void zdo_get_simple_descriptor(uint8_t end_point, zdp_simple_descriptor_t *desc);
extern void zdo_get_ep_cluster_count(uint8_t end_point, uint8_t *input, uint8_t *output);
extern void zdo_get_ep_input_cluster(uint8_t end_point, uint16_t *buffer);
extern void zdo_get_ep_output_cluster(uint8_t end_point, uint16_t *buffer);

zdo_get_active_ep_list

Put the number of endpoint to the size argument. Note, there are at most 239 endpoints (1-240).

Also fill the endpoints to buffer. Note, the list shall be sorted.

The buffer is 256 bytes long. Do not overwrite the buffer.

zdo_get_simple_descriptor

Fill in the simple descriptor of specified endpoint.

typedef struct {
	uint8_t			end_point;
	uint16_t		application_profile_id;
	uint16_t		application_device_id;
	uint8_t			application_device_version : 4;
	uint8_t			reserved : 4;
} zdp_simple_descriptor_t;

Note we use ZCL_HA_PROFILE_ID as application_profile_id.

application_device_id is a 16 bit integer. Here is a list of known device ID for Libertas Hub.

zdo_get_ep_cluster_count

Returns input and output cluster count forgiuven endpoint.

zdo_get_ep_input_cluster

Fill in the list of the input cluster of given endpoint.

Note an endpoint can support up to 127 clusters. The buffer is 128 size long. Do not overwrite it!

Also the number of clusters in the list must match the count returned from zdo_get_ep_cluster_count.

zdo_get_ep_output_cluster

Fill in the list of the output cluster of given endpoint.

Note an endpoint can support up to 127 clusters (input or output). The buffer is 128 size long. Do not overwrite it!

Also the number of clusters in the list must match the count returned from zdo_get_ep_cluster_count.