Introduction

The nodes of a ZigBee wireless network are based on device types defined by the ZigBee Alliance. Such a device type is a software entity that determines the functionality supported by a node. This chapter introduces ZigBee device types and describes related concepts that are required in programming software applications for ZigBee nodes.

Note: ZigBee device types have previously been collected together in market-specific application profiles, such as Home Automation. ZigBee 3.0 allows devices from different market sectors to exist in the same network. Therefore, application profiles are not so prevalent in ZigBee 3.0 but are still supported for backward compatibility.

ZigBee device types

A device type is a software entity which defines the functionality of a ZigBee node. The device type defines a collection of clusters that make up this functionality. A cluster is therefore a basic building-block of device functionality. Some clusters are mandatory and some are optional. For example, the Thermostat device uses the Basic and Temperature Measurement clusters, and can also use one or more optional clusters.

Note: The clusters used by a device type are supplied in the ZigBee Cluster Library (ZCL). The ZCL is detailed in the ZigBee Cluster Library (for ZigBee 3.0) User Guide (JNUG3132).

A device is an instance of a device type.

A network node can support more than one device type. The application for a device type runs on a software entity called an endpoint and each node can have up to 240 endpoints, numbered from 1.

In addition, every ZigBee 3.0 node must employ the following devices:

ZigBee Base Device (ZBD): This is a standard device type which handles fundamental operations such as commissioning. This device does not need an endpoint. The ZigBee Base Device is fully detailed in Zigbee Base Device.
ZigBee Device Objects (ZDO): This represents the ZigBee node type (Coordinator, Router, or End Device) and has a number of communication roles. This device occupies endpoint 0.

The relative locations of the different devices are indicated in Software Architecture.

Parent topic:Introduction

Software architecture

The figure below shows the basic ZigBee 3.0 software architecture, which illustrates the locations of the ZigBee devices.

For more detailed software architecture information, refer to the ZigBee 3.0 User Guide (JNUG3130).

Parent topic: Introduction

Shared device structure

The basic operations in a ZigBee 3.0 network are concerned with reading and setting the attribute values of the clusters of a device. In each device, attribute values are exchanged between the application and the ZigBee Cluster Library (ZCL) by means of a shared structure. This structure is protected by a mutex (described in the ZCL User Guide (JNUG3132)). The structure for a particular device contains structures for the clusters supported by that device.

Note: In order to use a cluster which is supported by a device, the relevant option for the cluster must be specified at build-time - see Compile-time options.

A shared device structure may be used in either of the following ways:

The local application writes attribute values to the structure, allowing the ZCL to respond to commands relating to these attributes.
The ZCL parses incoming commands that write attribute values to the structure. The written values can then be read by the local application.

Remote read and write operations involving a shared device structure are illustrated in the figure below.

As shown in the above figure, the shared device structure is located on the server device, which hosts the cluster server to be accessed. The client device, which performs the remote access, hosts the corresponding cluster client. See

Note: If there are no remote attribute writes, the attributes of a cluster server (in the shared structure) on a device are maintained by the local application.

For more detailed descriptions of these operations, refer to the ZCL User Guide (JNUG3132).

Parent topic: Introduction

Endpoint callback functions

A user-defined callback function must be provided for each endpoint used. The callback function is invoked when an event occurs (such as an incoming message) relating to the endpoint. The callback function is registered when the endpoint is registered using the registration function for the device type that the endpoint supports (see Device initialization) - for example, using the function eZLO_RegisterOnOffLightEndPoint() for an On/Off Light device (see On/Off light).

The endpoint callback function has the type definition given below:

typedef void (* tfpZCL_ZCLCallBackFunction)
(tsZCL_CallBackEvent *pCallBackEvent);

Here, pCallBackEvent is a pointer to the pCallBackEvent event.

Note: Events that do not have an associated endpoint are delivered via the general stack-supplied callback function APP_vGenCallback(). For example, stack leave and join events can be received by the application through this callback function. Stack events are described in the ZigBee 3.0 Stack User Guide (JNUG3130).

Parent topic: Introduction

Device initialization

A ZigBee 3.0 application is initialized as described in the section “Forming and Joining a Network” of the ZigBee 3.0 Stack User Guide (JNUG3130). In addition, some device initialization must be performed.

ZigBee devices must be initialized in the following order and steps:

