Header file for XBee API frame handling. More...

#include "xbee_at_cmds.h"
#include "xbee.h"

Include dependency graph for xbee_api_frames.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	xbee_api_frame_t
	Structure to represent an XBee API frame. More...

Macros
#define	XBEE_MAX_FRAME_DATA_SIZE 256

#define	API_SEND_SUCCESS 0

#define	API_SEND_ERROR_TIMEOUT -1

#define	API_SEND_ERROR_INVALID_COMMAND -2

#define	API_SEND_ERROR_UART_FAILURE -3

#define	API_SEND_ERROR_FRAME_TOO_LARGE -4

#define	API_SEND_AT_CMD_ERROR -5

#define	API_SEND_AT_CMD_RESONSE_TIMEOUT -6

Enumerations
enum	xbee_deliveryStatus_t { XBEE_DELIVERY_STATUS_SUCCESS = 0x00 , XBEE_DELIVERY_STATUS_NO_ACK = 0x01 , XBEE_DELIVERY_STATUS_CCA_FAILURE = 0x02 , XBEE_DELIVERY_STATUS_PURGED = 0x03 , XBEE_DELIVERY_STATUS_INVALID_DEST = 0x15 , XBEE_DELIVERY_STATUS_NET_ACK_FAILURE = 0x21 , XBEE_DELIVERY_STATUS_NOT_JOINED = 0x22 , XBEE_DELIVERY_STATUS_SELF_ADDRESSED = 0x23 , XBEE_DELIVERY_STATUS_ADDRESS_NOT_FOUND = 0x24 , XBEE_DELIVERY_STATUS_ROUTE_NOT_FOUND = 0x25 , XBEE_DELIVERY_STATUS_PAYLOAD_TOO_LARGE = 0x74 }
	Delivery status codes for XBee Transmit Status frames (0x89). More...

enum	xbee_api_frame_type_t { XBEE_API_TYPE_AT_COMMAND = 0x08 , XBEE_API_TYPE_TX_REQUEST = 0x10 , XBEE_API_TYPE_MODEM_STATUS = 0x8A , XBEE_API_TYPE_AT_RESPONSE = 0x88 , XBEE_API_TYPE_TX_STATUS = 0x89 , XBEE_API_TYPE_LR_JOIN_REQUEST = 0x14 , XBEE_API_TYPE_LR_TX_REQUEST = 0x50 , XBEE_API_TYPE_LR_RX_PACKET = 0xD0 , XBEE_API_TYPE_LR_EXPLICIT_RX_PACKET = 0xD1 , XBEE_API_TYPE_LR_EXPLICIT_TX_STATUS = 0xD2 , XBEE_API_TYPE_3RF_REMOTE_AT_COMMAND = 0x17 , XBEE_API_TYPE_3RF_REMOTE_AT_RESPONSE = 0x97 , XBEE_API_TYPE_3RF_RX_PACKET = 0x90 , XBEE_API_TYPE_3RF_RX_EXPLICIT_PACKET = 0x91 , XBEE_API_TYPE_CELLULAR_TX_IPV4 = 0x20 , XBEE_API_TYPE_CELLULAR_RX_IPV4 = 0xB0 , XBEE_API_TYPE_CELLULAR_MODEM_STATUS = 0x8A , XBEE_API_TYPE_IO_DATA_SAMPLE_RX = 0x92 , XBEE_API_TYPE_REMOTE_AT_COMMAND = 0x17 , XBEE_API_TYPE_REMOTE_AT_RESPONSE = 0x97 , XBEE_API_TYPE_IO_SAMPLE_RX_INDICATOR = 0x8F }
	Enumeration of XBee API frame types. More...

enum	api_receive_status_t { API_RECEIVE_SUCCESS = 0 , API_RECEIVE_ERROR_INVALID_POINTER = -1 , API_RECEIVE_ERROR_TIMEOUT_START_DELIMITER = -2 , API_RECEIVE_ERROR_INVALID_START_DELIMITER = -3 , API_RECEIVE_ERROR_TIMEOUT_LENGTH = -4 , API_RECEIVE_ERROR_FRAME_TOO_LARGE = -5 , API_RECEIVE_ERROR_TIMEOUT_DATA = -6 , API_RECEIVE_ERROR_TIMEOUT_CHECKSUM = -7 , API_RECEIVE_ERROR_INVALID_CHECKSUM = -8 , API_RECEIVE_ERROR_UART_FAILURE = -9 }
	Enumeration of status codes for receiving XBee API frames. More...

