Kev Mann / mbed-dev-OS5_10_4

RTC auf true

platform/ATCmdParser.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

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