API for sending and receiving touchlink (formerly Zigbee Light Link) commissioning messages.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.

/***************************************************************************/
#ifndef SILABS_ZLL_API_H
#define SILABS_ZLL_API_H

EmberStatus emberZllFormNetwork(EmberZllNetwork* networkInfo,
                                int8_t radioTxPower);

EmberStatus emberZllJoinTarget(const EmberZllNetwork* targetNetworkInfo);

EmberStatus emberZllSetSecurityStateWithoutKey(const EmberZllInitialSecurityState *securityState);

EmberStatus emberZllSetInitialSecurityState(const EmberKeyData *networkKey,
                                            const EmberZllInitialSecurityState *securityState);

EmberStatus emberZllStartScan(uint32_t channelMask,
                              int8_t radioPowerForScan,
                              EmberNodeType nodeType);

EmberStatus emberZllSetRxOnWhenIdle(uint32_t durationMs);

#ifdef DOXYGEN_SHOULD_SKIP_THIS
void emberZllCancelRxOnWhenIdle(void);
#else
#define emberZllCancelRxOnWhenIdle() emberZllSetRxOnWhenIdle(0)
#endif

void emberZllSetRadioIdleMode(EmberRadioPowerMode mode);

uint8_t emberZllGetRadioIdleMode(void);

void emberZllNetworkFoundHandler(const EmberZllNetwork* networkInfo,
                                 const EmberZllDeviceInfoRecord* deviceInfo);

void emberZllScanCompleteHandler(EmberStatus status);

void emberZllAddressAssignmentHandler(const EmberZllAddressAssignment* addressInfo);

void emberZllTouchLinkTargetHandler(const EmberZllNetwork *networkInfo);

void emberZllGetTokenStackZllData(EmberTokTypeStackZllData *token);

void emberZllGetTokenStackZllSecurity(EmberTokTypeStackZllSecurity *token);

void emberZllGetTokensStackZll(EmberTokTypeStackZllData *data,
                               EmberTokTypeStackZllSecurity *security);

void emberZllSetTokenStackZllData(EmberTokTypeStackZllData *token);

bool emberIsZllNetwork(void);

void emberZllSetNonZllNetwork(void);

EmberZllPolicy emberZllGetPolicy(void);

EmberStatus emberZllSetPolicy(EmberZllPolicy policy);

void emberSetZllNodeType(EmberNodeType nodeType);

void emberSetZllAdditionalState(uint16_t mask);

bool emberZllOperationInProgress(void);

bool emberZllRxOnWhenIdleGetActive(void);

uint32_t emberGetZllPrimaryChannelMask(void);

uint32_t emberGetZllSecondaryChannelMask(void);

void emberSetZllPrimaryChannelMask(uint32_t mask);

void emberSetZllSecondaryChannelMask(uint32_t mask);

void emberZllClearTokens(void);

void emberZllScanningComplete(void);
 // END addtogroup

#endif // SILABS_ZLL_API_H

Functions#

emberZllFormNetwork(EmberZllNetwork *networkInfo, int8_t radioTxPower)

Set the device type as a router or end device (depending on the passed nodeType) and set up a distributed commissioning network with the passed parameters. If panId is 0xFFFF, a random PAN ID will be generated. If extendedPanId is set to all F's, a random extended PAN ID will be generated. If channel is 0xFF, channel 11 will be used. If all F values are passed for PAN ID or Extended PAN ID, the randomly generated values will be returned in the passed structure.

emberZllJoinTarget(const EmberZllNetwork *targetNetworkInfo)

Cause the device to send a NWK start or join to the target device, which causes the remote AND local device to start operating on a network together. If the local device is a factory new end device, it will send a touchlink NWK start to the target requesting that the target generate new network parameters. If the local device is a router, it will form a new touchlink network itself. If the device is not factory new, the local device will send a NWK join request using the current network parameters.

emberZllSetSecurityStateWithoutKey(const EmberZllInitialSecurityState *securityState)

Update the touchlink security token information. Unlike emberZllSetInitialSecurityState, this can be called while a network is already established.

