14.2.3.6.1 Network Start

Starting network on a certain device means forming a new network if the device is the coordinator or discovering and joining to an existent network if the device is a router or an end device. In both cases the user should call the ZDO_StartNetworkReq_t function. The function takes a pointer to an instance of ZDO_StartNetworkReq_t type as an argument. The only field to be specified in the request parameters is a pointer to the confirmation callback given in the ZDO_StartNetworkConf field. Upon request completion the APS layer fills the confirm field with the execution status and information about the network entered by the device. A pointer to this field is received as the argument of the callback. The following code sample demonstrates how to perform a network start.

//The parameters for the network start request
 ZDO_StartNetworkReq_t networkParams;

//the definition of the callback for the network start request
static void ZDO_StartNetworkConf(ZDO_StartNetworkConf_t *confirmInfo)
{
    //code goes here
}
...
//configure the request parameters
networkParams.ZDO_StartNetworkConf = ZDO_StartNetworkConf;
//send the request 
ZDO_StartNetworkReq(&networkParams);

As for the most of requests in the stack, the status field of confirmation parameters reports whether the request has been executed successfully. The ZDO_SUCCESS_STATUS value indicates that the device has successfully formed or joined the network. In this case network parameters, the short address assigned to the device and the parent address are received as well (see documentation of ZDO_StartNetworkConf_t).

Configuring network start

The stack provides a user with means of further control of a network start. The way the network start goes depends on the ConfigServer parameters with the ID CS_JOIN_CONTROL_ID. The application can fill a structure of NWK_JoinControl_t type and set it a the value of the parameter, using the CS_WriteParameter value, at any item before network start.

The structure includes the method field, which sets the type of network start. Possible values are given in the NWK_JoinMethod_t enumeration. The default value is NWK_JOIN_BY_DEFAULT, which makes the stack select a network start type on the basis of ConfigServer parameters. Basically, if device's type is the coordinator, a new network is formed, and otherwise if the extended PANID of the network (CS_EXT_PANID) is unknown the association procedure is used, and if the extended PANID is already known the rejoining procedure is applied. A particular method for the network start is selecting by assigning a different value to the method field. The application can also set any appropriate value, though is shall ensure that all parameters required by the method are set or, otherwise, network start will fail.

Other fields, all of boolean type, of the NWK_JoinControl_t structure are (the application can set these fields as it seems appropriate regardless of the method field's value):

  • secured - determines if frames exchanged during network start are encrypted with the network key. The network key should be set in the CS_NETWORK_KEY parameter.
  • discoverNetworks - causes the stack to scan for networks during network start (if set to true) or not. During scanning, the neighbor table is filled with entries describing discovered devices. So if this field is set to false the application can fill neighbor table by itself.
  • annce - determines if a device announcement frame will be sent after network start, notifying other devices that a new node has entered the network. The application on a node can track device announcement frames sent by its child nodes if it subscribes to the BC_EVENT_DEVICE_ANNCE event, using the SYS_SubscribeToEvent() function.

In the following code example the node is configured to join the network via rejoin but without sending a device announcement frame on successful rejoin: 

NWK_JoinControl_t joinControl = {
  .method = NWK_JOIN_VIA_REJOIN,  //CS_EXT_PANID must be set
  .secured = true,
  .discoverNetworks = true,
  .annce = false//Device announcement won't be sent after network join
};
CS_WriteParameter(CS_JOIN_CONTROL_ID, &joinControl); //Set the parameter in ConfigServer