Macros
#define	touchLinkInProgress()

#define	scanForTouchLink() (emAfZllFlags & SCAN_FOR_TOUCH_LINK)

#define	scanForDeviceInformation() (emAfZllFlags & SCAN_FOR_DEVICE_INFORMATION)

#define	scanForIdentify() (emAfZllFlags & SCAN_FOR_IDENTIFY)

#define	scanForReset() (emAfZllFlags & SCAN_FOR_RESET)

#define	targetNetworkFound() (emAfZllFlags & TARGET_NETWORK_FOUND)

#define	abortingTouchLink() (emAfZllFlags & ABORTING_TOUCH_LINK)

#define	scanComplete() (emAfZllFlags & SCAN_COMPLETE)

#define	touchLinkTarget() (emAfZllFlags & TOUCH_LINK_TARGET)

#define	formingNetwork() (emAfZllFlags & FORMING_NETWORK)

#define	resettingToFactoryNew() (emAfZllFlags & RESETTING_TO_FACTORY_NEW)

#define	ZLL_FRAME_CONTROL_LEGACY 0x00

#define	ZLL_FRAME_CONTROL_CLIENT_TO_SERVER 0x11

#define	ZLL_FRAME_CONTROL_SERVER_TO_CLIENT 0x19

#define	ZLL_HEADER_FRAME_CONTROL_OFFSET 0

#define	ZLL_HEADER_SEQUENCE_NUMBER_OFFSET 1

#define	ZLL_HEADER_COMMAND_ID_OFFSET 2

#define	ZLL_HEADER_TRANSACTION_ID_OFFSET 3

#define	ZLL_HEADER_OVERHEAD 7

#define	debugPrintln(...)

#define	debugPrint(...)

#define	debugExec(x)

#define	emberAfPluginZllCommissioningInitialSecurityStateCallback emberAfPluginZllCommissioningCommonInitialSecurityStateCallback

#define	emberAfPluginZllCommissioningTouchLinkCompleteCallback emberAfPluginZllCommissioningCommonTouchLinkCompleteCallback

#define	emberAfPluginZllCommissioningResetToFactoryNewCallback emberAfPluginZllCommissioningCommonResetToFactoryNewCallback

Enumerations
enum	{ INITIAL = 0x0000, SCAN_FOR_TOUCH_LINK = 0x0001, SCAN_FOR_DEVICE_INFORMATION = 0x0002, SCAN_FOR_IDENTIFY = 0x0004, SCAN_FOR_RESET = 0x0008, TARGET_NETWORK_FOUND = 0x0010, ABORTING_TOUCH_LINK = 0x0020, SCAN_COMPLETE = 0x0040, TOUCH_LINK_TARGET = 0x0080, FORMING_NETWORK = 0x0100, RESETTING_TO_FACTORY_NEW = 0x0200 }

enum	{ EMBER_RADIO_POWER_MODE_RX_ON, EMBER_RADIO_POWER_MODE_OFF }

Functions
EmberStatus	emberZllFormNetwork (EmberZllNetwork *networkInfo, int8_t radioTxPower)
	This will set the device type as a router or end device (depending on the passed nodeType) and setup 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, then a random extended PAN ID will be generated. If channel is 0xFF, then channel 11 will be used. If all F values are passed for PAN ID or Extended PAN ID, then the randomly generated values will be returned in the passed structure.

EmberStatus	emberZllJoinTarget (const EmberZllNetwork *targetNetworkInfo)
	Causes 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, then 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, then 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.

EmberStatus	emberZllSetSecurityStateWithoutKey (const EmberZllInitialSecurityState *securityState)
	Updates the touchlink security token information. Unlike emberZllSetInitialSecurityState, this can be called while a network is already established.

EmberStatus	emberZllSetInitialSecurityState (const EmberKeyData networkKey, const EmberZllInitialSecurityState securityState)
	Causes the device to setup the security information used in its network. Must be called prior to forming, starting, or joining a network.

EmberStatus	emberZllStartScan (uint32_t channelMask, int8_t radioPowerForScan, EmberNodeType nodeType)
	Initiates a touchlink network scan on all the specified channels. Results will be returned in emberZllNetworkFoundHandler().

