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 {
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     char _in_prev;
00070     bool _dbg_on;
00071     bool _aborted;
00072 
00073     struct oob {
00074         unsigned len;
00075         const char *prefix;
00076         mbed::Callback<void()> cb;
00077         oob *next;
00078     };
00079     oob *_oobs;
00080 
00081 public:
00082 
00083     /**
00084      * Constructor
00085      *
00086      * @param fh A FileHandle to a digital interface to use for AT commands
00087      * @param output_delimiter end of command line termination
00088      * @param buffer_size size of internal buffer for transaction
00089      * @param timeout timeout of the connection
00090      * @param debug turns on/off debug output for AT commands
00091      */
00092     ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r",
00093              int buffer_size = 256, int timeout = 8000, bool debug = false)
00094             : _fh(fh), _buffer_size(buffer_size), _in_prev(0), _oobs(NULL)
00095     {
00096         _buffer = new char[buffer_size];
00097         set_timeout(timeout);
00098         set_delimiter(output_delimiter);
00099         debug_on(debug);
00100     }
00101 
00102     /**
00103      * Destructor
00104      */
00105     ~ATCmdParser()
00106     {
00107         while (_oobs) {
00108             struct oob *oob = _oobs;
00109             _oobs = oob->next;
00110             delete oob;
00111         }
00112         delete[] _buffer;
00113     }
00114 
00115     /**
00116      * Allows timeout to be changed between commands
00117      *
00118      * @param timeout timeout of the connection
00119      */
00120     void set_timeout(int timeout)
00121     {
00122         _timeout = timeout;
00123     }
00124 
00125     /**
00126      * For backwards compatibility.
00127      * @deprecated Do not use this function. This function has been replaced with set_timeout for consistency.
00128      *
00129      * Please use set_timeout(int) API only from now on.
00130      * Allows timeout to be changed between commands
00131      *
00132      * @param timeout timeout of the connection
00133      */
00134     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency")
00135     void setTimeout(int timeout)
00136     {
00137         set_timeout(timeout);
00138     }
00139 
00140     /**
00141      * Sets string of characters to use as line delimiters
00142      *
00143      * @param output_delimiter string of characters to use as line delimiters
00144      */
00145     void set_delimiter(const char *output_delimiter)
00146     {
00147         _output_delimiter = output_delimiter;
00148         _output_delim_size = strlen(output_delimiter);
00149     }
00150 
00151     /**
00152      * For backwards compatibility.
00153      * @deprecated Do not use this function. This function has been replaced with set_delimiter for consistency.
00154      *
00155      * Please use set_delimiter(const char *) API only from now on.
00156      * Sets string of characters to use as line delimiters
00157      *
00158      * @param output_delimiter string of characters to use as line delimiters
00159      */
00160     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
00161     void setDelimiter(const char *output_delimiter)
00162     {
00163         set_delimiter(output_delimiter);
00164     }
00165 
00166     /**
00167      * Allows traces from modem to be turned on or off
00168      *
00169      * @param on set as 1 to turn on traces and vice versa.
00170      */
00171     void debug_on(uint8_t on)
00172     {
00173         _dbg_on = (on) ? 1 : 0;
00174     }
00175 
00176     /**
00177      * For backwards compatibility.
00178      * @deprecated Do not use this function. This function has been replaced with debug_on for consistency.
00179      *
00180      * Allows traces from modem to be turned on or off
00181      *
00182      * @param on set as 1 to turn on traces and vice versa.
00183      */
00184     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency")
00185     void debugOn(uint8_t on)
00186     {
00187         debug_on(on);
00188     }
00189 
00190     /**
00191      * Sends an AT command
00192      *
00193      * Sends a formatted command using printf style formatting
00194      * @see printf
00195      *
00196      * @param command printf-like format string of command to send which
00197      *                is appended with a newline
00198      * @param ... all printf-like arguments to insert into command
00199      * @return true only if command is successfully sent
00200      */
00201     bool send(const char *command, ...) MBED_PRINTF_METHOD(1,2);
00202 
00203     bool vsend(const char *command, va_list args);
00204 
00205     /**
00206      * Receive an AT response
00207      *
00208      * Receives a formatted response using scanf style formatting
00209      * @see scanf
00210      *
00211      * Responses are parsed line at a time.
00212      * Any received data that does not match the response is ignored until
00213      * a timeout occurs.
00214      *
00215      * @param response scanf-like format string of response to expect
00216      * @param ... all scanf-like arguments to extract from response
00217      * @return true only if response is successfully matched
00218      */
00219     bool recv(const char *response, ...) MBED_SCANF_METHOD(1,2);
00220 
00221     bool vrecv(const char *response, va_list args);
00222 
00223     /**
00224      * Write a single byte to the underlying stream
00225      *
00226      * @param c The byte to write
00227      * @return The byte that was written or -1 during a timeout
00228      */
00229     int putc(char c);
00230 
00231     /**
00232      * Get a single byte from the underlying stream
00233      *
00234      * @return The byte that was read or -1 during a timeout
00235      */
00236     int getc();
00237 
00238     /**
00239      * Write an array of bytes to the underlying stream
00240      *
00241      * @param data the array of bytes to write
00242      * @param size number of bytes to write
00243      * @return number of bytes written or -1 on failure
00244      */
00245     int write(const char *data, int size);
00246 
00247     /**
00248      * Read an array of bytes from the underlying stream
00249      *
00250      * @param data the destination for the read bytes
00251      * @param size number of bytes to read
00252      * @return number of bytes read or -1 on failure
00253      */
00254     int read(char *data, int size);
00255 
00256     /**
00257      * Direct printf to underlying stream
00258      * @see printf
00259      *
00260      * @param format format string to pass to printf
00261      * @param ... arguments to printf
00262      * @return number of bytes written or -1 on failure
00263      */
00264     int printf(const char *format, ...) MBED_PRINTF_METHOD(1,2);
00265 
00266     int vprintf(const char *format, va_list args);
00267 
00268     /**
00269      * Direct scanf on underlying stream
00270      * @see scanf
00271      *
00272      * @param format format string to pass to scanf
00273      * @param ... arguments to scanf
00274      * @return number of bytes read or -1 on failure
00275      */
00276     int scanf(const char *format, ...) MBED_SCANF_METHOD(1,2);
00277 
00278     int vscanf(const char *format, va_list args);
00279 
00280     /**
00281      * Attach a callback for out-of-band data
00282      *
00283      * @param prefix string on when to initiate callback
00284      * @param func callback to call when string is read
00285      * @note out-of-band data is only processed during a scanf call
00286      */
00287     void oob(const char *prefix, mbed::Callback<void()> func);
00288 
00289     /**
00290      * Flushes the underlying stream
00291      */
00292     void flush();
00293 
00294     /**
00295      * Abort current recv
00296      *
00297      * Can be called from oob handler to interrupt the current
00298      * recv operation.
00299      */
00300     void abort();
00301     
00302     /**
00303     * Process out-of-band data
00304     *
00305     * Process out-of-band data in the receive buffer. This function
00306     * returns immediately if there is no data to process.
00307     *
00308     * @return true if oob data processed, false otherwise
00309     */
00310     bool process_oob(void);
00311 };
00312 
00313 /**@}*/
00314 
00315 /**@}*/
00316 
00317 } //namespace mbed
00318 
00319 #endif //MBED_ATCMDPARSER_H