mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

platform/ATCmdParser.h@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

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