EmberStatus	emberZllSetRxOnWhenIdle (uint32_t durationMs)
	Changes 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	emberZllCancelRxOnWhenIdle (void)
	Cancels the special touchlink radio idle mode immediately, without reverting the Stack's radio idle mode to its original setting.

void	emberZllSetRadioIdleMode (EmberRadioPowerMode mode)
	Sets 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	emberZllGetRadioIdleMode (void)
	Get the default radio power mode.

void	emberZllNetworkFoundHandler (const EmberZllNetwork networkInfo, const EmberZllDeviceInfoRecord deviceInfo)
	This call is fired 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)
	This call is fired when a touchlink network scan is complete.

void	emberZllAddressAssignmentHandler (const EmberZllAddressAssignment *addressInfo)
	This call is fired when network and group addresses are assigned to a remote mode in a network start or network join request.

void	emberZllTouchLinkTargetHandler (const EmberZllNetwork *networkInfo)
	This call is fired when the device is a target of a touch link.

void	emberZllGetTokenStackZllData (EmberTokTypeStackZllData *token)
	Reads the touchlink stack data token.

void	emberZllGetTokenStackZllSecurity (EmberTokTypeStackZllSecurity *token)
	Reads the touchlink stack security token.

void	emberZllGetTokensStackZll (EmberTokTypeStackZllData data, EmberTokTypeStackZllSecurity security)
	Reads both the touchlink stack data and security tokens.

void	emberZllSetTokenStackZllData (EmberTokTypeStackZllData *token)
	Sets the touchlink stack data token.

bool	emberIsZllNetwork (void)
	Returns 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	emberZllSetNonZllNetwork (void)
	Alters the touchlink data token to reflect the fact that the network is non-touchlink-compliant.

EmberZllPolicy	emberZllGetPolicy (void)
	Gets the policy that enables or disables touchlink processing, and to enable or disable stealing a non-factory-new device.

EmberStatus	emberZllSetPolicy (EmberZllPolicy policy)
	Sets the policy to enable or disable touchlink processing, and to enable or disable stealing a non-factory-new device.

void	emberSetZllNodeType (EmberNodeType nodeType)
	Sets the default node type for a factory new device.

void	emberSetZllAdditionalState (uint16_t mask)
	Sets additional capability bits in the touchlink state.

bool	emberZllOperationInProgress (void)
	Indicates that a touchlink network operation is in progress, that is, a network start or a network join.

bool	emberZllRxOnWhenIdleGetActive (void)
	This function is called to 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, when the device is not on a network.

uint32_t	emberGetZllPrimaryChannelMask (void)
	This call will get the primary touchlink channel mask.

uint32_t	emberGetZllSecondaryChannelMask (void)
	This call will get the secondary touchlink channel mask.

void	emberSetZllPrimaryChannelMask (uint32_t mask)
	This call will set the primary touchlink channel mask.

void	emberSetZllSecondaryChannelMask (uint32_t mask)
	This call will set the secondary touchlink channel mask.

void	emberZllClearTokens (void)
	This call will clear the ZLL stack tokens.

void	emberZllScanningComplete (void)
	This call will inform the API that all scanning is complete.

EmberStatus	emberAfZllInitiateTouchLink (void)
	Initiates the touch link procedure.

EmberStatus	emberAfZllDeviceInformationRequest (void)
	Initiates a touch link to retrieve information about a target device.

EmberStatus	emberAfZllIdentifyRequest (void)
	Initiates a touch link to cause a target device to identify itself.

EmberStatus	emberAfZllResetToFactoryNewRequest (void)
	Initiates a touch link for the purpose of resetting a target device.

void	emberAfZllAbortTouchLink (void)
	Aborts the touch link procedure.

EmberStatus	emberAfZllSetInitialSecurityState (void)
	Generates a random network key and initializes the security state of the device.

bool	emberAfZllTouchLinkInProgress (void)
	Indicates whether a touch link procedure is currently in progress.

void	emberAfZllResetToFactoryNew (void)
	Resets the local device to a factory new state.

EmberStatus	emberAfZllDisable (void)
	Disables touchlink processing.

EmberStatus	emberAfZllEnable (void)
	Enables touchlink processing.

EmberStatus	emberAfZllScanForJoinableNetwork (void)
	Scans for joinable networks.