emberZllSetInitialSecurityState(const EmberKeyData *networkKey, const EmberZllInitialSecurityState *securityState)

Cause the device to set up the security information used in its network. Must be called prior to forming, starting, or joining a network.

emberZllStartScan(uint32_t channelMask, int8_t radioPowerForScan, EmberNodeType nodeType)

Initiate a touchlink network scan on all the specified channels. Results will be returned in emberZllNetworkFoundHandler().

emberZllSetRxOnWhenIdle(uint32_t durationMs)

Change the mode of the radio so that the receiver is on when the device is idle. This permits a touchlink target to receive incoming scan requests and an initiator to communicate with a target before the network is established. The idle mode will be set to 'Rx On' until either the duration expires or is set to zero, or unless emberZllCancelRxOnWhenIdle is called.

void

Cancel the special touchlink radio idle mode immediately, without reverting the Stack's radio idle mode to its original setting.

void
emberZllSetRadioIdleMode(EmberRadioPowerMode mode)

Set the default radio power mode directly (This is the radio state when the device is not actively transmitting, and may be either EMBER_RADIO_POWER_MODE_RX_ON or EMBER_RADIO_POWER_MODE_RX_OFF.)

uint8_t

Get the default radio power mode.

void
emberZllNetworkFoundHandler(const EmberZllNetwork *networkInfo, const EmberZllDeviceInfoRecord *deviceInfo)

Called when a touchlink network scan finds a touchlinkable device, which may be joined on either a centralized or a distributed network, or may not be joined at all. The network information will be returned to the application for processing.

void
emberZllScanCompleteHandler(EmberStatus status)

Called when a touchlink network scan is complete.

void
emberZllAddressAssignmentHandler(const EmberZllAddressAssignment *addressInfo)

Called when network and group addresses are assigned to a remote mode in a network start or network join request.

void
emberZllTouchLinkTargetHandler(const EmberZllNetwork *networkInfo)

Called when the device is a target of a touch link.

void
emberZllGetTokenStackZllData(EmberTokTypeStackZllData *token)

Read the touchlink stack data token.

void
emberZllGetTokenStackZllSecurity(EmberTokTypeStackZllSecurity *token)

Read the touchlink stack security token.

void
emberZllGetTokensStackZll(EmberTokTypeStackZllData *data, EmberTokTypeStackZllSecurity *security)

Read both the touchlink stack data and security tokens.

void
emberZllSetTokenStackZllData(EmberTokTypeStackZllData *token)

Set the touchlink stack data token.

bool

Return whether or not the network is a touchlink network, that is, a distributed network formed by touchlink commissioning, and supporting touchlink-compliant address and group id assignment.

void

Alter the touchlink data token to reflect the fact that the network is non-touchlink-compliant.

Get the policy that enables or disables touchlink processing and enable or disable stealing a non-factory-new device.

emberZllSetPolicy(EmberZllPolicy policy)

Set the policy to enable or disable touchlink processing, and enable or disable stealing a non-factory-new device.

void
emberSetZllNodeType(EmberNodeType nodeType)

Set the default node type for a factory new device.

void

Set additional capability bits in the touchlink state.

bool

Indicate that a touchlink network operation is in progress, that is, a network start or a network join.

bool

Indicate whether the special touchlink radio idle mode is active, i.e., whether the radio receiver will remain on when the device is not transmitting and when the device is not on a network.

uint32_t

Get the primary touchlink channel mask.

uint32_t

Get the secondary touchlink channel mask.

void

Set the primary touchlink channel mask.

void

Set the secondary touchlink channel mask.

void

Clear the ZLL stack tokens.

void

Inform the API that all scanning is complete.

Function Documentation#

emberZllFormNetwork#

EmberStatus emberZllFormNetwork (EmberZllNetwork * networkInfo, int8_t radioTxPower)

Set the device type as a router or end device (depending on the passed nodeType) and set up a distributed commissioning network with the passed parameters. If panId is 0xFFFF, a random PAN ID will be generated. If extendedPanId is set to all F's, a random extended PAN ID will be generated. If channel is 0xFF, channel 11 will be used. If all F values are passed for PAN ID or Extended PAN ID, the randomly generated values will be returned in the passed structure.

