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. 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 simplelink_<device>_sdk_2_30_00_xx\examples\rtos\CC13x2 or 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.