ZStack-Lighting-1.0.1 FAQ

From Texas Instruments Wiki
Jump to: navigation, search

ZStack-Lighting-1.0.x FAQ

How do I remove the need for the button on the ZLight2 Reference Platform

The ZLight2 board has a button that is used to allow easy developement. It enables 3 functions, that make development easier by removing the need for commands from other ZLL/ZigBee devices. These Functions are:

  • Press for <2s: Permit join for 60s.
  • Press for 2-10s: Reset to Factory New.
  • Press for >10s: Attempt to classically join a ZigBee Network.

All of these functions can be achieved in other ways.

Making ZLight2 Permit Join without a button press

Enabling Permit join is required to allow other ZigBee devices to associate the network through the ZLight2. In a typical usecase there would be a gateway with a button which is pressed by the user to add a new device to the network. This button press on the gateway among other things could send a message to all devices on the network instructing them to permit join for a specified length of time, hence removing the need for this button function on the ZLight2. With TI ZStack this can be done with the following code:

static void enablePermitJoin( byte duration )
{
  zAddrType_t dstAddr;
  //only needs to be done once, can be moved to init code
  ZDSecMgrPermitJoining( 0xFF );

  //permit join on the device
  NLME_PermitJoiningRequest( duration );

  //Permit join to network
  dstAddr.addr.shortAddr = NWK_BROADCAST_SHORTADDR_DEVZCZR;
  dstAddr.addrMode = Addr16Bit;
  ZDP_MgmtPermitJoinReq( &dstAddr, duration, 1, 0 );
}

Making ZLight2 Reset to Factory New without a button press

This can be achieved with a ZLL initiator programmed with the ZLL certification key, such as the ZLL remote sample application supply in ZStack-Lighting-1.0.x. This can be done by starting a TouchLink and insuring the Light and Remote are within the proximity required for the TouchLink to succeed:

static void enablePermitJoin( byte duration )
zllInitiator_StartDevDisc();

When the ZLight flashes to identify send the Reset to Factory New inter-pan command:

static void enablePermitJoin( byte duration )
zllInitiator_ResetToFNSelectedTarget();

Making ZLight2 Classically Join a ZigBee Network without a button press

The ZLight2 can automatically try to join a ZigBee Network when it is powered and it is Factory new. This will mean when it is powered for the first time it will search and join a ZigBee network, if there is no ZigBee Network found it will wait for a TouchLink. This will continue in subsequent power cycles until a ZigBee Network is found or a the ZLight2 is TouchLinked. The same behavior will resume if the ZLight2 is Reset to Factory New. this can be done by making the following code addition to Projects\zstack\ZLL\SampleLight\Source\zll_samplelight.c:

  • In the INCLUDES section at the top of the file, add the following line below #include "zll_target.h":
#include "ZDProfile.h"
#include "zll_target.h"
#include "zll.h"
  • At the end of the void zllSampleLight_Init( byte task_id ) function, add the following code:
  if ( zll_IsFactoryNew() )
  {
    zllTarget_ClassicalCommissioningStart();
  }

Will ZStack-Lighting-1.0.x inter-operate with ZLL devices on the market

Yes, but there are some limitation that need to be understood.

ZLL products on the market have gone through the same ZigBee Light Link certification process as ZStack-Lighting-1.0.0, this process uses a publicly known ZLL Certification Key. However product manufacturers have taken an extra step to request the secret ZLL Master Key from the ZigBee Alliance, which TI have not done as it cannot be put in the ZStack-Lighting release due to the secret nature of the ZLL Master Key.

The ZLL TouchLink process uses a key bitmask so devices know what ZLL Keys are supported by other devices. A random network key is then encrypted by the TouchLink Initiator (ZLL Remote) with the ZLL Key found to be common between the Remote and Light from the key bitsmask, the ZLL target (ZLL Light) will then decode the network key using the same common ZLL Key.