Functions
api_receive_status_t	apiReceiveApiFrame (XBee self, xbee_api_frame_t frame)
	Checks for and receives an XBee API frame, populating the provided frame pointer. More...

int	apiSendAtCommand (XBee self, at_command_t command, const uint8_t parameter, uint8_t paramLength)
	Sends an AT command through an API frame. More...

int	apiSendFrame (XBee self, uint8_t frame_type, const uint8_t data, uint16_t len)
	Sends an XBee API frame. More...

int	apiSendAtCommandAndGetResponse (XBee self, at_command_t command, const uint8_t parameter, uint8_t paramLength, uint8_t responseBuffer, uint8_t responseLength, uint32_t timeoutMs)
	Sends an AT command via an API frame and waits for the response. More...

void	apiHandleFrame (XBee *self, xbee_api_frame_t frame)
	Calls registered handlers based on the received API frame type. More...

void	xbeeHandleAtResponse (XBee self, xbee_api_frame_t frame)

void	xbeeHandleModemStatus (XBee self, xbee_api_frame_t frame)

void	xbeeHandleRxPacket (XBee self, xbee_api_frame_t frame)

Detailed Description

Header file for XBee API frame handling.

This file defines the interface for creating, parsing, and handling XBee API frames. API frames are the primary method for structured data exchange with XBee modules, enabling the control and configuration of the modules as well as data transmission. This file includes prototypes for functions that manage the construction, validation, and interpretation of these frames.

Version: 1.0

Date: 2024-08-08

@license MIT Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Author: Felix Galindo @contact felix.nosp@m..gal.nosp@m.indo@.nosp@m.digi.nosp@m..com

Macro Definition Documentation

◆ API_SEND_AT_CMD_ERROR

#define API_SEND_AT_CMD_ERROR -5

◆ API_SEND_AT_CMD_RESONSE_TIMEOUT

#define API_SEND_AT_CMD_RESONSE_TIMEOUT -6

◆ API_SEND_ERROR_FRAME_TOO_LARGE

#define API_SEND_ERROR_FRAME_TOO_LARGE -4

◆ API_SEND_ERROR_INVALID_COMMAND

#define API_SEND_ERROR_INVALID_COMMAND -2

◆ API_SEND_ERROR_TIMEOUT

#define API_SEND_ERROR_TIMEOUT -1

◆ API_SEND_ERROR_UART_FAILURE

#define API_SEND_ERROR_UART_FAILURE -3

◆ API_SEND_SUCCESS

#define API_SEND_SUCCESS 0

◆ XBEE_MAX_FRAME_DATA_SIZE

#define XBEE_MAX_FRAME_DATA_SIZE 256

Enumeration Type Documentation

◆ api_receive_status_t

enum api_receive_status_t

Enumeration of status codes for receiving XBee API frames.

This enum defines the possible status codes that can be returned by the api_receive_api_frame function. These status codes indicate whether the frame was successfully received or if there was an error, and if so, what type of error occurred.

Enumerator
API_RECEIVE_SUCCESS	Frame received successfully.
API_RECEIVE_ERROR_INVALID_POINTER	Invalid frame pointer (NULL)
API_RECEIVE_ERROR_TIMEOUT_START_DELIMITER	Timeout or error reading start delimiter.
API_RECEIVE_ERROR_INVALID_START_DELIMITER	Invalid start delimiter received.
API_RECEIVE_ERROR_TIMEOUT_LENGTH	Timeout or error reading frame length.
API_RECEIVE_ERROR_FRAME_TOO_LARGE	Frame length exceeds buffer size.
API_RECEIVE_ERROR_TIMEOUT_DATA	Timeout or error reading frame data.
API_RECEIVE_ERROR_TIMEOUT_CHECKSUM	Timeout or error reading checksum.
API_RECEIVE_ERROR_INVALID_CHECKSUM	Invalid checksum detected.
API_RECEIVE_ERROR_UART_FAILURE	UART read or write failure.

◆ xbee_api_frame_type_t

enum xbee_api_frame_type_t

Enumeration of XBee API frame types.

This enumeration defines the various API frame types used in XBee communication. API frames are structured data packets that facilitate communication between the host (e.g., microcontroller) and the XBee module. Different frame types serve different purposes, such as sending commands, receiving data, controlling GPIOs, or reading ADC values.

The frame types are divided into common frames, specific frames for XBee LR, XBee 3 RF, XBee Cellular, and GPIO/ADC-related frames.

