Kyle Wengryn / platform

update

ATCmdParser.h@0:bfff72fb3650, 2021-04-08 (annotated)

Committer:
kwengryn3
Date:
Thu Apr 08 16:43:07 2021 +0000
Revision:
0:bfff72fb3650
update;

Who changed what in which revision?

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