Messaging#

emberMessageSentHandler#

void emberMessageSentHandler (EmberStatus status, EmberOutgoingMessage *message)

This handler is invoked when the stack has completed sending a message.

Warnings

• Implement associated callback emberAfMessageSentCallback() to use. See Handlers for additional information.

emberMacMessageSentHandler#

void emberMacMessageSentHandler (EmberStatus status, EmberOutgoingMacMessage *message)

This handler is invoked when a node of EMBER_MAC_MODE_DEVICE type or EMBER_MAC_MODE_SLEEPY_DEVICE type has completed sending a MAC frame.

Warnings

• Implement associated callback emberAfMacMessageSentCallback() to use. See Handlers for additional information.

emberIncomingMessageHandler#

void emberIncomingMessageHandler (EmberIncomingMessage *message)

This handler is invoked when a packet has been received from a node type other than EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE.

Warnings

• Implement associated callback emberAfIncomingMessageCallback() to use. See Handlers for additional information.

emberIncomingMacMessageHandler#

void emberIncomingMacMessageHandler (EmberIncomingMacMessage *message)

This handler is invoked when a node of EMBER_MAC_MODE_DEVICE type or EMBER_MAC_MODE_SLEEPY_DEVICE has received a MAC frame.

Warnings

• Implement associated callback emberAfIncomingMacMessageCallback() to use. See Handlers for additional information.

emberMessageSend#

EmberStatus emberMessageSend (EmberNodeId destination, uint8_t endpoint, uint8_t messageTag, EmberMessageLength messageLength, uint8_t *message, EmberMessageOptions options)

Send a message to the passed destination short ID.

Returns

• an EmberStatus value of:

  • EMBER_SUCCESS if the message was accepted by the stack. If a success status is returned, the emberMessageSentHandler() callback is invoked by the stack to indicate whether the message was successfully delivered or the reason for failure.

  • EMBER_INVALID_CALL if the node is not joined to a network or the node is of EMBER_MAC_MODE_DEVICE device type or EMBER_MAC_MODE_SLEEPY_DEVICE (use emberMacMessageSend instead).

  • EMBER_BAD_ARGUMENT if the packet length is 0, the passed TX options indicates some feature that is not supported, the passed endpoint exceeds EMBER_MAX_ENDPOINT

  • EMBER_MESSAGE_TOO_LONG if the message does not fit in a single frame.

  • EMBER_PHY_TX_BUSY if the message cannot be sent since the node does not support MAC queuing and the radio is currently busy.

  • EMBER_MAC_TRANSMIT_QUEUE_FULL if the outgoing MAC queue is currently full.

  • EMBER_NO_BUFFERS if the stack could not allocate enough RAM to store the submitted message.

  • EMBER_MAC_UNKNOWN_DESTINATION if the node is part of a star network and the destination node does not appear in the node's routing table.

  • EMBER_MAC_SECURITY_NOT_SUPPORTED if the message was requested to be sent out secured and either the local node does not support security or the destination node is known to not support security.

  • EMBER_MAC_BUSY if the message was not accepted because the MAC is currently performing some critical operation.

emberMacMessageSend#

EmberStatus emberMacMessageSend (EmberMacFrame *macFrame, uint8_t messageTag, EmberMessageLength messageLength, uint8_t *message, EmberMessageOptions options)

Create a MAC level frame and sends it to the passed destination. This API can only be used for nodes of EMBER_MAC_MODE_DEVICE node type or EMBER_MAC_MODE_SLEEPY_DEVICE node type.

Returns

• an EmberStatus value of:

  • EMBER_SUCCESS if the message was accepted by the stack. If a success status is returned, the emberMacMessageSentHandler() callback will be invoked by the stack to indicate whether the message was successfully delivered or the reason for failure.

  • EMBER_INVALID_CALL if the node is of a node type other than EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE.

  • EMBER_BAD_ARGUMENT if the packet length is 0, the passed TX options indicates some feature that is not supported or the destination address mode is set to EMBER_MAC_ADDRESS_MODE_NONE.

  • EMBER_MESSAGE_TOO_LONG if the message does not fit in a single frame.

  • EMBER_PHY_TX_BUSY if the message cannot be sent since the node does not support MAC queuing and the radio is currently busy.

  • EMBER_MAC_TRANSMIT_QUEUE_FULL if the outgoing MAC queue is currently full.

  • EMBER_NO_BUFFERS if the stack could not allocate enough RAM to store the submitted message.

  • EMBER_MAC_SECURITY_NOT_SUPPORTED if the message was requested to be sent out with a security but no security plugin was enabled.

  • EMBER_MAC_BUSY if the message was not accepted because the MAC is currently performing a critical operation.