EmberStatus	emberAfZllScanForUnusedPanId (void)
	Scans for an unused PAN ID.

EmberStatus	emberAfZllNoTouchlinkForNFN (void)
	No touchlink for non-factory new device.

EmberStatus	emberAfZllNoResetForNFN (void)
	No reset for non-factory new device.

Variables
EmberZllNetwork	emAfZllNetwork

uint16_t	emAfZllFlags

uint8_t	emAfInitiatorRejoinRetryCount

Detailed Description

See zll-api.h for source code.

Macro Definition Documentation

◆ abortingTouchLink

#define abortingTouchLink ( ) (emAfZllFlags & ABORTING_TOUCH_LINK)

◆ debugExec

#define debugExec ( x )

◆ debugPrint

#define debugPrint ( ... )

◆ debugPrintln

#define debugPrintln ( ... )

◆ emberAfPluginZllCommissioningInitialSecurityStateCallback

#define emberAfPluginZllCommissioningInitialSecurityStateCallback emberAfPluginZllCommissioningCommonInitialSecurityStateCallback

◆ emberAfPluginZllCommissioningResetToFactoryNewCallback

#define emberAfPluginZllCommissioningResetToFactoryNewCallback emberAfPluginZllCommissioningCommonResetToFactoryNewCallback

◆ emberAfPluginZllCommissioningTouchLinkCompleteCallback

#define emberAfPluginZllCommissioningTouchLinkCompleteCallback emberAfPluginZllCommissioningCommonTouchLinkCompleteCallback

◆ formingNetwork

#define formingNetwork ( ) (emAfZllFlags & FORMING_NETWORK)

◆ resettingToFactoryNew

#define resettingToFactoryNew ( ) (emAfZllFlags & RESETTING_TO_FACTORY_NEW)

◆ scanComplete

#define scanComplete ( ) (emAfZllFlags & SCAN_COMPLETE)

◆ scanForDeviceInformation

#define scanForDeviceInformation ( ) (emAfZllFlags & SCAN_FOR_DEVICE_INFORMATION)

◆ scanForIdentify

#define scanForIdentify ( ) (emAfZllFlags & SCAN_FOR_IDENTIFY)

◆ scanForReset

#define scanForReset ( ) (emAfZllFlags & SCAN_FOR_RESET)

◆ scanForTouchLink

#define scanForTouchLink ( ) (emAfZllFlags & SCAN_FOR_TOUCH_LINK)

◆ targetNetworkFound

#define targetNetworkFound ( ) (emAfZllFlags & TARGET_NETWORK_FOUND)

◆ touchLinkInProgress

#define touchLinkInProgress ( )

Value:

(emAfZllFlags                     \
                                    & (SCAN_FOR_TOUCH_LINK           \
                                       | SCAN_FOR_DEVICE_INFORMATION \
                                       | SCAN_FOR_IDENTIFY           \
                                       | SCAN_FOR_RESET              \
                                       | TOUCH_LINK_TARGET))

◆ touchLinkTarget

#define touchLinkTarget ( ) (emAfZllFlags & TOUCH_LINK_TARGET)

◆ ZLL_FRAME_CONTROL_CLIENT_TO_SERVER

#define ZLL_FRAME_CONTROL_CLIENT_TO_SERVER 0x11

◆ ZLL_FRAME_CONTROL_LEGACY

#define ZLL_FRAME_CONTROL_LEGACY 0x00

◆ ZLL_FRAME_CONTROL_SERVER_TO_CLIENT

#define ZLL_FRAME_CONTROL_SERVER_TO_CLIENT 0x19

◆ ZLL_HEADER_COMMAND_ID_OFFSET

#define ZLL_HEADER_COMMAND_ID_OFFSET 2

◆ ZLL_HEADER_FRAME_CONTROL_OFFSET

#define ZLL_HEADER_FRAME_CONTROL_OFFSET 0

◆ ZLL_HEADER_OVERHEAD

#define ZLL_HEADER_OVERHEAD 7

◆ ZLL_HEADER_SEQUENCE_NUMBER_OFFSET

#define ZLL_HEADER_SEQUENCE_NUMBER_OFFSET 1

