-
Notifications
You must be signed in to change notification settings - Fork 305
/
nrf_modem_at.h
270 lines (249 loc) · 9.16 KB
/
nrf_modem_at.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
/*
* Copyright (c) 2021 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
*/
/**
* @file nrf_modem_at.h
*
* @defgroup nrf_modem_at AT commands interface
* @{
* @brief Modem library AT commands interface.
*/
#ifndef NRF_MODEM_AT_H__
#define NRF_MODEM_AT_H__
#include <stddef.h>
#include <stdbool.h>
#ifdef __cplusplus
extern "C" {
#endif
/** @brief Modem response type for 'ERROR' responses. */
#define NRF_MODEM_AT_ERROR 1
/** @brief Modem response type for '+CME ERROR' responses. */
#define NRF_MODEM_AT_CME_ERROR 2
/** @brief Modem response type for '+CMS ERROR' responses. */
#define NRF_MODEM_AT_CMS_ERROR 3
/**
* @brief AT Notification handler prototype.
*
* @note This handler is executed in an interrupt service routine.
* Offload any intensive operation as necessary.
*
* @param notif The AT notification.
*/
typedef void (*nrf_modem_at_notif_handler_t)(const char *notif);
/**
* @brief AT CFUN handler prototype.
*
* @param mode CFUN mode.
*/
typedef void (*nrf_modem_at_cfun_handler_t)(int mode);
/**
* @brief Set a handler function for AT notifications.
*
* @note The callback is executed in an interrupt service routine.
* Take care to offload any processing as appropriate.
*
* @param callback The AT notification callback. Use @c NULL to unset handler.
*
* @retval 0 On success.
*/
int nrf_modem_at_notif_handler_set(nrf_modem_at_notif_handler_t callback);
/**
* @brief Set a handler function for CFUN AT commands.
*
* @note The handler is executed after the CFUN command is successfully processed by the modem.
*
* @param handler The CFUN handler. Use @c NULL to unset handler.
*/
void nrf_modem_at_cfun_handler_set(nrf_modem_at_cfun_handler_t handler);
/**
* @brief Send a formatted AT command to the modem.
*
* Supports all format specifiers of printf() as implemented by the selected C library.
* This function can return a negative value, zero or a positive value.
*
* @param fmt Command format.
* @param ... Format arguments.
*
* @retval 0 On "OK" responses.
* @returns A positive value On "ERROR", "+CME ERROR", and "+CMS ERROR" responses.
* The type of error can be distinguished using @c nrf_modem_at_err_type.
* The error value can be retrieved using @c nrf_modem_at_err.
* @retval -NRF_EPERM The Modem library is not initialized.
* @retval -NRF_EFAULT @c fmt is @c NULL.
* @retval -NRF_EINVAL Bad format @c fmt.
* @retval -NRF_EAGAIN Timed out while waiting for another AT command to complete.
* @retval -NRF_ENOMEM Not enough shared memory for this request.
* @retval -NRF_ESHUTDOWN If modem was shut down.
*/
int nrf_modem_at_printf(const char *fmt, ...);
/**
* @brief Send an AT command to the modem and read the formatted response
* into the supplied argument list.
*
* Supports all the format specifiers of scanf() as implemented by the selected C library.
* This function does not support retrieving the modem response beyond reading
* the formatted response into the argument list.
*
* @param cmd AT command.
* @param fmt Response format.
* @param ... Variable argument list.
*
* @returns The number of arguments matched.
* @retval -NRF_EPERM The Modem library is not initialized.
* @retval -NRF_EFAULT @c cmd or @c fmt are @c NULL.
* @retval -NRF_EBADMSG No arguments were matched.
* @retval -NRF_EAGAIN Timed out while waiting for another AT command to complete.
* @retval -NRF_ENOMEM Not enough shared memory for this request.
* @retval -NRF_ESHUTDOWN If the modem was shut down.
*/
int nrf_modem_at_scanf(const char *cmd, const char *fmt, ...);
/**
* @brief Send a formatted AT command to the modem
* and receive the response into the supplied buffer.
*
* @param buf Buffer to receive the response into.
* @param len Buffer length.
* @param fmt Command format.
* @param ... Format arguments.
*
* @retval 0 On "OK" responses.
* @returns A positive value On "ERROR", "+CME ERROR", and "+CMS ERROR" responses.
* The type of error can be distinguished using @c nrf_modem_at_err_type.
* The error value can be retrieved using @c nrf_modem_at_err.
* @retval -NRF_EPERM The Modem library is not initialized.
* @retval -NRF_EFAULT @c buf or @c fmt are @c NULL.
* @retval -NRF_EINVAL Bad format @c fmt, or @c len is zero.
* @retval -NRF_EAGAIN Timed out while waiting for another AT command to complete.
* @retval -NRF_ENOMEM Not enough shared memory for this request.
* @retval -NRF_E2BIG The response is larger than the supplied buffer @c buf.
* @retval -NRF_ESHUTDOWN If the modem was shut down.
*/
int nrf_modem_at_cmd(void *buf, size_t len, const char *fmt, ...);
/**
* @brief AT response handler prototype.
*
* @note This handler is executed in an interrupt service routine.
* Offload any intensive operations as necessary.
*
* @param resp The AT command response.
*/
typedef void (*nrf_modem_at_resp_handler_t)(const char *resp);
/**
* @brief Send a formatted AT command to the modem
* and receive the response asynchronously via a callback.
*
* This function waits for the Modem to acknowledge the AT command
* but will return without waiting for the command execution.
*
* @note The callback is executed in an interrupt context.
* Take care to offload any processing as appropriate.
*
* @param callback Callback to receive the response.
* @param fmt Command format.
* @param ... Format arguments.
*
* @retval 0 On "OK" responses.
* @retval -NRF_EPERM The Modem library is not initialized.
* @retval -NRF_EFAULT @c callback or @c fmt are @c NULL.
* @retval -NRF_EINVAL Bad format @c fmt.
* @retval -NRF_EINPROGRESS Another AT command is executing.
* @retval -NRF_ENOMEM Not enough shared memory for this request.
* @retval -NRF_ESHUTDOWN If the modem was shut down.
*/
int nrf_modem_at_cmd_async(nrf_modem_at_resp_handler_t callback, const char *fmt, ...);
/** @brief AT command handler prototype.
*
* Implements a custom AT command in the application.
*
* @param buf Buffer to receive the response into.
* @param len Buffer length.
* @param at_cmd AT command.
*
* @retval 0 On "OK" responses.
* @returns A positive value On "ERROR", "+CME ERROR", and "+CMS ERROR" responses.
* The type of error can be distinguished using @c nrf_modem_at_err_type.
* The error value can be retrieved using @c nrf_modem_at_err.
* @retval -NRF_EPERM The Modem library is not initialized.
* @retval -NRF_EFAULT @c buf or @c fmt are @c NULL.
* @retval -NRF_ENOMEM Not enough shared memory for this request.
* @retval -NRF_E2BIG The response is larger than the supplied buffer @c buf.
*/
typedef int (*nrf_modem_at_cmd_custom_handler_t)(char *buf, size_t len, char *at_cmd);
/**
* @brief Custom AT command.
*
* Application-defined AT command implementation.
*/
struct nrf_modem_at_cmd_custom {
/** The AT command to implement. */
const char * const cmd;
/** The function implementing the AT command. */
const nrf_modem_at_cmd_custom_handler_t callback;
};
/**
* @brief Set a list of custom AT commands that are implemented in the application.
*
* When a custom AT command list is set, AT commands sent via @c nrf_modem_at_cmd that match any
* AT command in the list, will be redirected to the custom callback function instead
* of being sent to the modem.
*
* @note The custom commands are disabled by passing NULL to the @c custom_commands and
* 0 to the @c len.
*
* @param custom_commands List of custom AT commands.
* @param len Custom AT command list size.
*
* @retval 0 On success.
* @retval -NRF_EINVAL On invalid parameters.
*/
int nrf_modem_at_cmd_custom_set(struct nrf_modem_at_cmd_custom *custom_commands, size_t len);
/**
* @brief Configure how long to wait for ongoing AT commands to complete when sending AT commands.
*
* AT commands are executed one at a time. While one AT command is being executed, the other
* AT commands wait on a semaphore for the ongoing AT command to complete.
*
* This function configures how long @c nrf_modem_at_printf, @c nrf_modem_at_scanf and
* @c nrf_modem_at_cmd will wait for ongoing AT commands to complete.
*
* By default, the timeout is infinite.
*
* @param timeout_ms Timeout in milliseconds. Use NRF_MODEM_OS_FOREVER for infinite timeout
* or NRF_MODEM_OS_NO_WAIT for no timeout.
*
* @return int Zero on success, a negative errno otherwise.
*/
int nrf_modem_at_sem_timeout_set(int timeout_ms);
/**
* @brief Return the error type represented by the return value of
* @c nrf_modem_at_printf and @c nrf_modem_at_cmd.
*
* @param error The return value of @c nrf_modem_at_printf or @c nrf_modem_at_cmd.
*
* @retval NRF_MODEM_AT_ERROR If the modem response was 'ERROR'.
* @retval NRF_MODEM_AT_CME_ERROR If the modem response was '+CME ERROR'.
* @retval NRF_MODEM_AT_CMS_ERROR If the modem response was '+CMS ERROR'.
*/
static inline int nrf_modem_at_err_type(int error)
{
return (error & 0x00ff0000) >> 16;
}
/**
* @brief Retrieve the specific CME or CMS error from the return value of
* a @c nrf_modem_at_printf or @c nrf_modem_at_cmd call.
*
* @param error The return value of a @c nrf_modem_at_printf or @c nrf_modem_at_cmd call.
*
* @returns int The CME or CMS error code.
*/
static inline int nrf_modem_at_err(int error)
{
return (error & 0xff00ffff);
}
#ifdef __cplusplus
}
#endif
#endif /* NRF_MODEM_AT_H__ */
/** @} */