uartat, le910: initial implementation.

uartat is the underlying UART driver, specifically for use with
AT-style command driven devices like modems.

The le910 support is provided in the form of examples that make use
of the uartat driver to interact with the device.

Signed-off-by: Jon Trulson <jtrulson@ics.com>

src/uartat/CMakeLists.txt

@@ -0,0 +1,8 @@
+upm_mixed_module_init (NAME uartat
+    DESCRIPTION "Generic UART driver for serial AT command driven devices"
+    C_HDR uartat.h uartat_defs.h
+    C_SRC uartat.c
+    CPP_HDR uartat.hpp
+    CPP_SRC uartat.cxx
+    CPP_WRAPS_C
+    REQUIRES mraa)

src/uartat/javaupm_uartat.i

@@ -0,0 +1,21 @@
+%module javaupm_uartat
+%include "../upm.i"
+%include "std_string.i"
+%include "stdint.i"
+%include "typemaps.i"
+
+%include "uartat.hpp"
+%{
+    #include "uartat.hpp"
+%}
+
+%pragma(java) jniclasscode=%{
+    static {
+        try {
+            System.loadLibrary("javaupm_uartat");
+        } catch (UnsatisfiedLinkError e) {
+            System.err.println("Native code library failed to load. \n" + e);
+            System.exit(1);
+        }
+    }
+%}

src/uartat/jsupm_uartat.i

@@ -0,0 +1,8 @@
+%module jsupm_uartat
+%include "../upm.i"
+%include "std_string.i"
+
+%include "uartat.hpp"
+%{
+    #include "uartat.hpp"
+%}

src/uartat/pyupm_uartat.i

@@ -0,0 +1,12 @@
+// Include doxygen-generated documentation
+%include "pyupm_doxy2swig.i"
+%module pyupm_uartat
+%include "../upm.i"
+%include "std_string.i"
+
+%feature("autodoc", "3");
+
+%include "uartat.hpp"
+%{
+    #include "uartat.hpp"
+%}

src/uartat/uartat.c