◆ ZLL_HEADER_TRANSACTION_ID_OFFSET

#define ZLL_HEADER_TRANSACTION_ID_OFFSET 3

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
INITIAL
SCAN_FOR_TOUCH_LINK
SCAN_FOR_DEVICE_INFORMATION
SCAN_FOR_IDENTIFY
SCAN_FOR_RESET
TARGET_NETWORK_FOUND
ABORTING_TOUCH_LINK
SCAN_COMPLETE
TOUCH_LINK_TARGET
FORMING_NETWORK
RESETTING_TO_FACTORY_NEW

◆ anonymous enum

anonymous enum

Enumerator
EMBER_RADIO_POWER_MODE_RX_ON
EMBER_RADIO_POWER_MODE_OFF

Function Documentation

◆ emberAfZllAbortTouchLink()

void emberAfZllAbortTouchLink ( void )

Aborts the touch link procedure.

This function can be called to cancel the touch link procedure. This can be useful, for example, if the touch link target is incorrect.

◆ emberAfZllDeviceInformationRequest()

EmberStatus emberAfZllDeviceInformationRequest ( void )

Initiates a touch link to retrieve information about a target device.

As with a traditional touch link, this function causes the stack to broadcast messages to discover a target device. When the target is selected (based on RSSI), the plugin will retrieve information about it by unicasting a series of DeviceInformationRequest commands via inter-PAN messaging. If the process completes successfully, the plugin will call emberAfPluginZllCommissioningTouchLinkCompleteCallback with information about the target. If touch linking fails, the plugin will call emberAfPluginZllCommissioningTouchLinkFailedCallback.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllDisable()

EmberStatus emberAfZllDisable ( void )

Disables touchlink processing.

This function will cause the device to refuse network start/join requests if it receives them and will not allow touchlinking. Note that this will have the effect of overriding the emberAfZllNoTouchlinkForNFN function.

◆ emberAfZllEnable()

EmberStatus emberAfZllEnable ( void )

Enables touchlink processing.

This function will cause the device to accept network start/join requests if it receives them and will not allow touchlinking. Note that this will have the effect of overriding the emberAfZllNoTouchlinkForNFN function.

◆ emberAfZllIdentifyRequest()

EmberStatus emberAfZllIdentifyRequest ( void )

Initiates a touch link to cause a target device to identify itself.

As with a traditional touch link, this function causes the stack to broadcast messages to discover a target device. When the target is selected (based on RSSI), the plugin will cause it to identify itself by unicasting an IdentifyRequest command via inter-PAN messaging. If the process completes successfully, the plugin will call emberAfPluginZllCommissioningTouchLinkCompleteCallback with information about the target. If touch linking fails, the plugin will call emberAfPluginZllCommissioningTouchLinkFailedCallback.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllInitiateTouchLink()

EmberStatus emberAfZllInitiateTouchLink ( void )

Initiates the touch link procedure.

This function causes the stack to broadcast a series of ScanRequest commands via inter-PAN messaging. The plugin selects the target that sent a ScanResponse command with the strongest RSSI and attempts to link with it. If touch linking completes successfully, the plugin will call emberAfPluginZllCommissioningTouchLinkCompleteCallback with information about the network and the target. If touch linking fails, the plugin will call emberAfPluginZllCommissioningTouchLinkFailedCallback.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllNoResetForNFN()

EmberStatus emberAfZllNoResetForNFN ( void )

No reset for non-factory new device.

This function will cause an NFN device on a centralized security network to a touchlink reset-to-factory-new request from a remote device.

◆ emberAfZllNoTouchlinkForNFN()

EmberStatus emberAfZllNoTouchlinkForNFN ( void )

No touchlink for non-factory new device.

This function will cause an NFN device to refuse network start/join/update requests and thus to forbid commissioning by touchlinking. This can be useful to restrict touchlink stealing.

◆ emberAfZllResetToFactoryNew()

void emberAfZllResetToFactoryNew ( void )

Resets the local device to a factory new state.

This function causes the device to leave the network and clear its network parameters, resets its attributes to their default values, and clears the group and scene tables.

◆ emberAfZllResetToFactoryNewRequest()

EmberStatus emberAfZllResetToFactoryNewRequest ( void )