In the header file zcl_options.h, enable the required compile-time options. These options include the clusters to be used by the device, the client/server status of each cluster and the optional attributes for each cluster. For more information on compile-time options, refer to Compile-time options.
In the application, create an instance of the device structure by declaring a file scope variable - for example:

tsZLO_DimmableLightDevicesDevice;

In the initialization part of the application, set up the device handled by your code, as follows:

a) Set the initial values of the cluster attributes to be used by the device - for example:

sDevice.sBasicCluster.u8StackVersion=1;
sDevice.sBasicCluster....

b) After calling eZCL_Initialise() and before calling ZPS_eAplAfInit(), register the device by calling the relevant device registration function - for example, eZLO_RegisterDimmableLightEndPoint(). In this function call, the device allocates a unique endpoint (in the range 1-240). In addition, its device structure is specified as well as a user-defined callback function is invoked when an event occurs relating to the endpoint (see Section 1.5). As soon as this function has been called, the shared device structure is read by another device.

c) After calling ZPS_eAplAfInit(), initialize and start the ZigBee Base Device (ZBD) by calling BDB_vInit() and then BDB_vStart(). Refer to Section 2.1 for more details of ZigBee Base Device initialization.

Note:

The set of endpoint registration functions for the different device types is detailed in the device type descriptions - for example, in Chapter 3 for Lighting and Occupancy devices.
The device registration functions create instances of all the clusters used by the device. Thus, there is no need to call the individual cluster creation functions explicitly, for example, eCLD_IdentifyCreateIdentify() for the Identify cluster.

Parent topic:Introduction

Compile-time options

Before a ZigBee 3.0 application is built, configure compile-time options in the header file zcl_options.h for the application.

Note:

Cluster-specific compile-time options are detailed in the cluster descriptions in the ZCL User Guide (JNUG3132).
In addition, set compile-time options for the ZigBee Base Device in the file bdb_options.h - see Section 2.10.

Number of Endpoints

An application must specify the highest numbered endpoint used by it - for example:

#define BDB_FB_NUMBER_OF_ENDPOINTS3

Normally, the endpoints starting at endpoint 1 are for application use, so the above case uses endpoints 1 to 3. It is possible, however, to use the lower numbered endpoints for non-application purposes, for example, to run other protocols on endpoints 1 and 2, and the application on endpoint 3. With BDB_FB_NUMBER_OF_ENDPOINTS set to 3, some storage is statically allocated for endpoints 1 and 2 but never used. Note that this define applies only to local endpoints - the application can refer to remote endpoints with numbers beyond the locally defined value of BDB_FB_NUMBER_OF_ENDPOINTS.

Manufacturer Code

The ZCL allows a manufacturer code to define devices developed by a certain manufacturer. The value allocated to a manufacturer by the ZigBee Alliance is a 16-bit and is set as follows:

#define ZCL_MANUFACTURER_CODE 0x1037

The above example sets the manufacturer code to the default value of 0x1037 (which belongs to NXP) but manufacturers should set their own allocated value.

Enabled Clusters

Enable all the required clusters in the options header file. For example, an application for an On/Off Light device that uses all the possible clusters requires the following definitions:

#define CLD_BASIC
#define CLD_IDENTIFY
#define CLD_GROUPS
#define CLD_SCENES
#define CLD_ONOFF

Server and Client options

Many clusters have options that indicate whether the cluster acts as a server or a client on the local device. If the cluster is enabled using one of the above definitions, define the server/client status of the cluster. For example, to employ the Groups cluster as a server, include the following in the header file:

#define GROUPS_SERVER

Support for attribute Read/Write

Compile read/write access to cluster attributes into the application explicitly. Separately enable the server and client sides of a cluster using the following macros in the options header file:

#define ZCL_ATTRIBUTE_READ_SERVER_SUPPORTED
#define ZCL_ATTRIBUTE_READ_CLIENT_SUPPORTED
#define ZCL_ATTRIBUTE_WRITE_SERVER_SUPPORTED
#define ZCL_ATTRIBUTE_WRITE_CLIENT_SUPPORTED

Each of the above definitions applies to all clusters used in the application.

Optional attributes

Many clusters have optional attributes that may enable at compile time via the options header file - for example, the Basic cluster ‘application version’ attribute is enabled as follows:

#define CLD_BAS_ATTR_APPLICATION_VERSION

Parent topic:Introduction