Z-Stack 3.1.0 to Z-Stack 3.2.0

This section will describe a way to migrate a project from Z-Stack 3.1.0 to a Z-Stack 3.2.0 project.

For this guide, samplelight from Z-Stack 3.1.0 will be ported over to Z-Stack 3.2.0. The two releases have minor differences mostly pertaining to bug fixes listed in the Z-Stack release notes, however one change to note is Z-Stack’s transition from a SDK Plugin to being a part of the SDK itself. 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

  1. Choose a Z-Stack 3.2.0 example project that contains your target project’s base functionality. For reference and use in this example, zc_light from C:\ti\simplelink_CC26x2_sdk_x_xx_xx_xx\examples\rtos\CC26x2_LAUNCHXL\zstack is chosen as a starting point.

  2. No changes are required for the Z-Stack 3.2.0 zcl_samplelight_data.c file unless clusters, attributes, or simple descriptors were added or altered in the Z-Stack 3.1.0 project. Note that SAMPLELIGHT_ZCLVERSION has been redefined as BASIC_ZCL_VERSION.

  3. In zcl_samplelight.h, User Interface and Green Power events have been redefined:

    // UI Events
    #define SAMPLEAPP_UI_AUTO_REFRESH_EVT         0x0010
    #define SAMPLEAPP_UI_INPUT_EVT                0x0040
    #define SAMPLEAPP_PROCESS_UI_GPP_EVT          0x0080
    
    // Green Power Events
    #define SAMPLEAPP_PROCESS_GP_DATA_SEND_EVT              0x0100
    #define SAMPLEAPP_PROCESS_GP_EXPIRE_DUPLICATE_EVT       0x0200
    #define SAMPLEAPP_PROCESS_GP_TEMP_MASTER_EVT            0x0400
    
  4. macCryptoDriverTable is used instread of cryptoDriverTable in main.c

The following items specifically concern zcl_samplelight.c:

  1. Include timer.h has been renamed util_timer.h and string.h is added by default

  2. User interface functions have changed due to deprecated LCD functionality:

    • zclSampleLight_UiUpdateLcd is now zclSampleLight_UiRefresh
    • UI_Init and events in zclSampleLight_process_loop have updated to reflect the new definitions from zcl_samplelight.h
    • UI_UpdateLcd is now UI_Refresh