Initiates a touch link for the purpose of resetting a target device.

As with a traditional touch link, this function causes the stack to broadcast messages to discover a target device. When the target is selected (based on RSSI), the plugin will reset it by unicasting a ResetToFactoryNewRequest command via inter-PAN messaging. If the process completes successfully, the plugin will call emberAfPluginZllCommissioningTouchLinkCompleteCallback with information about the target. If touch linking fails, the plugin will call emberAfPluginZllCommissioningTouchLinkFailedCallback.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllScanForJoinableNetwork()

EmberStatus emberAfZllScanForJoinableNetwork ( void )

Scans for joinable networks.

This function will scan the primary channel set for joinable networks. If a joinable network is found, the plugin will attempt to join to it. If no joinable networks are found or if joining is not successful, the plugin will scan the secondary channel set for joinable networks. If a joinable network is found, the plugin will attempt to join to it. The plugin will only scan the secondary channel set if ::EMBER_AF_PLUGIN_ZLL_COMMISSIONING_COMMON_SCAN_SECONDARY_CHANNELS is defined. Otherwise, scanning stops after the initial scan of the primary channel set.

Routers and end devices should scan for joinable networks when directed by the application. Scanning for joinable networks enables classic Zigbee commissioning with non-ZLL devices.

Note, for Zigbee 3.0 compatability, an application should use ::emberAfPluginNetworkSteeringStart rather than this routine, which may be deprecated in a future release.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllScanForUnusedPanId()

EmberStatus emberAfZllScanForUnusedPanId ( void )

Scans for an unused PAN ID.

This function scans the primary channel set for a channel with low average energy and then selects a PAN ID that is not in use on that channel. The plugin will then form a ZLL network on that channel with the chosen PAN ID.

Factory new routers may form a new ZLL network at startup, but this is not mandatory, since a network will be created during touch linking if required. Similarly, a router may chose to form a new ZLL network if classical ZigBee commissioning has failed, but this is not mandatory either. However, if a router choses not to form a network, then the application should call ::emberAfPluginZllCommissioningInitCallback to ensure the radio is switched on and is tuned to the default channel. Alternatively, the 'Rx always on' plugin option, ::EMBER_AF_PLUGIN_ZLL_COMMISSIONING_RX_ALWAYS_ON, may be set to true.

End devices should not use this API and should instead form ZLL networks via touch linking (or to be precise, join a ZLL network formed by a router target or a router initiator).

Note, for Zigbee 3.0 compatability, a router device should use ::emberAfPluginNetworkCreatorStart with centralizedNetwork=false to form a distributed network rather than this routine, which may be deprecated in a future release.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllSetInitialSecurityState()

EmberStatus emberAfZllSetInitialSecurityState ( void )

Generates a random network key and initializes the security state of the device.

This function is a convenience wrapper for emberZllSetInitialSecurityState, which must be called before starting or joining a network. The plugin initializes the security state for the initiator during touch linking. The target must initialize its own security state prior to forming a network either by using this function or by calling emberZllSetInitialSecurityState directly.

Returns: An EmberStatus value that indicates the success or failure of the command.

◆ emberAfZllTouchLinkInProgress()

bool emberAfZllTouchLinkInProgress ( void )

Indicates whether a touch link procedure is currently in progress.

Returns: True if a touch link is in progress or false otherwise.

◆ emberGetZllPrimaryChannelMask()

uint32_t emberGetZllPrimaryChannelMask ( void )

This call will get the primary touchlink channel mask.

Returns: The touchlink primary channel mask.

◆ emberGetZllSecondaryChannelMask()

uint32_t emberGetZllSecondaryChannelMask ( void )

This call will get the secondary touchlink channel mask.

Returns: The touchlink secondary channel mask.

◆ emberIsZllNetwork()

bool emberIsZllNetwork ( void )

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

◆ emberSetZllAdditionalState()

void emberSetZllAdditionalState ( uint16_t mask )

Sets additional capability bits in the touchlink state.

Parameters

`A`	mask with the bits to be set or cleared.

◆ emberSetZllNodeType()

void emberSetZllNodeType ( EmberNodeType nodeType )

Sets the default node type for a factory new device.

Parameters

The node type to be set.

◆ emberSetZllPrimaryChannelMask()

