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