Ember Connect APIs sending and receiving messages. More...

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

#define	EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH

#define	EMBER_MAX_ENDPOINT

Handlers
void	emberMessageSentHandler ( `EmberStatus` status, EmberOutgoingMessage *message)
	A callback invoked when the stack has completed sending a message. More...

void	emberMacMessageSentHandler ( `EmberStatus` status, EmberOutgoingMacMessage *message)
	A callback invoked when a node of EMBER_MAC_MODE_DEVICE type or EMBER_MAC_MODE_SLEEPY_DEVICE type has completed sending a MAC frame. More...

void	emberIncomingMessageHandler ( EmberIncomingMessage *message)
	A callback invoked when a packet has been received. More...

void	emberIncomingMacMessageHandler ( EmberIncomingMacMessage *message)
	A callback invoked when a node of EMBER_MAC_MODE_DEVICE type or EMBER_MAC_MODE_SLEEPY_DEVICE has received a MAC frame. More...

APIs
`EmberStatus`	emberMessageSend ( EmberNodeId destination, uint8_t endpoint, uint8_t messageTag, EmberMessageLength messageLength, uint8_t *message, EmberMessageOptions options)
	Sends a message to the passed destination short ID. More...

`EmberStatus`	emberMacMessageSend ( EmberMacFrame macFrame, uint8_t messageTag, EmberMessageLength messageLength, uint8_t message, EmberMessageOptions options)
	Creates 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. More...

`EmberStatus`	emberPollForData (void)
	Sends 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. More...

`EmberStatus`	emberSetPollDestinationAddress ( EmberMacAddress *destination)
	Sets data polls destination address for nodes of EMBER_MAC_MODE_DEVICE node type or EMBER_MAC_MODE_SLEEPY_DEVICE node type. More...

`EmberStatus`	emberPurgeIndirectMessages (void)
	Purges all indirect transmissions from the indirect message queue. More...

uint8_t	emberGetMaximumPayloadLength ( EmberMacAddressMode srcAddressMode, EmberMacAddressMode dstAddressMode, bool interpan, bool secured)
	Returns the maximum payload according to the passed source and destination addressing modes, the passed secured flag, and the current configuration of the node. More...

Detailed Description

Ember Connect APIs sending and receiving messages.

See message.h for source code.

Macro Definition Documentation

#define EMBER_MAX_ENDPOINT

Deprecated:: The maximum allowed endpoint value.

Definition at line 34 of file message.h .

#define EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH

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

Definition at line 30 of file message.h .

#define EMBER_MAX_UNSECURED_APPLICATION_PAYLOAD_LENGTH

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

Definition at line 24 of file message.h .

Function Documentation

uint8_t emberGetMaximumPayloadLength	(	EmberMacAddressMode	`srcAddressMode,`
		EmberMacAddressMode	`dstAddressMode,`
		bool	`interpan,`
		bool	`secured`
	)

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

Parameters

`srcAddressMode`	An EmberMacAddressMode value indicating the mode of the source address. Note, this parameter is only meaningful if the node was started as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE .
`dstAddressMode`	An EmberMacAddressMode value indicating the mode of the destination address. Note, this parameter is only meaningful if the node was started as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE .
`intrapan`	Indicates whether the frame is an interpan frame or not. Note, this parameter is only meaningful if the node was started as EMBER_MAC_MODE_DEVICE or EMBER_MAC_MODE_SLEEPY_DEVICE .
`secured`	Indicates whether the frame should be secured or not.

Returns: an invalid value of 0xFF if the node is currently active on a network or any of the passed parameters are invalid. Otherise, it returns the maximum payload length achievable according to the passed parameters.

void emberIncomingMacMessageHandler ( EmberIncomingMacMessage * message )

A callback invoked when a node of EMBER_MAC_MODE_DEVICE type or EMBER_MAC_MODE_SLEEPY_DEVICE has received a MAC frame.

Parameters

message An ::EmberMacIncomingMessage describing the incoming packet.

void emberIncomingMessageHandler ( EmberIncomingMessage * message )

A callback invoked when a packet has been received.

Parameters

message An EmberIncomingMessage describing the incoming packet.

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

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

Parameters

