ATCmdParser.h

00001 /* Copyright (c) 2017 ARM Limited
00002  * SPDX-License-Identifier: Apache-2.0
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  *
00016  * @section DESCRIPTION
00017  *
00018  * Parser for the AT command syntax
00019  *
00020  */
00021 #ifndef MBED_ATCMDPARSER_H
00022 #define MBED_ATCMDPARSER_H
00023 
00024 #include <cstdarg>
00025 #include "Callback.h"
00026 #include "NonCopyable.h"
00027 #include "FileHandle.h"
00028 
00029 namespace mbed {
00030 
00031 /** \addtogroup platform */
00032 /** @{*/
00033 /**
00034  * \defgroup platform_ATCmdParser ATCmdParser class
00035  * @{
00036  */
00037 
00038 /**
00039  * Parser class for parsing AT commands
00040  *
00041  * Here are some examples:
00042  * @code
00043  * UARTSerial serial = UARTSerial(D1, D0);
00044  * ATCmdParser at = ATCmdParser(&serial, "\r\n");
00045  * int value;
00046  * char buffer[100];
00047  *
00048  * at.send("AT") && at.recv("OK");
00049  * at.send("AT+CWMODE=%d", 3) && at.recv("OK");
00050  * at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value);
00051  * at.recv("+IPD,%d:", &value);
00052  * at.read(buffer, value);
00053  * at.recv("OK");
00054  * @endcode
00055  */
00056 
00057 class ATCmdParser : private NonCopyable<ATCmdParser> {
00058 private:
00059     // File handle
00060     // Not owned by ATCmdParser
00061     FileHandle *_fh;
00062 
00063     int _buffer_size;
00064     char *_buffer;
00065     int _timeout;
00066 
00067     // Parsing information
00068     const char *_output_delimiter;
00069     int _output_delim_size;
00070     int _oob_cb_count;
00071     char _in_prev;
00072     bool _dbg_on;
00073     bool _aborted;
00074 
00075     struct oob {
00076         unsigned len;
00077         const char *prefix;
00078         mbed::Callback<void()> cb;
00079         oob *next;
00080     };
00081     oob *_oobs;
00082 
00083 public:
00084 
00085     /**
00086      * Constructor
00087      *
00088      * @param fh A FileHandle to the digital interface, used for AT commands
00089      * @param output_delimiter End of command-line termination
00090      * @param buffer_size Size of internal buffer for transaction
00091      * @param timeout Timeout of the connection
00092      * @param debug Turns on/off debug output for AT commands
00093      */
00094     ATCmdParser(FileHandle *fh, const char *output_delimiter = "\r",
00095                 int buffer_size = 256, int timeout = 8000, bool debug = false)
00096         : _fh(fh), _buffer_size(buffer_size), _oob_cb_count(0), _in_prev(0), _oobs(NULL)
00097     {
00098         _buffer = new char[buffer_size];
00099         set_timeout(timeout);
00100         set_delimiter(output_delimiter);
00101         debug_on(debug);
00102     }
00103 
00104     /**
00105      * Destructor
00106      */
00107     ~ATCmdParser()
00108     {
00109         while (_oobs) {
00110             struct oob *oob = _oobs;
00111             _oobs = oob->next;
00112             delete oob;
00113         }
00114         delete[] _buffer;
00115     }
00116 
00117     /**
00118      * Allows timeout to be changed between commands
00119      *
00120      * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
00121      *                error if no response is received in `timeout` duration
00122      */
00123     void set_timeout(int timeout)
00124     {
00125         _timeout = timeout;
00126     }
00127 
00128     /**
00129      * For backward compatibility.
00130      * @deprecated Do not use this function. This function has been replaced with set_timeout for consistency.
00131      *
00132      * Please use set_timeout(int) API only from now on.
00133      * Allows timeout to be changed between commands
00134      *
00135      * @param timeout ATCmdParser APIs (read/write/send/recv ..etc) throw an
00136      *                error if no response is received in `timeout` duration
00137      *
00138      */
00139     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency")
00140     void setTimeout(int timeout)
00141     {
00142         set_timeout(timeout);
00143     }
00144 
00145     /**
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     void set_delimiter(const char *output_delimiter)
00151     {
00152         _output_delimiter = output_delimiter;
00153         _output_delim_size = strlen(output_delimiter);
00154     }
00155 
00156     /**
00157      * For backwards compatibility.
00158      * @deprecated Do not use this function. This function has been replaced with set_delimiter for consistency.
00159      *
00160      * Please use set_delimiter(const char *) API only from now on.
00161      * Sets string of characters to use as line delimiters
00162      *
00163      * @param output_delimiter string of characters to use as line delimiters
00164      */
00165     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency")
00166     void setDelimiter(const char *output_delimiter)
00167     {
00168         set_delimiter(output_delimiter);
00169     }
00170 
00171     /**
00172      * Allows traces from modem to be turned on or off
00173      *
00174      * @param on Set as 1 to turn on traces and 0 to disable traces.
00175      */
00176     void debug_on(uint8_t on)
00177     {
00178         _dbg_on = (on) ? 1 : 0;
00179     }
00180 
00181     /**
00182      * For backward compatibility.
00183      * @deprecated Do not use this function. This function has been replaced with debug_on for consistency.
00184      *
00185      * Allows traces from modem to be turned on or off
00186      *
00187      * @param on Set as 1 to turn on traces and 0 to disable traces.
00188      */
00189     MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency")
00190     void debugOn(uint8_t on)
00191     {
00192         debug_on(on);
00193     }
00194 
00195     /**
00196      * Sends an AT command
00197      *
00198      * Sends a formatted command using printf style formatting
00199      * @see printf
00200      *
00201      * @param command printf-like format string of command to send which
00202      *                is appended with a newline
00203      * @param ... all printf-like arguments to insert into command
00204      * @return true only if command is successfully sent
00205      */
00206     bool send(const char *command, ...) MBED_PRINTF_METHOD(1, 2);
00207 
00208     bool vsend(const char *command, std::va_list args);
00209 
00210     /**
00211      * Receive an AT response
00212      *
00213      * Receives a formatted response using scanf style formatting
00214      * @see scanf
00215      *
00216      * Responses are parsed line at a time.
00217      * Any received data that does not match the response is ignored until
00218      * a timeout occurs.
00219      *
00220      * @param response scanf-like format string of response to expect
00221      * @param ... all scanf-like arguments to extract from response
00222      * @return true only if response is successfully matched
00223      */
00224     bool recv(const char *response, ...) MBED_SCANF_METHOD(1, 2);
00225 
00226     bool vrecv(const char *response, std::va_list args);
00227 
00228     /**
00229      * Write a single byte to the underlying stream
00230      *
00231      * @param c The byte to write
00232      * @return The byte that was written or -1 during a timeout
00233      */
00234     int putc(char c);
00235 
00236     /**
00237      * Get a single byte from the underlying stream
00238      *
00239      * @return The byte that was read or -1 during a timeout
00240      */
00241     int getc();
00242 
00243     /**
00244      * Write an array of bytes to the underlying stream
00245      *
00246      * @param data The array of bytes to write
00247      * @param size Number of bytes to write
00248      * @return number of bytes written or -1 on failure
00249      */
00250     int write(const char *data, int size);
00251 
00252     /**
00253      * Read an array of bytes from the underlying stream
00254      *
00255      * @param data The buffer for filling the read bytes
00256      * @param size Number of bytes to read
00257      * @return number of bytes read or -1 on failure
00258      */
00259     int read(char *data, int size);
00260 
00261     /**
00262      * Direct printf to underlying stream
00263      * @see printf
00264      *
00265      * @param format Format string to pass to printf
00266      * @param ... Variable arguments to printf
00267      * @return number of bytes written or -1 on failure
00268      */
00269     int printf(const char *format, ...) MBED_PRINTF_METHOD(1, 2);
00270 
00271     int vprintf(const char *format, std::va_list args);
00272 
00273     /**
00274      * Direct scanf on underlying stream
00275      * @see scanf
00276      *
00277      * @param format Format string to pass to scanf
00278      * @param ... Variable arguments to scanf
00279      * @return number of bytes read or -1 on failure
00280      */
00281     int scanf(const char *format, ...) MBED_SCANF_METHOD(1, 2);
00282 
00283     int vscanf(const char *format, std::va_list args);
00284 
00285     /**
00286      * Attach a callback for out-of-band data
00287      *
00288      * @param prefix String on when to initiate callback
00289      * @param func Callback to call when string is read
00290      * @note out-of-band data is only processed during a scanf call
00291      */
00292     void oob(const char *prefix, mbed::Callback<void()> func);
00293 
00294     /**
00295      * Flushes the underlying stream
00296      */
00297     void flush();
00298 
00299     /**
00300      * Abort current recv
00301      *
00302      * Can be called from out-of-band handler to interrupt the current
00303      * recv operation.
00304      */
00305     void abort();
00306 
00307     /**
00308     * Process out-of-band data
00309     *
00310     * Process out-of-band data in the receive buffer. This function
00311     * returns immediately if there is no data to process.
00312     *
00313     * @return true if out-of-band data processed, false otherwise
00314     */
00315     bool process_oob(void);
00316 };
00317 
00318 /**@}*/
00319 
00320 /**@}*/
00321 
00322 } //namespace mbed
00323 
00324 #endif //MBED_ATCMDPARSER_H