From 4a04c9ce5deddab56c885e44b71f41ec13c2d49c Mon Sep 17 00:00:00 2001 From: Hasnain Virk Date: Thu, 16 Feb 2017 01:58:24 +0200 Subject: [PATCH] Extending ATParser to use FileHandle Existing ATParser is extended to use FileHandle. This essentially detaches ATParser from previous tight binding with various implementations of serial interfaces with buffering. Now the ATParser uses only abstract FileHandle and doesn't really care about the underlying implementation. Underneath, it could be a USB device type FileHandle or a Serial device type FileHandle etc. Some simplification steps were taken as the code provided opportunities to simplify and optimize. --- platform/ATParser.cpp | 382 ++++++++++++++++++++++++++++++++++++++ platform/ATParser.h | 281 ++++++++++++++++++++++++++++ platform/mbed_toolchain.h | 32 ++++ 3 files changed, 695 insertions(+) create mode 100644 platform/ATParser.cpp create mode 100644 platform/ATParser.h diff --git a/platform/ATParser.cpp b/platform/ATParser.cpp new file mode 100644 index 0000000000..f3ba31bce0 --- /dev/null +++ b/platform/ATParser.cpp @@ -0,0 +1,382 @@ +/* Copyright (c) 2017 ARM Limited + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @section DESCRIPTION + * + * Parser for the AT command syntax + * + */ + +#include "ATParser.h" +#include "mbed_poll.h" +#include "mbed_debug.h" + +#ifdef LF +#undef LF +#define LF 10 +#else +#define LF 10 +#endif + +#ifdef CR +#undef CR +#define CR 13 +#else +#define CR 13 +#endif + +// getc/putc handling with timeouts +int ATParser::putc(char c) +{ + pollfh fhs; + fhs.fh = _fh; + fhs.events = POLLOUT; + + int count = poll(&fhs, 1, _timeout); + if (count > 0 && (fhs.revents & POLLOUT)) { + return _fh->write(&c, 1) == 1 ? 0 : -1; + } else { + return -1; + } +} + +int ATParser::getc() +{ + pollfh fhs; + fhs.fh = _fh; + fhs.events = POLLIN; + + int count = poll(&fhs, 1, _timeout); + if (count > 0 && (fhs.revents & POLLIN)) { + unsigned char ch; + return _fh->read(&ch, 1) == 1 ? ch : -1; + } else { + return -1; + } +} + +void ATParser::flush() +{ + while (_fh->readable()) { + unsigned char ch; + _fh->read(&ch, 1); + } +} + + +// read/write handling with timeouts +int ATParser::write(const char *data, int size) +{ + int i = 0; + for ( ; i < size; i++) { + if (putc(data[i]) < 0) { + return -1; + } + } + return i; +} + +int ATParser::read(char *data, int size) +{ + int i = 0; + for ( ; i < size; i++) { + int c = getc(); + if (c < 0) { + return -1; + } + data[i] = c; + } + return i; +} + + +// printf/scanf handling +int ATParser::vprintf(const char *format, va_list args) +{ + + if (vsprintf(_buffer, format, args) < 0) { + return false; + } + + int i = 0; + for ( ; _buffer[i]; i++) { + if (putc(_buffer[i]) < 0) { + return -1; + } + } + return i; +} + +int ATParser::vscanf(const char *format, va_list args) +{ + // Since format is const, we need to copy it into our buffer to + // add the line's null terminator and clobber value-matches with asterisks. + // + // We just use the beginning of the buffer to avoid unnecessary allocations. + int i = 0; + int offset = 0; + + while (format[i]) { + if (format[i] == '%' && format[i+1] != '%' && format[i+1] != '*') { + _buffer[offset++] = '%'; + _buffer[offset++] = '*'; + i++; + } else { + _buffer[offset++] = format[i++]; + } + } + + // Scanf has very poor support for catching errors + // fortunately, we can abuse the %n specifier to determine + // if the entire string was matched. + _buffer[offset++] = '%'; + _buffer[offset++] = 'n'; + _buffer[offset++] = 0; + + // To workaround scanf's lack of error reporting, we actually + // make two passes. One checks the validity with the modified + // format string that only stores the matched characters (%n). + // The other reads in the actual matched values. + // + // We keep trying the match until we succeed or some other error + // derails us. + int j = 0; + + while (true) { + // Ran out of space + if (j+1 >= _buffer_size - offset) { + return false; + } + // Recieve next character + int c = getc(); + if (c < 0) { + return -1; + } + _buffer[offset + j++] = c; + _buffer[offset + j] = 0; + + // Check for match + int count = -1; + sscanf(_buffer+offset, _buffer, &count); + + // We only succeed if all characters in the response are matched + if (count == j) { + // Store the found results + vsscanf(_buffer+offset, format, args); + return j; + } + } +} + + +// Command parsing with line handling +bool ATParser::vsend(const char *command, va_list args) +{ + // Create and send command + if (vsprintf(_buffer, command, args) < 0) { + return false; + } + + for (int i = 0; _buffer[i]; i++) { + if (putc(_buffer[i]) < 0) { + return false; + } + } + + // Finish with newline + for (size_t i = 0; _output_delimiter[i]; i++) { + if (putc(_output_delimiter[i]) < 0) { + return false; + } + } + + debug_if(_dbg_on, "AT> %s\n", _buffer); + return true; +} + +bool ATParser::vrecv(const char *response, va_list args) +{ + _aborted = false; + // Iterate through each line in the expected response + while (response[0]) { + // Since response is const, we need to copy it into our buffer to + // add the line's null terminator and clobber value-matches with asterisks. + // + // We just use the beginning of the buffer to avoid unnecessary allocations. + int i = 0; + int offset = 0; + bool whole_line_wanted = false; + + while (response[i]) { + if (response[i] == '%' && response[i+1] != '%' && response[i+1] != '*') { + _buffer[offset++] = '%'; + _buffer[offset++] = '*'; + i++; + } else { + _buffer[offset++] = response[i++]; + // Find linebreaks, taking care not to be fooled if they're in a %[^\n] conversion specification + if (response[i - 1] == '\n' && !(i >= 3 && response[i-3] == '[' && response[i-2] == '^')) { + whole_line_wanted = true; + break; + } + } + } + + // Scanf has very poor support for catching errors + // fortunately, we can abuse the %n specifier to determine + // if the entire string was matched. + _buffer[offset++] = '%'; + _buffer[offset++] = 'n'; + _buffer[offset++] = 0; + + debug_if(_dbg_on, "AT? %s\n", _buffer); + // To workaround scanf's lack of error reporting, we actually + // make two passes. One checks the validity with the modified + // format string that only stores the matched characters (%n). + // The other reads in the actual matched values. + // + // We keep trying the match until we succeed or some other error + // derails us. + int j = 0; + char in_prev = 0; + + + while (true) { + // Receive next character + int c = getc(); + if (c < 0) { + debug_if(_dbg_on, "AT(Timeout)\n"); + return false; + } + // Simplify newlines (borrowed from retarget.cpp) + if ((c == CR && _in_prev != LF) || + (c == LF && _in_prev != CR)) { + _in_prev = c; + c = '\n'; + } else if ((c == CR && _in_prev == LF) || + (c == LF && _in_prev == CR)) { + _in_prev = c; + // onto next character + continue; + } else { + in_prev = c; + } + _buffer[offset + j++] = c; + _buffer[offset + j] = 0; + + // Check for oob data + for (struct oob *oob = _oobs; oob; oob = oob->next) { + if ((unsigned)j == oob->len && memcmp( + oob->prefix, _buffer+offset, oob->len) == 0) { + debug_if(_dbg_on, "AT! %s\n", oob->prefix); + oob->cb(); + + if (_aborted) { + debug_if(_dbg_on, "AT(Aborted)\n"); + return false; + } + // oob may have corrupted non-reentrant buffer, + // so we need to set it up again + return vrecv(response, args); + } + } + + // Check for match + int count = -1; + if (whole_line_wanted && c != '\n') { + // Don't attempt scanning until we get delimiter if they included it in format + // This allows recv("Foo: %s\n") to work, and not match with just the first character of a string + // (scanf does not itself match whitespace in its format string, so \n is not significant to it) + } else { + sscanf(_buffer+offset, _buffer, &count); + } + + // We only succeed if all characters in the response are matched + if (count == j) { + debug_if(_dbg_on, "AT= %s\n", _buffer+offset); + // Reuse the front end of the buffer + memcpy(_buffer, response, i); + _buffer[i] = 0; + + // Store the found results + vsscanf(_buffer+offset, _buffer, args); + + // Jump to next line and continue parsing + response += i; + break; + } + + // Clear the buffer when we hit a newline or ran out of space + // running out of space usually means we ran into binary data + if (c == '\n' || j+1 >= _buffer_size - offset) { + debug_if(_dbg_on, "AT< %s", _buffer+offset); + j = 0; + } + } + } + + return true; +} + +// Mapping to vararg functions +int ATParser::printf(const char *format, ...) +{ + va_list args; + va_start(args, format); + int res = vprintf(format, args); + va_end(args); + return res; +} + +int ATParser::scanf(const char *format, ...) +{ + va_list args; + va_start(args, format); + int res = vscanf(format, args); + va_end(args); + return res; +} + +bool ATParser::send(const char *command, ...) +{ + va_list args; + va_start(args, command); + bool res = vsend(command, args); + va_end(args); + return res; +} + +bool ATParser::recv(const char *response, ...) +{ + va_list args; + va_start(args, response); + bool res = vrecv(response, args); + va_end(args); + return res; +} + +// oob registration +void ATParser::oob(const char *prefix, Callback cb) +{ + struct oob oob; + oob.len = strlen(prefix); + oob.prefix = prefix; + oob.cb = cb; + _oobs.push_back(oob); +} + +void ATParser::abort() +{ + _aborted = true; +} diff --git a/platform/ATParser.h b/platform/ATParser.h new file mode 100644 index 0000000000..a66bb9acf5 --- /dev/null +++ b/platform/ATParser.h @@ -0,0 +1,281 @@ +/* Copyright (c) 2017 ARM Limited + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @section DESCRIPTION + * + * Parser for the AT command syntax + * + */ +#ifndef MBED_ATPARSER_H +#define MBED_ATPARSER_H + +#include "mbed.h" +#include +#include "BufferedSerial.h" +#include "Callback.h" + + +/** +* Parser class for parsing AT commands +* +* Here are some examples: +* @code +* ATParser at = ATParser(serial, "\r\n"); +* int value; +* char buffer[100]; +* +* at.send("AT") && at.recv("OK"); +* at.send("AT+CWMODE=%d", 3) && at.recv("OK"); +* at.send("AT+CWMODE?") && at.recv("+CWMODE:%d\r\nOK", &value); +* at.recv("+IPD,%d:", &value); +* at.read(buffer, value); +* at.recv("OK"); +* @endcode +*/ +class ATParser +{ +private: + // File handle + // Not owned by ATParser + FileHandle *_fh; + + int _buffer_size; + char *_buffer; + int _timeout; + + // Parsing information + const char *_output_delimiter; + int _output_delim_size; + bool _dbg_on; + bool _aborted; + + struct oob { + unsigned len; + const char *prefix; + mbed::Callback cb; + }; + std::vector _oobs; + + // Prohibiting use of of copy constructor + ATParser(const ATParser &); + // Prohibiting copy assignment Operator + ATParser &operator=(const ATParser &); + +public: + /** + * Constructor + * + * @param serial serial interface to use for AT commands + * @param buffer_size size of internal buffer for transaction + * @param timeout timeout of the connection + * @param debug turns on/off debug output for AT commands + */ + ATParser(FileHandle *fh, const char *output_delimiter="\r", int buffer_size = 256, int timeout = 8000, bool debug = true) : + _fh(fh), + _buffer_size(buffer_size) { + _buffer = new char[buffer_size]; + set_timeout(timeout); + set_delimiter(output_delimiter); + debug_on(debug); + } + + /** + * Destructor + */ + ~ATParser() { + delete [] _buffer; + } + + /** + * Allows timeout to be changed between commands + * + * @param timeout timeout of the connection + */ + void set_timeout(int timeout) { + _timeout = timeout; + } + + /** + * For backwards compatibility. + * + * Please use set_timeout(int) API only from now on. + * Allows timeout to be changed between commands + * + * @param timeout timeout of the connection + */ + MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_timeout for consistency") + void setTimeout(int timeout) { + set_timeout(timeout); + } + + /** + * Sets string of characters to use as line delimiters + * + * @param delimiter string of characters to use as line delimiters + */ + void set_delimiter(const char *output_delimiter) + { + _output_delimiter = output_delimiter; + _output_delim_size = strlen(output_delimiter); + } + + /** + * For backwards compatibility. + * + * Please use set_delimiter(const char *) API only from now on. + * Sets string of characters to use as line delimiters + * + * @param delimiter string of characters to use as line delimiters + */ + MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with set_delimiter for consistency") + void setDelimiter(const char *output_delimiter) + { + set_delimiter(output_delimiter); + } + + /** + * Allows echo to be on or off + * + * @param echo 1 for echo and 0 turns it off + */ + void debug_on(uint8_t on) { + _dbg_on = (on) ? 1 : 0; + } + + /** + * For backwards compatibility. + * + * Allows echo to be on or off + * + * @param echo 1 for echo and 0 turns it off + */ + MBED_DEPRECATED_SINCE("mbed-os-5.5.0", "Replaced with debug_on for consistency") + void debugOn(uint8_t on) { + debug_on(on); + } + + /** + * Sends an AT command + * + * Sends a formatted command using printf style formatting + * @see ::printf + * + * @param command printf-like format string of command to send which + * is appended with a newline + * @param ... all printf-like arguments to insert into command + * @return true only if command is successfully sent + */ + bool send(const char *command, ...) MBED_PRINTF_METHOD(1,2); + + bool vsend(const char *command, va_list args); + + /** + * Receive an AT response + * + * Receives a formatted response using scanf style formatting + * @see ::scanf + * + * Responses are parsed line at a time. + * Any received data that does not match the response is ignored until + * a timeout occurs. + * + * @param response scanf-like format string of response to expect + * @param ... all scanf-like arguments to extract from response + * @return true only if response is successfully matched + */ + bool recv(const char *response, ...) MBED_SCANF_METHOD(1,2); + + bool vrecv(const char *response, va_list args); + + /** + * Write a single byte to the underlying stream + * + * @param c The byte to write + * @return The byte that was written or -1 during a timeout + */ + int putc(char c); + + /** + * Get a single byte from the underlying stream + * + * @return The byte that was read or -1 during a timeout + */ + int getc(); + + /** + * Write an array of bytes to the underlying stream + * + * @param data the array of bytes to write + * @param size number of bytes to write + * @return number of bytes written or -1 on failure + */ + int write(const char *data, int size); + + /** + * Read an array of bytes from the underlying stream + * + * @param data the destination for the read bytes + * @param size number of bytes to read + * @return number of bytes read or -1 on failure + */ + int read(char *data, int size); + + /** + * Direct printf to underlying stream + * @see ::printf + * + * @param format format string to pass to printf + * @param ... arguments to printf + * @return number of bytes written or -1 on failure + */ + int printf(const char *format, ...) MBED_PRINTF_METHOD(1,2); + + int vprintf(const char *format, va_list args); + + /** + * Direct scanf on underlying stream + * @see ::scanf + * + * @param format format string to pass to scanf + * @param ... arguments to scanf + * @return number of bytes read or -1 on failure + */ + int scanf(const char *format, ...) MBED_SCANF_METHOD(1,2); + + int vscanf(const char *format, va_list args); + + /** + * Attach a callback for out-of-band data + * + * @param prefix string on when to initiate callback + * @param func callback to call when string is read + * @note out-of-band data is only processed during a scanf call + */ + void oob(const char *prefix, mbed::Callback func); + + /** + * Flushes the underlying stream + */ + void flush(); + + /** + * Abort current recv + * + * Can be called from oob handler to interrupt the current + * recv operation. + */ + void abort(); +}; + +#endif //MBED_ATPARSER_H diff --git a/platform/mbed_toolchain.h b/platform/mbed_toolchain.h index 9b2238fe97..a2dae81645 100644 --- a/platform/mbed_toolchain.h +++ b/platform/mbed_toolchain.h @@ -278,6 +278,38 @@ #endif #endif +#ifndef MBED_PRINTF +#if defined(__GNUC__) || defined(__CC_ARM) +#define MBED_PRINTF(format_idx, first_param_idx) __attribute__ ((__format__(__printf__, format_idx, first_param_idx))) +#else +#define MBED_PRINTF(format_idx, first_param_idx) +#endif +#endif + +#ifndef MBED_PRINTF_METHOD +#if defined(__GNUC__) || defined(__CC_ARM) +#define MBED_PRINTF_METHOD(format_idx, first_param_idx) __attribute__ ((__format__(__printf__, format_idx+1, first_param_idx+1))) +#else +#define MBED_PRINTF_METHOD(format_idx, first_param_idx) +#endif +#endif + +#ifndef MBED_SCANF +#if defined(__GNUC__) || defined(__CC_ARM) +#define MBED_SCANF(format_idx, first_param_idx) __attribute__ ((__format__(__scanf__, format_idx, first_param_idx))) +#else +#define MBED_SCANF(format_idx, first_param_idx) +#endif +#endif + +#ifndef MBED_SCANF_METHOD +#if defined(__GNUC__) || defined(__CC_ARM) +#define MBED_SCANF_METHOD(format_idx, first_param_idx) __attribute__ ((__format__(__scanf__, format_idx+1, first_param_idx+1))) +#else +#define MBED_SCANF_METHOD(format_idx, first_param_idx) +#endif +#endif + // FILEHANDLE declaration #if defined(TOOLCHAIN_ARM) #include