Messaging#

emberAfSendResponse#

EmberStatus emberAfSendResponse (void)

Send a ZCL response, based on the information that is currently in the outgoing buffer. It is expected that a complete ZCL message is present, including header. The application may use this method directly from within the message handling function and associated callbacks. However, this will result in the response being sent before the APS ACK is sent which is not ideal.

NOTE: This will overwrite the ZCL sequence number of the message to use the LAST received sequence number.

emberAfSendResponseWithCallback#

EmberStatus emberAfSendResponseWithCallback (EmberAfMessageSentFunction callback)

Send ZCL response with attached message sent callback.

emberAfSendMulticast#

EmberStatus emberAfSendMulticast (EmberMulticastId multicastId, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message)

Sends multicast.

emberAfSendMulticastToBindings#

EmberStatus emberAfSendMulticastToBindings (EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message)

Multicasts the message to the group in the binding table that matches the cluster and source endpoint in the APS frame. Note: if the binding table contains many matching entries, calling this API cause a significant amount of network traffic. Care should be taken when considering the effects of broadcasts in a network.

emberAfSendMulticastWithAliasWithCallback#

EmberStatus emberAfSendMulticastWithAliasWithCallback (EmberMulticastId multicastId, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message, EmberNodeId alias, uint8_t sequence, EmberAfMessageSentFunction callback)

Send Multicast with alias with attached message sent callback.

emberAfSendMulticastWithCallback#

EmberStatus emberAfSendMulticastWithCallback (EmberMulticastId multicastId, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message, EmberAfMessageSentFunction callback)

Send multicast with attached message sent callback.

emberAfSendBroadcast#

EmberStatus emberAfSendBroadcast (EmberNodeId destination, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message)

Send broadcast.

emberAfSendBroadcastWithCallback#

EmberStatus emberAfSendBroadcastWithCallback (EmberNodeId destination, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message, EmberAfMessageSentFunction callback)

Send broadcast with attached message sent callback.

emberAfSendBroadcastWithAliasWithCallback#

EmberStatus emberAfSendBroadcastWithAliasWithCallback (EmberNodeId destination, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message, EmberNodeId alias, uint8_t sequence, EmberAfMessageSentFunction callback)

Send broadcast with alias with attached message sent callback.

emberAfSendUnicast#

EmberStatus emberAfSendUnicast (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message)

Send unicast.

emberAfSendUnicastWithCallback#

EmberStatus emberAfSendUnicastWithCallback (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message, EmberAfMessageSentFunction callback)

Send unicast with attached message sent callback.

emberAfSendUnicastToBindings#

EmberStatus emberAfSendUnicastToBindings (EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message)

Unicast the message to each remote node in the binding table that matches the cluster and source endpoint in the APS frame. Note: if the binding table contains many matching entries, calling this API cause a significant amount of network traffic.

emberAfSendUnicastToBindingsWithCallback#

EmberStatus emberAfSendUnicastToBindingsWithCallback (EmberApsFrame *apsFrame, uint16_t messageLength, uint8_t *message, EmberAfMessageSentFunction callback)

emberAfSendUnicastToBindings with attached message sent callback.

emberAfSendInterPan#

EmberStatus emberAfSendInterPan (EmberPanId panId, const EmberEUI64 destinationLongId, EmberNodeId destinationShortId, EmberMulticastId multicastId, EmberAfClusterId clusterId, EmberAfProfileId profileId, uint16_t messageLength, uint8_t *messageBytes)

Send interpan message.

emberAfSendEndDeviceBind#

EmberStatus emberAfSendEndDeviceBind (uint8_t endpoint)

Send end device binding request.

emberAfSendCommandUnicastToBindings#

EmberStatus emberAfSendCommandUnicastToBindings (void)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API. It will be sent as unicast to each remote node in the binding table that matches the cluster and source endpoint in the APS frame. Note: if the binding table contains many matching entries, calling this API cause a significant amount of network traffic.

emberAfSendCommandUnicastToBindingsWithCallback#

EmberStatus emberAfSendCommandUnicastToBindingsWithCallback (EmberAfMessageSentFunction callback)

emberAfSendCommandUnicastToBindings with attached message sent callback.

emberAfSendCommandMulticast#

EmberStatus emberAfSendCommandMulticast (EmberMulticastId multicastId)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API. It will be sent as multicast.

emberAfSendCommandMulticastWithAlias#

EmberStatus emberAfSendCommandMulticastWithAlias (EmberMulticastId multicastId, EmberNodeId alias, uint8_t sequence)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API. It will be sent as multicast.

