4.1 Zigbee Project Generation

There are different zigbee device types supported in Microchip Zigbee framework. Few sample application projects are available as reference <Harmony Content Path>\wireless_apps_pic32cxbz2_wbz45\apps\zigbee . The projects for other device types can be generated by following the step by step procedure in this document.

SDK Setup

  1. Gettting Started with Software Development

Generating Intended Device Type project using MCC

  1. Create a new MCC Harmony Project. For more details, refer to 2.5 Creating a New MCC Harmony Project.

  2. Click on "+" symbol on the Intended Zigbee Device Type component from "Device Resources"
    • OnOffLight Device component is shown as an example:

    • "Accept Dependencies or satisfiers, select Yes
  3. Add UART components needed for console logs and commands (optional). Verify the UART SERCOM configuration as in Zigbee Console Commands
  4. Verify if the Project Graph window has all the expected MCC configurations

Generating a Code

For more details on code generation, refer to 14.2 MPLAB Code Configurator(MCC) Code Generation.

Files and Routines Automatically Generated by MCC

After generating the code from MCC tool by clicking Generate, below is the project folder structure.

Zigbee Stack Initialization and Application Callback Registration

  • The RF System, ZIGBEE, PERIPHERAL initialization routine executed during program initialization can be found in SYS_Initialize() of initialization.c file

  • Zigbee Stack provides various APIs for application, and those APIs belong to the specific module within dedicated group. The sequence of initialization is already taken care in the stack when Zigbee_Init() from initialization.c is called.
  • Zigbee Stack generate events to inform application if there is any status changed or activity. Application may need to get the relevant information from Zigbee Stack and do the corresponding procedure.

Zigbee Stack Application Events Handling

app.c file is autogenerated and has a state machine for application callback handling from Zigbee stacks

User Application Development

  • Compile MCC auto generated project
  • Edit device unique ID (zigbeeAppDeviceSelect.h)

    All the zigbee devices/modules will hold their unique IEEE address purchased from IEEE. For the demo purpose, where UID is not present in internal NVM, the pre-compiled fixed UID to be used. Edit the CS_UID to user defined value and not matching with combined interface UID (default 0xbee) as below in zigbeeAppDeviceSelect.h

Programming the Application using MPLABX IDE

Build the project after doing all the above changes and program on Curiosity board.

Hints: Custom code modification (app_zigbee_handler.c)

There will be 3 major events which the stack would provide to the user application in app_zigbee_handler.c file. They are ,

  • Zigbee Events which is defined as "EVENT_ZIGBEE"

  • ZCL and Cluster Events defined as "EVENT_CLUSTER"

    For more details regarding clusters, please refer to, the specification from Zigbee Alliance -> Link to Zigbee Cluster Library Specification by Zigbee Alliance.

    ZCL specific cluster events are received in ZCL EVENT_CLUSTER Cluster_Event_Handler() in application layer. For the all the supported device types, most of the ZCL specific activities are automatically handled in middleware. If user wish to take some action of ZCL events, can do changes in this Cluster_Event_Handler() for the specific ZCL event.
  • Board Specific Package (BSP) Events defined as "EVENT_BSP"

    In addition to above ZCL event, BSP event will also be called when specific ZCL command is received. BSP_Event_Handler() API is called for EVENT_BSP event. This will enable the user to write the board specific functionality code like switch on/off the on board LED, controlling the thermostat. Refer to Extended Light BSP Handling

Hints: Zigbee Specific MCC Configuration

  • Harmony3 based Microchip Zigbee stack framework allows, user to do different configurations and generate the code based on that configurations.

Auto and Manual Configuration

  • When the device type component is added in project graph, the default will be auto configuration. All the allowable configurations will take already defined default values in the generated code.

  • Enabling "Manual Configuration" will allow user to change the configurations.

Stack configuration

Zigbee stack specific configurations like routing table size, maximum allowable children to get joined in one parent, etc., can be changed based on the customer application use case. The changed configurations will be reflected in stackConfig.h.
Note: The table size configurations will have impact on RAM memory size. So, care must be taken while choosing the values.

Commissioning Configuration

Commissioning is the process of initializing the devices to join a network and to work together. The Zigbee Base Device Behaviour specification specifies the procedures for different commissioning mechanisms. MCC configuration allows user to configure this from configurator. The details of different commissioning procedure is explained in Zigbee Commissioning

These configuration changes are reflected in zigbeeAppConfig.h.

Application Configuration

  • Application specific configurations like enabling the console commands is done here.

  • The console based commands would be practically needed during development stage. This may not be needed end product stage. So, this configuration gives flexibility to enable/disable based on the need.

    • "Enable Zigbee Console Commands" to be checked always.

    • When the console command is enabled, make sure the required UART driver is configured as done in UART Component Addition The details of manual commands and usage is explained Console commands

  • Another configuration is zigbee primary/secondary channel masks configuration. Zigbee supports 16 channels (channel 11 to 26) in 2.4G Hz frequency band. These 16 channels are bit mapped to bits 11 to 26. For example in channel mask 0x0000800, bit 11 is set. This means channel 11 is enabled. These configuration changes are reflected in zigbeeAppConfig.h and stackConfig.h files.
  • Under Application Configuration there is an option to set the Tx power. Prior to setting the Tx Power, the Regulatory Region must be selected. Regulatory Region selection setting is available in the Configuration Options of Device_Support component, as shown in the image below. User can select one or more Regulatory Region. By default, ETSI/UK is selected.
    Figure 4-1. Regulatory Region Selection

    The Maximum power that each Regulatory Region can transmit differs for different Region. The table below depicts the different regulatory Region and their respective maximum Tx Power (also called as EIRP).

    Table 4-1. Regulatory regions and EIRP
    Regulatory Region EIRP(dbm)
    ETSI/UK 11
    FCC/IC 15
    JAPAN 12
    KOREA 11
    CHINA 15
    TAIWAN 15

    After selecting the Regulatory Region, the user can enter the required Tx power in dbm in the “Tx Power Set” option available in the Configuration Options as shown below. By default Tx Power Set is set to 3dbm

    Figure 4-2. Tx Power Configuration

Cluster Configuration

  • All the supported mandatory and optional clusters in specific device type as per specification are implemented. The MCC configurator allows user to add/remove the optional clusters/attributes/commands.

Timer Configuration

  • The timer configuration provides an option to select between TC0 and TCC2 timer. By default, TC0 is Selected. Depending on the silicon version used the customer must choose between TC0 and TCC2. If A2 silicon version is used, then TCC2 must be used or else if A0 is used then TC0 should be used.
  • For more details regarding Zigbee lighting and Occupancy device types, refer to Zigbee Lighting and Occupancy (ZLO) device Specification by Zigbee Alliance