Loading...
Searching...
No Matches
AT (Hayes) command set library

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.

Error reporting

Most DCEs (Data Circuit-terminating Equipment, aka modem) can return extra error information instead of the rather opaque "ERROR" message. They have the form:

For +CME, this behavior is usually off by default and can be toggled with: AT+CMEE=<type> where <type> may be:

Some of the API calls below support detailed error reporting. Whenever they detect extended error responses, -AT_ERR_EXTENDED is returned and <err_code> can be retrieved by calling at_get_err_info().

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...
 
struct  at_dev_init_t
 AT device initialization parameters. More...
 

Macros

#define AT_BUF_SIZE   (1 << CONFIG_AT_BUF_SIZE_EXP)
 Size of buffer used to process unsolicited result code data.
 
#define AT_ERR_EXTENDED   200
 Error cause can be further investigated.
 
#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.
 

Functions

static char const * at_get_err_info (at_dev_t *dev)
 Get extended error information of the last command sent.
 
int at_dev_init (at_dev_t *dev, at_dev_init_t const *init)
 Initialize AT device struct.
 
int at_send_cmd_wait_ok (at_dev_t *dev, const char *command, uint32_t timeout)
 Simple command helper.
 
int at_send_cmd_wait_prompt (at_dev_t *dev, const char *command, uint32_t timeout)
 Send AT command, wait for a prompt.
 
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.
 
ssize_t at_send_cmd_get_resp_wait_ok (at_dev_t *dev, const char *command, const char *resp_prefix, char *resp_buf, size_t len, uint32_t timeout)
 Send AT command, wait for response plus OK.
 
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.
 
int at_expect_bytes (at_dev_t *dev, const char *bytes, uint32_t timeout)
 Expect bytes from device.
 
int at_wait_bytes (at_dev_t *dev, const char *bytes, uint32_t timeout)
 Repeatedly calls at_expect_bytes() until a match or timeout occurs.
 
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.
 
void at_send_bytes (at_dev_t *dev, const char *bytes, size_t len)
 Send raw bytes to a device.
 
ssize_t at_recv_bytes (at_dev_t *dev, char *bytes, size_t len, uint32_t timeout)
 Receive raw bytes from a device.
 
int at_send_cmd (at_dev_t *dev, const char *command, uint32_t timeout)
 Send command to device.
 
int at_parse_resp (at_dev_t *dev, char const *resp)
 Parse a response from the device.
 
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.
 
ssize_t at_readline_skip_empty (at_dev_t *dev, char *resp_buf, size_t len, bool keep_eol, uint32_t timeout)
 Read a line from device, skipping a possibly empty line.
 
int at_wait_ok (at_dev_t *dev, uint32_t timeout)
 Wait for an OK response.
 
void at_drain (at_dev_t *dev)
 Drain device input buffer.
 
void at_dev_poweron (at_dev_t *dev)
 Power device on.
 
void at_dev_poweroff (at_dev_t *dev)
 Power device off.
 
void at_add_urc (at_dev_t *dev, at_urc_t *urc)
 Add a callback for an unsolicited response code.
 
void at_remove_urc (at_dev_t *dev, at_urc_t *urc)
 Remove an unsolicited response code from the list.
 
void at_process_urc (at_dev_t *dev, uint32_t timeout)
 Process out-of-band data received from the device.
 

Macro Definition Documentation

◆ AT_BUF_SIZE

#define AT_BUF_SIZE   (1 << CONFIG_AT_BUF_SIZE_EXP)

Size of buffer used to process unsolicited result code data.

Definition at line 166 of file at.h.

◆ AT_ERR_EXTENDED

#define AT_ERR_EXTENDED   200

Error cause can be further investigated.

Definition at line 190 of file at.h.

◆ AT_SEND_EOL_LEN

#define AT_SEND_EOL_LEN   (sizeof(CONFIG_AT_SEND_EOL) - 1)

Shortcut for getting send end of line length.

Definition at line 193 of file at.h.

Typedef Documentation

◆ at_urc_cb_t

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

Unsolicited result code callback.

Parameters
[in]argoptional argument
[in]codeurc string received from the device

Definition at line 175 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]devdevice to operate on
[in]urcunsolicited result code to register

◆ at_dev_init()

int at_dev_init ( at_dev_t dev,
at_dev_init_t const *  init 
)

Initialize AT device struct.

Parameters
[in]devstruct to initialize
[in]initinit struct, may be destroyed after return
Return values
successcode UART_OK on success
errorcode UART_NODEV or UART_NOBAUD otherwise

◆ at_dev_poweroff()

void at_dev_poweroff ( at_dev_t dev)

Power device off.

Parameters
[in]devdevice to power off

◆ at_dev_poweron()

void at_dev_poweron ( at_dev_t dev)

Power device on.

Parameters
[in]devdevice 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]devdevice 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]devdevice to operate on
[in]bytesbuffer containing bytes to expect (NULL-terminated)
[in]timeouttimeout (in usec)
Return values
0on success
<0otherwise