Enumerator
XBEE_API_TYPE_AT_COMMAND	Frame for sending AT commands. XBee Common API Frames Frame type for sending AT commands to the XBee module. The command is executed locally by the module.
XBEE_API_TYPE_TX_REQUEST	Frame for transmitting data. Frame type for transmitting data to another device in the network. This frame initiates the transmission of a data packet.
XBEE_API_TYPE_MODEM_STATUS	Frame for modem status reports. Frame type that reports the status of the modem (e.g., hardware reset, network join). This frame is automatically generated by the XBee module.
XBEE_API_TYPE_AT_RESPONSE	Frame for receiving AT command responses. Frame type for receiving the response to a previously sent AT command. It contains the result of the command execution.
XBEE_API_TYPE_TX_STATUS	Frame for delivery status reports. XBee LR Specific API Frames Frame type that reports the delivery status of a previously sent TX Request. This frame provides feedback on whether the transmission was successful or failed.
XBEE_API_TYPE_LR_JOIN_REQUEST	Frame for LoRaWAN join requests. Frame type specific to XBee LR modules for sending a Join Request in a LoRaWAN network. This frame is used to join the network.
XBEE_API_TYPE_LR_TX_REQUEST	Frame for transmitting data in LoRaWAN. Frame type specific to XBee LR modules for transmitting data in a LoRaWAN network. It initiates the transmission of a data packet within the LoRaWAN.
XBEE_API_TYPE_LR_RX_PACKET	Frame for receiving data packets in LoRaWAN. Frame type specific to XBee LR modules for receiving data packets from the LoRaWAN network. This frame carries the payload received from another device.
XBEE_API_TYPE_LR_EXPLICIT_RX_PACKET	Frame for receiving explicitly addressed packets in LoRaWAN. Frame type specific to XBee LR modules for receiving explicitly addressed data packets from the LoRaWAN network. It provides additional addressing information with the payload.
XBEE_API_TYPE_LR_EXPLICIT_TX_STATUS	Frame for explicit TX status in LoRaWAN. XBee 3 RF Specific API Frames
XBEE_API_TYPE_3RF_REMOTE_AT_COMMAND	Frame for sending remote AT commands (XBee 3 RF) Frame type specific to XBee 3 RF modules for sending remote AT commands to another device in the network. This allows configuration of remote devices.
XBEE_API_TYPE_3RF_REMOTE_AT_RESPONSE	Frame for receiving remote AT responses (XBee 3 RF) Frame type specific to XBee 3 RF modules for receiving responses to remote AT commands. It contains the result of the remote command execution.
XBEE_API_TYPE_3RF_RX_PACKET	Frame for receiving data packets (XBee 3 RF) Frame type specific to XBee 3 RF modules for receiving data packets from another device in the network. This frame carries the received payload.
XBEE_API_TYPE_3RF_RX_EXPLICIT_PACKET	Frame for receiving explicitly addressed packets (XBee 3 RF) XBee Cellular Specific API Frames Frame type specific to XBee 3 RF modules for receiving explicitly addressed data packets. It includes addressing information along with the received payload.
XBEE_API_TYPE_CELLULAR_TX_IPV4	Frame for transmitting IPv4 data (XBee Cellular) Frame type specific to XBee Cellular modules for transmitting IPv4 data packets. It initiates the transmission of an IPv4 packet over the cellular network.
XBEE_API_TYPE_CELLULAR_RX_IPV4	Frame for receiving IPv4 data (XBee Cellular) Frame type specific to XBee Cellular modules for receiving IPv4 data packets. It carries the received IPv4 packet from the cellular network.
XBEE_API_TYPE_CELLULAR_MODEM_STATUS	Frame for cellular modem status (XBee Cellular) XBee GPIO/ADC Related API Frames Frame type specific to XBee Cellular modules that reports the status of the cellular modem, including network registration, signal strength, and other modem status information.
XBEE_API_TYPE_IO_DATA_SAMPLE_RX	Frame for receiving IO data samples (GPIO/ADC) Frame type for receiving IO data samples. This frame contains the values read from the GPIOs and ADCs of the remote XBee module.
XBEE_API_TYPE_REMOTE_AT_COMMAND	Frame for sending remote AT commands (GPIO/ADC) Frame type for sending remote AT commands related to GPIO/ADC configuration or control. This allows configuration of remote XBee modules.
XBEE_API_TYPE_REMOTE_AT_RESPONSE	Frame for receiving remote AT command responses (GPIO/ADC) Frame type for receiving responses to remote AT commands related to GPIO/ADC configuration or control. It contains the result of the command execution.
XBEE_API_TYPE_IO_SAMPLE_RX_INDICATOR	Frame for receiving IO samples with explicit addressing (GPIO/ADC) Frame type for receiving IO samples with explicit addressing. This frame includes GPIO and ADC readings from a specific XBee module and additional addressing information. Additional frame types can be added to this enumeration as needed to support new functionality or XBee modules.

