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 needs multiple socket protocols like TCP, UDP, TLS, AT, and so on, the available 8 socket instances become a limiting factor. The AT command interface is designed to let multiple threads share a single AT socket instance.

The AT command interface always parses the return code from the modem. Non-notification data such as OK, ERROR, and +CMS/+CME is removed from the string that is returned to the user. The return codes are returned as error codes in the return code of the write functions (at_cmd_write() and at_cmd_write_with_callback()) 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 are overlapping. Any subsequent writes from other threads are queued until all the 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, because it is not possible to distinguish between two separate sessions. The kernel thread priority scheme determines the thread to get write access if multiple threads are queued.

There are two schemes by which data returned immediately from the modem (for instance, the modem response for an AT+CNUM command) is delivered to the user. The user can call the write function by submitting either of the following input parameters in the write function:

• A reference to a string buffer

• A reference to a handler function

In the case of a string buffer, the AT command interface removes the return code and then delivers the rest of the string in the buffer if the buffer is large enough. Data is returned to the user if the return code is OK.

In the case of a handler function, the return code is removed and the rest of the string is delivered to the handler function through a char pointer parameter. Allocation and deallocation of the buffer is handled by the AT command interface, 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. This callback function is separate from the one that is used to handle data returned immediately after sending a command. This callback is set by at_cmd_set_notification_handler().

API documentation

Header file: include/modem/at_cmd.h

Source file: lib/at_cmd/at_cmd.c

group at_cmd

Public APIs for the AT command interface driver.

Typedefs

typedef void (*at_cmd_handler_t)(const char *response)

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:

enumerator AT_CMD_OK

enumerator AT_CMD_ERROR

enumerator AT_CMD_ERROR_CMS

enumerator AT_CMD_ERROR_CME

enumerator AT_CMD_ERROR_QUEUE

enumerator AT_CMD_ERROR_WRITE

enumerator AT_CMD_ERROR_READ

enumerator AT_CMD_NOTIFICATION

Functions

int at_cmd_init(void)

Initialize or recover the 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)

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.

Note

The handler function runs from at_cmd’s thread. It must not call at_cmd_write, as that would lead to a deadlock.

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).

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.

• -EHOSTDOWN: is returned if the Modem library is shutdown.

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.

• -EHOSTDOWN: is returned if the Modem library is shutdown.

void at_cmd_set_notification_handler(at_cmd_handler_t handler)

Function to set AT command global notification handler.

Note

The handler function runs from at_cmd’s thread. It must not call at_cmd_write, as that would lead to a deadlock.

Parameters

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