Parameters
N/AnetworkInfo

A pointer to an EmberZllNetwork struct indicating the network parameters to use when forming the network. If random values are requested, the stack's randomly generated values will be returned in the structure.

N/AradioTxPower

The radio output power at which a node is to operate.

Returns

  • An EmberStatus value indicating whether the operation succeeded or why it failed.


Definition at line 45 of file stack/include/zll-api.h

emberZllJoinTarget#

EmberStatus emberZllJoinTarget (const EmberZllNetwork * targetNetworkInfo)

Cause the device to send a NWK start or join to the target device, which causes the remote AND local device to start operating on a network together. If the local device is a factory new end device, it will send a touchlink NWK start to the target requesting that the target generate new network parameters. If the local device is a router, it will form a new touchlink network itself. If the device is not factory new, the local device will send a NWK join request using the current network parameters.

Parameters
N/AtargetNetworkInfo

A pointer to an EmberZllNetwork structure that indicates the info about what device to send the NWK start/join request to. This information must have previously been returned from a touchlink scan.

Returns

  • An EmberStatus value indicating whether the operation succeeded or why it failed.


Definition at line 65 of file stack/include/zll-api.h

emberZllSetSecurityStateWithoutKey#

EmberStatus emberZllSetSecurityStateWithoutKey (const EmberZllInitialSecurityState * securityState)

Update the touchlink security token information. Unlike emberZllSetInitialSecurityState, this can be called while a network is already established.

Parameters
N/AsecurityState

The security configuration to be set.

Returns

  • An EmberStatus value indicating whether the operation succeeded or why it failed.


Definition at line 76 of file stack/include/zll-api.h

emberZllSetInitialSecurityState#

EmberStatus emberZllSetInitialSecurityState (const EmberKeyData * networkKey, const EmberZllInitialSecurityState * securityState)

Cause the device to set up the security information used in its network. Must be called prior to forming, starting, or joining a network.

Parameters
N/AnetworkKey

A pointer to an EmberKeyData structure containing the value for the network key. If the value is set to all F's, then a random network key will be generated.

N/AsecurityState

The security configuration to be set.

Returns

  • An EmberStatus value indicating whether the operation succeeded or why it failed.


Definition at line 90 of file stack/include/zll-api.h

emberZllStartScan#

EmberStatus emberZllStartScan (uint32_t channelMask, int8_t radioPowerForScan, EmberNodeType nodeType)

Initiate a touchlink network scan on all the specified channels. Results will be returned in emberZllNetworkFoundHandler().

Parameters
N/AchannelMask

Indicates the range of channels to scan.

N/AradioPowerForScan

The radio output power used for the scan requests.

N/AnodeType

The node type of the local device.

Returns

  • An EmberStatus value indicating whether the operation succeeded or why it failed.


Definition at line 104 of file stack/include/zll-api.h

emberZllSetRxOnWhenIdle#

EmberStatus emberZllSetRxOnWhenIdle (uint32_t durationMs)

Change the mode of the radio so that the receiver is on when the device is idle. This permits a touchlink target to receive incoming scan requests and an initiator to communicate with a target before the network is established. The idle mode will be set to 'Rx On' until either the duration expires or is set to zero, or unless emberZllCancelRxOnWhenIdle is called.

Parameters
N/AdurationMs

The duration in milliseconds for which to set the idle mode to 'Rx On'. A duration of 0xffffffff indicates an indefinite duration, so that the device will always be able to respond to touchlink requests when not joined. A duration of 0 will cancel the current touchlink radio idle mode.

Note that, if the device joins or attempts to join a network during this period, then the Stack will suspend the special touchlink radio idle mode, and the Stack's radio idle mode will revert to the joined default appropriate to the node type. If, however, the device leaves, or the join fails, then the touchlink radio idle mode will be resumed, provided that the duration timer has not expired.

