AT parser

The AT parser is a library that parses AT command responses, notifications, and events.

Overview 

The library exports an API that lets the user iterate through an AT command string and retrieve any of its elements based on their indices, efficiently and without heap allocations. Under the hood, this library uses regular expressions converted to deterministic finite automata by the free and open-source lexer generator re2c.

Configuration 

To begin using the AT parser, you first need to initialize it. This is done by invoking the at_parser_init() function, where you provide a pointer to the AT parser and the AT command string that needs to be parsed.

The following code snippet shows how to initialize the AT parser for an AT command response:

int err;
struct at_parser parser;
const char *at_response = "+CFUN: 1";

err = at_parser_init(&parser, at_response);
if (err) {
   return err;
}

Usage 

Based on the type of the element at a given index, you can obtain its value by calling the type-generic macro at_parser_num_get for integer values, or the function at_params_string_get() for string values.

The following code snippet shows how to retrieve the prefix, a uint16_t value, and a string value from an AT command response using the AT parser:

int err;
struct at_parser parser;
const char *at_response = "+CGCONTRDP: 0,,\"internet\",\"\",\"\",\"10.0.0.1\",\"10.0.0.2\",,,,,1028";
uint16_t num;
char buffer[16] = { 0 };
size_t len = sizeof(buffer);

err = at_parser_init(&parser, at_response);
if (err) {
   return err;
}

/* Retrieve the AT command response prefix, at index 0 of the AT command string. */
err = at_parser_string_get(&parser, 0, buffer, &len);
if (err) {
   return err;
}

/* "Prefix: `+CGCONTRDP`" */
printk("Prefix: `%s`\n", buffer);

/* Retrieve the first subparameter, at index 1 of the AT command string.
 * `at_parser_num_get` is a type-generic macro that retrieves an integer based on the type
 * of the passed variable. In this example, the preprocessor will expand the macro to the
 * function corresponding to the `uint16_t` type, which is the function `at_parser_uint16_get`.
 */
err = at_parser_num_get(&parser, 1, &num);
if (err) {
   return err;
}

/* "First subparameter: 0" */
printk("First subparameter: %u\n", num);

/* Reset the buffer length. */
len = sizeof(buffer);

/* Retrieve the third subparameter, at index 3 of the AT command string. */
err = at_parser_string_get(&parser, 3, buffer, &len);
if (err) {
   return err;
}

/* "Third subparameter: `internet`" */
printk("Third subparameter: `%s`\n", buffer);

API documentation 

Header file: include/modem/at_parser.h

Source file: lib/at_parser/src/at_parser.c

group at_parser

Parser for AT commands and notifications.

Defines

at_parser_num_get(parser, index, value)

Type-generic macro for getting an integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

Enums

enum at_parser_cmd_type

Identifies the type of a given AT command prefix.

Values:

enumerator AT_PARSER_CMD_TYPE_UNKNOWN: Unknown command, indicates that the actual command type could not be resolved.

enumerator AT_PARSER_CMD_TYPE_SET: AT set command.

enumerator AT_PARSER_CMD_TYPE_READ: AT read command.

enumerator AT_PARSER_CMD_TYPE_TEST: AT test command.

Functions

int at_parser_init(struct at_parser *parser, const char *at)

Initialize an AT parser for a given AT command string.

Parameters:

parser – [in] A pointer to the AT parser.
at – [in] A pointer to the AT command string to parse.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.

int at_parser_cmd_next(struct at_parser *parser)

Move the cursor of an AT parser to the next command line of its configured AT command string.

It is possible to call this function successfully with a given AT parser if and only if its configured AT command string has multiple lines and its current line is not the last one.

Parameters:

parser – [in] A pointer to the AT parser.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – The cursor cannot move to the next line. This error occurs if there is no next line to move to or the configured AT command string is malformed.

int at_parser_cmd_type_get(struct at_parser *parser, enum at_parser_cmd_type *type)

Get the type of the command prefix in the current AT command line.

Parameters:

parser – [in] A pointer to the AT parser.
type – [out] A pointer to the AT command prefix type.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the given AT command line.

int at_parser_cmd_count_get(struct at_parser *parser, size_t *count)

Get the number of values that exist in the current AT command line.

Parameters:

parser – [in] A pointer to the AT parser.
count – [out] A pointer to the number of parsed values.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EBADMSG – The AT command string is malformed.

int at_parser_int16_get(struct at_parser *parser, size_t index, int16_t *value)

Get a signed 16-bit integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_uint16_get(struct at_parser *parser, size_t index, uint16_t *value)

Get an unsigned 16-bit integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_int32_get(struct at_parser *parser, size_t index, int32_t *value)

Get a signed 32-bit integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_uint32_get(struct at_parser *parser, size_t index, uint32_t *value)

Get an unsigned 32-bit integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_int64_get(struct at_parser *parser, size_t index, int64_t *value)

Get a signed 64-bit integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_uint64_get(struct at_parser *parser, size_t index, uint64_t *value)

Get an unsigned 64-bit integer value.

Parameters:

parser – [in] AT parser.
index – [in] Subparameter index in the current AT command line configured in parser.
value – [out] Subparameter value.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ERANGE – Parsed integer value is out of range for the expected type.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_string_get(struct at_parser *parser, size_t index, char *str, size_t *len)

Get a string value.

The data type must be a string (quoted or non-quoted), an AT command prefix, or an array, otherwise an error is returned. The string value is copied to the buffer and null-terminated. len must be at least string length plus one, or an error is returned.

Parameters:

parser – [in] AT parser.
index – [in] Index in the current AT command line configured in parser.
str – [in] Pointer to the buffer where to copy the value.
len – [inout] Available space in str, returns the length of the copied string.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the type of value at the given index.
-ENOMEM – str is smaller than the null-terminated string to be copied.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

int at_parser_string_ptr_get(struct at_parser *parser, size_t index, const char **str_ptr, size_t *len)

Get a pointer to a string value.

The data type must be a string (quoted or non-quoted), an AT command prefix, or an array, otherwise an error is returned.

Parameters:

parser – [in] AT parser.
index – [in] Index in the current AT command line configured in parser.
str_ptr – [out] Pointer to the address of the string.
len – [out] Length of the string.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-EINVAL – One or more of the supplied parameters are invalid.
-EPERM – parser has not been initialized.
-EOPNOTSUPP – Operation not supported for the subparameter type at the given index.
-EBADMSG – The AT command string is malformed.
-EAGAIN – Parsing of the current AT command line is terminated and a subsequent line is available. Returned when index is greater than the maximum index for the current AT command line.
-EIO – There is nothing more to parse in the AT command string configured in parser. Returned when index is greater than the maximum index for the current AT command line.

struct at_parser

#include <at_parser.h>

AT parser.

Holds the parsing state for a configured AT command string.

AT parser

Overview

Configuration

Usage

API documentation

Overview 

Configuration 

Usage 

API documentation 