ATCmdParser.h

00001 /* Copyright (c) 2017-2019 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 "platform/Callback.h"
00026 #include "platform/NonCopyable.h"
00027 #include "platform/FileHandle.h"
00028 
00029 namespace mbed {
00030 /** \addtogroup platform-public-api Platform */
00031 /** @{*/
00032 /**
00033  * \defgroup platform_ATCmdParser ATCmdParser class
00034  * @{
00035  */
00036 
00037 /**
00038  * Parser class for parsing AT commands
00039  *
00040  * Here are some examples:
00041  * @code
00042  * UARTSerial serial = UARTSerial(D1, D0);
00043  * ATCmdParser at = ATCmdParser(&serial, "\r\n");
00044  * int value;
00045  * char buffer[100];
00046  *
00047  * at.send("AT") && at.recv("OK");
00048  * at.send("AT+CWMODE=%d", 3) && at.recv("OK");
00049  * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value);
00050  * at.recv("+IPD,%d:", &value);
00051  * at.read(buffer, value);
00052  * at.recv("OK");
00053  * @endcode
00054  */
00055 
00056 class ATCmdParser : private NonCopyable<ATCmdParser> {
00057 private:
00058     // File handle
00059     // Not owned by ATCmdParser
00060     FileHandle *_fh;
00061 
00062     int _buffer_size;
00063     char *_buffer;
00064     int _timeout;
00065 
00066     // Parsing information
00067     const char *_output_delimiter;
00068     int _output_delim_size;
00069     int _oob_cb_count;
00070     char _in_prev;
00071     bool _dbg_on;
00072     bool _aborted;
00073 
00074     struct oob {
00075         unsigned len;
00076         const char *prefix;
00077         mbed::Callback<void()> cb;
00078         oob *next;
00079     };
00080     oob *_oobs;
00081 
00082     /**
00083      * Receive an AT response
00084      *
00085      * Receives a formatted response using scanf style formatting
00086      * @see scanf
00087      *
00088      * Responses are parsed line at a time.
00089      * If multiline is set to false parse only one line otherwise parse multiline response
00090      * Any received data that does not match the response is ignored until
00091      * a timeout occurs.
00092      *
00093      * @param response scanf-like format string of response to expect
00094      * @param ... all scanf-like arguments to extract from response
00095      * @param multiline determinate if parse one or multiple lines.
00096      * @return number of bytes read or -1 on failure
00097      */
00098     int vrecvscanf(const char *response, std::va_list args, bool multiline);
00099 
00100 public:
00101 
00102     /**
00103      * Constructor
00104      *
00105      * @param fh A FileHandle to the digital interface, used for AT commands
00106      * @param output_delimiter End of command-line termination
00107      * @param buffer_size Size of internal buffer for transaction
00108      * @param timeout Timeout of the connection
00109      * @param debug Turns on/off debug output for AT commands
00110      */
00111     ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r",
00112                 int buffer_size = 256, int timeout = 8000, bool debug = false)
00113         : _fh(fh), _buffer_size(buffer_size), _oob_cb_count(0), _in_prev(0), _aborted(false), _oobs(NULL)
00114     {
00115         _buffer = new char[buffer_size];
00116         set_timeout(timeout);
00117         set_delimiter(output_delimiter);
00118         debug_on(debug);
00119     }
00120 
00121     /**
00122      * Destructor
00123      */
00124     ~ATCmdParser()
00125     {
00126         while (_oobs) {
00127             struct oob *oob = _oobs;
00128             _oobs = oob->next;
00129             delete oob;
00130         }
00131         delete[] _buffer;
00132     }
00133 
00134     /**
00135      * Allows timeout to be changed between commands
00136      *
00137      * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
00138      *                error if no response is received in `timeout` duration
00139      */
00140     void set_timeout(int timeout)
00141     {
00142         _timeout = timeout;
00143     }
00144 
00145     /**
00146      * For backward compatibility.
00147      * @deprecated Do not use this function. This function has been replaced with set_timeout for consistency.
00148      *
00149      * Please use set_timeout(int) API only from now on.
00150      * Allows timeout to be changed between commands
00151      *
00152      * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
00153      *                error if no response is received in `timeout` duration
00154      *
00155      */
00156     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency")
00157     void setTimeout(int timeout)
00158     {
00159         set_timeout(timeout);
00160     }
00161 
00162     /**
00163      * Sets string of characters to use as line delimiters
00164      *
00165      * @param output_delimiter String of characters to use as line delimiters
00166      */
00167     void set_delimiter(const char *output_delimiter)
00168     {
00169         _output_delimiter = output_delimiter;
00170         _output_delim_size = strlen(output_delimiter);
00171     }
00172 
00173     /**
00174      * For backwards compatibility.
00175      * @deprecated Do not use this function. This function has been replaced with set_delimiter for consistency.
00176      *
00177      * Please use set_delimiter(const char *) API only from now on.
00178      * Sets string of characters to use as line delimiters
00179      *
00180      * @param output_delimiter string of characters to use as line delimiters
00181      */
00182     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
00183     void setDelimiter(const char *output_delimiter)
00184     {
00185         set_delimiter(output_delimiter);
00186     }
00187 
00188     /**
00189      * Allows traces from modem to be turned on or off
00190      *
00191      * @param on Set as 1 to turn on traces and 0 to disable traces.
00192      */
00193     void debug_on(uint8_t on)
00194     {
00195         _dbg_on = (on) ? 1 : 0;
00196     }
00197 
00198     /**
00199      * For backward compatibility.
00200      * @deprecated Do not use this function. This function has been replaced with debug_on for consistency.
00201      *
00202      * Allows traces from modem to be turned on or off
00203      *
00204      * @param on Set as 1 to turn on traces and 0 to disable traces.
00205      */
00206     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency")
00207     void debugOn(uint8_t on)
00208     {
00209         debug_on(on);
00210     }
00211 
00212     /**
00213      * Sends an AT command
00214      *
00215      * Sends a formatted command using printf style formatting
00216      * @see printf
00217      *
00218      * @param command printf-like format string of command to send which
00219      *                is appended with a newline
00220      * @param ... all printf-like arguments to insert into command
00221      * @return true only if command is successfully sent
00222      */
00223     bool send(const char *command, ...) MBED_PRINTF_METHOD(1, 2);
00224 
00225     bool vsend(const char *command, std::va_list args);
00226 
00227     /**
00228      * Receive an AT response
00229      *
00230      * Receives a formatted response using scanf style formatting
00231      * @see scanf
00232      *
00233      * Responses are parsed line at a time.
00234      * Any received data that does not match the response is ignored until
00235      * a timeout occurs.
00236      *
00237      * @param response scanf-like format string of response to expect
00238      * @param ... all scanf-like arguments to extract from response
00239      * @return true only if response is successfully matched
00240      */
00241     bool recv(const char *response, ...) MBED_SCANF_METHOD(1, 2);
00242 
00243     bool vrecv(const char *response, std::va_list args);
00244 
00245     /**
00246      * Write a single byte to the underlying stream
00247      *
00248      * @param c The byte to write
00249      * @return The byte that was written or -1 during a timeout
00250      */
00251     int putc(char c);
00252 
00253     /**
00254      * Get a single byte from the underlying stream
00255      *
00256      * @return The byte that was read or -1 during a timeout
00257      */
00258     int getc();
00259 
00260     /**
00261      * Write an array of bytes to the underlying stream
00262      *
00263      * @param data The array of bytes to write
00264      * @param size Number of bytes to write
00265      * @return number of bytes written or -1 on failure
00266      */
00267     int write(const char *data, int size);
00268 
00269     /**
00270      * Read an array of bytes from the underlying stream
00271      *
00272      * @param data The buffer for filling the read bytes
00273      * @param size Number of bytes to read
00274      * @return number of bytes read or -1 on failure
00275      */
00276     int read(char *data, int size);
00277 
00278     /**
00279      * Direct printf to underlying stream
00280      * @see printf
00281      *
00282      * @param format Format string to pass to printf
00283      * @param ... Variable arguments to printf
00284      * @return number of bytes written or -1 on failure
00285      */
00286     int printf(const char *format, ...) MBED_PRINTF_METHOD(1, 2);
00287 
00288     int vprintf(const char *format, std::va_list args);
00289 
00290     /**
00291      * Direct scanf on underlying stream
00292      * This function does not itself match whitespace in its format string, so \n is not significant to it.
00293      * It should be used only when certain string is needed or format ends with certain character, otherwise
00294      * it will fill the output with one character.
00295      * @see scanf
00296      *
00297      * @param format Format string to pass to scanf
00298      * @param ... Variable arguments to scanf
00299      * @return number of bytes read or -1 on failure
00300      */
00301     int scanf(const char *format, ...) MBED_SCANF_METHOD(1, 2);
00302 
00303     int vscanf(const char *format, std::va_list args);
00304 
00305     /**
00306      * Attach a callback for out-of-band data
00307      *
00308      * @param prefix String on when to initiate callback
00309      * @param func Callback to call when string is read
00310      * @note out-of-band data is only processed during a scanf call
00311      */
00312     void oob(const char *prefix, mbed::Callback<void()> func);
00313 
00314     /**
00315      * @brief remove_oob Removes oob callback handler
00316      * @param prefix Prefix to identify oob to be removed.
00317      */
00318     void remove_oob(const char *prefix);
00319 
00320     /**
00321      * Flushes the underlying stream
00322      */
00323     void flush();
00324 
00325     /**
00326      * Abort current recv
00327      *
00328      * Can be called from out-of-band handler to interrupt the current
00329      * recv operation.
00330      */
00331     void abort();
00332 
00333     /**
00334     * Process out-of-band data
00335     *
00336     * Process out-of-band data in the receive buffer. This function
00337     * returns immediately if there is no data to process.
00338     *
00339     * @return true if out-of-band data processed, false otherwise
00340     */
00341     bool process_oob(void);
00342 };
00343 
00344 /**@}*/
00345 
00346 /**@}*/
00347 
00348 } //namespace mbed
00349 
00350 #endif //MBED_ATCMDPARSER_H