4. Network Management
4.3 Network Management by ZigBee Device Profile Requests
4.3.5 Network Update Request
The ZDP command with type MGMT_NWK_UPDATE_CLID, or network update request, is designed to cope with multiple tasks, such as energy detection scan and changing a working channel. The actual task performed by the request depends on the value of the scanDuration field of the network update request’s payload:
•
Energy detection scanning:scanDuration field set to values from ZDO_MGMT_ED_SCAN_DUR_0 (0x00) to ZDO_MGMT_ED_SCAN_DUR_5 (0x05)•
Changing the current channel:scanDuration field set to ZDO_MGMT_CHANNEL_CHANGE (0xFE)•
Changing the channel mask and the network manager’s address:scanDuration field set to4.3.5.1 Energy Detection Scan
Energy detection scan measures energy level in dBm on each of the provided channels. To perform energy detection scan send a ZDP request, setting MGMT_NWK_UPDATE_CLID as reqCluster and configuring the
req.reqPayload.mgmtNwkUpdateReq field in the following way: set scanDuration to a value in the range from ZDO_MGMT_ED_SCAN_DUR_0 (0x00) to ZDO_MGMT_ED_SCAN_DUR_5 (0x05), provide channels to scan in the
scanChannels field, and the number of scan attempts in the scanCount field. Actual duration of scanning depends exponentially on the scanDuration value.
The scanning is performed by the node specified in the request as the destination, which is identified by dstAddrMode and dstNwkAddr fields. To made the node that sends the request perform the scan its own address shall be specified. The payload’s scanCount specifies how many times the specified channels shall be scanned. Separate response will be received for each scanning attempt.
See the example code below:
zdpReq.reqCluster = MGMT_NWK_UPDATE_CLID; zdpReq.dstAddrMode = SHORT_ADDR_MODE;
zdpReq.dstNwkAddr = DST_SHORT_ADDRESS; //A value defined by the application
//Get current channel mask from Configuration Server uint32_t chMask;
CS_ReadParameter(CS_CHANNEL_MASK_ID, &chMask);
zdpReq.req.reqPayload.mgmtNwkUpdateReq.scanChannels = chMask;
zdpReq.req.reqPayload.mgmtNwkUpdateReq.scanDuration = ZDO_MGMT_ED_SCAN_DUR_5; zdpReq.req.reqPayload.mgmtNwkUpdateReq.scanCount = 0x01; //One attempt zdpReq.ZDO_ZdpResp = ZDO_ZdpResp; //The callback function is called when //the request is sent
ZDO_ZdpReq(&zdpReq);
Note that the callback function specified in the ZDO_ZdpResp field is called when the request is sent, and does not indicate that energy detection has been completed. In case the callback function reports success, the result of the scanning is received as a network update notification; the stack indicates it to the application, calling the
ZDO_MgmtNwkUpdateNotf() function with status ZDO_SUCCESS_STATUS. The argument’s scanResult field in this case contains scan data. The application may process this in the following way:
void ZDO_MgmtNwkUpdateNotf(ZDO_MgmtNwkUpdateNotf_t *nwkParams) {
switch (nwkParams->status) {
case ZDO_SUCCESS_STATUS: {
EDScan_t* edScan = &nwkParams->scanResult; // Process edScan’s fields
} } }
EDScan_t structure obtained from the argument contains scan results:
•
The scanChannels field is the bitmask of scanned channels (channels mask)•
The totalTransmissions field reports the total number of transmissions done during energy detection scan, and transmissionsFailures reports the number of failed transmissions•
Energy values measured for scanned channels are given in the energyValues array havingscannedChannelsListCount items. Values are within the range from 0 to 84. Actually measured input power in dBm can be obtained by subtracting 91 from a value.
4.3.5.2 Changing Channel
The need to change a working channel arises when the current channel has too much noise on it. This is usually done by a network manager, which performs the energy detection scan to determine the noise level on a specific node. If a node other than the network manager issues a request to change a working channel on a remote node, the request will be declined.
To change an operating channel send a ZDP request, setting MGMT_NWK_UPDATE_CLID as reqCluster and configuring the req.reqPayload.mgmtNwkUpdateReq field in the following way: set scanDuration to
ZDO_MGMT_CHANNEL_CHANGE to indicate that this is a changing channel request and specify the new channel in the scanChannels field. To set a particular channel in the scanChannels field shift 1 via the << operator by the channel’s number (see the code example below).
The request may be sent to a particular node or broadcasted across the whole network (typically, such broadcast command is sent by the stack on the network manager node).
See the example code below:
//Define a variable in the file scope ZDO_ZdpReq_t zdpReq;
...
zdpReq.ZDO_ZdpResp = appZdpNwkUpdateResp; //Set to the pointer of a callback // function to check request’s status zdpReq.reqCluster = MGMT_NWK_UPDATE_CLID;
zdpReq.dstAddrMode = SHORT_ADDR_MODE;
zdpReq.dstNwkAddr = DST_SHORT_ADDRESS; //The short address of the destination node zdpReq.req.reqPayload.mgmtNwkUpdateReq.scanDuration = ZDO_MGMT_CHANNEL_CHANGE; zdpReq.req.reqPayload.mgmtNwkUpdateReq.scanChannels = 1ul << NEW_CHANNEL; ZDO_ZdpReq(&zdpReq);
The callback function’s field in the example is set to NULL, although a function’s pointer may be provided to check that request has been sent.
4.3.5.3 Changing Network Parameters
A ZDP request with the reqCluster field of the argument set to MGMT_NWK_UPDATE_CLID and the scanDuration field of the payload set to ZDO_MGMT_NWK_PARAMS_CHANGE (0xFF) is used to change the channel mask and the network manager’s address parameters (the network update ID may be also changed via this request). The request is formed in the same way as the change channel request (see Section 4.3.5.2), but with scanDuration set to a different value and with the network manager short address provided in the nwkManagerAddr field (network update ID may be set in the nwkUpdateId filed). As part of confirmation ZDO_MgmtNwkUpdateNotf() function will get called which can be handled in the application.