mbed library sources. Supersedes mbed-src.

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

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

Who changed what in which revision?

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