Network Context and Stack APIs#

The EmberZNet PRO stack internally manages multiple networks by maintaining multiple network contexts and by switching to the appropriate network context when required. The internal network context at the stack is totally transparent to the application, and the application has no means of interfering with the stack internal network context.

The stack also stores the application's current network context. Every API call invoked in the application code refers to the application current network. For instance, an emberGetNodeId() call returns the node's short ID on the network referred by the application current network. The following table lists the APIs provided to set and get the application current network.

The first two APIs are straightforward get and set functions for the application network context. The application network context is set by passing emberSetCurrentNetwork a network context index. If the network index to this function is invalid, the API returns the error code EMBER_INDEX_OUT_OF_RANGE.

Note: The set function is also available as a Command Line Interface (CLI) command network set \<x\>. This allows for a seamless extension of other CLI commands to perform network specific operations. The following is an example on how the set API may be used on a multi-PAN device to form two centralized networks.

// Set network context. This serves as application network index for the APIs that follow
// This is similar to CLI command "network set 0"
emberSetNetwork(0);

// Form centralized network on network index 0 
emberAfPluginNetworkCreatorStart(true); 

// Set network context. This serves as application network index for the APIs that follow
// This is similar to CLI command "network set 1"
emberSetNetwork(1);

// Form centralized network on network index 1
// params.channels must match the single channel from the first network!
emberFormNetwork(params);

The emberGetCallbackNetwork() API makes the application aware of the network context for the callback. For instance, when the stack calls emberIncomingMessageHandler(), the application may invoke emberGetCallbackNetwork() inside the callback to retrieve the index of the network on which the packet was received. The following is an example on how to query the network context for a handler.

void emberIncomingMessageHandler ( EmberIncomingMessageType type,
 EmberApsFrame *apsFrame, 
 EmberMessageBuffer message)
{
 //Get network index for incoming packet
 uint8_t nwkIndex = emberGetCallbackNetwork();
 
 emberAfPushCallbackNetworkIndex();
 // Perform any network specific operations here
 emberAfPopNetworkIndex();
}