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 /**
00028  * Parser class for parsing AT commands
00029  *
00030  * Here are some examples:
00031  * @code
00032  * ATCmdParser at = ATCmdParser(serial, "\r\n");
00033  * int value;
00034  * char buffer[100];
00035  *
00036  * at.send("AT") && at.recv("OK");
00037  * at.send("AT+CWMODE=%d", 3) && at.recv("OK");
00038  * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value);
00039  * at.recv("+IPD,%d:", &value);
00040  * at.read(buffer, value);
00041  * at.recv("OK");
00042  * @endcode
00043  */
00044 
00045 namespace mbed {
00046 
00047 class ATCmdParser : private NonCopyable<ATCmdParser>
00048 {
00049 private:
00050     // File handle
00051     // Not owned by ATCmdParser
00052     FileHandle *_fh;
00053 
00054     int _buffer_size;
00055     char *_buffer;
00056     int _timeout;
00057 
00058     // Parsing information
00059     const char *_output_delimiter;
00060     int _output_delim_size;
00061     char _in_prev;
00062     bool _dbg_on;
00063     bool _aborted;
00064 
00065     struct oob {
00066         unsigned len;
00067         const char *prefix;
00068         mbed::Callback<void()> cb;
00069         oob *next;
00070     };
00071     oob *_oobs;
00072 
00073 public:
00074 
00075     /**
00076      * Constructor
00077      *
00078      * @param fh A FileHandle to a digital interface to use for AT commands
00079      * @param output_delimiter end of command line termination
00080      * @param buffer_size size of internal buffer for transaction
00081      * @param timeout timeout of the connection
00082      * @param debug turns on/off debug output for AT commands
00083      */
00084     ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r",
00085              int buffer_size = 256, int timeout = 8000, bool debug = false)
00086             : _fh(fh), _buffer_size(buffer_size), _in_prev(0), _oobs(NULL)
00087     {
00088         _buffer = new char[buffer_size];
00089         set_timeout(timeout);
00090         set_delimiter(output_delimiter);
00091         debug_on(debug);
00092     }
00093 
00094     /**
00095      * Destructor
00096      */
00097     ~ATCmdParser()
00098     {
00099         while (_oobs) {
00100             struct oob *oob = _oobs;
00101             _oobs = oob->next;
00102             delete oob;
00103         }
00104         delete[] _buffer;
00105     }
00106 
00107     /**
00108      * Allows timeout to be changed between commands
00109      *
00110      * @param timeout timeout of the connection
00111      */
00112     void set_timeout(int timeout)
00113     {
00114         _timeout = timeout;
00115     }
00116 
00117     /**
00118      * For backwards compatibility.
00119      *
00120      * Please use set_timeout(int) API only from now on.
00121      * Allows timeout to be changed between commands
00122      *
00123      * @param timeout timeout of the connection
00124      */
00125     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency")
00126     void setTimeout(int timeout)
00127     {
00128         set_timeout(timeout);
00129     }
00130 
00131     /**
00132      * Sets string of characters to use as line delimiters
00133      *
00134      * @param output_delimiter string of characters to use as line delimiters
00135      */
00136     void set_delimiter(const char *output_delimiter)
00137     {
00138         _output_delimiter = output_delimiter;
00139         _output_delim_size = strlen(output_delimiter);
00140     }
00141 
00142     /**
00143      * For backwards compatibility.
00144      *
00145      * Please use set_delimiter(const char *) API only from now on.
00146      * Sets string of characters to use as line delimiters
00147      *
00148      * @param output_delimiter string of characters to use as line delimiters
00149      */
00150     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
00151     void setDelimiter(const char *output_delimiter)
00152     {
00153         set_delimiter(output_delimiter);
00154     }
00155 
00156     /**
00157      * Allows traces from modem to be turned on or off
00158      *
00159      * @param on set as 1 to turn on traces and vice versa.
00160      */
00161     void debug_on(uint8_t on)
00162     {
00163         _dbg_on = (on) ? 1 : 0;
00164     }
00165 
00166     /**
00167      * For backwards compatibility.
00168      *
00169      * Allows traces from modem to be turned on or off
00170      *
00171      * @param on set as 1 to turn on traces and vice versa.
00172      */
00173     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency")
00174     void debugOn(uint8_t on)
00175     {
00176         debug_on(on);
00177     }
00178 
00179     /**
00180      * Sends an AT command
00181      *
00182      * Sends a formatted command using printf style formatting
00183      * @see printf
00184      *
00185      * @param command printf-like format string of command to send which
00186      *                is appended with a newline
00187      * @param ... all printf-like arguments to insert into command
00188      * @return true only if command is successfully sent
00189      */
00190     bool send(const char *command, ...) MBED_PRINTF_METHOD(1,2);
00191 
00192     bool vsend(const char *command, va_list args);
00193 
00194     /**
00195      * Receive an AT response
00196      *
00197      * Receives a formatted response using scanf style formatting
00198      * @see scanf
00199      *
00200      * Responses are parsed line at a time.
00201      * Any received data that does not match the response is ignored until
00202      * a timeout occurs.
00203      *
00204      * @param response scanf-like format string of response to expect
00205      * @param ... all scanf-like arguments to extract from response
00206      * @return true only if response is successfully matched
00207      */
00208     bool recv(const char *response, ...) MBED_SCANF_METHOD(1,2);
00209 
00210     bool vrecv(const char *response, va_list args);
00211 
00212     /**
00213      * Write a single byte to the underlying stream
00214      *
00215      * @param c The byte to write
00216      * @return The byte that was written or -1 during a timeout
00217      */
00218     int putc(char c);
00219 
00220     /**
00221      * Get a single byte from the underlying stream
00222      *
00223      * @return The byte that was read or -1 during a timeout
00224      */
00225     int getc();
00226 
00227     /**
00228      * Write an array of bytes to the underlying stream
00229      *
00230      * @param data the array of bytes to write
00231      * @param size number of bytes to write
00232      * @return number of bytes written or -1 on failure
00233      */
00234     int write(const char *data, int size);
00235 
00236     /**
00237      * Read an array of bytes from the underlying stream
00238      *
00239      * @param data the destination for the read bytes
00240      * @param size number of bytes to read
00241      * @return number of bytes read or -1 on failure
00242      */
00243     int read(char *data, int size);
00244 
00245     /**
00246      * Direct printf to underlying stream
00247      * @see printf
00248      *
00249      * @param format format string to pass to printf
00250      * @param ... arguments to printf
00251      * @return number of bytes written or -1 on failure
00252      */
00253     int printf(const char *format, ...) MBED_PRINTF_METHOD(1,2);
00254 
00255     int vprintf(const char *format, va_list args);
00256 
00257     /**
00258      * Direct scanf on underlying stream
00259      * @see scanf
00260      *
00261      * @param format format string to pass to scanf
00262      * @param ... arguments to scanf
00263      * @return number of bytes read or -1 on failure
00264      */
00265     int scanf(const char *format, ...) MBED_SCANF_METHOD(1,2);
00266 
00267     int vscanf(const char *format, va_list args);
00268 
00269     /**
00270      * Attach a callback for out-of-band data
00271      *
00272      * @param prefix string on when to initiate callback
00273      * @param func callback to call when string is read
00274      * @note out-of-band data is only processed during a scanf call
00275      */
00276     void oob(const char *prefix, mbed::Callback<void()> func);
00277 
00278     /**
00279      * Flushes the underlying stream
00280      */
00281     void flush();
00282 
00283     /**
00284      * Abort current recv
00285      *
00286      * Can be called from oob handler to interrupt the current
00287      * recv operation.
00288      */
00289     void abort();
00290 };
00291 } //namespace mbed
00292 
00293 #endif //MBED_ATCMDPARSER_H