Forming and Joining Networks#

Functions for finding an existing network to join and for finding an unused PAN id with which to form a network.

Summary of application requirements:

For the SoC:

For an EZSP Host:

  • Define ::EZSP_APPLICATION_HAS_ENERGY_SCAN_RESULT_HANDLER in the configuration header.

  • Include form-and-join.c and form-and-join-host-adapter.c in the build.

  • Optionally include form-and-join-host-callbacks.c in the build.

For either platform, the application can omit the form-and-join-*-callback.c file from the build and implement the callbacks itself if necessary. In this case, the appropriate form-and-join callback function must be called from within each callback as within the form-and-join-*-callback.c files.

On either platform, FORM_AND_JOIN_MAX_NETWORKS can be explicitly defined to limit (or expand) the number of joinable networks that the library will save for consideration during the scan process.

The library can resume scanning for joinable networks from where it left off, via a call to emberScanForNextJoinableNetwork(). Therefore, if the first joinable network found is not the correct one, the application can continue scanning without starting from the beginning and without finding the same network that it has already rejected. The library can also be used on the host processor.

Functions#

emberScanForUnusedPanId(uint32_t channelMask, uint8_t duration)

Find an unused PAN ID.

emberScanForJoinableNetwork(uint32_t channelMask, uint8_t *extendedPanId)

Find a joinable network.

bool

Return true if and only if the form and join library is in the process of scanning and is therefore expecting scan results to be passed to it from the application.

bool

Return true if and only if the application can continue a joinable network scan by calling emberScanForNextJoinableNetwork(). See emberScanForJoinableNetwork().

void
emberJoinableNetworkFoundHandler(EmberZigbeeNetwork *networkFound, uint8_t lqi, int8_t rssi)

A callback the application needs to implement.

void
emberScanErrorHandler(EmberStatus status)

A callback the application needs to implement.

bool
emberFormAndJoinScanCompleteHandler(uint8_t channel, EmberStatus status)

The application must call this function from within its emberScanCompleteHandler() (on the node) or ezspScanCompleteHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

bool
emberFormAndJoinNetworkFoundHandler(EmberZigbeeNetwork *networkFound, uint8_t lqi, int8_t rssi)

The application must call this function from within its emberNetworkFoundHandler() (on the node) or ezspNetworkFoundHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

bool
emberFormAndJoinEnergyScanResultHandler(uint8_t channel, int8_t maxRssiValue)

The application must call this function from within its emberEnergyScanResultHandler() (on the node) or ezspEnergyScanResultHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

bool
emberFormAndJoinUnusedPanIdFoundHandler(EmberPanId panId, uint8_t channel)

The application must call this function from within its emberUnusedPandIdFoundHandler() (on the node) or ezspEnergyScanResultHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

void

When processor idling is desired on the SOC, this must be called to properly initialize the form and join library.

void

When processor idling is desired on the SOC, this should be called regularly instead of emberFormAndJoinTick()

void
emberFormAndJoinCleanup(EmberStatus status)

When form-and-join state is no longer needed, the application can call this routine to cleanup and free resources. On the SOC platforms this will free the allocated message buffer.

void
emberAfPluginFormAndJoinNetworkFoundCallback(EmberZigbeeNetwork *networkFound, uint8_t lqi, int8_t rssi)

Network found.

void
emberAfPluginFormAndJoinUnusedPanIdFoundCallback(EmberPanId panId, uint8_t channel)

Unused Pan ID found.

Macros#

#define
NETWORK_STORAGE_SIZE 16

Number of bytes required to store relevant info for a saved network.

#define
NETWORK_STORAGE_SIZE_SHIFT 4

Log_base2 of NETWORK_STORAGE_SIZE.

#define
FORM_AND_JOIN_MAX_NETWORKS 15

Number of joinable networks that can be remembered during the scan process.

Function Documentation#

emberScanForUnusedPanId#

EmberStatus emberScanForUnusedPanId (uint32_t channelMask, uint8_t duration)

Find an unused PAN ID.

Parameters
TypeDirectionArgument NameDescription
uint32_tN/AchannelMask
uint8_tN/Aduration

