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¶
include/modem/at_cmd.h
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
Functions
-
int
at_cmd_init
(void)¶ Initialize or recover the AT command driver.
- Returns
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).
- Returns 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).
- Returns -ENOBUFS
is returned if AT_CMD_RESPONSE_MAX_LEN is not large enough to hold the data returned from the modem.
- Returns -ENOEXEC
is returned if the modem returned ERROR.
- Returns -ENOMEM
is returned if allocation of callback worker failed.
- Returns -EIO
is returned if the function failed to send the command.
- Returns -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
andbuf
parameters in order to save RAM. The function will not modifybuf
contents until the entirecmd
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.
- Returns 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).
- Returns -ENOBUFS
is returned if AT_CMD_RESPONSE_MAX_LEN is not large enough to hold the data returned from the modem.
- Returns -ENOEXEC
is returned if the modem returned ERROR.
- Returns -EMSGSIZE
is returned if the supplied buffer is to small or NULL.
- Returns -EIO
is returned if the function failed to send the command.
- Returns -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.
-
typedef void (*