AT (Hayes) command set library. More...

Detailed Description

AT (Hayes) command set library.

This module provides functions to interact with devices using AT commands.

Most functions compare the bytes echoed by the device with what they intended to send, and bail out if there's no match.

Furthermore, the library tries to cope with difficulties regarding different line endings. It usually sends "<command><CR>", but expects "<command>\LF\CR" as echo.

As a debugging aid, when compiled with "-DAT_PRINT_INCOMING=1", every input byte gets printed.

Unsolicited Result Codes (URC)

An unsolicited result code is a string message that is not triggered as a information text response to a previous AT command and can be output at any time to inform a specific event or status change.

The module provides a basic URC handling by adding the at_urc module to the application. This allows to register and de-register URC strings to check. Later, at_process_urc can be called to check if any of the registered URCs have been detected. If a registered URC has been detected the correspondent callback function is called. The mode of operation requires that the user of the module processes periodically the URCs.

Alternatively, one of the at_urc_isr_<priority> modules can be included. priority can be one of low, medium or highest, which correspond to the priority of the thread that processes the URCs. For more information on the priorities check the Event Queue module. This will extend the functionality of at_urc by processing the URCs when the AT_RECV_EOL_2 character is detected and there is no pending response. This works by posting an event to an event thread that processes the URCs.

Modules
	AT driver compile configuration

Files
file	at.h
	AT (Hayes) library interface.

Data Structures
struct	at_urc_t
	Unsolicited result code data structure. More...

struct	at_dev_t
	AT device structure. More...

Macros
#define	AT_BUF_SIZE (1 << CONFIG_AT_BUF_SIZE_EXP)
	Size of buffer used to process unsolicited result code data.

#define	AT_SEND_EOL_LEN (sizeof(CONFIG_AT_SEND_EOL) - 1)
	Shortcut for getting send end of line length.

Typedefs
typedef void(*	at_urc_cb_t) (void arg, const char code)
	Unsolicited result code callback. More...

Functions
int	at_dev_init (at_dev_t dev, uart_t uart, uint32_t baudrate, char buf, size_t bufsize)
	Initialize AT device struct. More...

int	at_send_cmd_wait_ok (at_dev_t dev, const char command, uint32_t timeout)
	Simple command helper. More...

int	at_send_cmd_wait_prompt (at_dev_t dev, const char command, uint32_t timeout)
	Send AT command, wait for a prompt. More...

ssize_t	at_send_cmd_get_resp (at_dev_t dev, const char command, char *resp_buf, size_t len, uint32_t timeout)
	Send AT command, wait for response. More...

ssize_t	at_send_cmd_get_lines (at_dev_t dev, const char command, char *resp_buf, size_t len, bool keep_eol, uint32_t timeout)
	Send AT command, wait for multiline response. More...

int	at_expect_bytes (at_dev_t dev, const char bytes, uint32_t timeout)
	Expect bytes from device. More...

int	at_recv_bytes_until_string (at_dev_t dev, const char string, char bytes, size_t bytes_len, uint32_t timeout)
	Receives bytes into `bytes` buffer until the string pattern `string` is received or the buffer is full. More...

void	at_send_bytes (at_dev_t dev, const char bytes, size_t len)
	Send raw bytes to a device. More...

ssize_t	at_recv_bytes (at_dev_t dev, char bytes, size_t len, uint32_t timeout)
	Receive raw bytes from a device. More...

int	at_send_cmd (at_dev_t dev, const char command, uint32_t timeout)
	Send command to device. More...

ssize_t	at_readline (at_dev_t dev, char resp_buf, size_t len, bool keep_eol, uint32_t timeout)
	Read a line from device. More...

void	at_drain (at_dev_t *dev)
	Drain device input buffer. More...

void	at_dev_poweron (at_dev_t *dev)
	Power device on. More...

void	at_dev_poweroff (at_dev_t *dev)
	Power device off. More...

void	at_add_urc (at_dev_t dev, at_urc_t urc)
	Add a callback for an unsolicited response code. More...

