Nicolas Borla / Mbed OS BBR_1Ebene

BBR 1 Ebene

mbed-os/platform/ATCmdParser.h@0:fbdae7e6d805, 2018-05-14 (annotated)

Committer:
borlanic
Date:
Mon May 14 11:29:06 2018 +0000
Revision:
0:fbdae7e6d805
BBR

Who changed what in which revision?

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