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