Also note that a subsequent call to emberZllSetRxOnWhenIdle may only extend the (currently outstanding) 'Rx On' duration. If a shorter duration is required, (or if an indefinite duration is currently set) then emberZllSetRxOnWhenIdle must be called first with a duration of 0, in order to cancel the current touchlink radio idle mode.

Returns

  • An EmberStatus value indicating whether the operation succeeded or why it failed. A return value of EMBER_INVALID_CALL indicates that the special touchlink radio idle mode is active, but has been suspended by the Stack, because the device has joined a network, or is in the process of joining, or that an attempt was made to reduce the 'Rx On' duration without canceling the existing touchlink radio idle mode.


Definition at line 140 of file stack/include/zll-api.h

emberZllCancelRxOnWhenIdle#

void emberZllCancelRxOnWhenIdle (void )

Cancel the special touchlink radio idle mode immediately, without reverting the Stack's radio idle mode to its original setting.

Parameters
N/A

Definition at line 148 of file stack/include/zll-api.h

emberZllSetRadioIdleMode#

void emberZllSetRadioIdleMode (EmberRadioPowerMode mode)

Set the default radio power mode directly (This is the radio state when the device is not actively transmitting, and may be either EMBER_RADIO_POWER_MODE_RX_ON or EMBER_RADIO_POWER_MODE_RX_OFF.)

Parameters
N/Amode

The power mode to set.


Definition at line 160 of file stack/include/zll-api.h

emberZllGetRadioIdleMode#

uint8_t emberZllGetRadioIdleMode (void )

Get the default radio power mode.

Parameters
N/A

Returns

  • The current default radio power mode


Definition at line 167 of file stack/include/zll-api.h

emberZllNetworkFoundHandler#

void emberZllNetworkFoundHandler (const EmberZllNetwork * networkInfo, const EmberZllDeviceInfoRecord * deviceInfo)

Called when a touchlink network scan finds a touchlinkable device, which may be joined on either a centralized or a distributed network, or may not be joined at all. The network information will be returned to the application for processing.

Parameters
N/AnetworkInfo

A pointer to an EmberZllNetwork struct containing the Zigbee and touchlink specific information about the discovered network.

N/AdeviceInfo

A pointer to an EmberZllDeviceInfoRecord struct containing the device specific info. This pointer may be NULL, indicating the device has either 0 sub-devices or more than 1 sub-devices.


Definition at line 183 of file stack/include/zll-api.h

emberZllScanCompleteHandler#

void emberZllScanCompleteHandler (EmberStatus status)

Called when a touchlink network scan is complete.

Parameters
N/Astatus

An EmberStatus value indicating whether the operation succeeded, or why it failed. If the status is not EMBER_SUCCESS, the application should not attempt to start or join a network returned via emberZllNetworkFoundHandler.


Definition at line 194 of file stack/include/zll-api.h

emberZllAddressAssignmentHandler#

void emberZllAddressAssignmentHandler (const EmberZllAddressAssignment * addressInfo)

Called when network and group addresses are assigned to a remote mode in a network start or network join request.

Parameters
N/AaddressInfo

A pointer to an EmberZllAddressAssignment struct containing the address assignment information.


Definition at line 203 of file stack/include/zll-api.h

emberZllTouchLinkTargetHandler#

void emberZllTouchLinkTargetHandler (const EmberZllNetwork * networkInfo)

Called when the device is a target of a touch link.

Parameters
N/AnetworkInfo

A pointer to an EmberZllNetwork struct containing the Zigbee and touchlink specific information about the initiator.


Definition at line 211 of file stack/include/zll-api.h

emberZllGetTokenStackZllData#

void emberZllGetTokenStackZllData (EmberTokTypeStackZllData * token)

Read the touchlink stack data token.

Parameters
N/Atoken

Definition at line 216 of file stack/include/zll-api.h

emberZllGetTokenStackZllSecurity#

void emberZllGetTokenStackZllSecurity (EmberTokTypeStackZllSecurity * token)

Read the touchlink stack security token.

Parameters
N/Atoken

Definition at line 221 of file stack/include/zll-api.h

emberZllGetTokensStackZll#