void emberSetZllPrimaryChannelMask ( uint32_t mask )

This call will set the primary touchlink channel mask.

Parameters

The touchlink primary channel mask.

◆ emberSetZllSecondaryChannelMask()

void emberSetZllSecondaryChannelMask ( uint32_t mask )

This call will set the secondary touchlink channel mask.

Parameters

The touchlink secondary channel mask.

◆ emberZllAddressAssignmentHandler()

void emberZllAddressAssignmentHandler ( const EmberZllAddressAssignment * addressInfo )

This call is fired when network and group addresses are assigned to a remote mode in a network start or network join request.

Parameters

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

◆ emberZllCancelRxOnWhenIdle()

void emberZllCancelRxOnWhenIdle ( void )

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

◆ emberZllClearTokens()

void emberZllClearTokens ( void )

This call will clear the ZLL stack tokens.

◆ emberZllFormNetwork()

EmberStatus emberZllFormNetwork	(	EmberZllNetwork *	`networkInfo,`
		int8_t	`radioTxPower`
	)

This will set the device type as a router or end device (depending on the passed nodeType) and setup 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, then a random extended PAN ID will be generated. If channel is 0xFF, then channel 11 will be used. If all F values are passed for PAN ID or Extended PAN ID, then the randomly generated values will be returned in the passed structure.

Parameters

`networkInfo`	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.
`radioTxPower`	The radio output power at which a node is to operate.

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

◆ emberZllGetPolicy()

EmberZllPolicy emberZllGetPolicy ( void )

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

◆ emberZllGetRadioIdleMode()

uint8_t emberZllGetRadioIdleMode ( void )

Get the default radio power mode.

Returns: The current default radio power mode

◆ emberZllGetTokensStackZll()

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

Reads both the touchlink stack data and security tokens.

◆ emberZllGetTokenStackZllData()

void emberZllGetTokenStackZllData ( EmberTokTypeStackZllData * token )

Reads the touchlink stack data token.

◆ emberZllGetTokenStackZllSecurity()

void emberZllGetTokenStackZllSecurity ( EmberTokTypeStackZllSecurity * token )

Reads the touchlink stack security token.

◆ emberZllJoinTarget()

EmberStatus emberZllJoinTarget ( const EmberZllNetwork * targetNetworkInfo )

Causes 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, then 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, then 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

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

◆ emberZllNetworkFoundHandler()

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

This call is fired 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

`networkInfo`	A pointer to an EmberZllNetwork struct containing the Zigbee and touchlink specific information about the discovered network.
`deviceInfo`	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.

◆ emberZllOperationInProgress()

bool emberZllOperationInProgress ( void )

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

◆ emberZllRxOnWhenIdleGetActive()

bool emberZllRxOnWhenIdleGetActive ( void )

This function is called to 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, when the device is not on a network.

◆ emberZllScanCompleteHandler()

void emberZllScanCompleteHandler ( EmberStatus status )

This call is fired when a touchlink network scan is complete.

Parameters

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

◆ emberZllScanningComplete()

void emberZllScanningComplete ( void )

This call will inform the API that all scanning is complete.

◆ emberZllSetInitialSecurityState()

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

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

Parameters

`networkKey`	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.
`securityState`	The security configuration to be set.

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

◆ emberZllSetNonZllNetwork()

void emberZllSetNonZllNetwork ( void )

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

◆ emberZllSetPolicy()

EmberStatus emberZllSetPolicy ( EmberZllPolicy policy )

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

◆ emberZllSetRadioIdleMode()

void emberZllSetRadioIdleMode ( EmberRadioPowerMode mode )

Sets 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

mode The power mode to set.

◆ emberZllSetRxOnWhenIdle()

EmberStatus emberZllSetRxOnWhenIdle ( uint32_t durationMs )

Changes 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 please 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.

Parameters

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

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.

◆ emberZllSetSecurityStateWithoutKey()

EmberStatus emberZllSetSecurityStateWithoutKey ( const EmberZllInitialSecurityState * securityState )

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

Parameters

securityState The security configuration to be set.

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

◆ emberZllSetTokenStackZllData()

void emberZllSetTokenStackZllData ( EmberTokTypeStackZllData * token )

