Configuration of Zigbee 3.0 device on KW41Z

[#1]

In developing a Zigbee application, certain static configuration is required before the application is built. Configuring the network size, adding a new cluster, making the device discoverable and adding a new endpoint can be done by changing parameters in the following files:

1. app_zps_cfg.h
2. app_zcl_cfg.h
3. app_zcl_global.c

These files are responsible for setting up network parameters like device type and associated parameters, mainly related to the APS and NWK layers of the ZigBee PRO stack.

Network Configuration

The ZigBee device can be configured to be a coordinator, router and end device. The following section details the way in which the user can configure each device type.

The app_zps_cfg header file lets the user configure the ZPS ZDO parameters of the node. The following macros are necessary for the corresponding device types:

• For coordinator in a ZigBee network

  #define ZPS_COORDINATOR
  #define ZPS_ZDO_DEVICE_TYPE                              ZPS_ZDO_DEVICE_COORD

• For router in a ZigBee network

  #define ZPS_ROUTER
  #define ZPS_ZDO_DEVICE_TYPE                              ZPS_ZDO_DEVICE_ROUTER

• For enddevice in a ZigBee network

  #define ZPS_ENDDEVICE
  #define ZPS_ZDO_DEVICE_TYPE                              ZPS_ZDO_DEVICE_ENDDEVICE

Other ZPS ZDO configurations which are defined using macro are explained in comments inside the header file (app_zps_cfg.h). These macros provide the user with the ability to configure the device according to their network needs.

The type of security for the ZigBee network can also be configured by the macro ZPS_ZDO_NWK_KEY_STATE. The user can change the security type to no network security (ZPS_ZDO_NO_NETWORK_KEY), pre-configured link key security (ZPS_ZDO_PRECONFIGURED_LINK_KEY), distributed link key security (ZPS_ZDO_DISTRIBUTED_LINK_KEY) or pre-configured installation code security (ZPS_ZDO_PRCONFIGURED_INSTALLATION_CODE).

/* Specify No network Security */
#define ZPS_ZDO_NWK_KEY_STATE                               ZPS_ZDO_NO_NETWORK_KEY

The application allows through this header file to configure ZPS APS AIB parameters, like extended PANID (ZPS_APS_AIB_INIT_USE_EXTENDED_PANID) or channel mask (ZPS_APS_AIB_INIT_CHANNEL_MASK).

/* NWK EXTENDED PANID (EPID) that the device will use.*/
#define ZPS_APS_AIB_INIT_USE_EXTENDED_PANID                 0x0000000000000000ULL
/*! CHANNEL MASK : Define all channels from 11 to 26*/
#define ZPS_APS_AIB_INIT_CHANNEL_MASK                       0x07fff800UL

User can also configure the simple descriptor table size (AF_SIMPLE_DESCRIPTOR_TABLE_SIZE) as part of the ZPS AF Layer configuration parameters.The value depends on number of endpoints defined in application, one endpoint is always reserved for ZDO . So, for a device with one endpoint, the value would be 2 (1 ZDO + 1 application endpoint)

#define AF_SIMPLE_DESCRIPTOR_TABLE_SIZE                     2

Among other ZPS network configuration parameters that can be changed by the user are scan duration (ZPS_SCAN_DURATION), default permit joining time (ZPS_DEFAULT_PERMIT_JOINING_TIME) and the maximum number of simultaneous key requests (ZPS_MAX_NUM_SIMULTANEOUS_REQUEST_KEY_REQS).

Also, NIB values can be changed, like for example, the maximum number of routers in the network (ZPS_NWK_NIB_INIT_MAX_ROUTERS), the maximum number of children for a node (ZPS_NWK_NIB_INIT_MAX_CHILDREN), the maximum network depth (ZPS_NWK_NIB_INIT_MAX_DEPTH) or the network security level (ZPS_NWK_NIB_INIT_SECURITY_LEVEL).

Different ZigBee network table sizes can be adjusted by the user from this header file. The important tables are mentioned below:

1. The active neighbor table size (ZPS_NEIGHBOUR_TABLE_SIZE).
2. The neighbor discovery table size, used to keep a list of the neighboring devices associated with the node (ZPS_NEIGHBOUR_DISCOVERY_TABLE_SIZE).
3. The network address map table size, which represents the size of the address map that maps 64-bit IEEE addresses to 16-bit network (short) addresses (ZPS_ADDRESS_MAP_TABLE_SIZE).
4. The network security material set size (ZPS_SECURITY_MATERIAL_SETS).
5. The broadcast transaction table size, which stores the records of the broadcast messages received by the node (ZPS_BROADCAST_TRANSACTION_TABLE_SIZE).
6. The route record table size (ZPS_ROUTE_RECORD_TABLE_SIZE) for the table that records each route, storing the destination network address, a count of the number of relay nodes to reach the destination and a list of the network addresses of the relay nodes.
7. The route discovery table size (ZPS_ROUTE_DISCOVERY_TABLE_SIZE), used by the node to store temporary information used during route discovery.
8. The MAC address table size (ZPS_MAC_ADDRESS_TABLE_SIZE).
9. The binding table size (ZPS_BINDING_TABLE_SIZE).
10. The group table size (ZPS_GROUP_TABLE_SIZE).
11. The number of supported network keys, known also as the security material sets (ZPS_KEY_TABLE_SIZE).
12. The child table size (ZPS_CHILD_TABLE_SIZE), that gives the size of the persisted sub-table of the active neighbor table. The stored entries are for the node’s parent and immediate children.
13. The trust center device table size (ZPS_TRUST_CENTER_DEVICE_TABLE_SIZE).

ZCL Configuration

The app_zcl_cfg header file is used by the application to configure the ZigBee Cluster library. This file contains the definition for the application profile and cluster ids. The default application profiles are ZDP, HA, ZLO, GP.

The ZDP (ZigBee Device Profile) id is identified by the following line:

#define ZDP_PROFILE_ID             (0x0000)

ZDP provides services for the following categories as cluster Ids:

• Device discovery services (for example, ZDP_DISCOVERY_CACHE_REQ_CLUSTER_ID)
• Service discovery services (for example, ZDP_IEEE_ADDR_REQ_CLUSTER_ID)
• Binding services (for example, ZDP_BIND_RSP_CLUSTER_ID)
• Management services (for example, ZDP_MGMT_NWK_DISC_REQ_CLUSTER_ID)

The HA (Home Automation) profile id is identified by the following line:

#define HA_PROFILE_ID             (0x0104)

HA provides services for the following categories as cluster Ids:

• Generic devices (for example, HA_BASIC_CLUSTER_ID)
• Lighting devices (for example, HA_LEVELCONTROL_CLUSTER_ID)
• Intruder Alarm System (IAS) devices (for example, HA_IASZONE_CLUSTER_ID)

The ZLO (ZigBee Lighting and Occupancy) profile is not an application profile but devices in this collection use the same application profile id as for the Home Automation application profile. This ensures backward compatibility with applications for devices based on the Home Automation 1.2 profile.

ZigBee Green Power (GP) is an optional cluster with the aim of minimizing the power demands on a network node in order to support:

• Nodes that are completely self-powered through energy harvesting
• Battery-powered nodes that require ultra-long battery life

The GP profile id is identified by the following line:

#define GP_PROFILE_ID               (0xa1e0)

The Zigbee GP cluster ID is defined as following:

#define GP_GREENPOWER_CLUSTER_ID    (0x0021)

Depending on the application, the app_zcl_cfg header file also contains the defines for the node endpoints. For example, the occupancy_sensor application contains the following endpoints:

/* Node 'Coordinator' */
/* Endpoints */
#define COORDINATOR_ZDO_ENDPOINT    (0)
#define COORDINATOR_COORD_ENDPOINT    (1)
/* Node 'OccupancySensor' */
/* Endpoints */
#define OCCUPANCYSENSOR_ZDO_ENDPOINT    (0)
#define OCCUPANCYSENSOR_SENSOR_ENDPOINT    (1)
/* Node 'LightSensor' */
/* Endpoints */
#define LIGHTSENSOR_ZDO_ENDPOINT    (0)
#define LIGHTSENSOR_SENSOR_ENDPOINT    (1)
/* Node 'LightTemperatureOccupancySensor' */
/* Endpoints */
#define LIGHTTEMPERATUREOCCUPANCYSENSOR_ZDO_ENDPOINT    (0)
#define LIGHTTEMPERATUREOCCUPANCYSENSOR_SENSOR_ENDPOINT    (1)

The source file app_zcl_globals.c is used to declare the cluster lists for each endpoint. These act as simple descriptors for the node.

Each endpoint has two cluster lists, containing uint16_t data. One is for input and one for output. The sizes of these two lists must be equal. For example, for endpoint 0, the declared lists will be the following:

PRIVATE const uint16 s_au16Endpoint0InputClusterList[16]  =  { 0x0000, 0x0001, 0x0002, 0x0003, 0x0004, 0x0005, 0x0006 , 0x0007, \
                                                              0x0008, 0x0010, 0x0011, 0x0012, 0x0012, 0x0013, 0x0014 , 0x0015};
PRIVATE const uint16 s_au16Endpoint0OutputClusterList[16] =  { 0x0000, 0x0001, 0x0002, 0x0003, 0x0004, 0x0005, 0x0006 , 0x0007, \
                                                             0x0008, 0x0010, 0x0011, 0x0012, 0x0012, 0x0013, 0x0014 , 0x0015};

The input list must also have a corresponding cluster APDU list, matching in size. For the endpoint 0 example, this will look like:

PRIVATE const PDUM_thAPdu s_ahEndpoint0InputClusterAPdus[16] = { apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP,\
                                                                 apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP, apduZDP};

Each output and input cluster list has a corresponding cluster discovery enabled flags list. As each bit inside the Cluster Disc Flag corresponds to cluster , for 16 clusters declared in Input and Output cluster list, one needs 2 bytes for Discoverable flag. In this example, the declaration is the following:

PRIVATE uint8 s_au8Endpoint0InputClusterDiscFlags[2] = {0x1F, 0x08};
PRIVATE uint8 s_au8Endpoint0OutputClusterDiscFlags[2] = {0x08, 0x1B};

These parameters are registered in the node’s endpoints simple descriptor structure. The declared variable for the structure is s_asSimpleDescConts and its size depends on the number of endpoints available on the node. For example, for two endpoints, the declaration will be as below:

PUBLIC zps_tsAplAfSimpleDescCont s_asSimpleDescConts[2] = {
    {
        {
            0x0000,
            0,
            0,
            0,
            84,
            84,
            s_au16Endpoint0InputClusterList,
            s_au16Endpoint0OutputClusterList,
            s_au8Endpoint0InputClusterDiscFlags,
            s_au8Endpoint0OutputClusterDiscFlags,
        },
        s_ahEndpoint0InputClusterAPdus,
        1
    },
    {
        {
            0x0104,
            0,
            0,
            1,
            6,
            4,
            s_au16Endpoint1InputClusterList,
            s_au16Endpoint1OutputClusterList,
            s_au8Endpoint1InputClusterDiscFlags,
            s_au8Endpoint1OutputClusterDiscFlags,
        },
        s_ahEndpoint1InputClusterAPdus,
        1
    },
};

The AF Context definition is as below:

typedef struct _zps_tsAplAfSimpleDescCont
{
    ZPS_tsAplAfSimpleDescriptor sSimpleDesc;
    const PDUM_thAPdu *phAPduInClusters;
    bool_t bEnabled;
} zps_tsAplAfSimpleDescCont;

And the endpoint simple descriptor has the following structure definition:

typedef struct {
    uint16 u16ApplicationProfileId;
    uint16 u16DeviceId;
    uint8  u8DeviceVersion;
    uint8  u8Endpoint;
    uint8  u8InClusterCount;
    uint8  u8OutClusterCount;
    const uint16 *pu16InClusterList;
    const uint16 *pu16OutClusterList;
    uint8 *au8InDiscoveryEnabledFlags;
    uint8 *au8OutDiscoveryEnabledFlags;
} ZPS_tsAplAfSimpleDescriptor;