void	at_remove_urc (at_dev_t dev, at_urc_t urc)
	Remove an unsolicited response code from the list. More...

void	at_process_urc (at_dev_t *dev, uint32_t timeout)
	Process out-of-band data received from the device. More...

Typedef Documentation

◆ at_urc_cb_t

typedef void(* at_urc_cb_t) (void *arg, const char *code)

Unsolicited result code callback.

Parameters

[in]	arg	optional argument
[in]	code	urc string received from the device

Definition at line 171 of file at.h.

Function Documentation

◆ at_add_urc()

void at_add_urc	(	at_dev_t *	dev,
		at_urc_t *	urc
	)

Add a callback for an unsolicited response code.

Parameters

[in]	dev	device to operate on
[in]	urc	unsolicited result code to register

◆ at_dev_init()

int at_dev_init	(	at_dev_t *	dev,
		uart_t	uart,
		uint32_t	baudrate,
		char *	buf,
		size_t	bufsize
	)

Initialize AT device struct.

Parameters

[in]	dev	struct to initialize
[in]	uart	UART the device is connected to
[in]	baudrate	baudrate of the device
[in]	buf	input buffer
[in]	bufsize	size of `buf`

Returns: success code UART_OK on success; error code UART_NODEV or UART_NOBAUD otherwise

◆ at_dev_poweroff()

void at_dev_poweroff ( at_dev_t * dev )

Power device off.

Parameters

[in] dev device to power off

◆ at_dev_poweron()

void at_dev_poweron ( at_dev_t * dev )

Power device on.

Parameters

[in] dev device to power on

◆ at_drain()

void at_drain ( at_dev_t * dev )

Drain device input buffer.

This function drains any possible bytes waiting in the device's input buffer.

Parameters

[in] dev device to operate on

◆ at_expect_bytes()

int at_expect_bytes	(	at_dev_t *	dev,
		const char *	bytes,
		uint32_t	timeout
	)

Expect bytes from device.

Parameters

[in]	dev	device to operate on
[in]	bytes	buffer containing bytes to expect (NULL-terminated)
[in]	timeout	timeout (in usec)

Returns: 0 on success; <0 otherwise

◆ at_process_urc()

void at_process_urc	(	at_dev_t *	dev,
		uint32_t	timeout
	)

Process out-of-band data received from the device.

Parameters

[in]	dev	device to operate on
[in]	timeout	timeout (in usec)

◆ at_readline()

ssize_t at_readline	(	at_dev_t *	dev,
		char *	resp_buf,
		size_t	len,
		bool	keep_eol,
		uint32_t	timeout
	)

Read a line from device.

Parameters

[in]	dev	device to operate on
[in]	resp_buf	buffer to store line
[in]	len	size of `resp_buf`
[in]	keep_eol	true to keep the CR character in the response
[in]	timeout	timeout (in usec)

Returns: line length on success; <0 on error

◆ at_recv_bytes()

ssize_t at_recv_bytes	(	at_dev_t *	dev,
		char *	bytes,
		size_t	len,
		uint32_t	timeout
	)

Receive raw bytes from a device.

Parameters

[in]	dev	device to operate on
[in]	bytes	buffer where store received bytes
[in]	len	maximum number of bytes to receive
[in]	timeout	timeout (in usec) of inactivity to finish read

Returns: Number of bytes read, eventually zero if no bytes available

◆ at_recv_bytes_until_string()

int at_recv_bytes_until_string	(	at_dev_t *	dev,
		const char *	string,
		char *	bytes,
		size_t *	bytes_len,
		uint32_t	timeout
	)

Receives bytes into bytes buffer until the string pattern string is received or the buffer is full.

Parameters

[in]	dev	device to operate on
[in]	string	string pattern to expect
[out]	bytes	buffer to store received bytes
[in,out]	bytes_len	pointer to the maximum number of bytes to receive. On return stores the amount of received bytes.
[in]	timeout	timeout (in usec) of inactivity to finish read