◆ xbee_deliveryStatus_t

enum xbee_deliveryStatus_t

Delivery status codes for XBee Transmit Status frames (0x89).

This enumeration defines the possible delivery status codes that can be returned in the Transmit Status frame (0x89) by the XBee module. These codes indicate the result of a data transmission, helping to determine whether the transmission was successful or if an error occurred.

The status codes can be used to troubleshoot issues in communication by identifying the specific reason for a transmission failure.

Enumerator
XBEE_DELIVERY_STATUS_SUCCESS	Indicates that the transmission was successful. The packet was delivered to the intended recipient without any errors.
XBEE_DELIVERY_STATUS_NO_ACK	Indicates that no acknowledgment was received from the recipient. This typically means that the packet was not successfully received or acknowledged.
XBEE_DELIVERY_STATUS_CCA_FAILURE	Indicates a Clear Channel Assessment (CCA) failure. The XBee module was unable to transmit because the channel was not clear (e.g., due to interference).
XBEE_DELIVERY_STATUS_PURGED	Indicates that the transmission was purged from the queue and not sent. This may occur if the module was unable to transmit the packet within the allowed timeframe.
XBEE_DELIVERY_STATUS_INVALID_DEST	Indicates that the destination endpoint was invalid. The packet could not be delivered because the specified destination was not valid.
XBEE_DELIVERY_STATUS_NET_ACK_FAILURE	Indicates a network acknowledgment failure. The packet was not acknowledged at the network level, suggesting that it was not delivered successfully.
XBEE_DELIVERY_STATUS_NOT_JOINED	Indicates that the module is not joined to a network. Transmission failed because the XBee module is not part of a network.
XBEE_DELIVERY_STATUS_SELF_ADDRESSED	Indicates that the transmission was attempted to the module's own address, which is not allowed.
XBEE_DELIVERY_STATUS_ADDRESS_NOT_FOUND	Indicates that the destination address was not found. The XBee module could not find the specified address in the network.
XBEE_DELIVERY_STATUS_ROUTE_NOT_FOUND	Indicates that no route to the destination was found. The module could not find a valid path to the destination address within the network.
XBEE_DELIVERY_STATUS_PAYLOAD_TOO_LARGE	Indicates that the payload was too large for transmission. The size of the data exceeded the maximum allowed payload size for the XBee module.

Function Documentation

◆ apiHandleFrame()

void apiHandleFrame	(	XBee *	self,
		xbee_api_frame_t	frame
	)

Calls registered handlers based on the received API frame type.

This function processes a received XBee API frame by calling the appropriate handler function based on the frame's type. It supports handling AT responses, modem status, transmit status, and received packet frames. For each frame type, the corresponding handler function is invoked if it is registered in the XBee virtual table (vtable). If the frame type is unknown, a debug message is printed.

Parameters

[in]	self	Pointer to the XBee instance.
[in]	frame	The received API frame to be handled.

Returns: void This function does not return a value.

◆ apiReceiveApiFrame()

api_receive_status_t apiReceiveApiFrame	(	XBee *	self,
		xbee_api_frame_t *	frame
	)

Checks for and receives an XBee API frame, populating the provided frame pointer.

This function attempts to read and receive an XBee API frame from the UART interface. It validates the received data by checking the start delimiter, frame length, and checksum. If the frame is successfully received and validated, the frame structure is populated with the received data. The function returns API_RECEIVE_SUCCESS if successful, or an error code from api_receive_status_t if any step in the process fails, including timeout.

Parameters

[in]	self	Pointer to the XBee instance.
[out]	frame	Pointer to an `xbee_api_frame_t` structure where the received frame data will be stored.

Returns: api_receive_status_t Returns API_RECEIVE_SUCCESS if the frame is successfully received, or an error code if a failure occurs.

◆ apiSendAtCommand()

int apiSendAtCommand	(	XBee *	self,
		at_command_t	command,
		const uint8_t *	parameter,
		uint8_t	paramLength
	)

Sends an AT command through an API frame.