emberPollForData#

EmberStatus emberPollForData (void)

Send a data request command to the parent node. Note that if the node short ID is a value of EMBER_USE_LONG_ADDRESS, the node shall use its long ID as source address.

Returns

• and EmberStatus value of:

  • EMBER_SUCCESS if the data poll was accepted by the MAC layer.

  • EMBER_INVALID_CALL if the node is not joined to a network, the node is not an end device, an EMBER_MAC_MODE_DEVICE or an EMBER_MAC_MODE_SLEEPY_DEVICE, or the node is of EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE node type, is not joined to a coordinator and the poll destination was not correctly set via the emberSetPollDestinationAddress() API.

  • EMBER_MAC_BUSY if the MAC is currently performing a critical operation.

emberSetPollDestinationAddress#

EmberStatus emberSetPollDestinationAddress (EmberMacAddress *destination)

Set data polls destination address for nodes of EMBER_MAC_MODE_DEVICE node type or EMBER_MAC_MODE_SLEEPY_DEVICE node type.

Returns

• and EmberStatus value of EMBER_SUCCESS if the data poll destination was correctly set, or another EmberStatus value indicating the reason of failure.

emberGetMaximumPayloadLength#

uint16_t emberGetMaximumPayloadLength (EmberMacAddressMode srcAddressMode, EmberMacAddressMode dstAddressMode, bool interpan, bool secured)

Return the maximum payload according to the passed source and destination addressing modes, the passed secured flag, and the current configuration of the node.

Returns

• The maximum payload length in bytes achievable according to the passed parameters or 0xFF if the node is currently active on a network or any of the passed parameters are invalid.

emberUsingLongMessages#

bool emberUsingLongMessages (void)

Indicates if the stack is currently using long messages or not.

Returns

• True if the stack currently uses long messages (length stored in a uint16_t) or false if it is not the case (length stored in a uint8_t).

emberNcpSetLongMessagesUse#

EmberStatus emberNcpSetLongMessagesUse (bool useLongMessages)

Set the current message length that the stack uses.

Note

• This API is here to assure retro compatibility with old NCP Host lib versions. In NCP Host lib versions that do not support OFDM features (v1.1 and older), only short messaging is supported. For the NCP, short messages are used by default. The Host lib needs to call this API with useLongMessages set to true if it supports OFDM.

Warnings

• This API changes the behavior of the Connect Serialization Protocol. It only has effect when using a RTOS or the NCP. Changing it may result in packets being incorrectly transfered through CSP when using a SUN-OFDM or SUN-FSK PHY.

emberPurgeIndirectMessages#

EmberStatus emberPurgeIndirectMessages (void)

Purge all indirect transmissions from the indirect message queue.

Returns

• an EmberStatus value of EMBER_SUCCESS if all indirect messages were purged, or another EmberStatus value indicating the reason of failure.

emberSetIndirectQueueTimeout#

EmberStatus emberSetIndirectQueueTimeout (uint32_t timeoutMs)

Set indirect queue timeout value. The indirect queue timeout is set by default to EMBER_INDIRECT_TRANSMISSION_TIMEOUT_MS.

Returns

• an EmberStatus value of EMBER_SUCCESS if the passed timeout was successfully set, or a value of EMBER_BAD_ARGUMENT if the passed value is invalid.

EMBER_MAX_UNSECURED_APPLICATION_PAYLOAD_LENGTH#

#define EMBER_MAX_UNSECURED_APPLICATION_PAYLOAD_LENGTH

111

DeprecatedThe maximum length in bytes of the application payload for an unsecured message. This define has been deprecated, you should use the emberGetMaximumPayloadLength API instead.

EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH#

#define EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH

102

DeprecatedThe maximum length in bytes of the application payload for a secured message. This define has been deprecated, you should use the emberGetMaximumPayloadLength API instead.

EMBER_MAX_ENDPOINT#

#define EMBER_MAX_ENDPOINT

0xF

The maximum allowed endpoint value.