Elijah Stanger-Jones / mbed-dev-f303

test

platform/ATCmdParser.h@2:4364577b5ad8, 2020-11-09 (annotated)

Committer:
elijahsj
Date:
Mon Nov 09 00:33:19 2020 -0500
Revision:
2:4364577b5ad8
Parent:
1:8a094db1347f 
copied mbed library

Who changed what in which revision?

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