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     int _oob_cb_count;
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 the digital interface, used 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), _oob_cb_count(0), _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 ATCmdParser APIs (read/write/send/recv ..etc) throw an
00119      *                error if no response is received in `timeout` duration
00120      */
00121     void set_timeout(int timeout)
00122     {
00123         _timeout = timeout;
00124     }
00125 
00126     /**
00127      * For backward compatibility.
00128      * @deprecated Do not use this function. This function has been replaced with set_timeout for consistency.
00129      *
00130      * Please use set_timeout(int) API only from now on.
00131      * Allows timeout to be changed between commands
00132      *
00133      * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
00134      *                error if no response is received in `timeout` duration
00135      *
00136      */
00137     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency")
00138     void setTimeout(int timeout)
00139     {
00140         set_timeout(timeout);
00141     }
00142 
00143     /**
00144      * Sets string of characters to use as line delimiters
00145      *
00146      * @param output_delimiter String of characters to use as line delimiters
00147      */
00148     void set_delimiter(const char *output_delimiter)
00149     {
00150         _output_delimiter = output_delimiter;
00151         _output_delim_size = strlen(output_delimiter);
00152     }
00153 
00154     /**
00155      * For backwards compatibility.
00156      * @deprecated Do not use this function. This function has been replaced with set_delimiter for consistency.
00157      *
00158      * Please use set_delimiter(const char *) API only from now on.
00159      * Sets string of characters to use as line delimiters
00160      *
00161      * @param output_delimiter string of characters to use as line delimiters
00162      */
00163     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
00164     void setDelimiter(const char *output_delimiter)
00165     {
00166         set_delimiter(output_delimiter);
00167     }
00168 
00169     /**
00170      * Allows traces from modem to be turned on or off
00171      *
00172      * @param on Set as 1 to turn on traces and vice versa.
00173      */
00174     void debug_on(uint8_t on)
00175     {
00176         _dbg_on = (on) ? 1 : 0;
00177     }
00178 
00179     /**
00180      * For backward compatibility.
00181      * @deprecated Do not use this function. This function has been replaced with debug_on for consistency.
00182      *
00183      * Allows traces from modem to be turned on or off
00184      *
00185      * @param on Set as 1 to turn on traces and vice versa.
00186      */
00187     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency")
00188     void debugOn(uint8_t on)
00189     {
00190         debug_on(on);
00191     }
00192 
00193     /**
00194      * Sends an AT command
00195      *
00196      * Sends a formatted command using printf style formatting
00197      * @see printf
00198      *
00199      * @param command printf-like format string of command to send which
00200      *                is appended with a newline
00201      * @param ... all printf-like arguments to insert into command
00202      * @return true only if command is successfully sent
00203      */
00204     bool send(const char *command, ...) MBED_PRINTF_METHOD(1, 2);
00205 
00206     bool vsend(const char *command, va_list args);
00207 
00208     /**
00209      * Receive an AT response
00210      *
00211      * Receives a formatted response using scanf style formatting
00212      * @see scanf
00213      *
00214      * Responses are parsed line at a time.
00215      * Any received data that does not match the response is ignored until
00216      * a timeout occurs.
00217      *
00218      * @param response scanf-like format string of response to expect
00219      * @param ... all scanf-like arguments to extract from response
00220      * @return true only if response is successfully matched
00221      */
00222     bool recv(const char *response, ...) MBED_SCANF_METHOD(1, 2);
00223 
00224     bool vrecv(const char *response, va_list args);
00225 
00226     /**
00227      * Write a single byte to the underlying stream
00228      *
00229      * @param c The byte to write
00230      * @return The byte that was written or -1 during a timeout
00231      */
00232     int putc(char c);
00233 
00234     /**
00235      * Get a single byte from the underlying stream
00236      *
00237      * @return The byte that was read or -1 during a timeout
00238      */
00239     int getc();
00240 
00241     /**
00242      * Write an array of bytes to the underlying stream
00243      *
00244      * @param data The array of bytes to write
00245      * @param size Number of bytes to write
00246      * @return number of bytes written or -1 on failure
00247      */
00248     int write(const char *data, int size);
00249 
00250     /**
00251      * Read an array of bytes from the underlying stream
00252      *
00253      * @param data The buffer for filling the read bytes
00254      * @param size Number of bytes to read
00255      * @return number of bytes read or -1 on failure
00256      */
00257     int read(char *data, int size);
00258 
00259     /**
00260      * Direct printf to underlying stream
00261      * @see printf
00262      *
00263      * @param format Format string to pass to printf
00264      * @param ... Variable arguments to printf
00265      * @return number of bytes written or -1 on failure
00266      */
00267     int printf(const char *format, ...) MBED_PRINTF_METHOD(1, 2);
00268 
00269     int vprintf(const char *format, va_list args);
00270 
00271     /**
00272      * Direct scanf on underlying stream
00273      * @see scanf
00274      *
00275      * @param format Format string to pass to scanf
00276      * @param ... Variable arguments to scanf
00277      * @return number of bytes read or -1 on failure
00278      */
00279     int scanf(const char *format, ...) MBED_SCANF_METHOD(1, 2);
00280 
00281     int vscanf(const char *format, va_list args);
00282 
00283     /**
00284      * Attach a callback for out-of-band data
00285      *
00286      * @param prefix String on when to initiate callback
00287      * @param func Callback to call when string is read
00288      * @note out-of-band data is only processed during a scanf call
00289      */
00290     void oob(const char *prefix, mbed::Callback<void()> func);
00291 
00292     /**
00293      * Flushes the underlying stream
00294      */
00295     void flush();
00296 
00297     /**
00298      * Abort current recv
00299      *
00300      * Can be called from out-of-band handler to interrupt the current
00301      * recv operation.
00302      */
00303     void abort();
00304 
00305     /**
00306     * Process out-of-band data
00307     *
00308     * Process out-of-band data in the receive buffer. This function
00309     * returns immediately if there is no data to process.
00310     *
00311     * @return true if out-of-band data processed, false otherwise
00312     */
00313     bool process_oob(void);
00314 };
00315 
00316 /**@}*/
00317 
00318 /**@}*/
00319 
00320 } //namespace mbed
00321 
00322 #endif //MBED_ATCMDPARSER_H