void emberZllGetTokensStackZll (EmberTokTypeStackZllData * data, EmberTokTypeStackZllSecurity * security)

Read both the touchlink stack data and security tokens.

Parameters
N/Adata
N/Asecurity

Definition at line 226 of file stack/include/zll-api.h

emberZllSetTokenStackZllData#

void emberZllSetTokenStackZllData (EmberTokTypeStackZllData * token)

Set the touchlink stack data token.

Parameters
N/Atoken

Definition at line 232 of file stack/include/zll-api.h

emberIsZllNetwork#

bool emberIsZllNetwork (void )

Return whether or not the network is a touchlink network, that is, a distributed network formed by touchlink commissioning, and supporting touchlink-compliant address and group id assignment.

Parameters
N/A

Definition at line 239 of file stack/include/zll-api.h

emberZllSetNonZllNetwork#

void emberZllSetNonZllNetwork (void )

Alter the touchlink data token to reflect the fact that the network is non-touchlink-compliant.

Parameters
N/A

Definition at line 245 of file stack/include/zll-api.h

emberZllGetPolicy#

EmberZllPolicy emberZllGetPolicy (void )

Get the policy that enables or disables touchlink processing and enable or disable stealing a non-factory-new device.

Parameters
N/A

Definition at line 251 of file stack/include/zll-api.h

emberZllSetPolicy#

EmberStatus emberZllSetPolicy (EmberZllPolicy policy)

Set the policy to enable or disable touchlink processing, and enable or disable stealing a non-factory-new device.

Parameters
N/Apolicy

Definition at line 257 of file stack/include/zll-api.h

emberSetZllNodeType#

void emberSetZllNodeType (EmberNodeType nodeType)

Set the default node type for a factory new device.

Parameters
N/AnodeType

node type to be set.


Definition at line 264 of file stack/include/zll-api.h

emberSetZllAdditionalState#

void emberSetZllAdditionalState (uint16_t mask)

Set additional capability bits in the touchlink state.

Parameters
N/Amask

mask with the bits to be set or cleared.


Definition at line 271 of file stack/include/zll-api.h

emberZllOperationInProgress#

bool emberZllOperationInProgress (void )

Indicate that a touchlink network operation is in progress, that is, a network start or a network join.

Parameters
N/A

Definition at line 277 of file stack/include/zll-api.h

emberZllRxOnWhenIdleGetActive#

bool emberZllRxOnWhenIdleGetActive (void )

Indicate whether the special touchlink radio idle mode is active, i.e., whether the radio receiver will remain on when the device is not transmitting and when the device is not on a network.

Parameters
N/A

Definition at line 284 of file stack/include/zll-api.h

emberGetZllPrimaryChannelMask#

uint32_t emberGetZllPrimaryChannelMask (void )

Get the primary touchlink channel mask.

Parameters
N/A

Returns

  • The touchlink primary channel mask.


Definition at line 291 of file stack/include/zll-api.h

emberGetZllSecondaryChannelMask#

uint32_t emberGetZllSecondaryChannelMask (void )

Get the secondary touchlink channel mask.

Parameters
N/A

Returns

  • The touchlink secondary channel mask.


Definition at line 298 of file stack/include/zll-api.h

emberSetZllPrimaryChannelMask#

void emberSetZllPrimaryChannelMask (uint32_t mask)

Set the primary touchlink channel mask.

Parameters
N/Amask

touchlink primary channel mask.


Definition at line 305 of file stack/include/zll-api.h

emberSetZllSecondaryChannelMask#

void emberSetZllSecondaryChannelMask (uint32_t mask)

Set the secondary touchlink channel mask.

Parameters
N/Amask

touchlink secondary channel mask.


Definition at line 312 of file stack/include/zll-api.h

emberZllClearTokens#

void emberZllClearTokens (void )

Clear the ZLL stack tokens.

Parameters
N/A

Definition at line 318 of file stack/include/zll-api.h

emberZllScanningComplete#

void emberZllScanningComplete (void )

Inform the API that all scanning is complete.

Parameters
N/A

Definition at line 324 of file stack/include/zll-api.h