Mistake on this page?
Report an issue in GitHub or email us
ATCmdParser.h
1 /* Copyright (c) 2017-2019 ARM Limited
2  * SPDX-License-Identifier: Apache-2.0
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  * @section DESCRIPTION
17  *
18  * Parser for the AT command syntax
19  *
20  */
21 #ifndef MBED_ATCMDPARSER_H
22 #define MBED_ATCMDPARSER_H
23 
24 #include <cstdarg>
25 #include "platform/Callback.h"
26 #include "platform/NonCopyable.h"
27 #include "platform/FileHandle.h"
28 
29 namespace mbed {
30 /** \addtogroup platform-public-api Platform */
31 /** @{*/
32 /**
33  * \defgroup platform_ATCmdParser ATCmdParser class
34  * @{
35  */
36 
37 /**
38  * Parser class for parsing AT commands
39  *
40  * Here are some examples:
41  * @code
42  * UARTSerial serial = UARTSerial(D1, D0);
43  * ATCmdParser at = ATCmdParser(&serial, "\r\n");
44  * int value;
45  * char buffer[100];
46  *
47  * at.send("AT") && at.recv("OK");
48  * at.send("AT+CWMODE=%d", 3) && at.recv("OK");
49  * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value);
50  * at.recv("+IPD,%d:", &value);
51  * at.read(buffer, value);
52  * at.recv("OK");
53  * @endcode
54  */
55 
56 class ATCmdParser : private NonCopyable<ATCmdParser> {
57 private:
58  // File handle
59  // Not owned by ATCmdParser
60  FileHandle *_fh;
61 
62  int _buffer_size;
63  char *_buffer;
64  int _timeout;
65 
66  // Parsing information
67  const char *_output_delimiter;
68  int _output_delim_size;
69  int _oob_cb_count;
70  char _in_prev;
71  bool _dbg_on;
72  bool _aborted;
73 
74  struct oob {
75  unsigned len;
76  const char *prefix;
78  oob *next;
79  };
80  oob *_oobs;
81 
82 public:
83 
84  /**
85  * Constructor
86  *
87  * @param fh A FileHandle to the digital interface, used for AT commands
88  * @param output_delimiter End of command-line termination
89  * @param buffer_size Size of internal buffer for transaction
90  * @param timeout Timeout of the connection
91  * @param debug Turns on/off debug output for AT commands
92  */
93  ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r",
94  int buffer_size = 256, int timeout = 8000, bool debug = false)
95  : _fh(fh), _buffer_size(buffer_size), _oob_cb_count(0), _in_prev(0), _aborted(false), _oobs(NULL)
96  {
97  _buffer = new char[buffer_size];
98  set_timeout(timeout);
99  set_delimiter(output_delimiter);
100  debug_on(debug);
101  }
102 
103  /**
104  * Destructor
105  */
107  {
108  while (_oobs) {
109  struct oob *oob = _oobs;
110  _oobs = oob->next;
111  delete oob;
112  }
113  delete[] _buffer;
114  }
115 
116  /**
117  * Allows timeout to be changed between commands
118  *
119  * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
120  * error if no response is received in `timeout` duration
121  */
122  void set_timeout(int timeout)
123  {
124  _timeout = timeout;
125  }
126 
127  /**
128  * For backward compatibility.
129  * @deprecated Do not use this function. This function has been replaced with set_timeout for consistency.
130  *
131  * Please use set_timeout(int) API only from now on.
132  * Allows timeout to be changed between commands
133  *
134  * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
135  * error if no response is received in `timeout` duration
136  *
137  */
138  MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency")
139  void setTimeout(int timeout)
140  {
141  set_timeout(timeout);
142  }
143 
144  /**
145  * Sets string of characters to use as line delimiters
146  *
147  * @param output_delimiter String of characters to use as line delimiters
148  */
149  void set_delimiter(const char *output_delimiter)
150  {
151  _output_delimiter = output_delimiter;
152  _output_delim_size = strlen(output_delimiter);
153  }
154 
155  /**
156  * For backwards compatibility.
157  * @deprecated Do not use this function. This function has been replaced with set_delimiter for consistency.
158  *
159  * Please use set_delimiter(const char *) API only from now on.
160  * Sets string of characters to use as line delimiters
161  *
162  * @param output_delimiter string of characters to use as line delimiters
163  */
164  MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
165  void setDelimiter(const char *output_delimiter)
166  {
167  set_delimiter(output_delimiter);
168  }
169 
170  /**
171  * Allows traces from modem to be turned on or off
172  *
173  * @param on Set as 1 to turn on traces and 0 to disable traces.
174  */
175  void debug_on(uint8_t on)
176  {
177  _dbg_on = (on) ? 1 : 0;
178  }
179 
180  /**
181  * For backward compatibility.
182  * @deprecated Do not use this function. This function has been replaced with debug_on for consistency.
183  *
184  * Allows traces from modem to be turned on or off
185  *
186  * @param on Set as 1 to turn on traces and 0 to disable traces.
187  */
188  MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency")
189  void debugOn(uint8_t on)
190  {
191  debug_on(on);
192  }
193 
194  /**
195  * Sends an AT command
196  *
197  * Sends a formatted command using printf style formatting
198  * @see printf
199  *
200  * @param command printf-like format string of command to send which
201  * is appended with a newline
202  * @param ... all printf-like arguments to insert into command
203  * @return true only if command is successfully sent
204  */
205  bool send(const char *command, ...) MBED_PRINTF_METHOD(1, 2);
206 
207  bool vsend(const char *command, std::va_list args);
208 
209  /**
210  * Receive an AT response
211  *
212  * Receives a formatted response using scanf style formatting
213  * @see scanf
214  *
215  * Responses are parsed line at a time.
216  * Any received data that does not match the response is ignored until
217  * a timeout occurs.
218  *
219  * @param response scanf-like format string of response to expect
220  * @param ... all scanf-like arguments to extract from response
221  * @return true only if response is successfully matched
222  */
223  bool recv(const char *response, ...) MBED_SCANF_METHOD(1, 2);
224 
225  bool vrecv(const char *response, std::va_list args);
226 
227  /**
228  * Write a single byte to the underlying stream
229  *
230  * @param c The byte to write
231  * @return The byte that was written or -1 during a timeout
232  */
233  int putc(char c);
234 
235  /**
236  * Get a single byte from the underlying stream
237  *
238  * @return The byte that was read or -1 during a timeout
239  */
240  int getc();
241 
242  /**
243  * Write an array of bytes to the underlying stream
244  *
245  * @param data The array of bytes to write
246  * @param size Number of bytes to write
247  * @return number of bytes written or -1 on failure
248  */
249  int write(const char *data, int size);
250 
251  /**
252  * Read an array of bytes from the underlying stream
253  *
254  * @param data The buffer for filling the read bytes
255  * @param size Number of bytes to read
256  * @return number of bytes read or -1 on failure
257  */
258  int read(char *data, int size);
259 
260  /**
261  * Direct printf to underlying stream
262  * @see printf
263  *
264  * @param format Format string to pass to printf
265  * @param ... Variable arguments to printf
266  * @return number of bytes written or -1 on failure
267  */
268  int printf(const char *format, ...) MBED_PRINTF_METHOD(1, 2);
269 
270  int vprintf(const char *format, std::va_list args);
271 
272  /**
273  * Direct scanf on underlying stream
274  * This function does not itself match whitespace in its format string, so \n is not significant to it.
275  * It should be used only when certain string is needed or format ends with certain character, otherwise
276  * it will fill the output with one character.
277  * @see scanf
278  *
279  * @param format Format string to pass to scanf
280  * @param ... Variable arguments to scanf
281  * @return number of bytes read or -1 on failure
282  */
283  int scanf(const char *format, ...) MBED_SCANF_METHOD(1, 2);
284 
285  int vscanf(const char *format, std::va_list args);
286 
287  /**
288  * Attach a callback for out-of-band data
289  *
290  * @param prefix String on when to initiate callback
291  * @param func Callback to call when string is read
292  * @note out-of-band data is only processed during a scanf call
293  */
294  void oob(const char *prefix, mbed::Callback<void()> func);
295 
296  /**
297  * Flushes the underlying stream
298  */
299  void flush();
300 
301  /**
302  * Abort current recv
303  *
304  * Can be called from out-of-band handler to interrupt the current
305  * recv operation.
306  */
307  void abort();
308 
309  /**
310  * Process out-of-band data
311  *
312  * Process out-of-band data in the receive buffer. This function
313  * returns immediately if there is no data to process.
314  *
315  * @return true if out-of-band data processed, false otherwise
316  */
317  bool process_oob(void);
318 };
319 
320 /**@}*/
321 
322 /**@}*/
323 
324 } //namespace mbed
325 
326 #endif //MBED_ATCMDPARSER_H
void debug_on(uint8_t on)
Allows traces from modem to be turned on or off.
Definition: ATCmdParser.h:175
void setTimeout(int timeout)
For backward compatibility.
Definition: ATCmdParser.h:139
int getc()
Get a single byte from the underlying stream.
void set_timeout(int timeout)
Allows timeout to be changed between commands.
Definition: ATCmdParser.h:122
int scanf(const char *format,...) MBED_SCANF_METHOD(1
Direct scanf on underlying stream This function does not itself match whitespace in its format string...
Class FileHandle.
Definition: FileHandle.h:46
int putc(char c)
Write a single byte to the underlying stream.
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:169
void abort()
Abort current recv.
ATCmdParser(FileHandle *fh, const char *output_delimiter="\r", int buffer_size=256, int timeout=8000, bool debug=false)
Constructor.
Definition: ATCmdParser.h:93
void oob(const char *prefix, mbed::Callback< void()> func)
Attach a callback for out-of-band data.
bool recv(const char *response,...) MBED_SCANF_METHOD(1
Receive an AT response.
void debugOn(uint8_t on)
For backward compatibility.
Definition: ATCmdParser.h:189
int write(const char *data, int size)
Write an array of bytes to the underlying stream.
void set_delimiter(const char *output_delimiter)
Sets string of characters to use as line delimiters.
Definition: ATCmdParser.h:149
~ATCmdParser()
Destructor.
Definition: ATCmdParser.h:106
void flush()
Flushes the underlying stream.
Parser class for parsing AT commands.
Definition: ATCmdParser.h:56
static void debug(const char *format,...) MBED_PRINTF(1
Output a debug message.
Definition: mbed_debug.h:44
bool process_oob(void)
Process out-of-band data.
int read(char *data, int size)
Read an array of bytes from the underlying stream.
int printf(const char *format,...) MBED_PRINTF_METHOD(1
Direct printf to underlying stream.
bool send(const char *command,...) MBED_PRINTF_METHOD(1
Sends an AT command.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
void setDelimiter(const char *output_delimiter)
For backwards compatibility.
Definition: ATCmdParser.h:165
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.