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 "BufferedSpi.h"
00027 #include "Callback.h"
00028 
00029 #define DEFAULT_SPI_TIMEOUT 60000 /* 1 minute */
00030 
00031 /**
00032 * Parser class for parsing AT commands
00033 *
00034 * Here are some examples:
00035 * @code
00036 * ATParser at = ATParser(serial, "\r\n");
00037 * int value;
00038 * char buffer[100];
00039 *
00040 * at.send("AT") && at.recv("OK");
00041 * at.send("AT+CWMODE=%d", 3) && at.recv("OK");
00042 * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value);
00043 * at.recv("+IPD,%d:", &value);
00044 * at.read(buffer, value);
00045 * at.recv("OK");
00046 * @endcode
00047 */
00048 class ATParser {
00049 private:
00050     // Serial information
00051     BufferedSpi *_serial_spi;
00052     int _buffer_size;
00053     char *_buffer;
00054     Mutex _bufferMutex;
00055 
00056     // Parsing information
00057     const char *_delimiter;
00058     int _delim_size;
00059     char _in_prev;
00060     volatile bool _aborted;
00061 
00062     struct oob {
00063         unsigned len;
00064         const char *prefix;
00065         mbed::Callback<void()> cb;
00066         oob *next;
00067     };
00068     oob *_oobs;
00069 
00070 public:
00071     /**
00072     * Constructor
00073     *
00074     * @param serial spi interface to use for AT commands
00075     * @param buffer_size size of internal buffer for transaction
00076     * @param timeout timeout of the connection
00077     * @param delimiter string of characters to use as line delimiters
00078     */
00079     ATParser(BufferedSpi &serial_spi, const char *delimiter = "\r\n", int buffer_size = 1440, int timeout = DEFAULT_SPI_TIMEOUT);
00080 
00081     /**
00082     * Destructor
00083     */
00084     ~ATParser()
00085     {
00086         while (_oobs) {
00087             struct oob *oob = _oobs;
00088             _oobs = oob->next;
00089             delete oob;
00090         }
00091         delete[] _buffer;
00092     }
00093 
00094     /**
00095     * Allows timeout to be changed between commands
00096     *
00097     * @param timeout timeout of the connection
00098     */
00099     void setTimeout(int timeout)
00100     {
00101         _serial_spi->setTimeout(timeout);
00102     }
00103 
00104     /**
00105     * Sets string of characters to use as line delimiters
00106     *
00107     * @param delimiter string of characters to use as line delimiters
00108     */
00109     void setDelimiter(const char *delimiter)
00110     {
00111         _delimiter = delimiter;
00112         _delim_size = strlen(delimiter);
00113     }
00114 
00115     /**
00116      * Sends an AT command
00117      *
00118      * Sends a formatted command using printf style formatting
00119      * @see printf
00120      *
00121      * @param command printf-like format string of command to send which
00122      *                is appended with a newline
00123      * @param ... all printf-like arguments to insert into command
00124      * @return true only if command is successfully sent
00125      */
00126     bool send(const char *command, ...);
00127 
00128     bool vsend(const char *command, va_list args);
00129 
00130     /**
00131      * Receive an AT response
00132      *
00133      * Receives a formatted response using scanf style formatting
00134      * @see scanf
00135      *
00136      * Responses are parsed line at a time.
00137      * Any received data that does not match the response is ignored until
00138      * a timeout occurs.
00139      *
00140      * @param response scanf-like format string of response to expect
00141      * @param ... all scanf-like arguments to extract from response
00142      * @return true only if response is successfully matched
00143      */
00144     bool recv(const char *response, ...);
00145     bool vrecv(const char *response, va_list args);
00146 
00147 
00148     /**
00149      * Write a single byte to the underlying stream
00150      *
00151      * @param c The byte to write
00152      * @return The byte that was written or -1 during a timeout
00153      */
00154     int putc(char c);
00155 
00156     /**
00157      * Get a single byte from the underlying stream
00158      *
00159      * @return The byte that was read or -1 during a timeout
00160      */
00161     int getc();
00162 
00163     /**
00164      * Write an array of bytes to the underlying stream
00165      * assuming the header of the command is already in _txbuffer
00166      *
00167      * @param data the array of bytes to write
00168      * @param size_of_data number of bytes in data array
00169      * @param size_in_buff number of bytes already in the internal buff
00170      * @return number of bytes written or -1 on failure
00171      */
00172     int write(const char *data, int size_of_data, int size_in_buff);
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);
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 
00204     int vscanf(const char *format, va_list args);
00205 
00206     /**
00207      * Attach a callback for out-of-band data
00208      *
00209      * @param prefix string on when to initiate callback
00210      * @param func callback to call when string is read
00211      * @note out-of-band data is only processed during a scanf call
00212      */
00213     void oob(const char *prefix, mbed::Callback<void()> func);
00214 
00215     /**
00216      * Flushes the underlying stream
00217      */
00218     void flush();
00219 
00220     /**
00221      * Abort current recv
00222      *
00223      * Can be called from oob handler to interrupt the current
00224      * recv operation.
00225      */
00226     void abort();
00227 
00228     /**
00229     * Process out-of-band data
00230     *
00231     * Process out-of-band data in the receive buffer. This function
00232     * returns immediately if there is no data to process.
00233     *
00234     * @return true if oob data processed, false otherwise
00235     */
00236     bool process_oob(void);
00237     /**
00238     * Get buffer_size
00239     */
00240     int get_size(void)
00241     {
00242         return _buffer_size;
00243     }
00244 
00245 };
00246 #endif