emberAfSendCommandMulticastWithCallback#

EmberStatus emberAfSendCommandMulticastWithCallback (EmberMulticastId multicastId, EmberAfMessageSentFunction callback)

emberAfSendCommandMulticast with attached message sent callback.

emberAfSendCommandMulticastToBindings#

EmberStatus emberAfSendCommandMulticastToBindings (void)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API. It will be sent as multicast to the group specified in the binding table that matches the cluster and source endpoint in the APS frame. Note: if the binding table contains many matching entries, calling this API cause a significant amount of network traffic.

emberAfSendCommandUnicast#

EmberStatus emberAfSendCommandUnicast (EmberOutgoingMessageType type, uint16_t indexOrDestination)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API. It will be sent as unicast.

emberAfSendCommandUnicastWithCallback#

EmberStatus emberAfSendCommandUnicastWithCallback (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberAfMessageSentFunction callback)

emberAfSendCommandUnicast with attached message sent callback.

emberAfSendCommandBroadcast#

EmberStatus emberAfSendCommandBroadcast (EmberNodeId destination)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API.

emberAfSendCommandBroadcastWithCallback#

EmberStatus emberAfSendCommandBroadcastWithCallback (EmberNodeId destination, EmberAfMessageSentFunction callback)

emberAfSendCommandBroadcast with attached message sent callback.

emberAfSendCommandBroadcastWithAliasWithCallback#

EmberStatus emberAfSendCommandBroadcastWithAliasWithCallback (EmberNodeId destination, EmberNodeId alias, uint8_t sequence, EmberAfMessageSentFunction callback)

emberAfSendCommandBroadcast from alias with attached message sent callback.

emberAfSendCommandBroadcastWithAlias#

EmberStatus emberAfSendCommandBroadcastWithAlias (EmberNodeId destination, EmberNodeId alias, uint8_t sequence)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API.

emberAfSendCommandInterPan#

EmberStatus emberAfSendCommandInterPan (EmberPanId panId, const EmberEUI64 destinationLongId, EmberNodeId destinationShortId, EmberMulticastId multicastId, EmberAfProfileId profileId)

Send the command prepared with emberAfFill.... macro.

This function is used to send a command that was previously prepared using the emberAfFill... macros from the client command API. It will be sent via inter-PAN. If destinationLongId is not NULL, the message will be sent to that long address using long addressing mode; otherwise, the message will be sent to destinationShortId using short address mode. IF multicastId is not zero, the message will be sent using multicast mode.

emberAfSendDefaultResponse#

EmberStatus emberAfSendDefaultResponse (const EmberAfClusterCommand *cmd, EmberAfStatus status)

Send a default response to a cluster command.

This function is used to prepare and send a default response to a cluster command.

Returns

• An ::EmberStatus value that indicates the success or failure of sending the response.

emberAfSendDefaultResponseWithCallback#

EmberStatus emberAfSendDefaultResponseWithCallback (const EmberAfClusterCommand *cmd, EmberAfStatus status, EmberAfMessageSentFunction callback)

emberAfSendDefaultResponse with attached message sent callback.

emberAfSendImmediateDefaultResponse#

EmberStatus emberAfSendImmediateDefaultResponse (EmberAfStatus status)

Send a default response to a cluster command using the current command.

This function is used to prepare and send a default response to a cluster command.

Returns

• An ::EmberStatus value that indicates the success or failure of sending the response.

emberAfSendImmediateDefaultResponseWithCallback#

EmberStatus emberAfSendImmediateDefaultResponseWithCallback (EmberAfStatus status, EmberAfMessageSentFunction callback)

emberAfSendImmediateDefaultResponse with attached message sent callback.

emberAfMaximumApsPayloadLength#

uint8_t emberAfMaximumApsPayloadLength (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame *apsFrame)

Return the maximum size of the payload that the Application Support sub-layer will accept for the given message type, destination, and APS frame.

The size depends on multiple factors, including the security level in use and additional information added to the message to support the various options.

Returns

• The maximum APS payload length for the given message.

emberAfGetCommandApsFrame#

EmberApsFrame* emberAfGetCommandApsFrame (void)

Access to client API APS frame.

emberAfSetCommandEndpoints#

void emberAfSetCommandEndpoints (uint8_t sourceEndpoint, uint8_t destinationEndpoint)

Set the source and destination endpoints in the client API APS frame.

emberAfFindDevicesByProfileAndCluster#

