update
Embed:
(wiki syntax)
Show/hide line numbers
ATCmdParser.h
00001 /* Copyright (c) 2017 ARM Limited 00002 * SPDX-License-Identifier: Apache-2.0 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 * 00016 * @section DESCRIPTION 00017 * 00018 * Parser for the AT command syntax 00019 * 00020 */ 00021 #ifndef MBED_ATCMDPARSER_H 00022 #define MBED_ATCMDPARSER_H 00023 00024 #include <cstdarg> 00025 #include "Callback.h" 00026 #include "NonCopyable.h" 00027 #include "FileHandle.h" 00028 00029 namespace mbed { 00030 00031 /** \addtogroup platform */ 00032 /** @{*/ 00033 /** 00034 * \defgroup platform_ATCmdParser ATCmdParser class 00035 * @{ 00036 */ 00037 00038 /** 00039 * Parser class for parsing AT commands 00040 * 00041 * Here are some examples: 00042 * @code 00043 * UARTSerial serial = UARTSerial(D1, D0); 00044 * ATCmdParser at = ATCmdParser(&serial, "\r\n"); 00045 * int value; 00046 * char buffer[100]; 00047 * 00048 * at.send("AT") && at.recv("OK"); 00049 * at.send("AT+CWMODE=%d", 3) && at.recv("OK"); 00050 * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value); 00051 * at.recv("+IPD,%d:", &value); 00052 * at.read(buffer, value); 00053 * at.recv("OK"); 00054 * @endcode 00055 */ 00056 00057 class ATCmdParser : private NonCopyable<ATCmdParser> { 00058 private: 00059 // File handle 00060 // Not owned by ATCmdParser 00061 FileHandle *_fh; 00062 00063 int _buffer_size; 00064 char *_buffer; 00065 int _timeout; 00066 00067 // Parsing information 00068 const char *_output_delimiter; 00069 int _output_delim_size; 00070 int _oob_cb_count; 00071 char _in_prev; 00072 bool _dbg_on; 00073 bool _aborted; 00074 00075 struct oob { 00076 unsigned len; 00077 const char *prefix; 00078 mbed::Callback<void()> cb; 00079 oob *next; 00080 }; 00081 oob *_oobs; 00082 00083 public: 00084 00085 /** 00086 * Constructor 00087 * 00088 * @param fh A FileHandle to the digital interface, used for AT commands 00089 * @param output_delimiter End of command-line termination 00090 * @param buffer_size Size of internal buffer for transaction 00091 * @param timeout Timeout of the connection 00092 * @param debug Turns on/off debug output for AT commands 00093 */ 00094 ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r", 00095 int buffer_size = 256, int timeout = 8000, bool debug = false) 00096 : _fh(fh), _buffer_size(buffer_size), _oob_cb_count(0), _in_prev(0), _oobs(NULL) 00097 { 00098 _buffer = new char[buffer_size]; 00099 set_timeout(timeout); 00100 set_delimiter(output_delimiter); 00101 debug_on(debug); 00102 } 00103 00104 /** 00105 * Destructor 00106 */ 00107 ~ATCmdParser() 00108 { 00109 while (_oobs) { 00110 struct oob *oob = _oobs; 00111 _oobs = oob->next; 00112 delete oob; 00113 } 00114 delete[] _buffer; 00115 } 00116 00117 /** 00118 * Allows timeout to be changed between commands 00119 * 00120 * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an 00121 * error if no response is received in `timeout` duration 00122 */ 00123 void set_timeout(int timeout) 00124 { 00125 _timeout = timeout; 00126 } 00127 00128 /** 00129 * For backward compatibility. 00130 * @deprecated Do not use this function. This function has been replaced with set_timeout for consistency. 00131 * 00132 * Please use set_timeout(int) API only from now on. 00133 * Allows timeout to be changed between commands 00134 * 00135 * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an 00136 * error if no response is received in `timeout` duration 00137 * 00138 */ 00139 MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency") 00140 void setTimeout(int timeout) 00141 { 00142 set_timeout(timeout); 00143 } 00144 00145 /** 00146 * Sets string of characters to use as line delimiters 00147 * 00148 * @param output_delimiter String of characters to use as line delimiters 00149 */ 00150 void set_delimiter(const char *output_delimiter) 00151 { 00152 _output_delimiter = output_delimiter; 00153 _output_delim_size = strlen(output_delimiter); 00154 } 00155 00156 /** 00157 * For backwards compatibility. 00158 * @deprecated Do not use this function. This function has been replaced with set_delimiter for consistency. 00159 * 00160 * Please use set_delimiter(const char *) API only from now on. 00161 * Sets string of characters to use as line delimiters 00162 * 00163 * @param output_delimiter string of characters to use as line delimiters 00164 */ 00165 MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency") 00166 void setDelimiter(const char *output_delimiter) 00167 { 00168 set_delimiter(output_delimiter); 00169 } 00170 00171 /** 00172 * Allows traces from modem to be turned on or off 00173 * 00174 * @param on Set as 1 to turn on traces and 0 to disable traces. 00175 */ 00176 void debug_on(uint8_t on) 00177 { 00178 _dbg_on = (on) ? 1 : 0; 00179 } 00180 00181 /** 00182 * For backward compatibility. 00183 * @deprecated Do not use this function. This function has been replaced with debug_on for consistency. 00184 * 00185 * Allows traces from modem to be turned on or off 00186 * 00187 * @param on Set as 1 to turn on traces and 0 to disable traces. 00188 */ 00189 MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency") 00190 void debugOn(uint8_t on) 00191 { 00192 debug_on(on); 00193 } 00194 00195 /** 00196 * Sends an AT command 00197 * 00198 * Sends a formatted command using printf style formatting 00199 * @see printf 00200 * 00201 * @param command printf-like format string of command to send which 00202 * is appended with a newline 00203 * @param ... all printf-like arguments to insert into command 00204 * @return true only if command is successfully sent 00205 */ 00206 bool send(const char *command, ...) MBED_PRINTF_METHOD(1, 2); 00207 00208 bool vsend(const char *command, std::va_list args); 00209 00210 /** 00211 * Receive an AT response 00212 * 00213 * Receives a formatted response using scanf style formatting 00214 * @see scanf 00215 * 00216 * Responses are parsed line at a time. 00217 * Any received data that does not match the response is ignored until 00218 * a timeout occurs. 00219 * 00220 * @param response scanf-like format string of response to expect 00221 * @param ... all scanf-like arguments to extract from response 00222 * @return true only if response is successfully matched 00223 */ 00224 bool recv(const char *response, ...) MBED_SCANF_METHOD(1, 2); 00225 00226 bool vrecv(const char *response, std::va_list args); 00227 00228 /** 00229 * Write a single byte to the underlying stream 00230 * 00231 * @param c The byte to write 00232 * @return The byte that was written or -1 during a timeout 00233 */ 00234 int putc(char c); 00235 00236 /** 00237 * Get a single byte from the underlying stream 00238 * 00239 * @return The byte that was read or -1 during a timeout 00240 */ 00241 int getc(); 00242 00243 /** 00244 * Write an array of bytes to the underlying stream 00245 * 00246 * @param data The array of bytes to write 00247 * @param size Number of bytes to write 00248 * @return number of bytes written or -1 on failure 00249 */ 00250 int write(const char *data, int size); 00251 00252 /** 00253 * Read an array of bytes from the underlying stream 00254 * 00255 * @param data The buffer for filling the read bytes 00256 * @param size Number of bytes to read 00257 * @return number of bytes read or -1 on failure 00258 */ 00259 int read(char *data, int size); 00260 00261 /** 00262 * Direct printf to underlying stream 00263 * @see printf 00264 * 00265 * @param format Format string to pass to printf 00266 * @param ... Variable arguments to printf 00267 * @return number of bytes written or -1 on failure 00268 */ 00269 int printf(const char *format, ...) MBED_PRINTF_METHOD(1, 2); 00270 00271 int vprintf(const char *format, std::va_list args); 00272 00273 /** 00274 * Direct scanf on underlying stream 00275 * @see scanf 00276 * 00277 * @param format Format string to pass to scanf 00278 * @param ... Variable arguments to scanf 00279 * @return number of bytes read or -1 on failure 00280 */ 00281 int scanf(const char *format, ...) MBED_SCANF_METHOD(1, 2); 00282 00283 int vscanf(const char *format, std::va_list args); 00284 00285 /** 00286 * Attach a callback for out-of-band data 00287 * 00288 * @param prefix String on when to initiate callback 00289 * @param func Callback to call when string is read 00290 * @note out-of-band data is only processed during a scanf call 00291 */ 00292 void oob(const char *prefix, mbed::Callback<void()> func); 00293 00294 /** 00295 * Flushes the underlying stream 00296 */ 00297 void flush(); 00298 00299 /** 00300 * Abort current recv 00301 * 00302 * Can be called from out-of-band handler to interrupt the current 00303 * recv operation. 00304 */ 00305 void abort(); 00306 00307 /** 00308 * Process out-of-band data 00309 * 00310 * Process out-of-band data in the receive buffer. This function 00311 * returns immediately if there is no data to process. 00312 * 00313 * @return true if out-of-band data processed, false otherwise 00314 */ 00315 bool process_oob(void); 00316 }; 00317 00318 /**@}*/ 00319 00320 /**@}*/ 00321 00322 } //namespace mbed 00323 00324 #endif //MBED_ATCMDPARSER_H
Generated on Fri Jul 15 2022 12:20:00 by 1.7.2