◆ at_get_err_info()

static char const * at_get_err_info ( at_dev_t dev)
inlinestatic

Get extended error information of the last command sent.

If a previous at_* method returned with -AT_ERR_EXTENDED, you can retrieve a pointer to the error string with this.

Parameters
[in]devdevice to operate on
Return values
stringcontaining the error value.

Definition at line 241 of file at.h.

◆ at_parse_resp()

int at_parse_resp ( at_dev_t dev,
char const *  resp 
)

Parse a response from the device.

This is always called automatically in functions that may return -AT_ERR_EXTENDED. However, if you read the response by other methods (e.g. with at_recv_bytes()), you might want to call this on the response so that you don't have to parse it yourself.

Return values
0if the response is "OK"
-AT_ERR_EXTENDEDif the response is +CMx ERROR: <err>, and <err> has been successfully copied to dev->rp_buf
-1if the response is "ERROR", or +CMx ERROR: <err> but <err> could not be copied
1otherwise

◆ 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]devdevice to operate on
[in]timeouttimeout (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]devdevice to operate on
[in]resp_bufbuffer to store line
[in]lensize of resp_buf
[in]keep_eoltrue to keep the CR character in the response
[in]timeouttimeout (in usec)
Return values
nline length on success
<0on error

◆ at_readline_skip_empty()

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

Read a line from device, skipping a possibly empty line.

Parameters
[in]devdevice to operate on
[in]resp_bufbuffer to store line
[in]lensize of resp_buf
[in]keep_eoltrue to keep the CR character in the response
[in]timeouttimeout (in usec)
Return values
nline length on success
<0on 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]devdevice to operate on
[in]bytesbuffer where store received bytes
[in]lenmaximum number of bytes to receive
[in]timeouttimeout (in usec) of inactivity to finish read
Return values
nNumber 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]devdevice to operate on
[in]stringstring pattern to expect
[out]bytesbuffer to store received bytes
[in,out]bytes_lenpointer to the maximum number of bytes to receive. On return stores the amount of received bytes.
[in]timeouttimeout (in usec) of inactivity to finish read
Return values
0on success
<0on 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]devdevice to operate on
[in]urcunsolicited 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]devdevice to operate on
[in]bytesbuffer containing bytes to send
[in]lennumber 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]devdevice to operate on
[in]commandcommand to send
[in]timeouttimeout (in usec)
Return values
0on success
<0otherwise

◆ 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 contains a DTE error response, this function stops and returns accordingly.

Parameters
[in]devdevice to operate on
[in]commandcommand to send
[out]resp_bufbuffer for storing response
[in]lenlen of resp_buf
[in]keep_eoltrue to keep the CR character in the response
[in]timeouttimeout (in usec)
Return values
nlength of response on success
-AT_ERR_EXTENDEDif failed and a error code can be retrieved with at_get_err_info() (i.e. DCE answered with CMx ERROR)
<0other failures

◆ 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]devdevice to operate on
[in]commandcommand to send
[out]resp_bufbuffer for storing response
[in]lenlen of buffer
[in]timeouttimeout (in usec)
Return values
nlength of response on success
<0on error

◆ at_send_cmd_get_resp_wait_ok()

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

Send AT command, wait for response plus OK.

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

A possible empty line will be skipped.

Parameters
[in]devdevice to operate on
[in]commandcommand to send
[in]resp_prefixexpected prefix in the response
[out]resp_bufbuffer for storing response
[in]lenlen of buffer
[in]timeouttimeout (in usec)
Return values
nlength of response on success
-AT_ERR_EXTENDEDif failed and a error code can be retrieved with at_get_err_info() (i.e. DCE answered with CMx ERROR)
<0other failures

◆ 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]devdevice to operate on
[in]commandcommand string to send
[in]timeouttimeout (in usec)
Return values
0when device answers "OK"
-AT_ERR_EXTENDEDif failed and a error code can be retrieved with at_get_err_info() (i.e. DCE answered with CMx ERROR)
<0other failures

◆ 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]devdevice to operate on
[in]commandcommand string to send
[in]timeouttimeout (in usec)
Return values
0when prompt is received
-AT_ERR_EXTENDEDif failed and a error code can be retrieved with at_get_err_info() (i.e. DCE answered with CMx ERROR)
<0other failures

◆ at_wait_bytes()

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

Repeatedly calls at_expect_bytes() until a match or timeout occurs.

Parameters
[in]devdevice to operate on
[in]bytesbuffer containing bytes to expect (NULL-terminated)
[in]timeouttimeout (in usec)
Return values
0on success
<0otherwise

◆ at_wait_ok()

int at_wait_ok ( at_dev_t dev,
uint32_t  timeout 
)

Wait for an OK response.

Useful when crafting the command-response sequence by yourself.

Parameters
[in]devdevice to operate on
[in]timeouttimeout (in usec)
Return values
0when device answers "OK"
-AT_ERR_EXTENDEDif failed and a error code can be retrieved with at_get_err_info() (i.e. DCE answered with CMx ERROR)
<0other failures