mbed official / mbed-dev

mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

platform/ATCmdParser.h@178:79309dc6340a, 2017-11-23 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 23 11:57:25 2017 +0000
Revision:
178:79309dc6340a
Parent:
176:447f873cad2f
Child:
184:08ed48f1de7f
mbed-dev library. Release version 156

Who changed what in which revision?

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