ATParser.h

00001 /* Copyright (c) 2015 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 
00021 #include "mbed.h"
00022 #include <cstdarg>
00023 #include <vector>
00024 #include "BufferedSerial.h"
00025 #include "Callback.h"
00026 
00027 
00028 /**
00029 * Parser class for parsing AT commands
00030 *
00031 * Here are some examples:
00032 * @code
00033 * ATParser at = ATParser(serial, "\r\n");
00034 * int value;
00035 * char buffer[100];
00036 *
00037 * at.send("AT") && at.recv("OK");
00038 * at.send("AT+CWMODE=%d", 3) && at.recv("OK");
00039 * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value);
00040 * at.recv("+IPD,%d:", &value);
00041 * at.read(buffer, value);
00042 * at.recv("OK");
00043 * @endcode
00044 */
00045 class ATParser
00046 {
00047 private:
00048     // Serial information
00049     BufferedSerial *_serial;
00050     int _buffer_size;
00051     char *_buffer;
00052     int _timeout;
00053 
00054     // Parsing information
00055     const char *_delimiter;
00056     int _delim_size;
00057     bool dbg_on;
00058 
00059     struct oob {
00060         unsigned len;
00061         const char *prefix;
00062         mbed::Callback<void()> cb;
00063     };
00064     std::vector<oob> _oobs;
00065 
00066 public:
00067     /**
00068     * Constructor
00069     *
00070     * @param serial serial interface to use for AT commands
00071     * @param buffer_size size of internal buffer for transaction
00072     * @param timeout timeout of the connection
00073     * @param delimiter string of characters to use as line delimiters
00074     */
00075     ATParser(BufferedSerial &serial, const char *delimiter = "\r\n", int buffer_size = 256, int timeout = 8000, bool debug = false) :
00076         _serial(&serial),
00077         _buffer_size(buffer_size) {
00078         _buffer = new char[buffer_size];
00079         setTimeout(timeout);
00080         setDelimiter(delimiter);
00081         debugOn(debug);
00082     }
00083 
00084     /**
00085     * Destructor
00086     */
00087     ~ATParser() {
00088         delete [] _buffer;
00089     }
00090 
00091     /**
00092     * Allows timeout to be changed between commands
00093     *
00094     * @param timeout timeout of the connection
00095     */
00096     void setTimeout(int timeout) {
00097         _timeout = timeout;
00098     }
00099 
00100     /**
00101     * Sets string of characters to use as line delimiters
00102     *
00103     * @param delimiter string of characters to use as line delimiters
00104     */
00105     void setDelimiter(const char *delimiter) {
00106         _delimiter = delimiter;
00107         _delim_size = strlen(delimiter);
00108     }
00109     
00110     /**
00111     * Allows echo to be on or off
00112     *
00113     * @param echo 1 for echo and 0 turns it off
00114     */
00115     void debugOn(uint8_t on) {
00116         dbg_on = (on) ? 1 : 0;
00117     }
00118 
00119     /**
00120     * Sends an AT command
00121     *
00122     * Sends a formatted command using printf style formatting
00123     * @see ::printf
00124     *
00125     * @param command printf-like format string of command to send which
00126     *                is appended with the specified delimiter
00127     * @param ... all printf-like arguments to insert into command
00128     * @return true only if command is successfully sent
00129     */
00130     bool send(const char *command, ...);
00131     bool vsend(const char *command, va_list args);
00132 
00133     /**
00134     * Recieve an AT response
00135     *
00136     * Recieves a formatted response using scanf style formatting
00137     * @see ::scanf
00138     *
00139     * Responses are parsed line at a time using the specified delimiter.
00140     * Any recieved data that does not match the response is ignored until
00141     * a timeout occurs.
00142     *
00143     * @param response scanf-like format string of response to expect
00144     * @param ... all scanf-like arguments to extract from response
00145     * @return true only if response is successfully matched
00146     */
00147     bool recv(const char *response, ...);
00148     bool vrecv(const char *response, va_list args);
00149 
00150     /**
00151     * Write a single byte to the underlying stream
00152     *
00153     * @param c The byte to write
00154     * @return The byte that was written or -1 during a timeout
00155     */
00156     int putc(char c);
00157 
00158     /**
00159     * Get a single byte from the underlying stream
00160     *
00161     * @return The byte that was read or -1 during a timeout
00162     */
00163     int getc();
00164 
00165     /**
00166     * Write an array of bytes to the underlying stream
00167     *
00168     * @param data the array of bytes to write
00169     * @param size number of bytes to write
00170     * @return number of bytes written or -1 on failure
00171     */
00172     int write(const char *data, int size);
00173 
00174     /**
00175     * Read an array of bytes from the underlying stream
00176     *
00177     * @param data the destination for the read bytes
00178     * @param size number of bytes to read
00179     * @return number of bytes read or -1 on failure
00180     */
00181     int read(char *data, int size);
00182 
00183     /**
00184     * Direct printf to underlying stream
00185     * @see ::printf
00186     *
00187     * @param format format string to pass to printf
00188     * @param ... arguments to printf
00189     * @return number of bytes written or -1 on failure
00190     */
00191     int printf(const char *format, ...);
00192     int vprintf(const char *format, va_list args);
00193 
00194     /**
00195     * Direct scanf on underlying stream
00196     * @see ::scanf
00197     *
00198     * @param format format string to pass to scanf
00199     * @param ... arguments to scanf
00200     * @return number of bytes read or -1 on failure
00201     */
00202     int scanf(const char *format, ...);
00203     int vscanf(const char *format, va_list args);
00204 
00205     /**
00206     * Attach a callback for out-of-band data
00207     * 
00208     * @param prefix string on when to initiate callback
00209     * @param func callback to call when string is read
00210     * @note out-of-band data is only processed during a scanf call
00211     */
00212     void oob(const char *prefix, mbed::Callback<void()> func);
00213 
00214     /**
00215     * Attach a callback for out-of-band data
00216     *
00217     * @param prefix string on when to initiate callback
00218     * @param obj pointer to object to call member function on
00219     * @param method callback to call when string is read
00220     * @note out-of-band data is only processed during a scanf call
00221     */
00222     template <typename T, typename M>
00223     void oob(const char *prefix, T *obj, M method) {
00224         return oob(prefix, mbed::Callback<void()>(obj, method));
00225     }
00226 
00227     /**
00228     * Flushes the underlying stream
00229     */
00230     void flush();
00231 };
00232