Z-Stack 1.2.2a (CC253x) to Z-Stack 3.1.0Ā¶

This section will describe a way to migrate a project from Z-Stack 1.2.2a for CC253x to a Z-Stack 3.1.0 project.

For this guide, SampleLight from Z-Stack 1.2.2a for CC253x will be ported over to Z-Stack 3.1.0. The two releases are vastly divergent due to differences in both device and RTOS support, as is covered in CC253x to CC26x2. The recommended approach is to start with a Z-Stack 3.1.0 project that contains the same base application as the porting target project and merge any custom functionality.

Note

Z-Stack HA 1.2.2a is based off of the Zigbee PRO 2012 (r20) specification whereas Z-Stack 3.x.x follows Zigbee PRO 2015 (r21) and later. There are several significant changes between these specifications that greatly affect the behavior of the Zigbee mesh network, including child aging, enhanced security, BDB specification, and Green Power as described in the TI Z-Stack Wiki. This section will only address application-level changes, network configuration changes are further discussed in CC253x to CC26x2.

  1. Choose a Z-Stack 3.1.0 example project that contains your target project’s base functionality. For reference and use in this example, zc_light from C:\Texas Instruments\<SimpleLink SDK Path>\examples\rtos\CC26X2R1_LAUNCHXL\zstack is chosen as a starting point.
  2. Modify the following Z-Stack 3.1.0 example files if any of the corresponding were added or altered in the Z-Stack 1.2.2a project.
    • zcl_samplelight_data.c clusters, attributes, or simple descriptors
    • zcl_samplelight.h application event definitions
    • zcl_samplelight.c event loop cases and callbacks

The following items specifically concern zcl_samplelight.c:

  1. Note the following differences for which all related code from Z-Stack 1.2.2a should not be transferred to the Z-Stack 3.1.0 project:

    • #define ZCL_EZMODE is no longer used as this functionality is replaced by 3.0 Base Device Behavior
    • #define ZCL_REPORT is deprecated as no longer being optional
  2. Note the following changes due to the TI-RTOS implementation:

    • ICALL framework used to dispatch messages between Z-Stack and the application
    • Semaphores used to post and pend during event callbacks
    • Timer handling, i.e
    Timer_setTimeout( LevelControlClkHandle, 100 );
    Timer_start(&LevelControlClkStruct);
    

    versus osal_start_timerEx( zclSampleLight_TaskID, SAMPLELIGHT_LEVEL_CTRL_EVT, 100 );. Due to this and the reasons further provided below, all related code from Z-Stack 1.2.2a should not be transferred to the Z-Stack 3.1.0 project.

  3. Do not remove anything from the Z-Stack 3.1.0 file dealing with Green Power, #if ZG_BUILD_ENDDEVICE_TYPE, or Base Device Behavior commissioning as these are necessary for the Zigbee 3.0 Specifications.

  4. Key events are now handled locally in zclSampleLight_processKey instead of zclSampleLight_HandleKeys. A UART interface is preferred over LCD.

  5. main.c calls the zclSampleLight_task function

    void zclSampleLight_task(NVINTF_nvFuncts_t *pfnNV)
        {
          // Save and register the function pointers to the NV drivers
          pfnZdlNV = pfnNV;
          zclport_registerNV(pfnZdlNV, ZCL_PORT_SCENE_TABLE_NV_ID);
    
          // Initialize application
          zclSampleLight_initialization();
    
          // No return from task process
          zclSampleLight_process_loop();
        }
    

    to initialize the application

    static void zclSampleLight_initialization(void)
        {
    
            /* Initialize user clocks */
            zclSampleLight_initializeClocks();
    
            /* Initialize keys */
            Board_Key_initialize(zclSampleLight_changeKeyCallback);
    
            /* Initialize the LEDS */
            Board_Led_initialize();
    
            // Register the current thread as an ICall dispatcher application
            // so that the application can send and receive messages.
            ICall_registerApp(&zclSampleLight_Entity, &sem);
    
    
            //Initialize stack
            zclSampleLight_Init();
        }
    

    which in-turn initializes the clocks, keys, LEDs, and ICall dispatcher before initializing the stack. This is compared with Z-Stack 1.2.2a where all of the above was accomplished solely in zclSampleLight_Init.

  6. zclSampleLight_Init registers endpoints using

    //Register Endpoint
    zclSampleLightEpDesc.endPoint = SAMPLELIGHT_ENDPOINT;
    zclSampleLightEpDesc.simpleDesc = &zclSampleLight_SimpleDesc;
    zclport_registerEndpoint(zclSampleLight_Entity, &zclSampleLightEpDesc);
    

    instead of

    // Register the Simple Descriptor for this application
    zclHA_Init( &zclSampleLight_SimpleDesc );
    

    and registers applications with

    // Register the Application to receive the unprocessed Foundation command/response messages
    zclport_registerZclHandleExternal(zclSampleLight_ProcessIncomingMsg);
    

    as compared to

    // Register the Application to receive the unprocessed Foundation command/response messages
    zcl_registerForMsg( zclSampleLight_TaskID );
    
  7. zclSampleLight_process_loop is used in place of zclSampleLight_event_loop and uses ICall to receive messages instead of SYS_EVENT_MSG events and osal_msg_receive

  8. zclSampleLight_processZStackMsgs and zclSampleLight_processAfIncomingMsdInd is used in place of zclSampleLight_ProcessIncomingMsg

  9. Structure type zclIncomingMsg_t has been renamed zclIncoming_t

  10. Add any other Z-Stack 1.2.2a application changes to the Z-Stack 3.1.0 file if not pertaining to the items listed above.

Note

Difference comparison software is recommended for discerning all differences between software stacks.