AT command parser

The AT command parser is a library which parses any of the following:

  • A string response returned after issuing an AT command

  • An unsolicited event

  • A notification

After parsing the response, notification, or event, the AT command parser extracts the parameters from the string and saves them in a structured list.

The AT parameters storage module is used to store the parameters. Each element in the list is a parameter, identified by a specific type, length, and value. The resulting list can be used by any external module to obtain the value of the parameters. Based on the type of the parameter, you can obtain its value by calling at_params_int_get(), at_params_unsigned_int_get(), at_params_short_get(), at_params_unsigned_short_get(), at_params_array_get(), or at_params_string_get(). The function at_params_size_get() can be used to read the length of a parameter or to check if a parameter exists at a specified index of the list. Probing which type of element is stored on which index can be done using the at_params_type_get().

Before using the AT command parser, you must initialize a list of AT command/response parameters by calling at_params_list_init(). Then, to parse a string, simply pass the returned AT command string to the library function at_parser_params_from_str().

API documentation

Header file: include/modem/at_cmd_parser.h
Source file: lib/at_cmd_parser/src/at_cmd_parser.c
group at_cmd_parser

Basic parser for AT commands.

Enums

enum at_cmd_type

Values:

enumerator AT_CMD_TYPE_UNKNOWN

Unknown command, indicates that the actual command type could not be resolved.

enumerator AT_CMD_TYPE_SET_COMMAND

AT set command.

enumerator AT_CMD_TYPE_READ_COMMAND

AT read command.

enumerator AT_CMD_TYPE_TEST_COMMAND

AT test command.

Functions

int at_parser_max_params_from_str(const char *at_params_str, char **next_param_str, struct at_param_list *const list, size_t max_params_count)

Parse a maximum number of AT command or response parameters from a string.

This function parses the parameters from at_params_str and saves them in list. If there are more parameters than max_params_count, they are ignored.

list must be initialized. It can be reused to parse multiple commands. When calling this function, the list is cleared. The maximum number of AT parameters that can be parsed and stored is limited by the size of list.

If an error is returned by the parser, the content of list should be ignored.

Parameters

  • at_params_str – AT parameters as a null-terminated string. Can be numeric or string parameters.

  • next_param_str – In the case a string contains multiple notifications, the parser will stop parsing when it is done parsing the first notification, and return the remainder of the string in this pointer. The return code will be EAGAIN. If multinotification is not used, this pointer can be set to NULL.

  • list – Pointer to an initialized list where parameters are stored. Must not be NULL.

  • max_params_count – Maximum number of parameters expected in at_params_str. Can be set to a smaller value to parse only some parameters.

Return values

  • 0 – If the operation was successful.

  • -EAGAIN – New notification detected in string re-run the parser with the string pointed to by next_param_str.

  • -E2BIG – The at_param_list supplied cannot hold all detected parameters in string. The list will contain the maximum number of parameters possible.

  • -EINVAL – One or more of the supplied parameters are invalid.

int at_parser_params_from_str(const char *at_params_str, char **next_param_str, struct at_param_list *const list)

Parse AT command or response parameters from a string.

This function parses the parameters from at_params_str and saves them in list.

list must be initialized. It can be reused to parse multiple commands. When calling this function, the list is cleared. The maximum number of AT parameters that can be parsed and stored is limited by the size of list.

If an error is returned by the parser, the content of list should be ignored.

Parameters

  • at_params_str – AT parameters as a null-terminated string. Can be numeric or string parameters.

  • next_param_str – In the case a string contains multiple notifications, the parser will stop parsing when it is done parsing the first notification, and return the remainder of the string in this pointer. The return code will be EAGAIN. If multinotification is not used, this pointer can be set to NULL.

  • list – Pointer to an initialized list where parameters are stored. Must not be NULL.

Return values

  • 0 – If the operation was successful. Otherwise, a (negative) error code is returned.

  • -EAGAIN – New notification detected in string re-run the parser with the string pointed to by next_param_str.

  • -E2BIG – The at_param_list supplied cannot hold all detected parameters in string. The list will contain the maximum number of parameters possible.

  • -EINVAL – One or more of the supplied parameters are invalid.

enum at_cmd_type at_parser_cmd_type_get(const char *at_cmd)

Identify the AT command type.

Parameters

  • at_cmd – [in] A pointer to the AT command string.

Returns

Command type.