Sending and Receiving Messages#

sl_passive_ack_config_enum_t#

sl_passive_ack_config_enum_t

Allows the higher layers to control the broadcast behavior of a routing device. The originating device will rebroadcast the maximum number of times and The configurations below only restrict the number of broadcasts from neighboring routers. The configuration settings must be done on each node.

SL_PASSIVE_ACK_THRESHOLD_NO_REBROADCAST - All non originating configured nodes check for passive acks from minAcksNeeded neighbors. They will not rebroadcast received message if all passive acks have been received. If no passive acks received it will rebroadcast max times. SL_PASSIVE_ACK_THRESHOLD_WITH_REBROADCAST_ALL_NODES - This configuration is for both originating and relaying (non originating nodes). All configured nodes check for passive acks from minAcksNeeded neighbors. They will not rebroadcast received message if all passive acks have been received. If no passive acks received it will rebroadcast max times if minAcksNeeded is not set to 0

Returns

• None.

emberApsAckTimeoutMs#

uint16_t emberApsAckTimeoutMs

The APS ACK timeout value. The stack waits this amount of time between resends of APS retried messages. The default value is:

  ((EMBER_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS
    * EMBER_MAX_HOPS)
   + EMBER_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS)

emberMulticastTable#

EmberMulticastTableEntry emberMulticastTable[]

The multicast table.

Each entry contains a multicast ID and an endpoint, indicating that the endpoint is a member of the multicast group. Only devices with an endpoint in a multicast group will receive messages sent to that multicast group.

Entries with with an endpoint of 0 are ignored (the ZDO does not a member of any multicast groups). All endpoints are initialized to 0 on startup.

emberMulticastTableSize#

uint8_t emberMulticastTableSize

The number of entries in the multicast table.

emberMaximumApsPayloadLength#

uint8_t emberMaximumApsPayloadLength (void )

Return the maximum size of the payload that the Application Support sub-layer will accept.

The size depends on the security level in use. The value is the same as that found in the node descriptor.

Returns

• The maximum APS payload length.

emberSendMulticastWithAlias#

EmberStatus emberSendMulticastWithAlias (EmberApsFrame * apsFrame, uint8_t radius, uint8_t nonmemberRadius, EmberMessageBuffer message, EmberNodeId alias, uint8_t sequence)

Send a multicast message for an alias source to all endpoints that share a specific multicast ID and are within a specified number of hops of the sender.

Returns

• An EmberStatus value. For any result other than EMBER_SUCCESS, the message will not be sent.

  • EMBER_SUCCESS - The message has been submitted for transmission.

  • EMBER_INVALID_BINDING_INDEX - The bindingTableIndex refers to a non-multicast binding.

  • EMBER_NETWORK_DOWN - The node is not part of a network.

  • EMBER_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.

  • EMBER_NO_BUFFERS - The free packet buffer pool is empty.

  • EMBER_NETWORK_BUSY - Insufficient resources available in Network or MAC layers to send message.

emberSendMulticast#

EmberStatus emberSendMulticast (EmberApsFrame * apsFrame, uint8_t radius, uint8_t nonmemberRadius, EmberMessageBuffer message)

Send a multicast message to all endpoints that share a specific multicast ID and are within a specified number of hops of the sender.

Returns

• An EmberStatus value. For any result other than EMBER_SUCCESS, the message will not be sent.

  • EMBER_SUCCESS - The message has been submitted for transmission.

  • EMBER_INVALID_BINDING_INDEX - The bindingTableIndex refers to a non-multicast binding.

  • EMBER_NETWORK_DOWN - The node is not part of a network.

  • EMBER_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.

  • EMBER_NO_BUFFERS - The free packet buffer pool is empty.

  • EMBER_NETWORK_BUSY - Insufficient resources available in Network or MAC layers to send message.

emberSendUnicast#

EmberStatus emberSendUnicast (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame * apsFrame, EmberMessageBuffer message)

Send a unicast message per the Zigbee specification.

The message will arrive at its destination only if there is a known route to the destination node. Setting the ::ENABLE_ROUTE_DISCOVERY option will cause a route to be discovered if none is known. Setting the ::FORCE_ROUTE_DISCOVERY option will force route discovery. Routes to end-device children of the local node are always known.

Setting the APS_RETRY option will cause the message to be retransmitted until either a matching acknowledgment is received or three transmissions have been made.

Note

• Using the ::FORCE_ROUTE_DISCOVERY option will cause the first transmission to be consumed by a route request as part of discovery, so the application payload of this packet will not reach its destination on the first attempt. For the packet to reach its destination, the APS_RETRY option must be set so that another attempt is made to transmit the message with its application payload after the route has been constructed.

Setting the ::DESTINATION_EUI64 option will cause the long ID of the destination to be included in the network header. This is the only way to absolutely guarantee that the message is delivered to the correct node. Without it, a message may on occasion be delivered to the wrong destination in the event of an ID conflict that has not yet been detected and resolved by the network layer.

Note