`macFrame`	A pointer to an EmberMacFrame struct that specifies the source and destination addresses and the source and destination PAN IDs for the message to be sent. Note that if the source/destination PAN ID is not specified, it defaults to the node's PAN ID. Also, the destination address mode must be either EMBER_MAC_ADDRESS_MODE_SHORT or EMBER_MAC_ADDRESS_MODE_LONG . Also note that if the EMBER_OPTIONS_SECURITY_ENABLED in the passed options, the source address must be EMBER_MAC_ADDRESS_MODE_LONG .
`messageTag`	A value chosen by the application. This value will be passed in the corresponding emberMacMessageSentHandler() call.
`messageLength`	The size in bytes of the message payload. TODO: mention max length and getMaxPayload() API
`message`	A pointer to an array of bytes containing the message payload.
`options`	Specifies the EmberMessageOptions for the outgoing message.

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 , the packet length is 0, the passed TX options indicates some feature that is not supported, the destination address mode is set to EMBER_MAC_ADDRESS_MODE_NONE or the EMBER_OPTIONS_SECURITY_ENABLED option is set and the source address is set to a mode other than EMBER_MAC_ADDRESS_MODE_LONG .
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 level that is not supported.
EMBER_MAC_BUSY if the message was not accepted because the MAC is currently performing a critical operation.

void emberMacMessageSentHandler	(	`EmberStatus`	`status,`
		EmberOutgoingMacMessage *	`message`
	)

A callback invoked when a node of EMBER_MAC_MODE_DEVICE type or EMBER_MAC_MODE_SLEEPY_DEVICE type has completed sending a MAC frame.

Parameters


              status

An EmberStatus value of:

EMBER_SUCCESS if an ACK was received from the destination or no ACK was requested.
EMBER_MAC_NO_ACK_RECEIVED if an ACK was requested and no ACK was received.
EMBER_MAC_INDIRECT_TIMEOUT if the MAC frame was sent out via the indirect queue and the it timed-out before a data request was received.
EMBER_MAC_INDIRECT_MESSAGE_PURGED if the MAC frame was sent out via the indirect queue and it was removed prior to a data request being received.
EMBER_PHY_TX_CCA_FAIL if the node failed all the clear channel assessment attempts.
EMBER_PHY_TX_INCOMPLETE if the transmission was not completed correctly.

message An EmberOutgoingMacMessage describing the outgoing MAC frame.

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

Sends a message to the passed destination short ID.

Parameters

`destination`	The destination node short ID.
`endpoint`	The destination endpoint of the outgoing message. This value can't exceed EMBER_MAX_ENDPOINT .
`messageTag`	A value chosen by the application. This value will be passed in the corresponding emberMessageSentHandler() call.
`messageLength`	The size in bytes of the message payload. Use the emberGetMaximumPayloadLength() API to determine the maximum message length allowed.
`message`	A pointer to an array of bytes containing the message payload.
`options`	Specifies the EmberMessageOptions for the outgoing message.

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, the packet length is 0, the passed TX options indicates some feature that is not supported, the passed endpoint exceeds EMBER_MAX_ENDPOINT or the node is of EMBER_MAC_MODE_DEVICE device type or EMBER_MAC_MODE_SLEEPY_DEVICE (use emberMacMessageSend instead).
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.

void emberMessageSentHandler	(	`EmberStatus`	`status,`
		EmberOutgoingMessage *	`message`
	)

A callback invoked when the stack has completed sending a message.

Parameters


              status

An EmberStatus value of:

EMBER_SUCCESS if an ACK was received from the destination or no ACK was requested.
EMBER_MAC_NO_ACK_RECEIVED if an ACK was requested and no ACK was received.
EMBER_MAC_INDIRECT_TIMEOUT if the destination is a sleepy node and the packet timed-out before the sleepy node sent a data request.
EMBER_MAC_INDIRECT_MESSAGE_PURGED if the destination is a sleepy node and it was removed from the child table while the packet was stored in the indirect queue.
EMBER_PHY_TX_CCA_FAIL if the node failed all the clear channel assessment attempts.
EMBER_PHY_TX_INCOMPLETE if the transmission was not completed correctly.

message An EmberOutgoingMessage describing the outgoing packet.

EmberStatus emberPollForData ( void )

Sends 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, a EMBER_MAC_MODE_DEVICE or a 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.

EmberStatus emberPurgeIndirectMessages ( void )

Purges all indirect transmissions from the indirect message queue.

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

EmberStatus emberSetPollDestinationAddress ( EmberMacAddress * destination )

Sets 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, a value of EMBER_INVALID_CALL otherwise.

Messaging Silicon Labs Connect Stack API Reference

Macros

Handlers

APIs

Detailed Description

Macro Definition Documentation

Function Documentation

Messaging
Silicon Labs Connect Stack API Reference