@@ -0,0 +1,412 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#include <string.h>
+#include <assert.h>
+
+#include "uartat.h"
+
+#include "upm_utilities.h"
+
+#define UARTAT_MAX_BUFFER (1024)
+
+// milliseconds
+#define UARTAT_MAX_WAIT   (1000)
+
+// milliseconds
+#define UARTAT_DEFAULT_RESP_DELAY   (250)
+
+static uartat_context _uartat_preinit()
+{
+    // make sure MRAA is initialized
+    int mraa_rv;
+    if ((mraa_rv = mraa_init()) != MRAA_SUCCESS)
+    {
+        printf("%s: mraa_init() failed (%d).\n", __FUNCTION__, mraa_rv);
+        return NULL;
+    }
+
+    uartat_context dev =
+        (uartat_context)malloc(sizeof(struct _uartat_context));
+
+    if (!dev)
+        return NULL;
+
+    // zero out context
+    memset((void *)dev, 0, sizeof(struct _uartat_context));
+
+    dev->cmd_resp_wait_ms = UARTAT_DEFAULT_RESP_DELAY;
+
+    return dev;
+}
+
+static uartat_context _uartat_postinit(uartat_context dev,
+                                       unsigned int baudrate)
+{
+    assert(dev != NULL);
+
+    if (uartat_set_baudrate(dev, baudrate))
+    {
+        printf("%s: uartat_set_baudrate() failed.\n", __FUNCTION__);
+        uartat_close(dev);
+        return NULL;
+    }
+
+    if (uartat_set_flow_control(dev, UARTAT_FLOW_CONTROL_NONE))
+    {
+        printf("%s: uartat_set_flow_control() failed.\n", __FUNCTION__);
+        uartat_close(dev);
+        return NULL;
+    }
+
+    return dev;
+}
+
+// uart init
+uartat_context uartat_init(unsigned int uart, unsigned int baudrate)
+{
+    uartat_context dev;
+
+    if (!(dev = _uartat_preinit()))
+        return NULL;
+
+    // initialize the MRAA context
+
+    // uart, default should be 8N1
+    if (!(dev->uart = mraa_uart_init(uart)))
+    {
+        printf("%s: mraa_uart_init() failed.\n", __FUNCTION__);
+        uartat_close(dev);
+        return NULL;
+    }
+
+    return _uartat_postinit(dev, baudrate);
+}
+
+// uart tty init
+uartat_context uartat_init_tty(const char *uart_tty, unsigned int baudrate)
+{
+    uartat_context dev;
+
+    if (!(dev = _uartat_preinit()))
+        return NULL;
+
+    // initialize the MRAA context
+
+    // uart, default should be 8N1
+    if (!(dev->uart = mraa_uart_init_raw(uart_tty)))
+    {
+        printf("%s: mraa_uart_init_raw() failed.\n", __FUNCTION__);
+        uartat_close(dev);
+        return NULL;
+    }
+
+    return _uartat_postinit(dev, baudrate);
+}
+
+void uartat_close(uartat_context dev)
+{
+    assert(dev != NULL);
+
+    if (dev->uart)
+        mraa_uart_stop(dev->uart);
+
+    free(dev);
+}
+
+int uartat_read(const uartat_context dev, char *buffer, size_t len)
+{
+    assert(dev != NULL);
+
+    // uart
+    return mraa_uart_read(dev->uart, buffer, len);
+}
+
+int uartat_write(const uartat_context dev, const char *buffer, size_t len)
+{
+    assert(dev != NULL);
+
+    int rv = mraa_uart_write(dev->uart, buffer, len);
+    mraa_uart_flush(dev->uart);
+
+    return rv;
+}
+
+bool uartat_data_available(const uartat_context dev, unsigned int millis)
+{
+    assert(dev != NULL);
+
+    if (mraa_uart_data_available(dev->uart, millis))
+        return true;
+    else
+        return false;
+}
+
+upm_result_t uartat_set_baudrate(const uartat_context dev,
+                                 unsigned int baudrate)
+{
+    assert(dev != NULL);
+
+    if (mraa_uart_set_baudrate(dev->uart, baudrate))
+    {
+        printf("%s: mraa_uart_set_baudrate() failed.\n", __FUNCTION__);
+        return UPM_ERROR_OPERATION_FAILED;
+    }
+
+    return UPM_SUCCESS;
+}
+
+void uartat_set_response_wait_time(const uartat_context dev,
+                                   unsigned int wait_time)
+{
+    assert(dev != NULL);
+
+    dev->cmd_resp_wait_ms = wait_time;
+}
+
+bool uartat_command_mode(const uartat_context dev, const char *cmd_chars,
+                         unsigned int guard_ms)
+{
+    assert(dev != NULL);
+
+    uartat_drain(dev);
+
+    upm_delay_ms(guard_ms);
+
+    uartat_write(dev, cmd_chars, strlen(cmd_chars));
+
+    upm_delay_ms(guard_ms);
+
+    char resp[UARTAT_MAX_BUFFER];
+    if (uartat_data_available(dev, UARTAT_MAX_WAIT))
+    {
+        int rv = uartat_read(dev, resp, UARTAT_MAX_BUFFER);
+
+        if (rv > 0 && (strstr(resp, "OK") || strstr(resp, "0")))
+            return true;
+    }
+
+    return false;
+}
+
+bool uartat_in_command_mode(const uartat_context dev)
+{
+    assert(dev != NULL);
+
+    static int buflen = 32;
+    char buffer[buflen];
+
+    if (uartat_command_with_response(dev, "AT\r", buffer, buflen) <= 0)
+        return false;
+
+    // depending on verbosity, you may get "OK" or "0".  Try to catch both.
+    if (strstr(buffer, "OK") || strstr(buffer, "0"))
+        return true;
+    else
+        return false;
+}
+
+void uartat_drain(const uartat_context dev)
+{
+    assert(dev != NULL);
+
+    char resp[UARTAT_MAX_BUFFER];
+    int rv;
+    while (uartat_data_available(dev, 0))
+    {
+        rv = uartat_read(dev, resp, UARTAT_MAX_BUFFER);
+        if (rv < 0)
+        {
+            printf("%s: read failed\n", __FUNCTION__);
+            return;
+        }
+        // printf("%s: Tossed %d bytes\n", __FUNCTION__, rv);
+    }
+
+    return;
+}
+
+int uartat_command_with_response(const uartat_context dev,
+                                 const char *cmd,
+                                 char *resp, size_t resp_len)
+{
+    assert(dev != NULL);
+    assert(cmd != NULL);
+
+    uartat_drain(dev);
+    if (uartat_write(dev, cmd, strlen(cmd)) < 0)
+    {
+        printf("%s: uartat_write failed\n", __FUNCTION__);
+        return -1;
+    }
+
+    if (resp && resp_len > 1)
+    {
+        memset(resp, 0, resp_len);
+
+        upm_clock_t clock;
+        upm_clock_init(&clock);
+
+        int idx = 0;
+
+        do
+        {
+            if (uartat_data_available(dev, 1))
+            {
+                int rv = uartat_read(dev, &resp[idx], 1);
+
+                if (rv < 0)
+                    return rv;
+
+                if (dev->filter_cr && resp[idx] == '\r')
+                    continue;
+
+                if (idx >= resp_len - 1)
+                    return idx;
+
+                idx++;
+            }
+        } while (upm_elapsed_ms(&clock) < dev->cmd_resp_wait_ms);
+
+        return idx;
+    }
+    else
+    {
+        upm_delay_ms(dev->cmd_resp_wait_ms);
+        uartat_drain(dev);
+    }
+
+    return 0;
+}
+
+bool uartat_command_waitfor(const uartat_context dev, const char *cmd,
+                            char *resp, size_t resp_len,
+                            const char *wait_string,
+                            unsigned int millis)
+{
+    assert(dev != NULL);
+    assert(cmd != NULL);
+    assert(resp != NULL);
+    assert(resp_len > 0);
+    assert(wait_string != NULL);
+
+    uartat_drain(dev);
+    if (uartat_write(dev, cmd, strlen(cmd)) < 0)
+    {
+        printf("%s: uartat_write failed\n", __FUNCTION__);
+        return -1;
+    }
+
+    memset(resp, 0, resp_len);
+
+    upm_clock_t clock;
+    upm_clock_init(&clock);
+
+    int idx = 0;
+
+    do
+    {
+        if (uartat_data_available(dev, 1))
+        {
+            int rv = uartat_read(dev, &resp[idx], 1);
+
+            if (rv < 0)
+                return false;
+
+            if (dev->filter_cr && resp[idx] == '\r')
+                continue;
+
+            if (idx >= resp_len - 1)
+            {
+                // one last check
+                if (uartat_find(dev, resp, wait_string))
+                    return true;
+                else
+                    return false;
+            }
+            idx++;
+
+            // see if the string is present
+            if (uartat_find(dev, resp, wait_string))
+                return true;
+        }
+    } while (upm_elapsed_ms(&clock) < millis);
+
+    return false;
+}
+
+void uartat_command(const uartat_context dev, const char *cmd)
+{
+    assert(dev != NULL);
+    assert(cmd != NULL);
+
+    uartat_command_with_response(dev, cmd, NULL, 0);
+}
+
+upm_result_t uartat_set_flow_control(const uartat_context dev,
+                                     UARTAT_FLOW_CONTROL_T fc)
+{
+    assert(dev != NULL);
+
+    mraa_result_t rv = MRAA_SUCCESS;
+
+    switch(fc)
+    {
+    case UARTAT_FLOW_CONTROL_NONE:
+        rv = mraa_uart_set_flowcontrol(dev->uart, false, false);
+        break;
+
+    case UARTAT_FLOW_CONTROL_HARD:
+        rv = mraa_uart_set_flowcontrol(dev->uart, false, true);
+        break;
+
+    case UARTAT_FLOW_CONTROL_SOFT:
+        rv = mraa_uart_set_flowcontrol(dev->uart, true, false);
+        break;
+
+    default:
+        return UPM_ERROR_INVALID_PARAMETER;
+    }
+
+    if (rv == MRAA_SUCCESS)
+        return UPM_SUCCESS;
+    else
+        return UPM_ERROR_OPERATION_FAILED;
+}
+
+bool uartat_find(const uartat_context dev, const char *buffer, const char *str)
+{
+    assert(dev != NULL);
+    assert(buffer != NULL);
+    assert(str != NULL);
+
+    return ((strstr(buffer, str)) ? true : false);
+}
+
+void uartat_filter_cr(const uartat_context dev, bool enable)
+{
+    assert(dev != NULL);
+
+    dev->filter_cr = enable;
+}