Returns: 0 on success; <0 on error

◆ at_remove_urc()

void at_remove_urc	(	at_dev_t *	dev,
		at_urc_t *	urc
	)

Remove an unsolicited response code from the list.

Parameters

[in]	dev	device to operate on
[in]	urc	unsolicited result code to remove

◆ at_send_bytes()

void at_send_bytes	(	at_dev_t *	dev,
		const char *	bytes,
		size_t	len
	)

Send raw bytes to a device.

Parameters

[in]	dev	device to operate on
[in]	bytes	buffer containing bytes to send
[in]	len	number of bytes to send

◆ at_send_cmd()

int at_send_cmd	(	at_dev_t *	dev,
		const char *	command,
		uint32_t	timeout
	)

Send command to device.

Parameters

[in]	dev	device to operate on
[in]	command	command to send
[in]	timeout	timeout (in usec)

Returns: 0 on success; <0 otherwise

◆ at_send_cmd_get_lines()

ssize_t at_send_cmd_get_lines	(	at_dev_t *	dev,
		const char *	command,
		char *	resp_buf,
		size_t	len,
		bool	keep_eol,
		uint32_t	timeout
	)

Send AT command, wait for multiline response.

This function sends the supplied command, then returns all response lines until the device sends "OK".

If a line starts with "ERROR" or the buffer is full, the function returns -1. If a line starts with "+CME ERROR" or +CMS ERROR", the function returns -2. In this case resp_buf contains the error string.

Parameters

[in]	dev	device to operate on
[in]	command	command to send
[out]	resp_buf	buffer for storing response
[in]	len	len of `resp_buf`
[in]	keep_eol	true to keep the CR character in the response
[in]	timeout	timeout (in usec)

Returns: length of response on success; -1 on error; -2 on CMS or CME error

◆ at_send_cmd_get_resp()

ssize_t at_send_cmd_get_resp	(	at_dev_t *	dev,
		const char *	command,
		char *	resp_buf,
		size_t	len,
		uint32_t	timeout
	)

Send AT command, wait for response.

This function sends the supplied command, then waits and returns one line of response.

A possible empty line will be skipped.

Parameters

[in]	dev	device to operate on
[in]	command	command to send
[out]	resp_buf	buffer for storing response
[in]	len	len of `buffer`
[in]	timeout	timeout (in usec)

Returns: length of response on success; <0 on error

◆ at_send_cmd_wait_ok()

int at_send_cmd_wait_ok	(	at_dev_t *	dev,
		const char *	command,
		uint32_t	timeout
	)

Simple command helper.

This function sends an AT command to the device and waits for "OK".

Parameters

[in]	dev	device to operate on
[in]	command	command string to send
[in]	timeout	timeout (in usec)

Returns: 0 when device answers "OK"; <0 otherwise

◆ at_send_cmd_wait_prompt()

int at_send_cmd_wait_prompt	(	at_dev_t *	dev,
		const char *	command,
		uint32_t	timeout
	)

Send AT command, wait for a prompt.

This function sends the supplied command, then waits for the prompt (>) character and returns

Parameters

[in]	dev	device to operate on
[in]	command	command string to send
[in]	timeout	timeout (in usec)

Returns: 0 when prompt is received; <0 otherwise

Detailed Description

Unsolicited Result Codes (URC)

Modules

Files

Data Structures

Macros

Typedefs

Functions

Typedef Documentation

◆ at_urc_cb_t

Function Documentation

◆ at_add_urc()

◆ at_dev_init()

◆ at_dev_poweroff()

◆ at_dev_poweron()

◆ at_drain()

◆ at_expect_bytes()

◆ at_process_urc()

◆ at_readline()

◆ at_recv_bytes()

◆ at_recv_bytes_until_string()

◆ at_remove_urc()

◆ at_send_bytes()

◆ at_send_cmd()

◆ at_send_cmd_get_lines()

◆ at_send_cmd_get_resp()

◆ at_send_cmd_wait_ok()

◆ at_send_cmd_wait_prompt()