ATCmdParser.h

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