src/uartat/uartat.cxx

@@ -0,0 +1,173 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#include <iostream>
+#include <stdexcept>
+#include <string.h>
+
+#include "uartat.hpp"
+
+using namespace upm;
+using namespace std;
+
+UARTAT::UARTAT(unsigned int uart, unsigned int baudrate) :
+    m_uartat(uartat_init(uart, baudrate))
+{
+    if (!m_uartat)
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_init() failed");
+}
+
+UARTAT::UARTAT(string uart_path, unsigned int baudrate) :
+    m_uartat(uartat_init_tty(uart_path.c_str(), baudrate))
+{
+    if (!m_uartat)
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_init_tty() failed");
+}
+
+UARTAT::~UARTAT()
+{
+    uartat_close(m_uartat);
+}
+
+std::string UARTAT::readStr(size_t size)
+{
+    char buffer[size];
+
+    int rv;
+
+    if ((rv = uartat_read(m_uartat, buffer, size)) < 0)
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_read() failed");
+
+    return string(buffer, rv);
+}
+
+int UARTAT::writeStr(std::string buffer)
+{
+    int rv;
+
+    if ((rv = uartat_write(m_uartat, (char*)buffer.data(),
+                           buffer.size())) < 0)
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_write() failed");
+
+    return rv;
+}
+
+void UARTAT::setBaudrate(unsigned int baudrate)
+{
+    if (uartat_set_baudrate(m_uartat, baudrate))
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_baudrate() failed");
+}
+
+void UARTAT::setResponseWaitTime(unsigned int wait_time)
+{
+    uartat_set_response_wait_time(m_uartat, wait_time);
+}
+
+bool UARTAT::dataAvailable(unsigned int millis)
+{
+    return uartat_data_available(m_uartat, millis);
+}
+
+bool UARTAT::commandMode(std::string cmd_chars, unsigned int guard_ms)
+{
+    return uartat_command_mode(m_uartat, cmd_chars.c_str(), guard_ms);
+}
+
+bool UARTAT::inCommandMode()
+{
+    return uartat_in_command_mode(m_uartat);
+}
+
+void UARTAT::drain()
+{
+    uartat_drain(m_uartat);
+    return;
+}
+
+string UARTAT::commandWithResponse(const string cmd, size_t resp_len)
+{
+    char buffer[resp_len];
+
+    int rv;
+
+    if ((rv = uartat_command_with_response(m_uartat, cmd.c_str(), buffer,
+                                           resp_len)) < 0)
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_command_with_response() failed");
+
+    return string(buffer, rv);
+}
+
+string UARTAT::commandWaitFor(const std::string cmd, size_t resp_len,
+                              const std::string waitString,
+                              unsigned int millis)
+{
+    char buffer[resp_len];
+
+    if (uartat_command_waitfor(m_uartat, cmd.c_str(), buffer, resp_len,
+                               waitString.c_str(), millis))
+        return string(buffer, strlen(buffer));
+    else
+        return string("");
+}
+
+void UARTAT::command(const string cmd)
+{
+    uartat_command(m_uartat, cmd.c_str());
+
+    return;
+}
+
+string UARTAT::stringCR2LF(string str)
+{
+  for (size_t i=0; i<str.size(); i++)
+    if (str[i] == '\r')
+      str[i] = '\n';
+
+  return str;
+}
+
+void UARTAT::setFlowControl(UARTAT_FLOW_CONTROL_T fc)
+{
+    if (uartat_set_flow_control(m_uartat, fc))
+        throw std::runtime_error(string(__FUNCTION__)
+                                 + ": uartat_set_flow_control() failed");
+
+    return;
+}
+
+bool UARTAT::find(const std::string buffer, const std::string str)
+{
+    return uartat_find(m_uartat, buffer.c_str(), str.c_str());
+}
+
+void UARTAT::filterCR(bool enable)
+{
+    uartat_filter_cr(m_uartat, enable);
+}

