4.6.1 Network Start

To start a network on a certain device, the user must either form a new network if the device is the coordinator or discover and join an existing network if the device is a router or an end device. In both cases, the user must call the ZDO_StartNetworkReq_t function. This function requires a pointer to an instance of the ZDO_StartNetworkReq_t type as its argument. The user needs to specify only one field in the request parameters, a pointer to the confirmation callback, which the user can provide in the ZDO_StartNetworkConf field. After completing the request, the APS layer updates the confirm field with the execution status and information about the network that the device has entered. The callback receives a pointer to this field as its argument. The following code sample demonstrates how to initiate 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);

For most requests in the stack, the status field within the confirmation parameters indicates the successful execution of the request. The value ZDO_SUCCESS_STATUS signifies that the device has successfully formed or joined a network. In such cases, the network parameters, including the short address assigned to the device and the parent address, accompany the confirmation. For more details, refer to the ZDO_StartNetworkConf_t.

Configuring Network Start

The stack provides the user with the means to further the control of a network start. The initiation of the network start process depends on the ConfigServer parameters identified by CS_JOIN_CONTROL_ID. The application can populate a NWK_JoinControl_t structure and set it as the value of the parameter using the CS_WriteParameter at any point before initiating the network start.

The structure includes a method field that determines the type of network start. The NWK_JoinMethod_t enumeration lists possible values. The default, NWK_JOIN_BY_DEFAULT, allows the stack to choose a network start type based on ConfigServer parameters. If the device type is a coordinator, it forms a new network. If the network’s extended PANID (CS_EXT_PANID) is unknown, it uses the association procedure; if known, it applies the rejoining procedure. The application selects a specific network start method by assigning a different value to the method field. The application must ensure that all necessary parameters for the chosen method are set; otherwise, the network start is going to fail.

The application can set the boolean fields within the NWK_JoinControl_t structure as needed, independent of the value in the method field:
  • secured – Indicates whether frames exchanged during network start are encrypted with the network key, which is set in the CS_NETWORK_KEY parameter
  • discoverNetworks – Directs the stack to scan for networks during the network start (if set to true). Scanning populates the neighbor table with entries of discovered devices. If the field is set to false, the application can populate the neighbor table manually.
  • annce – specifies whether to send a device announcement frame after the network start, signaling that a new node joined the network. To monitor device announcements from child nodes, the application can subscribe to the BC_EVENT_DEVICE_ANNCE event using the SYS_SubscribeToEvent() function.
The following example code configures a node to rejoin the network without sending a device announcement frame upon a 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