EmberZNet API for sending and receiving messages. See Sending and Receiving Messages for documentation.
License#
Copyright 2018 Silicon Laboratories Inc. www.silabs.com
The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.
/***************************************************************************/
#ifndef SILABS_MESSAGE_H
#define SILABS_MESSAGE_H
#include "stack/include/sl_zigbee_types.h"
#ifdef __cplusplus
extern "C" {
#endif
uint8_t sl_zigbee_maximum_aps_payload_length(void);
#define SL_ZIGBEE_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS 50
#define SL_ZIGBEE_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS 100
uint16_t sl_zigbee_get_aps_ack_timeout_ms(void);
void sl_zigbee_set_aps_ack_timeout_ms(uint16_t timeout);
sl_status_t sl_zigbee_send_multicast(sl_zigbee_aps_frame_t *apsFrame,
uint8_t radius,
uint16_t broadcastAddr,
sl_802154_short_addr_t alias,
uint8_t nwkSequence,
uint16_t messageTag,
uint8_t messageLength,
const uint8_t *message,
uint8_t *apsSequence);
sl_status_t sl_zigbee_send_unicast(sl_zigbee_outgoing_message_type_t type,
uint16_t indexOrDestination,
sl_zigbee_aps_frame_t *apsFrame,
uint16_t messageTag,
uint8_t messageLength,
const uint8_t *message,
uint8_t *apsSequence);
sl_status_t sl_zigbee_send_broadcast(sl_802154_short_addr_t alias,
sl_802154_short_addr_t destination,
uint8_t nwkSequence,
sl_zigbee_aps_frame_t *apsFrame,
uint8_t radius,
uint16_t messageTag,
uint8_t messageLength,
const uint8_t *message,
uint8_t *apsSequence);
sl_status_t sl_zigbee_proxy_next_broadcast_from_long(const uint8_t* euiSource);
void sl_zigbee_incoming_many_to_one_route_request_handler(sl_802154_short_addr_t source,
sl_802154_long_addr_t longId,
uint8_t cost);
void sl_zigbee_incoming_route_error_handler(sl_status_t status,
sl_802154_short_addr_t target);
void sl_zigbee_incoming_network_status_handler(uint8_t errorCode,
sl_802154_short_addr_t target);
void sl_zigbee_override_incoming_route_record_handler(sl_zigbee_rx_packet_info_t *packetInfo,
uint8_t relayCount,
uint8_t *relayList,
bool* consumed);
uint8_t sl_zigbee_internal_override_append_source_route_handler(sl_802154_short_addr_t destination,
sli_buffer_manager_buffer_t* header,
bool* consumed);
void sl_zigbee_incoming_route_record_handler(sl_zigbee_rx_packet_info_t *packetInfo,
uint8_t relayCount,
uint8_t *relayList);
uint8_t sl_zigbee_append_source_route_handler(sl_802154_short_addr_t destination,
sli_buffer_manager_buffer_t header);
void sl_zigbee_message_sent_handler(sl_status_t status,
sl_zigbee_outgoing_message_type_t type,
uint16_t indexOrDestination,
sl_zigbee_aps_frame_t *apsFrame,
uint16_t messageTag,
uint8_t messageLength,
uint8_t *message);
void sl_zigbee_incoming_message_handler(sl_zigbee_incoming_message_type_t type,
sl_zigbee_aps_frame_t *apsFrame,
sl_zigbee_rx_packet_info_t *packetInfo,
uint8_t messageLength,
uint8_t *message);
sl_status_t sl_zigbee_send_reply(sl_802154_short_addr_t destination,
sl_zigbee_aps_frame_t* apsFrame,
uint8_t messageLength,
uint8_t* messageContents);
void sl_zigbee_set_reply_fragment_data(uint16_t fragmentData);
sl_status_t sl_zigbee_set_address_table_info(uint8_t addressTableIndex,
sl_802154_long_addr_t eui64,
sl_802154_short_addr_t id);
bool sl_zigbee_address_table_entry_is_active(uint8_t addressTableIndex);
sl_status_t sl_zigbee_get_address_table_info(uint8_t addressTableIndex,
sl_802154_short_addr_t *nodeId,
sl_802154_long_addr_t eui64);
sl_status_t sl_zigbee_set_extended_timeout(sl_802154_long_addr_t remoteEui64, bool extendedTimeout);
sl_status_t sl_zigbee_get_extended_timeout(sl_802154_long_addr_t remoteEui64);
void sl_zigbee_id_conflict_handler(sl_802154_short_addr_t conflictingId);
bool sl_zigbee_pending_acked_messages(void);
sl_zigbee_multicast_table_entry_t* sl_zigbee_get_multicast_table(void);
sl_status_t sl_zigbee_set_multicast_table(const sl_zigbee_multicast_table_entry_t* entry);
uint8_t sl_zigbee_get_multicast_table_size(void);
sl_status_t sl_zigbee_set_multicast_table_size(uint8_t size);
sl_status_t sl_zigbee_set_passive_ack_config(sl_passive_ack_config_enum_t config, uint8_t minAcksNeeded);
#define sl_zigbee_broadcast_set_min_acks_needed(minAcksNeeded) \
sl_zigbee_set_passive_ack_config(SL_PASSIVE_ACK_THRESHOLD_WITH_REBROADCAST, minAcksNeeded)
sl_zigbee_packet_action_t sl_zigbee_internal_packet_handoff_incoming_handler(sl_zigbee_zigbee_packet_type_t packetType,
sli_buffer_manager_buffer_t packetBuffer,
uint8_t index,
void *data);
sl_zigbee_packet_action_t sl_zigbee_internal_packet_handoff_outgoing_handler(sl_zigbee_zigbee_packet_type_t packetType,
sli_buffer_manager_buffer_t packetBuffer,
uint8_t index,
void *data);
void sl_zigbee_redirect_outgoing_message_handler(uint8_t mac_index,
uint8_t packet_length,
uint8_t* packet_contents,
uint8_t priority);
sl_zigbee_packet_action_t sl_zigbee_af_incoming_packet_filter_cb(sl_zigbee_zigbee_packet_type_t packetType,
uint8_t* packetData,
uint8_t* size_p,
void *data);
sl_zigbee_packet_action_t sl_zigbee_af_outgoing_packet_filter_cb(sl_zigbee_zigbee_packet_type_t packetType,
uint8_t* packetData,
uint8_t* size_p,
void* data);
sl_status_t slx_zigbee_add_to_incoming_network_queue(int8_t rssi,
uint8_t lqi,
const sl_nwk_packet_exchange_t *nwk_packet);
//retrieve packet info from stack globals for callbacks
void sli_zigbee_fill_rx_packet_info(sl_zigbee_rx_packet_info_t* packetInfo);
#ifdef __cplusplus
}
#endif
#endif // SILABS_MESSAGE_H
Macros#
The per-hop delay allowed for in the calculation of the APS ACK timeout value. This is defined in the Zigbee specification. This times the maximum number of hops (SL_ZIGBEE_MAX_HOPS) plus the terminal encrypt/decrypt time is the timeout between retries of an APS ACKed message in milliseconds.
The terminal encrypt/decrypt time allowed for in the calculation of the APS ACK timeout value. This is defined in the ZigBee specification.
Set the number of broadcast passive acknowledgments required before terminating a broadcast transmission. A value of 0xFF causes the node to wait for all neighbors to re-broadcast the packet before terminating the transmission. The default value is 0xFF. API is kept for backwards compatibility.
Functions#
Return the maximum size of the payload that the Application Support sub-layer will accept.
Return the APS ACK timeout value. The stack waits this amount of time between resends of APS retried messages. The default value is:
Set the APS ACK timeout value.
Send a multicast message to all endpoints that share a specific multicast ID and are within a specified number of hops of the sender.
Send a unicast message per the Zigbee specification.
Send a broadcast message as per the ZigBee specification.
Proxy a broadcast message for another node.
Indicate that a many-to-one route to the concentrator with the given short and long ID is available for use.
Invoke when a route error message is received.
Invoke when a network status message is received that informs the application of the Over-the-Air error codes for the specific destination.
SoC only. It reports the arrival of a route record command frame to the application.
SoC only. The application can implement this callback to supply source routes to outgoing messages.
DEPRECTAED sl_zigbee_override_incoming_route_record_handler should be used Reports the arrival of a route record command frame to the application.
DEPRECATED sl_zigbee_internal_override_append_source_route_handler should be used The application can implement this callback to supply source routes to outgoing messages.
Invoke by the stack when it has completed sending a message.
Invoke by the EmberZNet stack when a message is received.
Send a reply for an application that has received a unicast message.
Set the fragment data to be used when sending a reply to a unicast message.
Setter function for address table entry.
Indicate whether any messages are currently being sent using this address table entry.
Getter function for address table entry info.
Tell the stack whether or not the normal interval between retransmissions of a retried unicast message should be increased by SL_ZIGBEE_INDIRECT_TRANSMISSION_TIMEOUT.
Indicate whether or not the stack will extend the normal interval between retransmissions of a retried unicast message by SL_ZIGBEE_INDIRECT_TRANSMISSION_TIMEOUT.
Invoke by the EmberZNet stack when an ID conflict is discovered, that is, two different nodes in the network were found to be using the same short ID.
Indicate whether there are pending messages in the APS retry queue.
Returns the multicast table.
Sets the multicast table pointer.
Return the number of entries in the multicast table.
Set the number of entries in the multicast table.
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.
Intercept an incoming packet from the stack and hands off to a plugin for further processing.
Intercept an outgoing packet from the stack and hands off to a plugin for further processing.
Intercept an outgoing packet from the Zigbee stack and hands it off to the relevant plugins for possible further processing and forwarding to non 15.4 interfaces.
Call when the stack receives a packet that is meant for one of the protocol layers specified in sl_zigbee_zigbee_packet_type_t.
The stack is preparing to send a protocol layer packet.
Add a network packet into the incoming network queue.
Macro Definition Documentation#
SL_ZIGBEE_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS#
#define SL_ZIGBEE_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MSValue:
50
The per-hop delay allowed for in the calculation of the APS ACK timeout value. This is defined in the Zigbee specification. This times the maximum number of hops (SL_ZIGBEE_MAX_HOPS) plus the terminal encrypt/decrypt time is the timeout between retries of an APS ACKed message in milliseconds.
51
of file stack/include/message.h
SL_ZIGBEE_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS#
#define SL_ZIGBEE_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MSValue:
100
The terminal encrypt/decrypt time allowed for in the calculation of the APS ACK timeout value. This is defined in the ZigBee specification.
56
of file stack/include/message.h
sl_zigbee_broadcast_set_min_acks_needed#
#define sl_zigbee_broadcast_set_min_acks_neededValue:
(minAcksNeeded)
Set the number of broadcast passive acknowledgments required before terminating a broadcast transmission. A value of 0xFF causes the node to wait for all neighbors to re-broadcast the packet before terminating the transmission. The default value is 0xFF. API is kept for backwards compatibility.
Returns
::SL_STATUS_OK if set passive ack success; SL_STATUS_INVALID_PARAMETER when pass wrong config argument
754
of file stack/include/message.h
Function Documentation#
sl_zigbee_maximum_aps_payload_length#
uint8_t sl_zigbee_maximum_aps_payload_length (void )
Return the maximum size of the payload that the Application Support sub-layer will accept.
N/A |
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.
43
of file stack/include/message.h
sl_zigbee_get_aps_ack_timeout_ms#
uint16_t sl_zigbee_get_aps_ack_timeout_ms (void )
Return the APS ACK timeout value. The stack waits this amount of time between resends of APS retried messages. The default value is:
N/A |
((SL_ZIGBEE_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS
* SL_ZIGBEE_MAX_HOPS)
+ SL_ZIGBEE_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS)
67
of file stack/include/message.h
sl_zigbee_set_aps_ack_timeout_ms#
void sl_zigbee_set_aps_ack_timeout_ms (uint16_t timeout)
Set the APS ACK timeout value.
N/A | timeout |
72
of file stack/include/message.h
sl_zigbee_send_multicast#
sl_status_t sl_zigbee_send_multicast (sl_zigbee_aps_frame_t * apsFrame, uint8_t radius, uint16_t broadcastAddr, sl_802154_short_addr_t alias, uint8_t nwkSequence, uint16_t messageTag, uint8_t messageLength, const uint8_t * message, uint8_t * apsSequence)
Send a multicast message to all endpoints that share a specific multicast ID and are within a specified number of hops of the sender.
N/A | apsFrame | The APS frame for the message. The multicast will be sent to the groupId in this frame. |
N/A | radius | The message will be delivered to all nodes within this number of hops of the sender. A value of zero is converted to SL_ZIGBEE_MAX_HOPS. |
N/A | broadcastAddr | A specific broadcast addrs that is prefered. If a non broadcast address is used here, the stack will either use SL_ZIGBEE_SLEEPY_BROADCAST_ADDRESS or SL_ZIGBEE_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS depending on if multicasts are to be sent to sleepies. |
N/A | alias | The alias from which to send the multicast. If not needed use SL_ZIGBEE_NULL_NODE_ID |
N/A | nwkSequence | The aliased NWK sequence number for the message. Only used if there is an alias source. |
N/A | messageTag | A value chosen by the application. It gets passed back up in sl_zigbee_message_sent_handler(). |
N/A | messageLength | The length of the message parameter in bytes. |
N/A | message | Content of the message. |
N/A | apsSequence | Return: The APS sequencer number that will be used when this message is transmitted. |
Returns
An ::sl_status_t value. For any result other than ::SL_STATUS_OK, the message will not be sent.
::SL_STATUS_OK - The message has been submitted for transmission.
::SL_STATUS_INVALID_INDEX - The
bindingTableIndex
refers to a non-multicast binding.::SL_STATUS_NETWORK_DOWN - The node is not part of a network.
::SL_STATUS_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.
::SL_STATUS_ALLOCATION_FAILED - The free packet buffer pool is empty.
::SL_STATUS_BUSY - Insufficient resources available in Network or MAC layers to send message.
118
of file stack/include/message.h
sl_zigbee_send_unicast#
sl_status_t sl_zigbee_send_unicast (sl_zigbee_outgoing_message_type_t type, uint16_t indexOrDestination, sl_zigbee_aps_frame_t * apsFrame, uint16_t messageTag, uint8_t messageLength, const uint8_t * message, uint8_t * apsSequence)
Send a unicast message per the Zigbee specification.
N/A | type | Specifies the outgoing message type. Must be one of SL_ZIGBEE_OUTGOING_DIRECT, SL_ZIGBEE_OUTGOING_VIA_ADDRESS_TABLE, or SL_ZIGBEE_OUTGOING_VIA_BINDING. |
N/A | indexOrDestination | Depending on the type of addressing used, this is either the sl_802154_short_addr_t of the destination, an index into the address table, or an index into the binding table. |
N/A | apsFrame | The APS frame which is to be added to the message. |
N/A | messageTag | A value chosen by the application. It gets passed back up in sl_zigbee_message_sent_handler(). |
N/A | messageLength | The length of the message parameter in bytes. |
N/A | message | Content of the message. |
N/A | apsSequence | Return: The APS sequencer number that will be used when this message is transmitted. |
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., SL_ZIGBEE_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 ::sl_status_t value. For any result other than ::SL_STATUS_OK, the message will not be sent.
::SL_STATUS_OK - The message has been submitted for transmission.
::SL_STATUS_INVALID_PARAMETER The passed message pointer is NULL and the messageLength is > 0
::SL_STATUS_ALLOCATION_FAILED The stack failed to allocate a buffer to store the message.
::SL_STATUS_INVALID_INDEX - The
bindingTableIndex
refers to a non-unicast binding.::SL_STATUS_NETWORK_DOWN - The node is not part of a network.
::SL_STATUS_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.
::SL_STATUS_ZIGBEE_MAX_MESSAGE_LIMIT_REACHED - The SL_ZIGBEE_APS_UNICAST_MESSAGE_COUNT limit has been reached.
198
of file stack/include/message.h
sl_zigbee_send_broadcast#
sl_status_t sl_zigbee_send_broadcast (sl_802154_short_addr_t alias, sl_802154_short_addr_t destination, uint8_t nwkSequence, sl_zigbee_aps_frame_t * apsFrame, uint8_t radius, uint16_t messageTag, uint8_t messageLength, const uint8_t * message, uint8_t * apsSequence)
Send a broadcast message as per the ZigBee specification.
N/A | alias | The aliased source from which to send the broadcast. ::SL_ZIGBEE__NULL_NODE_ID could be used if this is a simple broadcast message, and not aliased/proxied. |
N/A | destination | The destination to which to send the broadcast. This must be one of three ZigBee broadcast addresses. |
N/A | nwkSequence | The NWK sequence number for the message, if there is a non-null alias source. |
N/A | apsFrame | The APS frame data to be included in the message. |
N/A | radius | The maximum number of hops the message will be relayed. |
N/A | messageTag | A value chosen by the application. It gets passed back up in sl_zigbee_message_sent_handler(). |
N/A | messageLength | The length of the message parameter in bytes. |
N/A | message | Content of the message. |
N/A | apsSequence | Return: The APS sequencer number that will be used when this message is transmitted. |
The message will be delivered to all nodes within radius
hops of the sender. A radius of zero is converted to SL_ZIGBEE_MAX_HOPS.
Returns
An ::sl_status_t value indicating success or the reason for failure.
240
of file stack/include/message.h
sl_zigbee_proxy_next_broadcast_from_long#
sl_status_t sl_zigbee_proxy_next_broadcast_from_long (const uint8_t * euiSource)
Proxy a broadcast message for another node.
N/A | euiSource | The long source from which to send the broadcast. |
The function is used in conjunction with aliased/proxied sl_zigbee_send_broadcast, a message from a short ID. This function is used where a long source is also specified in the NWK frame control.
Returns
An ::sl_status_t value.
262
of file stack/include/message.h
sl_zigbee_incoming_many_to_one_route_request_handler#
void sl_zigbee_incoming_many_to_one_route_request_handler (sl_802154_short_addr_t source, sl_802154_long_addr_t 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.
N/A | source | The short ID of the concentrator that initiated the many-to-one route request. |
N/A | longId | The EUI64 of the concentrator. |
N/A | cost | The path cost to the concentrator. |
The application must define SL_ZIGBEE_APPLICATION_HAS_INCOMING_MANY_TO_ONE_ROUTE_REQUEST_HANDLER
in its configuration header to use this.
277
of file stack/include/message.h
sl_zigbee_incoming_route_error_handler#
void sl_zigbee_incoming_route_error_handler (sl_status_t status, sl_802154_short_addr_t target)
Invoke when a route error message is received.
N/A | status | ::SL_STATUS_ZIGBEE_SOURCE_ROUTE_FAILURE, ::SL_STATUS_ZIGBEE_MANY_TO_ONE_ROUTE_FAILURE, ::SL_STATUS_MAC_INDIRECT_TIMEOUT |
N/A | target | The short ID of the remote node. |
A status of ::SL_STATUS_ZIGBEE_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 ::SL_STATUS_ZIGBEE_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 ::SL_STATUS_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 SL_ZIGBEE_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 sl_zigbee_message_sent_handler().
If the application includes this callback, it must define SL_ZIGBEE_APPLICATION_HAS_INCOMING_ROUTE_ERROR_HANDLER
in its configuration header.
326
of file stack/include/message.h
sl_zigbee_incoming_network_status_handler#
void sl_zigbee_incoming_network_status_handler (uint8_t errorCode, sl_802154_short_addr_t target)
Invoke when a network status message is received that informs the application of the Over-the-Air error codes for the specific destination.
N/A | errorCode | uint8_t |
N/A | target | The short ID of the remote node. |
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 sl_zigbee_incoming_route_error_handler. The old API was only invoking the handler for a couple of the possible error codes and these were being translated into sl_status_t.
To make the API more generic and extensible in future, the new API sl_zigbee_incoming_network_status_handler simply copies the OTA error code as is. If the application includes this callback, it must define SL_ZIGBEE_APPLICATION_HAS_INCOMING_NETWORK_STATUS_HANDLER
in its configuration header.
349
of file stack/include/message.h
sl_zigbee_override_incoming_route_record_handler#
void sl_zigbee_override_incoming_route_record_handler (sl_zigbee_rx_packet_info_t * packetInfo, uint8_t relayCount, uint8_t * relayList, bool * consumed)
SoC only. It reports the arrival of a route record command frame to the application.
N/A | packetInfo | The received message information. |
N/A | relayCount | The number of relays in relayList. |
N/A | relayList | The route record. Each relay in the list is an uint16_t node ID. The list is passed as uint8_t * to avoid alignment problems. |
N/A | consumed | if set to true stack won't process the Incoming route record |
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 SL_ZIGBEE_APPLICATION_HAS_OVERRIDE_SOURCE_ROUTING
in its configuration header to use this.
368
of file stack/include/message.h
sl_zigbee_internal_override_append_source_route_handler#
uint8_t sl_zigbee_internal_override_append_source_route_handler (sl_802154_short_addr_t destination, sli_buffer_manager_buffer_t * header, bool * consumed)
SoC only. The application can implement this callback to supply source routes to outgoing messages.
N/A | destination | The network destination of the message. |
N/A | header | Pointer to the message buffer containing the partially complete packet header. The application appends the source route frame to this header. |
N/A | consumed | if set to true stack would skip appending the existing source route entry from the table |
The application must define :SL_ZIGBEE_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 :SL_ZIGBEE_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.
398
of file stack/include/message.h
sl_zigbee_incoming_route_record_handler#
void sl_zigbee_incoming_route_record_handler (sl_zigbee_rx_packet_info_t * packetInfo, uint8_t relayCount, uint8_t * relayList)
DEPRECTAED sl_zigbee_override_incoming_route_record_handler should be used Reports the arrival of a route record command frame to the application.
N/A | packetInfo | The received message information. |
N/A | relayCount | The number of relays in relayList. |
N/A | relayList | The route record. Each relay in the list is an uint16_t node ID. The list is passed as uint8_t * to avoid alignment problems. |
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 SL_ZIGBEE_APPLICATION_HAS_SOURCE_ROUTING
in its configuration header to use this.
418
of file stack/include/message.h
sl_zigbee_append_source_route_handler#
uint8_t sl_zigbee_append_source_route_handler (sl_802154_short_addr_t destination, sli_buffer_manager_buffer_t header)
DEPRECATED sl_zigbee_internal_override_append_source_route_handler should be used The application can implement this callback to supply source routes to outgoing messages.
N/A | destination | The network destination of the message. |
N/A | header | The message buffer containing the partially complete packet header. The application appends the source route frame to this header. |
The application must define :SL_ZIGBEE_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 :SL_ZIGBEE_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.
447
of file stack/include/message.h
sl_zigbee_message_sent_handler#
void sl_zigbee_message_sent_handler (sl_status_t status, sl_zigbee_outgoing_message_type_t type, uint16_t indexOrDestination, sl_zigbee_aps_frame_t * apsFrame, uint16_t messageTag, uint8_t messageLength, uint8_t * message)
Invoke by the stack when it has completed sending a message.
N/A | status | An ::sl_status_t value of ::SL_STATUS_OK if an ACK was received from the destination (for unicast requring an ACK) or ::SL_STATUS_ZIGBEE_DELIVERY_FAILED if no ACK was received in case an ACK was required. |
N/A | type | The type of message sent. |
N/A | indexOrDestination | The destination to which the message was sent. For direct unicasts, the destination to which the message was sent; for other unicasts, the address table or binding index to which the message was sent. The value is unspecified for multicasts and broadcasts. |
N/A | apsFrame | The APS frame for the message. |
N/A | messageTag | The value supplied in the sl_zigbee_send_unicast, ::sl_zigbee_send_multivast or sl_zigbee_send_broadcast API. |
N/A | messageLength | The length of the message parameter in bytes. |
N/A | message | The message that was sent. |
477
of file stack/include/message.h
sl_zigbee_incoming_message_handler#
void sl_zigbee_incoming_message_handler (sl_zigbee_incoming_message_type_t type, sl_zigbee_aps_frame_t * apsFrame, sl_zigbee_rx_packet_info_t * packetInfo, uint8_t messageLength, uint8_t * message)
Invoke by the EmberZNet stack when a message is received.
N/A | type | The type of the incoming message. One of the following: |
N/A | apsFrame | The APS frame from the incoming message. |
N/A | packetInfo | The received message information. |
N/A | messageLength | The length of the received message in bytes. |
N/A | message | The incoming message. |
The following functions may be called from sl_zigbee_incoming_message_handler():
sl_zigbee_send_reply() (for incoming APS retried unicasts only)
511
of file stack/include/message.h
sl_zigbee_send_reply#
sl_status_t sl_zigbee_send_reply (sl_802154_short_addr_t destination, sl_zigbee_aps_frame_t * apsFrame, uint8_t messageLength, uint8_t * messageContents)
Send a reply for an application that has received a unicast message.
N/A | destination | Node ID of the original message's sender |
N/A | apsFrame | APS Frame for the reply. |
N/A | messageLength | Length of the reply message. |
N/A | messageContents | A reply message. |
The reply will be included with the ACK that the stack automatically sends back.
Returns
An ::sl_status_t value. For any result other than ::SL_STATUS_OK, the message will not be sent.
::SL_STATUS_OK - The message has been submitted for transmission.
::SL_STATUS_INVALID_STATE - apsFrame's options do not include EMBER_APS_OPTION_REPLY and ZIGBEE_APS_FRAME_CONTROL_WANT_ACK.
::SL_STATUS_ALLOCATION_FAILED - Not enough memory was available to send the reply.
::SL_STATUS_BUSY - Either:
No route available.
Insufficient resources available in Network or MAC layers to send message.
542
of file stack/include/message.h
sl_zigbee_set_reply_fragment_data#
void sl_zigbee_set_reply_fragment_data (uint16_t fragmentData)
Set the fragment data to be used when sending a reply to a unicast message.
N/A | fragmentData | The low byte is the block number of the reply. The high byte is the ACK bitfield of the reply. |
Note
This function may be called only from within sl_zigbee_incoming_message_handler().
555
of file stack/include/message.h
sl_zigbee_set_address_table_info#
sl_status_t sl_zigbee_set_address_table_info (uint8_t addressTableIndex, sl_802154_long_addr_t eui64, sl_802154_short_addr_t id)
Setter function for address table entry.
N/A | addressTableIndex | The index of an address table entry. @eui64 The EUI64 to use for the address table entry. |
N/A | eui64 | The short ID corresponding to the remote node whose EUI64 is stored in the address table at the given index or SL_ZIGBEE_TABLE_ENTRY_UNUSED_NODE_ID which indicates that the entry stored in the address table at the given index is not in use. |
N/A | id |
This function will also check other address table entries, the child table and the neighbor table to see if the node ID for the given EUI64 is already known. If known, this function will also set the node ID. If not known, it will set the node ID to SL_ZIGBEE_UNKNOWN_NODE_ID.
Usually the application will not need to set the short ID in the address table. Once the remote EUI64 is set, the stack is capable of figuring out the short ID on its own. However, in cases where the application does set the short ID, the application must set the remote EUI64 prior to setting the short ID.
Returns
::SL_STATUS_OK if the info was successfully set, and ::SL_STATUS_ZIGBEE_ADDRESS_TABLE_ENTRY_IS_ACTIVE otherwise.
580
of file stack/include/message.h
sl_zigbee_address_table_entry_is_active#
bool sl_zigbee_address_table_entry_is_active (uint8_t addressTableIndex)
Indicate whether any messages are currently being sent using this address table entry.
N/A | addressTableIndex | The index of an address table entry. |
Note that this function does not indicate whether the address table entry is unused. To determine whether an address table entry is unused, check the remote node ID. The remote node ID will have the value SL_ZIGBEE_TABLE_ENTRY_UNUSED_NODE_ID when the address table entry is not in use.
Returns
True if the address table entry is active, false otherwise.
598
of file stack/include/message.h
sl_zigbee_get_address_table_info#
sl_status_t sl_zigbee_get_address_table_info (uint8_t addressTableIndex, sl_802154_short_addr_t * nodeId, sl_802154_long_addr_t eui64)
Getter function for address table entry info.
N/A | addressTableIndex | The index of an address table entry. |
N/A | nodeId | The EUI64 of the address table entry is copied to this location. |
N/A | eui64 | One of the following is copied to this location:
|
622
of file stack/include/message.h
sl_zigbee_set_extended_timeout#
sl_status_t sl_zigbee_set_extended_timeout (sl_802154_long_addr_t remoteEui64, bool extendedTimeout)
Tell the stack whether or not the normal interval between retransmissions of a retried unicast message should be increased by SL_ZIGBEE_INDIRECT_TRANSMISSION_TIMEOUT.
N/A | remoteEui64 | The address of the node for which the timeout is to be set. |
N/A | extendedTimeout | True if the retry interval should be increased by SL_ZIGBEE_INDIRECT_TRANSMISSION_TIMEOUT. False if the normal retry interval should be used. |
The interval needs to be increased when sending to a sleepy node so that the message is not retransmitted until the destination has had time to wake up and poll its parent. The stack will automatically extend the timeout:
For our own sleepy children.
When an address response is received from a parent on behalf of its child.
When an indirect transaction expiry route error is received.
When an end device announcement is received from a sleepy node.
Returns
SL_STATUS_OK if successful, else SL_STATUS_FAIL
648
of file stack/include/message.h
sl_zigbee_get_extended_timeout#
sl_status_t sl_zigbee_get_extended_timeout (sl_802154_long_addr_t remoteEui64)
Indicate whether or not the stack will extend the normal interval between retransmissions of a retried unicast message by SL_ZIGBEE_INDIRECT_TRANSMISSION_TIMEOUT.
N/A | remoteEui64 | The address of the node for which the timeout is to be returned. |
Returns
SL_STATUS_OK if the retry interval will be increased by SL_ZIGBEE_INDIRECT_TRANSMISSION_TIMEOUT and SL_STATUS_FAIL if the normal retry interval will be used.
661
of file stack/include/message.h
sl_zigbee_id_conflict_handler#
void sl_zigbee_id_conflict_handler (sl_802154_short_addr_t conflictingId)
Invoke by the EmberZNet stack when an ID conflict is discovered, that is, two different nodes in the network were found to be using the same short ID.
N/A | conflictingId | The short ID for which a conflict was detected. |
The stack automatically removes the conflicting short ID from its internal tables (address, binding, route, neighbor, and child tables). The application should discontinue any other use of the ID. If the application includes this callback, it must define ::SL_ZIGBEE_APPLICATION_HAS_ID_CONFLICT_HANDLER in its configuration header.
676
of file stack/include/message.h
sl_zigbee_pending_acked_messages#
bool sl_zigbee_pending_acked_messages (void )
Indicate whether there are pending messages in the APS retry queue.
N/A |
Returns
True if there is at least a pending message belonging to the current network in the APS retry queue, false otherwise.
683
of file stack/include/message.h
sl_zigbee_get_multicast_table#
sl_zigbee_multicast_table_entry_t * sl_zigbee_get_multicast_table (void )
Returns the multicast table.
N/A |
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.
695
of file stack/include/message.h
sl_zigbee_set_multicast_table#
sl_status_t sl_zigbee_set_multicast_table (const sl_zigbee_multicast_table_entry_t * entry)
Sets the multicast table pointer.
N/A | entry |
700
of file stack/include/message.h
sl_zigbee_get_multicast_table_size#
uint8_t sl_zigbee_get_multicast_table_size (void )
Return the number of entries in the multicast table.
N/A |
704
of file stack/include/message.h
sl_zigbee_set_multicast_table_size#
sl_status_t sl_zigbee_set_multicast_table_size (uint8_t size)
Set the number of entries in the multicast table.
N/A | size |
708
of file stack/include/message.h
sl_zigbee_set_passive_ack_config#
sl_status_t sl_zigbee_set_passive_ack_config (sl_passive_ack_config_enum_t config, uint8_t minAcksNeeded)
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.
N/A | config | The minimum number of acknowledgments (re-broadcasts) to wait for until deeming the broadcast transmission complete. |
N/A | minAcksNeeded |
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
::SL_STATUS_OK if set passive ack success; SL_STATUS_INVALID_PARAMETER when pass wrong config argument
740
of file stack/include/message.h
sl_zigbee_internal_packet_handoff_incoming_handler#
sl_zigbee_packet_action_t sl_zigbee_internal_packet_handoff_incoming_handler (sl_zigbee_zigbee_packet_type_t packetType, sli_buffer_manager_buffer_t packetBuffer, uint8_t index, void * data)
Intercept an incoming packet from the stack and hands off to a plugin for further processing.
N/A | packetType | The type of packet and the target stack layer. See sl_zigbee_zigbee_packet_type_t. |
N/A | packetBuffer | The sli_buffer_manager_buffer_t containing the packet. @parma index The starting index of the relevant packet data. The plugin\ will receive a flat copy of the packet starting from this index. |
N/A | index | Auxiliary data pointer |
N/A | data |
Returns
769
of file stack/include/message.h
sl_zigbee_internal_packet_handoff_outgoing_handler#
sl_zigbee_packet_action_t sl_zigbee_internal_packet_handoff_outgoing_handler (sl_zigbee_zigbee_packet_type_t packetType, sli_buffer_manager_buffer_t packetBuffer, uint8_t index, void * data)
Intercept an outgoing packet from the stack and hands off to a plugin for further processing.
N/A | packetType | The type of packet and the source stack layer. See sl_zigbee_zigbee_packet_type_t. |
N/A | packetBuffer | The sli_buffer_manager_buffer_t containing the packet. |
N/A | index | The starting index of the relevant packet data. The plugin\ will receive a flat copy of the packet starting from this index. |
N/A | data | Auxiliary data pointer |
Returns
786
of file stack/include/message.h
sl_zigbee_redirect_outgoing_message_handler#
void sl_zigbee_redirect_outgoing_message_handler (uint8_t mac_index, uint8_t packet_length, uint8_t * packet_contents, uint8_t priority)
Intercept an outgoing packet from the Zigbee stack and hands it off to the relevant plugins for possible further processing and forwarding to non 15.4 interfaces.
N/A | mac_index | The interface id from which this packet would need to be sent out |
N/A | packet_length | Length of this packet. |
N/A | packet_contents | Pointer to the contents of this packet. |
N/A | priority | Possible priority of this packet vs other packets that need to be sent out on the same interface |
805
of file stack/include/message.h
sl_zigbee_af_incoming_packet_filter_cb#
sl_zigbee_packet_action_t sl_zigbee_af_incoming_packet_filter_cb (sl_zigbee_zigbee_packet_type_t packetType, uint8_t * packetData, uint8_t * size_p, void * data)
Call when the stack receives a packet that is meant for one of the protocol layers specified in sl_zigbee_zigbee_packet_type_t.
N/A | packetType | The type of packet received. See sl_zigbee_zigbee_packet_type_t. |
N/A | packetData | A flat buffer containing the packet contents the buffer starts with the command id followed by the payload |
N/A | size_p | a pointer to the size of the packet data |
N/A | data | This is a pointer to auxiliary data for the command. |
The packetType argument is one of the values of the sl_zigbee_zigbee_packet_type_t enum. If the stack receives an 802.15.4 MAC beacon, it will call this function with the packetType argument set to SL_ZIGBEE_ZIGBEE_PACKET_TYPE_BEACON.
The implementation of this callback may alter the data contained in packetData, modify options and flags in the axillary data, or consume the packet itself, either sending the message, or discarding it as it sees fit.
Returns
a sl_zigbee_packet_action_t indicating what action should be taken for the packet, SL_ZIGBEE_ACCEPT_PACKET, SL_ZIGBEE_DROP_PACKET, or SL_ZIGBEE_MANGLE_PACKET
834
of file stack/include/message.h
sl_zigbee_af_outgoing_packet_filter_cb#
sl_zigbee_packet_action_t sl_zigbee_af_outgoing_packet_filter_cb (sl_zigbee_zigbee_packet_type_t packetType, uint8_t * packetData, uint8_t * size_p, void * data)
The stack is preparing to send a protocol layer packet.
N/A | packetType | The type of packet received. See sl_zigbee_zigbee_packet_type_t. |
N/A | packetData | A flat buffer containing the packet contents the buffer starts with the command id followed by the payload |
N/A | size_p | a pointer to the size of the packet data |
N/A | data | This is a pointer to auxiliary data for the command. ZDO commands pass the sl_zigbee_aps_frame_t associated with the packet here. Otherwise, this value is NULL. |
This is called when the stack is preparing to send a packet from one of the protocol layers specified in sl_zigbee_zigbee_packet_type_t.
The packetType argument is one of the values of the sl_zigbee_zigbee_packet_type_t enum. If the stack is preparing to send an 802.15.4 MAC beacon, it will call this function with the packetType argument set to SL_ZIGBEE_ZIGBEE_PACKET_TYPE_BEACON.
The implementation of this callback may alter the data contained in packetData, modify options and flags in the axillary data, or consume the packet itself, either sending the message, or discarding it as it sees fit.
Returns
a sl_zigbee_packet_action_t indicating what action should be taken for the packet, SL_ZIGBEE_ACCEPT_PACKET, SL_ZIGBEE_DROP_PACKET, or SL_ZIGBEE_MANGLE_PACKET
866
of file stack/include/message.h
slx_zigbee_add_to_incoming_network_queue#
sl_status_t slx_zigbee_add_to_incoming_network_queue (int8_t rssi, uint8_t lqi, const sl_nwk_packet_exchange_t * nwk_packet)
Add a network packet into the incoming network queue.
N/A | rssi | The RSSI of the incoming packet. |
N/A | lqi | The LQI of the incoming packet. |
N/A | nwk_packet | The network packet, for more information see sl_nwk_packet_exchange_t. |
Quality: Experimental API for prototyping.
The content of the networkPacket follows the formats below: -—Encrypted NWK Packet-— NWK Header (8 bytes) NWK Security (14 bytes) APS Header (8 bytes) APS Payload (Variable) NWK MIC (4 bytes)
-—Unencrypted NWK Packet-— NWK Header (8 bytes) APS Header (8 bytes) APS Payload (Variable)
Noted: This function does not free up the memory pointed by the networkPacket pointer. Users may need to free up the memory after calling this function. The network packet should not be larger than 115 bytes (TRANSMIT_BUFFER_SIZE 126 bytes - PACKET_HEADER_OVERHEAD 11 bytes).
Returns
::SL_STATUS_OK if the network packet was successfully added into the network queue, otherwise ::SL_STATUS_ALLOCATION_FAILED or ::SL_STATUS_MESSAGE_TOO_LONG.
901
of file stack/include/message.h
sli_zigbee_fill_rx_packet_info#
void sli_zigbee_fill_rx_packet_info (sl_zigbee_rx_packet_info_t * packetInfo)
N/A | packetInfo |
953
of file stack/include/message.h