EmberStatus emberAfFindDevicesByProfileAndCluster (EmberNodeId target, EmberAfProfileId profileId, EmberAfClusterId clusterId, bool serverCluster, EmberAfServiceDiscoveryCallback *callback)

Use this function to find devices in the network with endpoints matching a given profile ID and cluster ID in their descriptors. Target may either be a specific device, or the broadcast address EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS.

With this function a service discovery is initiated and received responses are returned by executing the callback function passed in. For unicast discoveries, the callback will be executed only once. Either the target will return a result or a timeout will occur. For broadcast discoveries, the callback may be called multiple times and after a period of time the discovery will be finished with a final call to the callback.

emberAfFindClustersByDeviceAndEndpoint#

EmberStatus emberAfFindClustersByDeviceAndEndpoint (EmberNodeId target, uint8_t targetEndpoint, EmberAfServiceDiscoveryCallback *callback)

Use this function to find all of the given in and out clusters implemented on a devices given endpoint. Target should only be the short address of a specific device.

With this function a single service discovery is initiated and the response is passed back to the passed callback.

emberAfFindIeeeAddress#

EmberStatus emberAfFindIeeeAddress (EmberNodeId shortAddress, EmberAfServiceDiscoveryCallback *callback)

Use this function to initiate a discovery for the IEEE address of the specified node id. This will send a unicast sent to the target node ID.

emberAfFindNodeId#

EmberStatus emberAfFindNodeId (EmberEUI64 longAddress, EmberAfServiceDiscoveryCallback *callback)

Use this function to initiate a discovery for the short ID of the specified long address. This will send a broadcast to all rx-on-when-idle devices (non-sleepies).

emberAfFindActiveEndpoints#

EmberStatus emberAfFindActiveEndpoints (EmberNodeId target, EmberAfServiceDiscoveryCallback *callback)

Initiate an Active Endpoint request ZDO message to the target node ID.

emberAfAddAddressTableEntry#

uint8_t emberAfAddAddressTableEntry (EmberEUI64 longId, EmberNodeId shortId)

Use this function to add an entry for a remote device to the address table.

If the EUI64 already exists in the address table, the index of the existing entry will be returned. Otherwise, a new entry will be created and the new new index will be returned. The framework will remember how many times the returned index has been referenced. When the address table entry is no longer needed, the application should remove its reference by calling emberAfRemoveAddressTableEntry.

Returns

• The index of the address table entry for this remove device or ::EMBER_NULL_ADDRESS_TABLE_INDEX if an error occurred (e.g., the address table is full).

emberAfSetAddressTableEntry#

EmberStatus emberAfSetAddressTableEntry (uint8_t index, EmberEUI64 longId, EmberNodeId shortId)

Use this function to add an entry for a remote device to the address table at a specific location.

The framework will remember how many times an address table index has been referenced through emberAfAddAddressTableEntry. If the reference count for the index passed to this function is not zero, the entry will be not changed. When the address table entry is no longer needed, the application should remove its reference by calling emberAfRemoveAddressTableEntry.

Returns

• ::EMBER_SUCCESS if the address table entry was successfully set, ::EMBER_ADDRESS_TABLE_ENTRY_IS_ACTIVE if any messages are being sent using the existing entry at that index or the entry is still referenced in the framework, or ::EMBER_ADDRESS_TABLE_INDEX_OUT_OF_RANGE if the index is out of range.

emberAfRemoveAddressTableEntry#

EmberStatus emberAfRemoveAddressTableEntry (uint8_t index)

Use this function to remove a specific entry from the address table.

The framework will remember how many times an address table index has been referenced through emberAfAddAddressTableEntry and emberAfSetAddressTableEntry. The address table entry at this index will not actually be removed until its reference count reaches zero.

Returns

• ::EMBER_SUCCESS if the address table entry was successfully removed or ::EMBER_ADDRESS_TABLE_INDEX_OUT_OF_RANGE if the index is out of range.

emberAfInitiateKeyEstablishment#

EmberStatus emberAfInitiateKeyEstablishment (EmberNodeId nodeId, uint8_t endpoint)

Use this function to initiate key establishment with a remote node. emberAfKeyEstablishmentCallback will be called as events occur and when key establishment completes.

Returns

• ::EMBER_SUCCESS if key establishment was initiated successfully

emberAfInitiateInterPanKeyEstablishment#

EmberStatus emberAfInitiateInterPanKeyEstablishment (EmberPanId panId, const EmberEUI64 eui64)