The duration of the energy scan. See the documentation for emberStartScan() in stack/include/network-formation.h for information on duration values.

Does an energy scan on the indicated channels and randomly chooses one from amongst those with the least average energy. Then picks a short PAN ID that does not appear during an active scan on the chosen channel. The chosen PAN ID and channel are returned via the emberUnusedPanIdFoundHandler() callback. If an error occurs, the application is informed via the emberScanErrorHandler().

Returns

  • EMBER_LIBRARY_NOT_PRESENT if the form and join library is not available.


Definition at line 133 of file app/util/common/form-and-join.h

emberScanForJoinableNetwork#

EmberStatus emberScanForJoinableNetwork (uint32_t channelMask, uint8_t * extendedPanId)

Find a joinable network.

Parameters
TypeDirectionArgument NameDescription
uint32_tN/AchannelMask
uint8_t *N/AextendedPanId

Performs an active scan on the specified channels looking for networks that:

  1. currently permit joining,

  2. match the stack profile of the application,

  3. match the extended PAN id argument if it is not NULL.

Upon finding a matching network, the application is notified via the emberJoinableNetworkFoundHandler() callback, and scanning stops. If an error occurs during the scanning process, the application is informed via the emberScanErrorHandler(), and scanning stops.

If the application determines that the discovered network is not the correct one, it may call emberScanForNextJoinableNetwork() to continue the scanning process where it was left off and find a different joinable network. If the next network is not the correct one, the application can continue to call emberScanForNextJoinableNetwork(). Each call must occur within 30 seconds of the previous one, otherwise the state of the scan process is deleted to free up memory. Calling emberScanForJoinableNetwork() causes any old state to be forgotten and starts scanning from the beginning.

Returns

  • EMBER_LIBRARY_NOT_PRESENT if the form and join library is not available.


Definition at line 161 of file app/util/common/form-and-join.h

emberScanForNextJoinableNetwork#

EmberStatus emberScanForNextJoinableNetwork (void )

See emberScanForJoinableNetwork().

Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 164 of file app/util/common/form-and-join.h

emberFormAndJoinIsScanning#

bool emberFormAndJoinIsScanning (void )

Return true if and only if the form and join library is in the process of scanning and is therefore expecting scan results to be passed to it from the application.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 170 of file app/util/common/form-and-join.h

emberFormAndJoinCanContinueJoinableNetworkScan#

bool emberFormAndJoinCanContinueJoinableNetworkScan (void )

Return true if and only if the application can continue a joinable network scan by calling emberScanForNextJoinableNetwork(). See emberScanForJoinableNetwork().

Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 176 of file app/util/common/form-and-join.h

emberJoinableNetworkFoundHandler#

void emberJoinableNetworkFoundHandler (EmberZigbeeNetwork * networkFound, uint8_t lqi, int8_t rssi)

A callback the application needs to implement.

Parameters
TypeDirectionArgument NameDescription
EmberZigbeeNetwork *N/AnetworkFound
uint8_tN/Alqi

The LQI value of the received beacon.

int8_tN/Arssi

The RSSI value of the received beacon.

Notifies the application of the network found after a call to emberScanForJoinableNetwork() or emberScanForNextJoinableNetwork().


Definition at line 191 of file app/util/common/form-and-join.h

emberScanErrorHandler#

void emberScanErrorHandler (EmberStatus status)

A callback the application needs to implement.

Parameters
TypeDirectionArgument NameDescription
EmberStatusN/Astatus

If an error occurs while scanning, this function is called and the scan effort is aborted.

Possible return status values are:


Definition at line 212 of file app/util/common/form-and-join.h

emberFormAndJoinScanCompleteHandler#

bool emberFormAndJoinScanCompleteHandler (uint8_t channel, EmberStatus status)

The application must call this function from within its emberScanCompleteHandler() (on the node) or ezspScanCompleteHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/Achannel
EmberStatusN/Astatus

Returns

  • true if the library made use of the call.


Definition at line 225 of file app/util/common/form-and-join.h

