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