Sets the touchlink stack data token.

◆ emberZllStartScan()

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

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

Parameters

`channelMask`	Indicates the range of channels to scan.
`radioPowerForScan`	The radio output power used for the scan requests.
`nodeType`	The node type of the local device.

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

◆ emberZllTouchLinkTargetHandler()

void emberZllTouchLinkTargetHandler ( const EmberZllNetwork * networkInfo )

This call is fired when the device is a target of a touch link.

Parameters

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

Variable Documentation

◆ emAfInitiatorRejoinRetryCount

uint8_t emAfInitiatorRejoinRetryCount

◆ emAfZllFlags

uint16_t emAfZllFlags

◆ emAfZllNetwork

EmberZllNetwork emAfZllNetwork

Ember ZigBee Light Link (ZLL) APIs and HandlersEmberZNet Stack API Reference

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ abortingTouchLink

◆ debugExec

◆ debugPrint

◆ debugPrintln

◆ emberAfPluginZllCommissioningInitialSecurityStateCallback

◆ emberAfPluginZllCommissioningResetToFactoryNewCallback

◆ emberAfPluginZllCommissioningTouchLinkCompleteCallback

◆ formingNetwork

◆ resettingToFactoryNew

◆ scanComplete

◆ scanForDeviceInformation

◆ scanForIdentify

◆ scanForReset

◆ scanForTouchLink

◆ targetNetworkFound

◆ touchLinkInProgress

◆ touchLinkTarget

◆ ZLL_FRAME_CONTROL_CLIENT_TO_SERVER

◆ ZLL_FRAME_CONTROL_LEGACY

◆ ZLL_FRAME_CONTROL_SERVER_TO_CLIENT

◆ ZLL_HEADER_COMMAND_ID_OFFSET

◆ ZLL_HEADER_FRAME_CONTROL_OFFSET

◆ ZLL_HEADER_OVERHEAD

◆ ZLL_HEADER_SEQUENCE_NUMBER_OFFSET

◆ ZLL_HEADER_TRANSACTION_ID_OFFSET

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ emberAfZllAbortTouchLink()

◆ emberAfZllDeviceInformationRequest()

◆ emberAfZllDisable()

◆ emberAfZllEnable()

◆ emberAfZllIdentifyRequest()

◆ emberAfZllInitiateTouchLink()

◆ emberAfZllNoResetForNFN()

◆ emberAfZllNoTouchlinkForNFN()

◆ emberAfZllResetToFactoryNew()

◆ emberAfZllResetToFactoryNewRequest()

◆ emberAfZllScanForJoinableNetwork()

◆ emberAfZllScanForUnusedPanId()

◆ emberAfZllSetInitialSecurityState()

◆ emberAfZllTouchLinkInProgress()

◆ emberGetZllPrimaryChannelMask()

◆ emberGetZllSecondaryChannelMask()

◆ emberIsZllNetwork()

◆ emberSetZllAdditionalState()

◆ emberSetZllNodeType()

◆ emberSetZllPrimaryChannelMask()

◆ emberSetZllSecondaryChannelMask()

◆ emberZllAddressAssignmentHandler()

◆ emberZllCancelRxOnWhenIdle()

◆ emberZllClearTokens()

◆ emberZllFormNetwork()

◆ emberZllGetPolicy()

◆ emberZllGetRadioIdleMode()

◆ emberZllGetTokensStackZll()

◆ emberZllGetTokenStackZllData()

◆ emberZllGetTokenStackZllSecurity()

◆ emberZllJoinTarget()

◆ emberZllNetworkFoundHandler()

◆ emberZllOperationInProgress()

◆ emberZllRxOnWhenIdleGetActive()

◆ emberZllScanCompleteHandler()

◆ emberZllScanningComplete()

◆ emberZllSetInitialSecurityState()

◆ emberZllSetNonZllNetwork()

◆ emberZllSetPolicy()

◆ emberZllSetRadioIdleMode()

◆ emberZllSetRxOnWhenIdle()

◆ emberZllSetSecurityStateWithoutKey()

◆ emberZllSetTokenStackZllData()

◆ emberZllStartScan()

Ember ZigBee Light Link (ZLL) APIs and Handlers
EmberZNet Stack API Reference