emberFormAndJoinNetworkFoundHandler#

bool emberFormAndJoinNetworkFoundHandler (EmberZigbeeNetwork * networkFound, uint8_t lqi, int8_t rssi)

The application must call this function from within its emberNetworkFoundHandler() (on the node) or ezspNetworkFoundHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Parameters
TypeDirectionArgument NameDescription
EmberZigbeeNetwork *N/AnetworkFound
uint8_tN/Alqi
int8_tN/Arssi

Returns

  • true if the library made use of the call.


Definition at line 234 of file app/util/common/form-and-join.h

emberFormAndJoinEnergyScanResultHandler#

bool emberFormAndJoinEnergyScanResultHandler (uint8_t channel, int8_t maxRssiValue)

The application must call this function from within its emberEnergyScanResultHandler() (on the node) or ezspEnergyScanResultHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/Achannel
int8_tN/AmaxRssiValue

Returns

  • true if the library made use of the call.


Definition at line 245 of file app/util/common/form-and-join.h

emberFormAndJoinUnusedPanIdFoundHandler#

bool emberFormAndJoinUnusedPanIdFoundHandler (EmberPanId panId, uint8_t channel)

The application must call this function from within its emberUnusedPandIdFoundHandler() (on the node) or ezspEnergyScanResultHandler() (on an EZSP host). Default callback implementations are provided in the form-and-join-*-callbacks.c files.

Parameters
TypeDirectionArgument NameDescription
EmberPanIdN/ApanId
uint8_tN/Achannel

Definition at line 252 of file app/util/common/form-and-join.h

emberFormAndJoinTick#

void emberFormAndJoinTick (void )
Parameters
TypeDirectionArgument NameDescription
voidN/A

Used by the form and join code on the node to time out a joinable scan after 30 seconds of inactivity. The application must call emberFormAndJoinTick() regularly. This function does not exist for the EZSP host library.


Definition at line 258 of file app/util/common/form-and-join.h

emberFormAndJoinTaskInit#

void emberFormAndJoinTaskInit (void )

When processor idling is desired on the SOC, this must be called to properly initialize the form and join library.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 263 of file app/util/common/form-and-join.h

emberFormAndJoinRunTask#

void emberFormAndJoinRunTask (void )

When processor idling is desired on the SOC, this should be called regularly instead of emberFormAndJoinTick()

Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 268 of file app/util/common/form-and-join.h

emberFormAndJoinCleanup#

void emberFormAndJoinCleanup (EmberStatus status)

When form-and-join state is no longer needed, the application can call this routine to cleanup and free resources. On the SOC platforms this will free the allocated message buffer.

Parameters
TypeDirectionArgument NameDescription
EmberStatusN/Astatus

Definition at line 274 of file app/util/common/form-and-join.h

emberAfPluginFormAndJoinNetworkFoundCallback#

void emberAfPluginFormAndJoinNetworkFoundCallback (EmberZigbeeNetwork * networkFound, uint8_t lqi, int8_t rssi)

Network found.

Parameters
TypeDirectionArgument NameDescription
EmberZigbeeNetwork *N/AnetworkFound

Ver.: always

uint8_tN/Alqi

Ver.: always

int8_tN/Arssi

Ver.: always

This is called by the form-and-join library to notify the application of the network found after a call to emberScanForJoinableNetwork() or emberScanForNextJoinableNetwork(). See form-and-join documentation for more information.


Definition at line 287 of file app/util/common/form-and-join.h

emberAfPluginFormAndJoinUnusedPanIdFoundCallback#

void emberAfPluginFormAndJoinUnusedPanIdFoundCallback (EmberPanId panId, uint8_t channel)

Unused Pan ID found.

Parameters
TypeDirectionArgument NameDescription
EmberPanIdN/ApanId

A randomly generated PAN ID without other devices on it. Ver.: always

uint8_tN/Achannel

The channel where the PAN ID can be used to form a new network. Ver.: always

This function is called when the form-and-join library finds an unused PAN ID that can be used to form a new network on.


Definition at line 301 of file app/util/common/form-and-join.h