Ember ZigBee Light Link (ZLL) APIs and Handlers#

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.

Returns

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

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.

Returns

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

emberZllSetSecurityStateWithoutKey#

EmberStatus emberZllSetSecurityStateWithoutKey (const EmberZllInitialSecurityState *securityState)

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

Returns

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

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.

Returns

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

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().

Returns

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

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.

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 cancelling the existing touchlink radio idle mode.

emberZllCancelRxOnWhenIdle#

void emberZllCancelRxOnWhenIdle (void)

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

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.)

emberZllGetRadioIdleMode#

uint8_t emberZllGetRadioIdleMode (void)

Get the default radio power mode.

Returns

• The current default radio power mode

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.

emberZllScanCompleteHandler#

void emberZllScanCompleteHandler (EmberStatus status)

Called when a touchlink network scan is complete.

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.

emberZllTouchLinkTargetHandler#

void emberZllTouchLinkTargetHandler (const EmberZllNetwork *networkInfo)

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

emberZllGetTokenStackZllData#

void emberZllGetTokenStackZllData (EmberTokTypeStackZllData *token)

Read the touchlink stack data token.

emberZllGetTokenStackZllSecurity#

void emberZllGetTokenStackZllSecurity (EmberTokTypeStackZllSecurity *token)

Read the touchlink stack security token.

emberZllGetTokensStackZll#

void emberZllGetTokensStackZll (EmberTokTypeStackZllData *data, EmberTokTypeStackZllSecurity *security)

Read both the touchlink stack data and security tokens.

emberZllSetTokenStackZllData#

void emberZllSetTokenStackZllData (EmberTokTypeStackZllData *token)

Set the touchlink stack data token.

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.

emberZllSetNonZllNetwork#

void emberZllSetNonZllNetwork (void)

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

emberZllGetPolicy#

EmberZllPolicy emberZllGetPolicy (void)

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

emberZllSetPolicy#

EmberStatus emberZllSetPolicy (EmberZllPolicy policy)

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

emberSetZllNodeType#

void emberSetZllNodeType (EmberNodeType nodeType)

Set the default node type for a factory new device.

emberSetZllAdditionalState#

void emberSetZllAdditionalState (uint16_t mask)

Set additional capability bits in the touchlink state.

emberZllOperationInProgress#

bool emberZllOperationInProgress (void)

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

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.

emberGetZllPrimaryChannelMask#

uint32_t emberGetZllPrimaryChannelMask (void)

Get the primary touchlink channel mask.

Returns

• The touchlink primary channel mask.

emberGetZllSecondaryChannelMask#

uint32_t emberGetZllSecondaryChannelMask (void)

Get the secondary touchlink channel mask.

Returns

• The touchlink secondary channel mask.

emberSetZllPrimaryChannelMask#

void emberSetZllPrimaryChannelMask (uint32_t mask)

Set the primary touchlink channel mask.

emberSetZllSecondaryChannelMask#

void emberSetZllSecondaryChannelMask (uint32_t mask)

Set the secondary touchlink channel mask.

emberZllClearTokens#

void emberZllClearTokens (void)

Clear the ZLL stack tokens.

emberZllScanningComplete#

void emberZllScanningComplete (void)

Inform the API that all scanning is complete.