License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

SPDX-License-Identifier: Zlib

The licensor of this software is Silicon Laboratories Inc.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

/***************************************************************************/
#ifndef __MESSAGE_H__
#define __MESSAGE_H__

#define EMBER_MAX_UNSECURED_APPLICATION_PAYLOAD_LENGTH     111

#define EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH       102

#define EMBER_MAX_ENDPOINT                                 0xF

void emberMessageSentHandler(EmberStatus status, EmberOutgoingMessage *message);

void emberMacMessageSentHandler(EmberStatus status,
                                EmberOutgoingMacMessage *message);

void emberIncomingMessageHandler(EmberIncomingMessage *message);

void emberIncomingMacMessageHandler(EmberIncomingMacMessage *message);


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

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

EmberStatus emberPollForData(void);

EmberStatus emberSetPollDestinationAddress(EmberMacAddress *destination);

EmberStatus emberPurgeIndirectMessages(void);

EmberStatus emberSetIndirectQueueTimeout(uint32_t timeoutMs);

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

bool emberUsingLongMessages(void);

EmberStatus emberNcpSetLongMessagesUse(bool useLongMessages);

#endif //__MESSAGE_H__

Handlers#

The Application Framework implements all handlers, directly calling their associated callbacks. By default, Connect projects declare such callbacks as stubs in flex-callbacks-stubs.c. Hence, to use an enabled Connect feature, applications should replace the stub with their own implementation of the associated callback (typically in flex-callbacks.c). See UG235.04 for more info.

void
emberMessageSentHandler(EmberStatus status, EmberOutgoingMessage *message)

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

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.

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.

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.

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.

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.

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.

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.

Purge all indirect transmissions from the indirect message queue.

emberSetIndirectQueueTimeout(uint32_t timeoutMs)

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

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.

bool

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

emberNcpSetLongMessagesUse(bool useLongMessages)

Set the current message length that the stack uses.

Macros#

#define

The maximum allowed endpoint value.

Handlers Documentation#

emberMessageSentHandler#

void emberMessageSentHandler (EmberStatus status, EmberOutgoingMessage * message)

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

Parameters
[in]status

An EmberStatus value of:

[in]message

An EmberOutgoingMessage describing the outgoing packet.

Warnings


Definition at line 95 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
[in]status

An EmberStatus value of:

[in]message

An EmberOutgoingMacMessage describing the outgoing MAC frame.

Warnings


Definition at line 127 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
[in]message

An EmberIncomingMessage describing the incoming packet.

Warnings


Definition at line 139 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
[in]message

An EmberIncomingMacMessage describing the incoming packet.

Warnings


Definition at line 152 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
[in]destination

The destination node short ID.

[in]endpoint

The destination endpoint of the outgoing message. This value can't exceed EMBER_MAX_ENDPOINT.

[in]messageTag

A value chosen by the application. This value will be passed in the corresponding emberMessageSentHandler() call.

[in]messageLength

The size of the message payload in bytes. Use the emberGetMaximumPayloadLength() API to determine the maximum message length allowed.

[in]message

A pointer to an array of bytes containing the message payload.

[in]options

Specifies the EmberMessageOptions for the outgoing message.

Returns


Definition at line 203 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
[in]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.

[in]messageTag

A value chosen by the application. This value will be passed in the corresponding emberMacMessageSentHandler() call.

[in]messageLength

The size in bytes of the message payload. The application can use the emberGetMaximumPayloadLength() API to determine the maximum allowable payload, given a permutation of source and destination addressing and other TX options.

[in]message

A pointer to an array of bytes containing the message payload.

[in]options

Specifies the EmberMessageOptions for the outgoing message.

Returns


Definition at line 257 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
N/A

Returns


Definition at line 278 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
N/Adestination

Returns


Definition at line 288 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

emberPurgeIndirectMessages#

EmberStatus emberPurgeIndirectMessages (void )

Purge all indirect transmissions from the indirect message queue.

Parameters
N/A

Returns


Definition at line 299 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
N/AtimeoutMs

The timeout in milliseconds to be set.

Returns


Definition at line 313 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

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.

Parameters
[in]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.

[in]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.

[in]interpan

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.

[in]secured

Indicates whether the frame should be secured or not.

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.


Definition at line 339 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

emberUsingLongMessages#

bool emberUsingLongMessages (void )

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

Parameters
N/A

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


Definition at line 351 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

emberNcpSetLongMessagesUse#

EmberStatus emberNcpSetLongMessagesUse (bool useLongMessages)

Set the current message length that the stack uses.

Parameters
[in]useLongMessages

True to use long messages (length stored in a uint16_t), false to use short messages (length stored in a uint8_t).

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.


Definition at line 370 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

Macro Definition Documentation#

EMBER_MAX_UNSECURED_APPLICATION_PAYLOAD_LENGTH#

#define EMBER_MAX_UNSECURED_APPLICATION_PAYLOAD_LENGTH
Value:
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.


Definition at line 48 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH#

#define EMBER_MAX_SECURED_APPLICATION_PAYLOAD_LENGTH
Value:
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.


Definition at line 54 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h

EMBER_MAX_ENDPOINT#

#define EMBER_MAX_ENDPOINT
Value:
0xF

The maximum allowed endpoint value.


Definition at line 58 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/stack/include/message.h