AT command interface

The socket interface has a global limitation of 8 socket instances that can be open at the same time. So if an application need multiple socket protocols TCP, UDP, TLS, AT, etc, the available 8 socket instances will be a limiting factor. The AT command interface driver is designed to let multiple “clients”, ie. threads, software modules/components to share one AT socket instance.

The AT command driver will always parse the return code, if any (non notification data) from the modem, ie. OK, ERROR, +CMS/+CME codes and remove it from the string returned to the user. The return codes are returned as error codes in the return code of the write function and also through the state parameter that can be supplied. The state parameter must be used to differentiate between +CMS and +CME errors as the error codes is overlapping. Any subsequent write from other threads will be queued until all data (return code + any payload) from the previous write is returned to the caller. This is to make sure that the correct thread gets the correct data and return code as there is no way to separate two “sessions” apart. The kernel thread priority scheme will decide which thread will get write access if multiple threads are queued.

There are two schemes for how immediately returned data from the modem is delivered to the user, for instance from an AT+CNUM command. The user can either submit a reference to a string buffer or a reference to a handler function in the write function. In the case of the user string buffer, the driver will remove the return code and then deliver the rest of the string in the buffer if it’s large enough. Data will only be returned to the user if the return code is OK.

In the case of a handler function, the return will be removed and the rest of the string will delivered to the handler function through a char pointer parameter. Allocation and deallocation of the buffer is handled by the driver, and the content should not be considered valid outside of the handler. Both schemes are limited to the maximum reception size defined by CONFIG_AT_CMD_RESPONSE_MAX_LEN.

Notifications are always handled by a callback function and is separate from the one used to handle data returned immediately after sending a command. This callback is set by @ref at_cmd_set_notification_handler.

API documentation

Header file: include/at_cmd.h
Source file: lib/at_cmd.c
group at_cmd

Public APIs for the AT command interface driver.

Typedefs

typedef void (*at_cmd_handler_t)(char *response)

at_cmd_handler_t

Because this driver let multiple threads share the same socket, it must make sure that the correct thread gets the correct data returned from the AT interface. The at_cmd_write_with_callback() function let the user specify the handler that will process the data from a specific AT command call. Notifications will be handled by the global handler defined using the at_cmd_set_notification_handler() function. Both handlers are of the type at_cmd_handler_t.

Parameters
  • response: Null terminated string containing the modem message

Enums

enum at_cmd_state

AT command return codes.

Values:

AT_CMD_OK
AT_CMD_ERROR
AT_CMD_ERROR_CMS
AT_CMD_ERROR_CME
AT_CMD_NOTIFICATION

Functions

int at_cmd_init(void)

Initialize AT command driver.

Return

Zero on success, non-zero otherwise.

int at_cmd_write_with_callback(const char *const cmd, at_cmd_handler_t handler, enum at_cmd_state *state)

Function to send an AT command to the modem, any data from the modem will trigger the callback defined by the handler parameter in the function prototype.

Parameters
  • cmd: Pointer to null terminated AT command string.

  • handler: Pointer to handler that will process any returned data. NULL pointer is allowed, which means that any returned data will not processed other than the return code (OK, ERROR, CMS or CME).

  • state: Pointer to enum at_cmd_state variable that can hold the error state returned by the modem. If the return state is a CMS or CME errors will the error code be returned in the the function return code as a positive value. NULL pointer is allowed.

Return Value
  • 0: If command execution was successful (same as OK returned from modem). Error codes returned from the driver or by the socket are returned as negative values, CMS and CME errors are returned as positive values, the state parameter will indicate if it’s a CME or CMS error. ERROR will return ENOEXEC (positve).

  • -ENOBUFS: is returned if AT_CMD_RESPONSE_MAX_LEN is not large enough to hold the data returned from the modem.

  • ENOEXEC: is returned if the modem returned ERROR.

  • -ENOMEM: is returned if allocation of callback worker failed.

  • -EIO: is returned if the function failed to send the command.

int at_cmd_write(const char *const cmd, char *buf, size_t buf_len, enum at_cmd_state *state)

Function to send an AT command and receive response immediately.

This function should be used if the response from the modem should be returned in a user supplied buffer. This function will return an empty buffer if nothing is returned by the modem.

Note

It is allowed to use the same buffer for both, cmd and buf parameters in order to save RAM. The function will not modify buf contents until the entire cmd is sent.

Parameters
  • cmd: Pointer to null terminated AT command string

  • buf: Buffer to put the response in. NULL pointer is allowed, see behaviour explanation for buf_len equals 0.

  • buf_len: Length of response buffer. 0 length is allowed and will send the command, process the return code from the modem, but any returned data will be dropped.

  • state: Pointer to enum at_cmd_state variable that can hold the error state returned by the modem. If the return state is a CMS or CME errors will the error code be returned in the the function return code as a positive value. NULL pointer is allowed.

Return Value
  • 0: If command execution was successful (same as OK returned from modem). Error codes returned from the driver or by the socket are returned as negative values, CMS and CME errors are returned as positive values, the state parameter will indicate if it’s a CME or CMS error. ERROR will return ENOEXEC (positve).

  • -ENOBUFS: is returned if AT_CMD_RESPONSE_MAX_LEN is not large enough to hold the data returned from the modem.

  • ENOEXEC: is returned if the modem returned ERROR.

  • -EMSGSIZE: is returned if the supplied buffer is to small or NULL.

  • -EIO: is returned if the function failed to send the command.

void at_cmd_set_notification_handler(at_cmd_handler_t handler)

Function to set AT command global notification handler.

Parameters
  • handler: Pointer to a received notification handler function of type at_cmd_handler_t.