3. Green Power Sink support can be optionally added by defining ENABLE_GREENPOWER_COMBO_BASIC and including several additions to the application code:

  • Includes and definitions

    #ifdef ENABLE_GREENPOWER_COMBO_BASIC
    #include "gp_sink.h"
    #define UI_STATE_GP_SINK_SET_COMMISSIONING  2
    static uint8 zclSampleLight_SetSinkCommissioningMode = 0;
    static void zclSampleLight_setGPSinkCommissioningMode(uint16 keys);
    static void zclSampleLight_GPSink_Toggle(zclGpNotification_t *zclGpNotification);
    static void zclSampleLight_GPSink_On(zclGpNotification_t *zclGpNotification);
    static void zclSampleLight_GPSink_Off(zclGpNotification_t *zclGpNotification);
    static void zclSampleLight_GPSink_Identify(zclGpNotification_t *zclGpNotification);
    const uiState_t zclSampleLight_UiStatesMain[] =
    {
      /*  UI_STATE_BACK_FROM_APP_MENU        */   {UI_STATE_DEFAULT_MOVE,       UI_STATE_GP_SINK_SET_COMMISSIONING, UI_KEY_SW_5_PRESSED, &UI_ActionBackFromAppMenu}, //do not change this line, except for the second item, which should point to the last entry in this menu
      /*  UI_STATE_TOGGLE_LIGHT              */   {UI_STATE_DEFAULT_MOVE,       UI_STATE_DEFAULT_MOVE,              UI_KEY_SW_5_PRESSED, &zclSampleLight_UiActionToggleLight},
      /*  UI_STATE_GP_SINK_SET_COMMISSIONING */   {UI_STATE_BACK_FROM_APP_MENU, UI_STATE_DEFAULT_MOVE,              UI_KEY_SW_5_PRESSED, &zclSampleLight_setGPSinkCommissioningMode},
    };
    const char sGpSink[]              = "GREEN POWER SINK";
    const char sGpSinkCommissioning[] = " COMMISSIONING  ";
    const char sGpSinkEnabled[]       = "<   ENABLED    >";
    const char sGpSinkDisabled[]      = "<   DISABLED   >";
    #else
    #define UI_STATE_TOGGLE_LIGHT 1 //UI_STATE_BACK_FROM_APP_MENU is item #0, so app item numbers should start from 1
    const uiState_t zclSampleLight_UiStatesMain[] =
    {
      /*  UI_STATE_BACK_FROM_APP_MENU  */   {UI_STATE_DEFAULT_MOVE,       UI_STATE_TOGGLE_LIGHT,  UI_KEY_SW_5_PRESSED, &UI_ActionBackFromAppMenu}, //do not change this line, except for the second item, which should point to the last entry in this menu
      /*  UI_STATE_TOGGLE_LIGHT        */   {UI_STATE_BACK_FROM_APP_MENU, UI_STATE_DEFAULT_MOVE,  UI_KEY_SW_5_PRESSED, &zclSampleLight_UiActionToggleLight},
    };
    #endif
    
  • Application Callbacks

    #if defined (ENABLE_GREENPOWER_COMBO_BASIC)
    GpSink_AppCallbacks_t zclSampleLight_GpSink_AppCallbacks =
    {
    #ifdef ZCL_IDENTIFY
        zclSampleLight_GPSink_Identify,     //IdentifyCmd;
    #endif
    #ifdef ZCL_SCENES
        NULL,                               //RecallSceneCmd;
        NULL,                               //StoreSceneCmd;
    #endif
    #ifdef ZCL_ON_OFF
        zclSampleLight_GPSink_Off,          //OffCmd;
        zclSampleLight_GPSink_On,           //OnCmd;
        zclSampleLight_GPSink_Toggle,       //ToggleCmd;
    #endif
    #ifdef ZCL_LEVEL_CTRL
        NULL,                               //LevelControlStopCmd;
        NULL,                               //MoveUpCmd;
        NULL,                               //MoveDownCmd;
        NULL,                               //StepUpCmd;
        NULL,                               //StepDownCmd;
        NULL,                               //MoveUpWithOnOffCmd;
        NULL,                               //MoveDownWithOnOffCmd;
        NULL,                               //StepUpWithOnOffCmd;
        NULL,                               //StepDownWithOnOffCmd;
    #endif
        NULL,                               //MoveHueStopCmd;
        NULL,                               //MoveHueUpCmd;
        NULL,                               //MoveHueDownCmd;
        NULL,                               //StepHueUpCmd;
        NULL,                               //StepHueDownCmd;
        NULL,                               //MoveSaturationStopCmd;
        NULL,                               //MoveSaturationUpCmd;
        NULL,                               //MoveSaturationDownCmd;
        NULL,                               //StepSaturationUpCmd;
        NULL,                               //StepSaturationDownCmd;
        NULL,                               //MoveColorCmd;
        NULL,                               //StepColorCmd;
    #ifdef ZCL_DOORLOCK
        NULL,                               //LockDoorCmd;
        NULL,                               //UnlockDoorCmd;
    #endif
        NULL,                               //AttributeReportingCmd;
        NULL,                               //MfrSpecificReportingCmd;
        NULL,                               //MultiClusterReportingCmd;
        NULL,                               //MfrSpecificMultiReportingCmd;
        NULL,                               //RequestAttributesCmd;
        NULL,                               //ReadAttributeRspCmd;
        NULL,                               //zclTunnelingCmd;
    };
    #endif
    
  • Endpoint registration and initialization in zclSampleLight_Init

    #if defined (ENABLE_GREENPOWER_COMBO_BASIC)
      zclGp_RegisterCBForGPDCommand(&zclSampleLight_GpSink_AppCallbacks);
      gp_endpointInit(zclSampleLight_Entity);
    #endif
    
  • zstackmsg_CmdIDs_GP_COMMISSIONING_MODE_IND case in zclSampleLight_processZStackMsgs

    #ifdef BOARD_DISPLAY_USE_UART
        case zstackmsg_CmdIDs_GP_COMMISSIONING_MODE_IND:
        {
          zstackmsg_gpCommissioningModeInd_t *pInd;
          pInd = (zstackmsg_gpCommissioningModeInd_t*)pMsg;
          UI_SetGPPCommissioningMode( &(pInd->Req) );
        }
    #endif
    
  • UI Commissioning lines in zclSampleLight_UiRefresh

    void zclSampleLight_UiRefresh(uint8 UiState, char * line[3])
    {
    #if defined (BOARD_DISPLAY_USE_UART)
    #if defined (ENABLE_GREENPOWER_COMBO_BASIC)
        if(UiState == UI_STATE_GP_SINK_SET_COMMISSIONING)
        {
            line[0] = (char *)sGpSink;
            line[1] = (char *)sGpSinkCommissioning;
    
          if(zclSampleLight_SetSinkCommissioningMode)
          {
            line[2] = (char*) sGpSinkEnabled;
          }
          else
          {
            line[2] = (char*) sGpSinkDisabled;
          }
        }
        else
        {
            #ifdef ZCL_LEVEL_CTRL
              zclHA_uint8toa( zclSampleLight_LevelCurrentLevel, &sLightLevel[9] );
              line[0] = (char *)sLightLevel;
            #endif // ZCL_LEVEL_CTRL
              line[1] = (char *)(zclSampleLight_OnOff ? sLightOn : sLightOff);
              line[2] = "< TOGGLE LIGHT >";
        }
    #else
        #ifdef ZCL_LEVEL_CTRL
          zclHA_uint8toa( zclSampleLight_LevelCurrentLevel, &sLightLevel[9] );
          line[0] = (char *)sLightLevel;
        #endif // ZCL_LEVEL_CTRL
          line[1] = (char *)(zclSampleLight_OnOff ? sLightOn : sLightOff);
          line[2] = "< TOGGLE LIGHT >";
    #endif
    #endif
    }
    
  • Local functions

    #if defined (ENABLE_GREENPOWER_COMBO_BASIC)
    
    static void zclSampleLight_setGPSinkCommissioningMode(uint16 keys)
    {
      zclSampleLight_SetSinkCommissioningMode ^= 1;
    
      gp_SetCommissioningMode(zclSampleLight_SetSinkCommissioningMode);
    
    }
    
    /*********************************************************************
     * @fn      zclSampleLight_GPSink_Identify
     *
     * @brief   Callback to process Identify command from a GPD
     *
     * @param   zclGpNotification
     *
     * @return  none
     */
    static void zclSampleLight_GPSink_Identify(zclGpNotification_t *zclGpNotification)
    {
      afAddrType_t  dstAddr;
    
      dstAddr.endPoint = SAMPLELIGHT_ENDPOINT;
      dstAddr.panId = 0;
      dstAddr.addrMode = afAddr16Bit;
      dstAddr.addr.shortAddr = _NIB.nwkDevAddress;
    
      //Identify is a payloadless command which triggers a 60 seconds identify in the device (doc 14-0563-16 GP spec Table 49)
      zclGeneral_SendIdentify(SAMPLELIGHT_ENDPOINT,&dstAddr,60,TRUE, 1);
    }
    
    /*********************************************************************
     * @fn      zclSampleLight_GPSink_Off
     *
     * @brief   Callback to process Off command from a GPD
     *
     * @param   zclGpNotification
     *
     * @return  none
     */
    static void zclSampleLight_GPSink_Off(zclGpNotification_t *zclGpNotification)
    {
      zclSampleLight_OnOffCB(COMMAND_OFF);
    }
    
    /*********************************************************************
     * @fn      zclSampleLight_GPSink_On
     *
     * @brief   Callback to process On command from a GPD
     *
     * @param   zclGpNotification
     *
     * @return  none
     */
    static void zclSampleLight_GPSink_On(zclGpNotification_t *zclGpNotification)
    {
      zclSampleLight_OnOffCB(COMMAND_ON);
    }
    
    /*********************************************************************
     * @fn      zclSampleLight_GPSink_Toggle
     *
     * @brief   Callback to process Toggle command from a GPD
     *
     * @param   zclGpNotification
     *
     * @return  none
     */
    static void zclSampleLight_GPSink_Toggle(zclGpNotification_t *zclGpNotification)
    {
      zclSampleLight_OnOffCB(COMMAND_TOGGLE);
    }
    #endif
    
  1. Code can optionally be added to zclSampleLight_initialization to clear the NV if the right push-button is pressed on startup:

    static void zclSampleLight_initialization(void)
    {
        uint8 key;
    
        /* Initialize user clocks */
        zclSampleLight_initializeClocks();
    
        /* Initialize keys */
        key = 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);
    
        if(key == KEY_RIGHT)
        {
            Zstackapi_bdbResetLocalActionReq(zclSampleLight_Entity);
        }
    
        //Initialize stack
        zclSampleLight_Init();
    }
    
  2. Add any other Z-Stack 3.1.0 application changes to the Z-Stack 3.2.0 file if not pertaining to the items listed above

Note

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