During certification, development and inter-op events the key bitmask of ZLL devices is set to the ZLL Certification Key, and the ZLL Certification Key is stored in the devices to encode/decode the random network key transferred during TouchLink. ZLL products do not have the ZLL Certification Key bit set in the key bitmask, but instead set the ZLL Master Key bit, and have the ZLL Master Key stored in the device.

This means that ZStack-Lighting-1.0.x devices containing ZLL Certification Key the will not be able to TouchLink with ZLL products on the market and join the same network. However In ZLL there is also a concept of “Classical Commissioning” that was included for HA inter-op. Once 2 devices TouchLink and create a "ZLL network" other devices can join the network using normal ZigBee association without the need to TouchLink, however there is no coordinator in this ZLL network and devices joining in a classical way to a "ZLL network" use a ZLL key in a similar way as a trust centre Link Key in HA. So even in this case the ZStack-Lighting-1.0.x devices will not be able to classically associate to the "ZLL network".

The way to make ZStack-Lighting-1.0.x devices work with ZLL products is to make the ZLL products classically associate with a HA network. Now they use the known HA trustcentre link key and ZStack-Lighting-1.0.x device can also classically join the same network. Now that the ZLL product and ZStack-Lighting-1.0.x devices are on the same network they can use TouchLink, ZStack-Lighting-1.0.x Remotes will add ZLL Light Products to the target list and control them, and likewise ZLL Product Remotes can touchlink. Once this is done the ZStack-Lighting-1.0.x Remote can send ZLL lighting commands to the ZLL light product and vice versa.

How do I make ZLL devices available on the market join a HA network

The ZLL spec mandates that ZLL devices must join a HA network. But the means in which this is done is manufacturer specific, details of how this can be done may be available from the ZLL product manufactures. For ZLL Remotes this will likely be some combination of button presses, for Lights (as they generally have no button) it is common that they will search for a HA network when powered if they are not yet part of a network.

How can I use the ZStack-Lighting-1.0.1 Remote to reset a certified ZLL product and cause it to leave the old network

ZLL products on the market can be reset to factory new by the ZStack-Lighting-1.0.1 Remote if you enable the MASTER_KEY, the actual key is not used during the reset, you just need the correct key bitmask during the initial TouchLink phase. See section 3.1 of the "ZStack Lighting Developers Guide.pdf" for more information about enabling the MASTER_KEY. To send a reset from a ZStack-Lighting Remote you need to start a TouchLink with zllInitiator_StartDevDisc(), then when the ZLL Light flashes send the zllInitiator_ResetToFNSelectedTarget().

NOTE: There is a bug which will cause issues if the ZLL Remote is on a different channel to the ZLL Light.

To fix this you will need to add:

  zll_SetChannel( selectedTarget.rxChannel );

to the zllInitiator_ResetToFNSelectedTarget function:

ZStatus_t zllInitiator_ResetToFNSelectedTarget()
{
  if ( ( zllTransID == 0 ) || ( selectedTarget.lastRssi == ZLL_TL_WORST_RSSI ) )
  {
    return ( ZFailure );
  }
  zclLLResetToFNReq_t req;
  req.transID = zllTransID;

  zll_SetChannel( selectedTarget.rxChannel );

  return zclLL_Send_ResetToFNReq( ZLL_INITIATOR_ENDPOINT, &(selectedTarget.srcAddr), &req, initiatorSeqNum++ );
}

Is ZStack-Lighitng-1.0.1 Compatible with the Philips Hue

ZStack-Lighting-1.0.x is ZigBee Light Link certified, but with default setting this will not inter-operate with Philips Hue Hub. There are some complications regarding the ZigBee Light Link Master Key which is secrete and cannot be contained in the TI public release, this is discussed in more detail in the above FAQ. However there are other important points to understand.