Use this function to initiate key establishment with a remote node on a different PAN. emberAfInterPanKeyEstablishmentCallback will be called as events occur and when key establishment completes.

Returns

• ::EMBER_SUCCESS if key establishment was initiated successfully

emberAfPerformingKeyEstablishment#

bool emberAfPerformingKeyEstablishment (void)

Use this function to tell if the device is in the process of performing key establishment.

Returns

• ::true if key establishment is in progress.

emberAfInitiatePartnerLinkKeyExchange#

EmberStatus emberAfInitiatePartnerLinkKeyExchange (EmberNodeId target, uint8_t endpoint, EmberAfPartnerLinkKeyExchangeCallback *callback)

Use this function to initiate partner link key exchange with a remote node.

Returns

• ::EMBER_SUCCESS if the partner link key exchange was initiated successfully.

emberAfIsCurrentSecurityProfileSmartEnergy#

bool emberAfIsCurrentSecurityProfileSmartEnergy (void)

Use this function to determine if the security profile of the current network was set to Smart Energy. The security profile is configured in AppBuilder. @ return true if the security profile is Smart Energy or false otherwise.

EMBER_AF_CLIENT_CLUSTER_DISCOVERY#

#define EMBER_AF_CLIENT_CLUSTER_DISCOVERY

false

Friendly define for use in discovering client clusters with emberAfFindDevicesByProfileAndCluster().

EMBER_AF_SERVER_CLUSTER_DISCOVERY#

#define EMBER_AF_SERVER_CLUSTER_DISCOVERY

true

Friendly define for use in discovering server clusters with emberAfFindDevicesByProfileAndCluster().

emberAfCurrentEndpoint#

#define emberAfCurrentEndpoint

()

Return the current endpoint that is being served.

The purpose of this macro is mostly to access endpoint that is being served in the command callbacks.

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_DISP#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_DISP

zcl msg disp [messageId:4] [messageControl:1] [startTime:4] [durationInMinutes:2] [message:-1] [optionalExtendedMessageControl:1]

• Command description for DisplayMessage

  • messageId - INT32U

  • messageControl - MessagingControlMask [BITMAP8]

  • startTime - UTC_TIME

  • durationInMinutes - INT16U

  • message - CHAR_STRING

  • optionalExtendedMessageControl - MessagingExtendedControlMask [BITMAP8]

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_CANCEL#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_CANCEL

zcl msg cancel [messageId:4] [messageControl:1]

• The CancelMessage command provides the ability to cancel the sending or acceptance of previously sent messages.

  • messageId - INT32U

  • messageControl - MessagingControlMask [BITMAP8]

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_DISP_PROTD#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_DISP_PROTD

zcl msg disp-protd [messageId:4] [messageControl:1] [startTime:4] [durationInMinutes:2] [message:-1] [optionalExtendedMessageControl:1]

• The DisplayProtected Message command is for use with messages that are protected by a password or PIN.

  • messageId - INT32U

  • messageControl - MessagingControlMask [BITMAP8]

  • startTime - UTC_TIME

  • durationInMinutes - INT16U

  • message - CHAR_STRING

  • optionalExtendedMessageControl - MessagingExtendedControlMask [BITMAP8]

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_X_ALL#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_X_ALL

zcl msg x-all [implementationDateTime:4]

• The CancelAllMessages command indicates to a client device that it should cancel all display messages currently held by it.

  • implementationDateTime - UTC_TIME

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_GET#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_GET

zcl msg get

• Command description for GetLastMessage

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_CONFIRM#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_CONFIRM

zcl msg confirm [messageId:4] [confirmationTime:4] [messageConfirmationControl:1] [messageResponse:-1]

• The Message Confirmation command provides an indication that a Utility Customer has acknowledged and/or accepted the contents of a previously sent message. Enhanced Message Confirmation commands shall contain an answer of 'NO', 'YES' and/or a message confirmation string.

  • messageId - INT32U

  • confirmationTime - UTC_TIME

  • messageConfirmationControl - BITMAP8

  • messageResponse - OCTET_STRING

EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_GET_MSG_X#

#define EMBER_AF_DOXYGEN_CLI_COMMAND_MESSAGING_GET_MSG_X

zcl msg get-msg-x [earliestImplementationTime:4]

• This command initiates the return of the first (and maybe only) Cancel All Messages command held on the associated server, and which has an implementation time equal to or later than the value indicated in the payload.

  • earliestImplementationTime - UTC_TIME