• When sending fragmented messages, the stack will only assign a new APS sequence number for the first fragment of the message (i.e., EMBER_APS_OPTION_FRAGMENT is set and the low-order byte of the groupId field in the APS frame is zero). For all subsequent fragments of the same message, the application must set the sequence number field in the APS frame to the sequence number assigned by the stack to the first fragment.

Returns

• An EmberStatus value. For any result other than EMBER_SUCCESS, the message will not be sent.

  • EMBER_SUCCESS - The message has been submitted for transmission.

  • EMBER_INVALID_BINDING_INDEX - The bindingTableIndex refers to a non-unicast binding.

  • EMBER_NETWORK_DOWN - The node is not part of a network.

  • EMBER_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.

  • EMBER_MAX_MESSAGE_LIMIT_REACHED - The EMBER_APS_UNICAST_MESSAGE_COUNT limit has been reached.

emberSendBroadcast#

EmberStatus emberSendBroadcast (EmberNodeId destination, EmberApsFrame * apsFrame, uint8_t radius, EmberMessageBuffer message)

Send a broadcast message as per the ZigBee specification.

The message will be delivered to all nodes within radius hops of the sender. A radius of zero is converted to EMBER_MAX_HOPS.

Returns

• An EmberStatus value.

emberProxyBroadcast#

EmberStatus emberProxyBroadcast (EmberNodeId source, EmberNodeId destination, uint8_t sequence, EmberApsFrame * apsFrame, uint8_t radius, EmberMessageBuffer message)

Proxy a broadcast message for another node.

The message will be delivered to all nodes within radius hops of the local node. A radius of zero is converted to EMBER_MAX_HOPS.

Returns

• An EmberStatus value.

emberProxyNextBroadcastFromLong#

EmberStatus emberProxyNextBroadcastFromLong (uint8_t * euiSource)

Proxy a broadcast message for another node.

The function is used in conjunction with emberProxyBroadcast, which proxies a message from a short ID. This function is used where a long source is also specified in the NWK frame control.

Returns

• An EmberStatus value.

emberSendManyToOneRouteRequest#

EmberStatus emberSendManyToOneRouteRequest (uint16_t concentratorType, uint8_t radius)

Send a route request packet that creates routes from every node in the network back to this node.

This function should be called by an application that wants to communicate with many nodes, for example, a gateway, central monitor, or controller. A device using this function was referred to as an "aggregator" in EmberZNet 2.x and earlier, and is referred to as a "concentrator" in the ZigBee specification and EmberZNet 3.

This function enables large scale networks because the other devices do not have to individually perform bandwidth-intensive route discoveries. Instead, when a remote node sends an APS unicast to a concentrator, its network layer automatically delivers a special route record packet first, which lists the network IDs of all intermediate relays. The concentrator can then use source routing to send outbound APS unicasts. (A source routed message is one in which the entire route is listed in the network layer header.) This allows the concentrator to communicate with thousands of devices without requiring large route tables on neighboring nodes.

This function is only available in ZigBee Pro (stack profile 2), and cannot be called on end devices. Any router can be a concentrator (not just the coordinator), and there can be multiple concentrators on a network.

Note that a concentrator does not automatically obtain routes to all network nodes after calling this function. Remote applications must first initiate an inbound APS unicast.

Many-to-one routes are not repaired automatically. Instead, the concentrator application must call this function to rediscover the routes as necessary, for example, upon failure of a retried APS message. This is necessary because there is no scalable one-size-fits-all route repair strategy. A common and recommended strategy is for the concentrator application to refresh the routes by calling this function periodically.

Returns

• EMBER_SUCCESS if the route request was successfully submitted to the transmit queue, and EMBER_ERR_FATAL otherwise.

emberGetSourceRouteTableEntry#

EmberStatus emberGetSourceRouteTableEntry (uint8_t index, EmberNodeId * destination, uint8_t * closerIndex)

Return the source route table entry fields.

emberGetSourceRouteTableFilledSize#

uint8_t emberGetSourceRouteTableFilledSize (void )

Return the number of filled entries in the source route table.

emberGetSourceRouteTableTotalSize#

uint8_t emberGetSourceRouteTableTotalSize (void )

Return the source route table total size.

emberIncomingManyToOneRouteRequestHandler#

void emberIncomingManyToOneRouteRequestHandler (EmberNodeId source, EmberEUI64 longId, uint8_t cost)

Indicate that a many-to-one route to the concentrator with the given short and long ID is available for use.

The application must define EMBER_APPLICATION_HAS_INCOMING_MANY_TO_ONE_ROUTE_REQUEST_HANDLER in its configuration header to use this.

emberIncomingRouteErrorHandler#

void emberIncomingRouteErrorHandler (EmberStatus status, EmberNodeId target)

Invoke when a route error message is received.

A status of EMBER_SOURCE_ROUTE_FAILURE indicates that a source-routed unicast sent from this node encountered a broken link. Note that this case occurs only if this node is a concentrator using many-to-one routing for inbound messages and source-routing for outbound messages. The node prior to the broken link generated the route error message and returned it to us along the many-to-one route.

