Ember ZigBee Light Link (ZLL) APIs and Handlers
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.)
|
|
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.
|
|
EmberStatus | emberSetLogicalAndRadioChannel (uint8_t channel) |
Sets the current logical and physical channel.
|
|
uint8_t | emberGetLogicalChannel (void) |
Gets the current logical channel.
|
|
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.
|
Detailed Description
See
zll-api.h
for source code.
Function Documentation
uint8_t emberGetLogicalChannel | ( | void |
|
) |
Gets the current logical channel.
uint32_t emberGetZllPrimaryChannelMask | ( | void |
|
) |
This call will get the primary touchlink channel mask.
- Returns
- The touchlink primary channel mask.
uint32_t emberGetZllSecondaryChannelMask | ( | void |
|
) |
This call will get the secondary touchlink channel mask.
- Returns
- The touchlink secondary channel mask.
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.
EmberStatus emberSetLogicalAndRadioChannel | ( | uint8_t |
channel
|
) |
Sets the current logical and physical channel.
void emberSetZllAdditionalState | ( | uint16_t |
mask
|
) |
Sets additional capability bits in the touchlink state.
- Parameters
-
A
mask with the bits to be set or cleared.
void emberSetZllNodeType | ( | EmberNodeType |
nodeType
|
) |
Sets the default node type for a factory new device.
- Parameters
-
The
node type to be set.
void emberSetZllPrimaryChannelMask | ( | uint32_t |
mask
|
) |
This call will set the primary touchlink channel mask.
- Parameters
-
The
touchlink primary channel mask.
void emberSetZllSecondaryChannelMask | ( | uint32_t |
mask
|
) |
This call will set the secondary touchlink channel mask.
- Parameters
-
The
touchlink secondary channel mask.
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.
void emberZllCancelRxOnWhenIdle | ( | void |
|
) |
Cancels the special touchlink radio idle mode immediately, without reverting the Stack's radio idle mode to its original setting.
void emberZllClearTokens | ( | void |
|
) |
This call will clear the ZLL stack tokens.
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.
EmberZllPolicy emberZllGetPolicy | ( | void |
|
) |
Gets the policy that enables or disables touchlink processing, and to enable or disable stealing a non-factory-new device.
void emberZllGetTokensStackZll | ( | EmberTokTypeStackZllData * |
data,
|
EmberTokTypeStackZllSecurity * |
security
|
||
) |
Reads both the touchlink stack data and security tokens.
void emberZllGetTokenStackZllData | ( | EmberTokTypeStackZllData * |
token
|
) |
Reads the touchlink stack data token.
void emberZllGetTokenStackZllSecurity | ( | EmberTokTypeStackZllSecurity * |
token
|
) |
Reads the touchlink stack security token.
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.
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.
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.
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 .
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.
void emberZllSetNonZllNetwork | ( | void |
|
) |
Alters the touchlink data token to reflect the fact that the network is non-touchlink-compliant.
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 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.
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.
- 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.
- 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.
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.
void emberZllSetTokenStackZllData | ( | EmberTokTypeStackZllData * |
token
|
) |
Sets the touchlink stack data token.
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.
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.