src/uartat/uartat.h

@@ -0,0 +1,282 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#include <upm.h>
+#include <mraa/uart.h>
+
+#include "uartat_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+    /**
+     * @file uartat.h
+     * @library uartat
+     * @brief Generic API for AT command based UART devices
+     *
+     */
+
+    /**
+     * Device context
+     */
+    typedef struct _uartat_context {
+        mraa_uart_context        uart;
+
+        // wait time for reading results after sending a command.  The
+        // default is 250ms.
+        unsigned int cmd_resp_wait_ms;
+
+        // filter carriage returns (CR) out of responses?
+        bool filter_cr;
+    } *uartat_context;
+
+    /**
+     * UARTAT Initializer for generic UART operation using a UART index.
+     *
+     * @param uart Specify which uart to use.
+     * @param baudrate Specify the baudrate to use.
+     * @return an initialized device context on success, NULL on error.
+     */
+    uartat_context uartat_init(unsigned int uart, unsigned int baudrate);
+
+    /**
+     * UARTAT Initializer for generic UART operation using a filesystem
+     * tty path (eg. /dev/ttyUSB0).
+     *
+     * @param uart_tty character string representing a filesystem path to a
+     * serial tty device.
+     * @param baudrate Specify the baudrate to use.
+     * @return an initialized device context on success, NULL on error.
+     */
+    uartat_context uartat_init_tty(const char *uart_tty, unsigned int baudrate);
+
+    /**
+     * UARTAT sensor close function
+     *
+     * @param dev Device context
+     */
+    void uartat_close(uartat_context dev);
+
+    /**
+     * Read character data from the device.
+     *
+     * @param dev Device context
+     * @param buffer The character buffer to read data into.
+     * @param len The maximum size of the buffer
+     * @return The number of bytes successfully read, or -1 on error
+     */
+    int uartat_read(const uartat_context dev, char *buffer, size_t len);
+
+    /**
+     * Write character data to the device.
+     *
+     * @param dev Device context
+     * @param buffer The character buffer containing data to write.
+     * @param len The number of bytes to write.
+     * @return The number of bytes successfully written, or -1 on error.
+     */
+    int uartat_write(const uartat_context dev, const char *buffer, size_t len);
+
+    /**
+     * Set the baudrate of the device.
+     *
+     * @param dev Device context
+     * @param baudrate The baud rate to set for the device.
+     * @return UPM result
+     */
+    upm_result_t uartat_set_baudrate(const uartat_context dev,
+                                     unsigned int baudrate);
+
+    /**
+     * Set the default time, in milliseconds, to wait for data to
+     * arrive after sending a command.
+     *
+     * @param dev Device context
+     * @param wait_ms The response delay to set, in milliseconds.
+     */
+    void uartat_set_response_wait_time(const uartat_context dev,
+                                       unsigned int wait_ms);
+
+    /**
+     * Determine whether there is data available to be read.  This
+     * function will wait up to "millis" milliseconds for data to
+     * become available.
+     *
+     * @param dev Device context
+     * @param millis The number of milliseconds to wait for data to
+     * become available.
+     * @return true if data is available to be read, false otherwise.
+     */
+    bool uartat_data_available(const uartat_context dev,
+                               unsigned int millis);
+
+    /**
+     * Place the device in AT command mode.  Many devices operate in a
+     * transparent mode and an AT command mode.  Command mode is
+     * required to issue AT based commands.  When in transparent mode,
+     * the device will usually listen for a special sequence of
+     * characters and delays, indicating that AT command mode should
+     * be entered.
+     *
+     * On most devices, the sequence is:
+     * <wait 1 second>+++<wait 1 second>
+     *
+     * For most devices, the wait time is 1 second (1000 ms) and the
+     * character sequence is "+++".  These options can often be
+     * configured on the device.
+     *
+     * This function will wait millis milliseconds, write the command
+     * characters (typically "+++"), then wait millis milliseconds again.
+     * At this time a read will be attempted, looking for the "OK"
+     * response indicating command mode was successfully entered.
+     *
+     * @param dev Device context
+     * @param cmd_chars The character sequence to write, typically "+++".
+     * @param guard_ms The number of milliseconds to delay before and
+     * after the cmd_chars are written.
+     * @return true if AT command mode ("OK" detected) was
+     * successfully entered, false otherwise.
+     */
+    bool uartat_command_mode(const uartat_context dev, const char *cmd_chars,
+                             unsigned int guard_ms);
+
+    /**
+     * Check to see if the device is in command mode.  This is
+     * accomplished by sending an "AT\r" command and seeing if "OK" or
+     * "0" is returned.
+     *
+     * @param dev Device context
+     * @return true if AT command mode was detected, false otherwise.
+     */
+    bool uartat_in_command_mode(const uartat_context dev);
+
+    /**
+     * Read and throw away any data currently available to be read.
+     * This is useful to avoid reading data that might have been the
+     * result of a previous command interfering with data you
+     * currently want to read.  This function is automatically called
+     * by uartat_command_with_response(), uartat_command(), and
+     * uartat_command_waitfor() prior to writing the requested command
+     * to the device.
+     *
+     * @param dev Device context
+     */
+    void uartat_drain(const uartat_context dev);
+
+    /**
+     * Send an AT command and optionally return a response.
+     *
+     * @param dev Device context
+     * @param cmd A character string containing the AT command to
+     * send, including the "AT" prefix and a terminating carriage
+     * return ("\r").
+     * @param resp A pointer to a buffer that will contain the
+     * response.  If NULL is specified, the response is ignored.  The
+     * returned string buffer will be 0 terminated like any ordinary C
+     * string.
+     * @param resp_len The length of the supplied response buffer.  If
+     * 0, then any response will be ignored.  No more than resp_len
+     * characters (including the trailing 0 byte) will be returned.
+     * @return The number of bytes read, or -1 on error.
+     */
+    int uartat_command_with_response(const uartat_context dev,
+                                     const char *cmd, char *resp,
+                                     size_t resp_len);
+
+    /**
+     * Send an AT command and ignore any response.  This is a
+     * shorthand version of uartat_command_with_response(), and is
+     * equivalent to calling uartat_command_with_response(dev, cmd,
+     * NULL, 0).
+     *
+     * @param dev Device context
+     * @param cmd The AT command to send, including the "AT" prefix
+     * and a terminating carriage return ("\r").
+     */
+    void uartat_command(const uartat_context dev, const char *cmd);
+
+    /**
+     * Read characters for up to millis milliseconds, returning
+     * as soon as the wait_string is found.
+     *
+     * @param dev Device context
+     * @param cmd The command to send
+     * @param resp The response character buffer
+     * @param resp_len The maximum size of the response buffer
+     * @param wait_string The string to search for
+     * @param millis The maximum number of milliseconds to look for
+     * the wait_string.
+     * @return true if the wait_string was found in the response,
+     * false otherwise.
+     */
+    bool uartat_command_waitfor(const uartat_context dev, const char *cmd,
+                                char *resp, size_t resp_len,
+                                const char *wait_string,
+                                unsigned int millis);
+
+    /**
+     * Set a flow control method for the UART.  By default, during
+     * initialization, flow control is disabled.
+     *
+     * @param dev Device context
+     * @param fc One of the UARTAT_FLOW_CONTROL_T values.
+     * @return the UPM result.
+     */
+    upm_result_t uartat_set_flow_control(const uartat_context dev,
+                                         UARTAT_FLOW_CONTROL_T fc);
+
+    /**
+     * Look for a string in a buffer.  This is a utility function that
+     * can be used to indicate if a given string is present in a
+     * supplied buffer.  The search is case sensitive.
+     *
+     * @param dev Device context
+     * @param buffer The 0 teminated buffer in which to search.
+     * @param str The 0 teminated string to search for.
+     * @return true if the string was found, false otherwise.
+     */
+    bool uartat_find(const uartat_context dev, const char *buffer,
+                     const char *str);
+
+    /**
+     * Filter out carriage returns (CR) from response buffers if
+     * enabled.  This operates only on the response buffers returned
+     * from uartat_command_with_response(), uartat_command(), and
+     * uartat_command_waitfor().
+     *
+     * @param dev Device context
+     * @param enable true to filter out CR's, false otherwise
+     */
+    void uartat_filter_cr(const uartat_context dev, bool enable);
+
+#ifdef __cplusplus
+}
+#endif

