Implementation of XBee API frame handling. More...

#include "xbee_api_frames.h"
#include "xbee.h"
#include "port.h"
#include <stdio.h>
#include <string.h>

Include dependency graph for xbee_api_frames.c:

Functions
int	apiSendFrame (XBee self, uint8_t frameType, const uint8_t data, uint16_t len)
	Sends an XBee API frame. 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...

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

void	apiHandleFrame (XBee *self, xbee_api_frame_t frame)
	Calls registered handlers based on the received API frame type. 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	xbeeHandleAtResponse (XBee self, xbee_api_frame_t frame)

void	xbeeHandleModemStatus (XBee self, xbee_api_frame_t frame)

Detailed Description

Implementation of XBee API frame handling.

This file contains the implementation of functions used to create, parse, and handle API frames for XBee communication. API frames are the primary method for structured data exchange with XBee modules.

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

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
	)

Functions

Detailed Description

Function Documentation

◆ apiHandleFrame()

◆ apiReceiveApiFrame()

◆ apiSendAtCommand()

◆ apiSendAtCommandAndGetResponse()

◆ apiSendFrame()

◆ xbeeHandleAtResponse()

◆ xbeeHandleModemStatus()