Takaaki Numai / mbed-dev

inport from local

Dependents:   Hobbyking_Cheetah_0511

platform/ATCmdParser.h@0:85b3fd62ea1a, 2020-03-16 (annotated)

Committer:
NYX
Date:
Mon Mar 16 06:35:48 2020 +0000
Revision:
0:85b3fd62ea1a
reinport to mbed;

Who changed what in which revision?

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