src/uartat/uartat.hpp

@@ -0,0 +1,260 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#pragma once
+
+#include <string>
+#include <iostream>
+
+#include "uartat.h"
+
+namespace upm {
+    /**
+     * @brief API for a generic AT command based UART device
+     * @defgroup uartat libupm-uartat
+     * @ingroup uart
+     */
+
+    /**
+     * @library uartat
+     * @sensor uartat
+     * @comname Generic AT command based UART device
+     * @type other
+     * @con uart
+     *
+     * @brief API for a Generic AT command based UART device
+     *
+     * This is a generic UART device driver for accessing UART based
+     * devices that utilize an "AT" command set.  Typically these
+     * devices are Radios, Modems, and similar devices that are
+     * configured and controlled by emitting "AT" commands.
+     */
+
+    class UARTAT {
+    public:
+
+        /**
+         * UARTAT object constructor for a UART specified by MRAA number.
+         *
+         * @param uart Specify which uart to use.
+         * @param baudrate Specify the baudrate to use.
+         */
+        UARTAT(unsigned int uart, unsigned int baudrate);
+
+        /**
+         * UARTAT object constructor for a UART specified by PATH (ex:
+         * /dev/ttyUSB0)
+         *
+         * @param uart_path Specify path of UART device.
+         * @param baudrate Specify the baudrate to use.
+         */
+        UARTAT(std::string uart_path, unsigned int baudrate);
+
+        /**
+         * UARTAT object destructor
+         */
+        ~UARTAT();
+
+        /**
+         * Read character data from the device.
+         *
+         * @param size The maximum number of characters to read.
+         * @return string containing the data read.
+         */
+        std::string readStr(size_t size);
+
+        /**
+         * Write character data to the device.
+         *
+         * @param buffer The string containing the data to write.
+         * @return The number of bytes written.
+         */
+        int writeStr(std::string buffer);
+
+        /**
+         * Set the baudrate of the device.
+         *
+         * @param baudrate The baud rate to set for the device.
+         */
+        void setBaudrate(unsigned int baudrate);
+
+        /**
+         * Set the default time, in milliseconds, to wait for data to
+         * arrive after sending a command.
+         *
+         * @param wait_ms The response delay to set, in milliseconds.
+         */
+        void setResponseWaitTime(unsigned int wait_time);
+
+        /**
+         * Determine whether there is data available to be read.  In the
+         * case of a UART, this function will wait up to "millis"
+         * milliseconds for data to become available.  In the case of an I2C
+         * device, the millis argument is ignored and the function will
+         * return immediately, indicating whether data is available.
+         *
+         * @param millis The number of milliseconds to wait for data to
+         * become available.
+         * @return true if data is available to be read, false otherwise.
+         */
+        bool dataAvailable(unsigned int millis);
+
+        /**
+         * Place the device in AT command mode.  Many devices operate in a
+         * transparent mode and an AT command mode.  Command mode is
+         * required to issue AT based commands.  When in transparent mode,
+         * the device will usually listen for a special sequence of
+         * characters and delays, indicating that AT command mode should
+         * be entered.
+         *
+         * On most devices, the sequence is:
+         * <wait 1 second>+++<wait 1 second>
+         *
+         * For most devices, the wait time is 1 second (1000 ms) and the
+         * character sequence is "+++".  These options can often be
+         * configured on the device.
+         *
+         * This function will wait millis milliseconds, write the command
+         * characters (typically "+++"), then wait millis milliseconds again.
+         * At this time a read will be attempted, looking for the "OK"
+         * response indicating command mode was successfully entered.
+         *
+         * @param cmd_chars The character sequence to write, typically "+++".
+         * @param guard_ms The number of milliseconds to delay before and
+         * after the cmd_chars are written.
+         * @return true if AT command mode ("OK" detected) was
+         * successfully entered, false otherwise.
+         */
+        bool commandMode(const std::string cmd_chars, unsigned int guard_ms);
+
+        /**
+         * Check to see if the device is in command mode.  This is
+         * accomplished by sending an "AT\r" command and seeing if
+         * "OK" or "0" is returned.
+         *
+         * @return true if AT command mode was detected, false otherwise.
+         */
+        bool inCommandMode();
+
+        /**
+         * Read and throw away any data currently available to be
+         * read.  This is useful to avoid reading data that might have
+         * been the result of a previous command interfering with data
+         * you currently want to read.  This function is automatically
+         * called by commandWithResponse(), command(), and
+         * commandWaitfor() prior to writing the requested command to
+         * the device.
+         *
+         */
+        void drain();
+
+        /**
+         * Send an AT command and optionally return a response.
+         *
+         * @param cmd A character string containing the AT command to
+         * send, including the "AT" prefix and a terminating carriage
+         * return ("\r").
+         * @param resp_len The maximum number of characters to read from the
+         * device.
+         * @return The device response string, if any.
+         */
+        std::string commandWithResponse(const std::string cmd, size_t resp_len);
+
+        /**
+         * Send an AT command and return a response, while waiting for
+         * a specific string.  If the string isn't found the returned
+         * string will be empty.  If the string is found, the function
+         * will return immediately.
+         *
+         * @param cmd A character string containing the AT command to
+         * send, including the "AT" prefix and a terminating carriage
+         * return ("\r").
+         * @param resp_len The maximum number of characters to read from the
+         * device.
+         * @param wait_string The string to look for.  If found, the
+         * response will be returned immediately regardless of the
+         * timeout setting.
+         * @param millis The maximum number of milliseconds to wait
+         * for the string.
+         * @return A string containing the response if the search
+         * string was found, otherwise and empty string is returned.
+         */
+        std::string commandWaitFor(const std::string cmd, size_t resp_len,
+                                   const std::string waitString,
+                                   unsigned int millis);
+
+        /**
+         * Send an AT command and ignore any response.
+         *
+         * @param cmd The AT command to send, including the "AT" prefix
+         * and a terminating carriage return ("\r").
+         */
+        void command(const std::string cmd);
+
+        /**
+         * This is a convenience method that converts each CR (\r) in a
+         * string to a LF (\n) and returns it.  This is useful for
+         * outputting the response to an AT command for instance, which is
+         * often CR terminated.
+         *
+         * @param str The string to convert
+         * @return The converted string
+         */
+        std::string stringCR2LF(std::string str);
+
+        /**
+         * Set a flow control method for the UART.  By default, during
+         * initialization, flow control is disabled.
+         *
+         * @param fc One of the UARTAT_FLOW_CONTROL_T values.
+         */
+        void setFlowControl(UARTAT_FLOW_CONTROL_T fc);
+
+        /**
+         * Look for a string in a buffer.  This is a utility function that
+         * can be used to indicate if a given string is present in a
+         * supplied buffer.  The search is case sensitive.
+         *
+         * @param buffer The string buffer in which to search.
+         * @param str The string to search for.
+         * @return true if the string was found, false otherwise.
+         */
+        bool find(const std::string buffer, const std::string str);
+
+        /**
+         * Filter out carriage returns (CR) from response buffers if
+         * enabled.  This operates only on the response buffers returned
+         * from commandWithResponse(), command(), and
+         * commandWaitfor().
+         *
+         * @param enable true to filter out CR's, false otherwise
+         */
+        void filterCR(bool enable);
+
+    protected:
+        // uartat device context
+        uartat_context m_uartat;
+
+    private:
+    };
+}

src/uartat/uartat_defs.h

@@ -0,0 +1,54 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+    // possible flow control methods
+    typedef enum {
+        UARTAT_FLOW_CONTROL_NONE           = 0,
+        UARTAT_FLOW_CONTROL_HARD,          // hardware flow control
+        UARTAT_FLOW_CONTROL_SOFT           // software flow control
+    } UARTAT_FLOW_CONTROL_T;
+
+
+    // Numeric response codes via ITU-T V25Ter recommendations
+    typedef enum {
+        UARTAT_RESPONSE_CODE_OK            = 0,
+        UARTAT_RESPONSE_CODE_CONNECT       = 1,
+        UARTAT_RESPONSE_CODE_RING          = 2,
+        UARTAT_RESPONSE_CODE_NO_CARRIER    = 3,
+        UARTAT_RESPONSE_CODE_ERROR         = 4,
+        // 5 unassigned
+        UARTAT_RESPONSE_CODE_NO_DIALTONE   = 6,
+        UARTAT_RESPONSE_CODE_BUSY          = 7,
+        UARTAT_RESPONSE_CODE_NO_ANSWER     = 8
+    } UARTAT_RESPONSE_CODE_T;
+
+#ifdef __cplusplus
+}
+#endif