This function constructs and sends an AT command in API frame mode. It prepares the frame by including the frame ID, the AT command, and any optional parameters. The function checks for various errors, such as invalid commands or parameters that are too large, and returns appropriate error codes. If the AT command is successfully sent, the function returns 0.

Parameters

[in]	self	Pointer to the XBee instance.
[in]	command	The AT command to be sent, specified as an `at_command_t` enum.
[in]	parameter	Pointer to the parameter data to be included with the AT command (can be NULL).
[in]	paramLength	Length of the parameter data in bytes (0 if no parameters).

Returns: int Returns 0 (API_SEND_SUCCESS) if the AT command is successfully sent, or a non-zero error code if there is a failure (API_SEND_ERROR_FRAME_TOO_LARGE, API_SEND_ERROR_INVALID_COMMAND, etc.).

◆ apiSendAtCommandAndGetResponse()

int apiSendAtCommandAndGetResponse	(	XBee *	self,
		at_command_t	command,
		const uint8_t *	parameter,
		uint8_t	paramLength,
		uint8_t *	responseBuffer,
		uint8_t *	responseLength,
		uint32_t	timeoutMs
	)

Sends an AT command via an API frame and waits for the response.

This function sends an AT command using an XBee API frame and then waits for a response from the XBee module within a specified timeout period. The response is captured and stored in the provided response buffer. The function continuously checks for incoming frames and processes them until the expected AT response frame is received or the timeout period elapses.

Parameters

[in]	self	Pointer to the XBee instance.
[in]	command	The AT command to be sent, specified as an `at_command_t` enum.
[in]	parameter	Pointer to the parameter data to be included with the AT command (can be NULL).
[out]	responseBuffer	Pointer to a buffer where the AT command response will be stored.
[out]	responseLength	Pointer to a variable where the length of the response will be stored.
[in]	timeoutMs	The timeout period in milliseconds within which the response must be received.

Returns: int Returns 0 (API_SEND_SUCCESS) if the AT command is successfully sent and a valid response is received, or a non-zero error code if there is a failure (API_SEND_AT_CMD_ERROR, API_SEND_AT_CMD_RESPONSE_TIMEOUT, etc.).

◆ apiSendFrame()

int apiSendFrame	(	XBee *	self,
		uint8_t	frameType,
		const uint8_t *	data,
		uint16_t	len
	)

Sends an XBee API frame.

This function constructs and sends an XBee API frame over the UART. The frame includes a start delimiter, length, frame type, data, and a checksum to ensure data integrity. The function increments the frame ID counter with each call, ensuring that frame IDs are unique. If the frame is successfully sent, the function returns 0; otherwise, it returns an error code indicating the failure.

Parameters

[in]	self	Pointer to the XBee instance.
[in]	frameType	The type of the API frame to send.
[in]	data	Pointer to the frame data to be included in the API frame.
[in]	len	Length of the frame data in bytes.

Returns: int Returns 0 (API_SEND_SUCCESS) if the frame is successfully sent, or a non-zero error code (API_SEND_ERROR_UART_FAILURE) if there is a failure.

◆ xbeeHandleAtResponse()

void xbeeHandleAtResponse	(	XBee *	self,
		xbee_api_frame_t *	frame
	)

◆ xbeeHandleModemStatus()

void xbeeHandleModemStatus	(	XBee *	self,
		xbee_api_frame_t *	frame
	)

◆ xbeeHandleRxPacket()

void xbeeHandleRxPacket	(	XBee *	self,
		xbee_api_frame_t *	frame
	)

Classes

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ API_SEND_AT_CMD_ERROR

◆ API_SEND_AT_CMD_RESONSE_TIMEOUT

◆ API_SEND_ERROR_FRAME_TOO_LARGE

◆ API_SEND_ERROR_INVALID_COMMAND

◆ API_SEND_ERROR_TIMEOUT

◆ API_SEND_ERROR_UART_FAILURE

◆ API_SEND_SUCCESS

◆ XBEE_MAX_FRAME_DATA_SIZE

Enumeration Type Documentation

◆ api_receive_status_t

◆ xbee_api_frame_type_t

◆ xbee_deliveryStatus_t

Function Documentation

◆ apiHandleFrame()

◆ apiReceiveApiFrame()

◆ apiSendAtCommand()

◆ apiSendAtCommandAndGetResponse()

◆ apiSendFrame()

◆ xbeeHandleAtResponse()

◆ xbeeHandleModemStatus()

◆ xbeeHandleRxPacket()