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@189:f392fc9709a3, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 22:31:08 2019 +0000
Revision:
189:f392fc9709a3
Parent:
188:bcfe06ba3d64 
mbed library release version 165

Who changed what in which revision?

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