NOTE: There is an important parameter in ZStack-Lighitng-1.0.1 that needs to be changed from the default value for a ZStack-Lighitng-1.0.1 Light to be recognized by Hue Hub. In ZStack-Lighitng-1.0.1 the simple descriptor is formed using HA Profile and currently defined HA Lighting Device ID’s, this is to allow it to be recognized by ZLL or HA gateways, this is at the cost that a ZLL gateway will not send enhanced ZLL commands (as the device is advertised as a HA device). However the Hue Hub does not CURRENTLY inspect the Profile ID and assumes the joining devices are ZLL devices (as it forms a ZLL network), for this reason the HA device ID used by default in a ZStack-Lighitng-1.0.1 will not be recognized by the Hue Hub.

Changes Require for a ZStack-Lighitng-1.0.1 Light to be Recognized Correctly by Hue Hub

For a ZStack-Lighitng-1.0.1 Light to be recognized by Hue Hub you need to modify zll_samplelight.c to change the HA Device ID’s to ZLL Device ID’s:

#define ZLL_HUB_COMPATIBILITY

#ifndef ZLL_DEVICEID
  #ifdef ZCL_COLOR_CTRL
    #define ZLL_DEVICEID  ZLL_DEVICEID_COLOR_LIGHT
    #ifdef ZLL_HUB_COMPATIBILITY
      #define HA_DEVICEID   ZLL_DEVICEID
    #else
      #define HA_DEVICEID   ZCL_HA_DEVICEID_COLORED_DIMMABLE_LIGHT
    #endif
  #else
    #ifdef ZCL_LEVEL_CTRL
      #define ZLL_DEVICEID  ZLL_DEVICEID_DIMMABLE_LIGHT
      #ifdef ZLL_HUB_COMPATIBILITY
        #define HA_DEVICEID  ZLL_DEVICEID
      #else
        #define HA_DEVICEID   ZCL_HA_DEVICEID_DIMMABLE_LIGHT
      #endif
    #else
      #define ZLL_DEVICEID  ZLL_DEVICEID_ON_OFF_LIGHT
      #ifdef ZLL_HUB_COMPATIBILITY
        #define HA_DEVICEID  ZLL_DEVICEID
      #else
        #define HA_DEVICEID   ZCL_HA_DEVICEID_ON_OFF_LIGHT
      #endif
    #endif
  #endif
#endif

The ZLL On/Off Light and Level Control Light device ID's clash with HA device ID's, and as such the above change may cause issues for a controller that tries to recognize HA and ZLL devices (only for ZLL On/Off Light and Level Control Light). The ZLL 1.1 spec and HA 1.2 spec will align on ZLL devices ID's, the ZLL On/Off Light and Level Control Light device ID's will change to avoid the clash that is present today.

Changing the Profile ID for the Application end point to be the ZLL Profile ID is not trivial and should not be attempted.

The touchlink endpoint device ID should also be changed to avoid a ZLL controller that does not check simple descriptors (including Hue Hub) seeing the touchlink endpoint as a controllable device. To do this change the AppDeviceId in zll_target.c:

SimpleDescriptionFormat_t zllTarget_SimpleDesc =
{
  ZLL_TARGET_ENDPOINT,              //  int Endpoint;
  ZLL_PROFILE_ID,                   //  uint16 AppProfId[2];

#ifdef ZLL_HUB_COMPATIBILITY
  0x2BEE,                           //  uint16 AppDeviceId[2] - set to an invalid device ID;
#else
  ZLL_DEVICEID_COLOR_LIGHT,         //  uint16 AppDeviceId[2];
#endif //ZLL_HUB_COMPATIBILITY

  ZLL_TARGET_DEVICE_VERSION,        //  int   AppDevVer:4;
  ZLL_TARGET_FLAGS,                 //  int   AppFlags:4;
  ZLL_TARGET_MAX_INCLUSTERS,        //  byte  AppNumInClusters;
  (cId_t *)zllTarget_InClusterList, //  byte *pAppInClusterList;
  ZLL_TARGET_MAX_OUTCLUSTERS,       //  byte  AppNumInClusters;
  (cId_t *)zllTarget_OutClusterList //  byte *pAppInClusterList;
};