A status of EMBER_MANY_TO_ONE_ROUTE_FAILURE also occurs only if the local device is a concentrator, and indicates that a unicast sent to the local device along a many-to-one route encountered a broken link. The node prior to the broken link generated the route error message and forwarded it to the local device via a randomly chosen neighbor, taking advantage of the many-to-one nature of the route.

A status of EMBER_MAC_INDIRECT_TIMEOUT indicates that a message sent to the target end device could not be delivered by the parent because the indirect transaction timer expired. Upon receipt of the route error, the stack sets the extended timeout for the target node in the address table, if present. It then calls this handler to indicate receipt of the error.

Note that if the original unicast data message is sent using the EMBER_APS_OPTION_RETRY option, a new route error message is generated for each failed retry. Therefore, it is not unusual to receive three route error messages in succession for a single failed retried APS unicast. On the other hand, it is also not guaranteed that any route error messages will be delivered successfully at all. The only sure way to detect a route failure is to use retried APS messages and to check the status of the emberMessageSentHandler().

If the application includes this callback, it must define EMBER_APPLICATION_HAS_INCOMING_ROUTE_ERROR_HANDLER in its configuration header.

emberIncomingNetworkStatusHandler#

void emberIncomingNetworkStatusHandler (uint8_t errorCode, EmberNodeId target)

Invoke when a network status message is received that informs the application of the Over-the-Air error codes for the specific destination.

Note: Network analyzer may flag this message as "route error" which is the old name for the "network status" command.

This handler is a superset of emberIncomingRouteErrorHandler. The old API was only invoking the handler for a couple of the possible error codes and these were being translated into EmberStatus.

To make the API more generic and extensible in future, the new API emberIncomingNetworkStatusHandler simply copies the OTA error code as is. If the application includes this callback, it must define EMBER_APPLICATION_HAS_INCOMING_NETWORK_STATUS_HANDLER in its configuration header.

emberOverrideIncomingRouteRecordHandler#

void emberOverrideIncomingRouteRecordHandler (EmberNodeId source, EmberEUI64 sourceEui, uint8_t relayCount, EmberMessageBuffer header, uint8_t relayListIndex, bool * consumed)

SoC only. It reports the arrival of a route record command frame to the application.

The route record command frame lists the short IDs of the relays that were used along the route from the source to us. This information is used by aggregators to be able to initiate source routed messages. The application must define EMBER_APPLICATION_HAS_OVERRIDE_SOURCE_ROUTING in its configuration header to use this.

emberOverrideAppendSourceRouteHandler#

uint8_t emberOverrideAppendSourceRouteHandler (EmberNodeId destination, EmberMessageBuffer * header, bool * consumed)

SoC only. The application can implement this callback to supply source routes to outgoing messages.

The application must define :EMBER_APPLICATION_HAS_OVERRIDE_SOURCE_ROUTING in its configuration header to use this. The application uses the supplied destination to look up a source route. If available, the application appends the source route to the supplied header using the proper frame format, as described in section 3.4.1.9 "Source Route Subframe Field" of the ZigBee specification. If a source route is appended, the stack takes care of setting the proper flag in the network frame control field. See app/util/source-route.c for a sample implementation.

If header is :EMBER_NULL_MESSAGE_BUFFER the only action is to return the size of the source route frame needed to the destination.

Returns

• The size in bytes of the source route frame, or zero if there is not one available.

emberIncomingRouteRecordHandler#

void emberIncomingRouteRecordHandler (EmberNodeId source, EmberEUI64 sourceEui, uint8_t relayCount, EmberMessageBuffer header, uint8_t relayListIndex)

DEPRECTAED emberOverrideIncomingRouteRecordHandler should be used Reports the arrival of a route record command frame to the application.

The route record command frame lists the short IDs of the relays that were used along the route from the source to us. This information is used by aggregators to be able to initiate source routed messages. The application must define EMBER_APPLICATION_HAS_SOURCE_ROUTING in its configuration header to use this.

emberAppendSourceRouteHandler#

uint8_t emberAppendSourceRouteHandler (EmberNodeId destination, EmberMessageBuffer header)

DEPRECATED emberOverrideAppendSourceRouteHandler should be used The application can implement this callback to supply source routes to outgoing messages.

The application must define :EMBER_APPLICATION_HAS_SOURCE_ROUTING in its configuration header to use this. The application uses the supplied destination to look up a source route. If available, the application appends the source route to the supplied header using the proper frame format, as described in section 3.4.1.9 "Source Route Subframe Field" of the ZigBee specification. If a source route is appended, the stack takes care of setting the proper flag in the network frame control field. See app/util/source-route.c for a sample implementation.

If header is :EMBER_NULL_MESSAGE_BUFFER the only action is to return the size of the source route frame needed to the destination.

Returns

• The size in bytes of the source route frame, or zero if there is not one available.

emberCancelMessage#

EmberStatus emberCancelMessage (EmberMessageBuffer message)

DEPRECATED.

Returns

• Always returns EMBER_SUCCESS.

emberMessageSentHandler#

void emberMessageSentHandler (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame * apsFrame, EmberMessageBuffer message, EmberStatus status)

Invoke by the stack when it has completed sending a message.