lcdks: renamed from sainsmartks, added backlight support

The sainsmartks driver has been reimplemented in it's own, new C/C++
library: lcdks (LCD Keypad Shield).

In addition, support for an optional backlight GPIO was added.

This was tested with the SainsmartKS and DFRobot LCD Keypad Shields.

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

docs/apichanges.md

@@ -6,6 +6,33 @@ compatibility between releases:
 
 # current master
 
+ * **sainsmartks** This driver has been renamed to *lcdks* (LCD Keypad
+ Shield) and moved into it's own library.  It uses the *lcm1602*
+ library to do most of it's work.  In addition, an additional argument
+ was added to the constructor to optionally allow specifying a GPIO
+ pin to be used to control the backlight.  This driver supports the
+ SainsmartKS and DFRobot LCD Keypad Shields.  Similiar devices from
+ other manufacturers should also work with this driver.
+
+ * **lcm1602/jhd1313m1** These drivers had been rewritten in C, with
+ C++ wrappers and placed into their own libraries in the previous
+ version of UPM, however, the original C++ implementation was kept in
+ the lcd/i2clcd library for compatibility reasons with existing code.
+ To avoid collisions with the header files, the new *lcm1602* and
+ *jhd1313m1* drivers had their C++ headers renamed to use a **.hxx**
+ suffix.
+
+ In this version of UPM, the *lcm1602* and *jhd1313m1* drivers have
+ been removed from the lcd/i2clcd library.  In addition, the header
+ files for the new implementation have been renamed from their **.hxx**
+ suffix to the normal **.hpp** suffix.
+
+ A change was also made to the new *lcm1602* and *jhd1313m1* C++
+ drivers.  The *createChar()* function now accepts a byte vector
+ *std::vector<uint8_t>* rather than the *char ** pointer that was
+ used previously.  This should make it easier to use with the SWIG
+ language bindings (Python, Javascript, and especially Java).
+
  * **bmp280/bme280** Some private methods are no longer exposed
  (such as the calibration and compensation routines).  In addition,
  the *getHumidity()* method no longer accepts an argument representing
@@ -20,8 +47,7 @@ compatibility between releases:
  "natural" looking Python/Javascript/Java code.  For Javascript, Java,
  and Python, the examples have been modified to use these methods
  rather than the methods that return data in argument pointers or
- arrays.  The "old style" C pointer API's are still present for
- backwards compatibility, but may be removed in the future.
+ arrays.
 
 # v1.1.0
 

examples/c++/CMakeLists.txt

@@ -332,6 +332,7 @@ add_example (max30100)
 add_example (sensortemplate)
 add_example (p9813)
 add_example (abpdrrt005pg2a5)
+add_example (lcdks)
 
 # These are special cases where you specify example binary, source file and module(s)
 include_directories (${PROJECT_SOURCE_DIR}/src)
@@ -343,7 +344,6 @@ add_custom_example (es08a-example-cxx es08a.cxx servo)
 add_custom_example (ssd1306-oled-example-cxx ssd1306-oled.cxx lcd)
 add_custom_example (ssd1308-oled-example-cxx ssd1308-oled.cxx lcd)
 add_custom_example (ssd1327-oled-example-cxx ssd1327-oled.cxx lcd)
-#add_custom_example (sainsmartks-example-cxx sainsmartks.cxx lcd)
 add_custom_example (eboled-example-cxx eboled.cxx lcd)
 add_custom_example (mpu60x0-example-cxx mpu60x0.cxx mpu9150)
 add_custom_example (ak8975-example-cxx ak8975.cxx mpu9150)

examples/c++/lcdks.cxx

@@ -1,6 +1,8 @@
 /*
  * Author: Jon Trulson <jtrulson@ics.com>
- * Copyright (c) 2015 Intel Corporation.
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * The MIT License
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files (the
@@ -26,41 +28,46 @@
 #include <signal.h>
 #include <iostream>
 
-#include "sainsmartks.hpp"
+#include "lcdks.hpp"
 
 using namespace std;
 
-int shouldRun = true;
+bool shouldRun = true;
 
 void sig_handler(int signo)
 {
-  if (signo == SIGINT)
-    shouldRun = false;
+    if (signo == SIGINT)
+        shouldRun = false;
 }
 
 
 int main(int argc, char **argv)
 {
-  signal(SIGINT, sig_handler);
-
-//! [Interesting]
-  // use default pins
-  upm::SAINSMARTKS* lcd = new upm::SAINSMARTKS();
-  lcd->setCursor(0,0);
-  lcd->write("Sainsmart KS");
-  lcd->setCursor(1,2);
-  lcd->write("Hello World");
-
-  // output current key value every second.
-   while (shouldRun)
-     {
-       cout << "Button value: " << lcd->getRawKeyValue() << endl;
-       sleep(1);
-     }
+    signal(SIGINT, sig_handler);
 
 //! [Interesting]
 
-  delete lcd;
-  
-  return 0;
+    // Instantiate a LCDKS (LCD Keypad Shield) using default pins
+
+    // NOTE: The default pins do not include support for a gpio
+    // controlled backlight.  If you need one, you will need to specify
+    // all neccessary pins to the constructor.
+    upm::LCDKS* lcd = new upm::LCDKS();
+
+    lcd->setCursor(0,0);
+    lcd->write("LCDKS driver");
+    lcd->setCursor(1,2);
+    lcd->write("Hello World");
+
+    // output current key value every second.
+    while (shouldRun)
+    {
+        cout << "Button value: " << lcd->getKeyValue() << endl;
+        sleep(1);
+    }
+
+    delete lcd;
+
+//! [Interesting]
+    return 0;
 }

examples/c/CMakeLists.txt

@@ -152,6 +152,7 @@ add_example (nunchuck)
 add_example (bno055)
 add_example (bmp280)
 add_example (abpdrrt005pg2a5)
+add_example (lcdks)
 
 # Custom examples
 add_custom_example (nmea_gps_i2c-example-c nmea_gps_i2c.c nmea_gps)

examples/c/lcdks.c

@@ -0,0 +1,89 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * The MIT License
+ *
+ * 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 <unistd.h>
+#include <signal.h>
+#include <stdio.h>
+
+#include "upm_utilities.h"
+#include "lcdks.h"
+
+bool shouldRun = true;
+
+void sig_handler(int signo)
+{
+    if (signo == SIGINT)
+        shouldRun = false;
+}
+
+
+int main(int argc, char **argv)
+{
+    signal(SIGINT, sig_handler);
+
+//! [Interesting]
+
+    // Instantiate a LCDKS (LCD Keypad Shield) using default pins
+
+    // LCD connection:
+    // LCD RS pin to digital pin 8
+    // LCD Enable pin to digital pin 9
+    // LCD D4 pin to digital pin 4
+    // LCD D5 pin to digital pin 5
+    // LCD D6 pin to digital pin 6
+    // LCD D7 pin to digital pin 7
+    // Keypad analog pin 0
+    // Backlight GPIO -1 (disabled)
+
+    // NOTE: The default pins do not include support for a gpio
+    // controlled backlight.  If you need one, specify the correct pin
+    // as the last argument instead of -1.
+    lcdks_context lcd = lcdks_init(8, 9, 4, 5, 6, 7, 0, -1);
+
+    if (!lcd)
+    {
+        printf("lcdks_init() failed.\n");
+        return 1;
+    }
+
+
+    lcdks_set_cursor(lcd, 0, 0);
+    lcdks_write(lcd, "LCDKS driver", 12);
+    lcdks_set_cursor(lcd, 1, 2);
+    lcdks_write(lcd, "Hello World", 11);
+
+    // output current key value every second.
+    while (shouldRun)
+    {
+        printf("Button value: %f\n", lcdks_get_key_value(lcd));
+        upm_delay(1);
+    }
+
+    lcdks_close(lcd);
+
+//! [Interesting]
+    return 0;
+}

examples/javascript/lcdks.js

@@ -1,6 +1,8 @@
 /*
  * Author: Jon Trulson <jtrulson@ics.com>
- * Copyright (c) 2015 Intel Corporation.
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * The MIT License
  *
  * Permission is hereby granted, free of charge, to any person obtaining
  * a copy of this software and associated documentation files (the
@@ -22,29 +24,32 @@
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-var sainsmartObj = require('jsupm_i2clcd');
+var lcdksObj = require('jsupm_lcdks');
 
-// Instantiate a Sainsmart LCD Keypad Shield using default pins
-var lcd = new sainsmartObj.SAINSMARTKS();
+// Instantiate a LCDKS (LCD Keypad Shield) using default pins
+
+// NOTE: The default pins do not include support for a gpio
+// controlled backlight.  If you need one, you will need to specify
+// all neccessary pins to the constructor.
+var lcd = new lcdksObj.LCDKS();
 
 lcd.setCursor(0,0);
-lcd.write("Sainsmart KS");
+lcd.write("LCDKS driver");
 lcd.setCursor(1,2);
 lcd.write("Hello World");
 
 // output current key value every second.
 setInterval(function()
 {
-    console.log("Button value: " + lcd.getRawKeyValue());
+    console.log("Button value: " + lcd.getKeyValue());
 }, 1000);
 
 // exit on ^C
 process.on('SIGINT', function()
 {
     lcd = null;
-    sainsmartObj.cleanUp();
-    sainsmartObj = null;
+    lcdksObj.cleanUp();
+    lcdksObj = null;
     console.log("Exiting.");
     process.exit(0);
 });
-

examples/python/lcdks.py

@@ -1,6 +1,8 @@
 #!/usr/bin/python
 # Author: Jon Trulson <jtrulson@ics.com>
-# Copyright (c) 2015 Intel Corporation.
+# Copyright (c) 2017 Intel Corporation.
+#
+# The MIT License
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -23,7 +25,7 @@
 
 from __future__ import print_function
 import time, sys, signal, atexit
-from upm import pyupm_i2clcd as sainsmartObj
+from upm import pyupm_lcdks as lcdksObj
 
 def main():
     ## Exit handlers ##
@@ -32,7 +34,6 @@ def main():
         raise SystemExit
 
     # This function lets you run code on exit,
-    # including functions from ringCoder
     def exitHandler():
         print("Exiting")
         sys.exit(0)
@@ -41,17 +42,21 @@ def main():
     atexit.register(exitHandler)
     signal.signal(signal.SIGINT, SIGINTHandler)
 
-    # Instantiate a Sainsmart LCD Keypad Shield using default pins
-    lcd = sainsmartObj.SAINSMARTKS()
+    # Instantiate a LCDKS (LCD Keypad Shield) using default pins
+
+    # NOTE: The default pins do not include support for a gpio
+    # controlled backlight.  If you need one, you will need to specify
+    # all neccessary pins to the constructor.
+    lcd = lcdksObj.LCDKS()
 
     lcd.setCursor(0,0)
-    lcd.write("Sainsmart KS")
+    lcd.write("LCDKS driver")
     lcd.setCursor(1,2)
     lcd.write("Hello World")
 
     # output current key value every second.
     while(1):
-        print("Button value: ", lcd.getRawKeyValue())
+        print("Button value: ", lcd.getKeyValue())
         time.sleep(1)
 
 if __name__ == '__main__':

src/lcdks/CMakeLists.txt

@@ -0,0 +1,8 @@
+upm_mixed_module_init (NAME lcdks
+    DESCRIPTION "LCD Display Driver for LCD Keypad Shield devices based on the LCM1602"
+    C_HDR lcdks.h
+    C_SRC lcdks.c
+    CPP_HDR lcdks.hpp
+    CPP_SRC lcdks.cxx
+    CPP_WRAPS_C
+    REQUIRES mraa lcm1602)

src/lcdks/javaupm_lcdks.i

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

src/lcdks/jsupm_lcdks.i

@@ -0,0 +1,8 @@
+%module jsupm_lcdks
+%include "../upm.i"
+%include "../upm_vectortypes.i"
+
+%include "lcdks.hpp"
+%{
+    #include "lcdks.hpp"
+%}

src/lcdks/lcdks.c

@@ -0,0 +1,217 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2016 Intel Corporation.
+ *
+ * Based on UPM C++ drivers originally developed by:
+ * Author: Yevgeniy Kiveisha <yevgeniy.kiveisha@intel.com>
+ * Copyright (c) 2014 Intel Corporation.
+ *
+ * The MIT License
+ *
+ * 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 <assert.h>
+#include <string.h>
+
+#include <upm_utilities.h>
+
+#include "lcdks.h"
+
+lcdks_context lcdks_init(int rs, int enable,
+                         int d0, int d1, int d2, int d3,
+                         int keypad, int backlight)
+{
+    lcdks_context dev =
+        (lcdks_context)malloc(sizeof(struct _lcdks_context));
+
+    if (!dev)
+        return NULL;
+
+    memset((void *)dev, 0, sizeof(struct _lcdks_context));
+
+    // make sure MRAA is initialized
+    if (mraa_init() != MRAA_SUCCESS)
+    {
+        printf("%s: mraa_init() failed.\n", __FUNCTION__);
+        lcdks_close(dev);
+        return NULL;
+    }
+
+    // initialize the lcm1602 context
+    if (!(dev->lcm1602 = lcm1602_gpio_init(rs, enable, d0, d1, d2, d3, 16, 2)))
+    {
+        printf("%s: lcm1602_init failed.\n", __FUNCTION__);
+        lcdks_close(dev);
+        return NULL;
+    }
+
+    // analog keypad
+    if (!(dev->aio = mraa_aio_init(keypad)))
+    {
+        printf("%s: mraa_aio_init() failed.\n", __FUNCTION__);
+        lcdks_close(dev);
+
+        return NULL;
+    }
+
+    // optional backlight control pin
+    if (backlight >= 0)
+    {
+        if (!(dev->gpio = mraa_gpio_init(backlight)))
+        {
+            printf("%s: mraa_gpio_init() failed.\n", __FUNCTION__);
+            lcdks_close(dev);
+
+            return NULL;
+        }
+
+        mraa_gpio_dir(dev->gpio, MRAA_GPIO_OUT);
+    }
+
+    // just in case...
+    lcdks_backlight_on(dev, true);
+
+    return dev;
+}
+
+void lcdks_close(lcdks_context dev)
+{
+    assert(dev != NULL);
+
+    if (dev->gpio)
+        mraa_gpio_close(dev->gpio);
+    if (dev->aio)
+        mraa_aio_close(dev->aio);
+    if (dev->lcm1602)
+        lcm1602_close(dev->lcm1602);
+
+    free(dev);
+}
+
+upm_result_t lcdks_write(const lcdks_context dev, char *buffer,
+                         int len)
+{
+    assert(dev != NULL);
+
+    return lcm1602_write(dev->lcm1602, buffer, len);
+}
+
+upm_result_t lcdks_set_cursor(const lcdks_context dev, unsigned int row,
+                              unsigned int column)
+{
+    assert(dev != NULL);
+
+    return lcm1602_set_cursor(dev->lcm1602, row, column);
+}
+
+upm_result_t lcdks_clear(const lcdks_context dev)
+{
+    assert(dev != NULL);
+
+    return lcm1602_clear(dev->lcm1602);
+}
+
+upm_result_t lcdks_home(const lcdks_context dev)
+{
+    assert(dev != NULL);
+
+    return lcm1602_home(dev->lcm1602);
+}
+
+upm_result_t lcdks_create_char(const lcdks_context dev,
+                                 unsigned int slot,
+                                 char *data)
+{
+    assert(dev != NULL);
+
+    return lcm1602_create_char(dev->lcm1602, slot, data);
+}
+
+upm_result_t lcdks_display_on(const lcdks_context dev, bool on)
+{
+    assert(dev != NULL);
+
+    return lcm1602_display_on(dev->lcm1602, on);
+}
+
+upm_result_t lcdks_cursor_on(const lcdks_context dev, bool on)
+{
+    assert(dev != NULL);
+
+    return lcm1602_cursor_on(dev->lcm1602, on);
+}
+
+upm_result_t lcdks_cursor_blink_on(const lcdks_context dev, bool on)
+{
+    assert(dev != NULL);
+
+    return lcm1602_cursor_blink_on(dev->lcm1602, on);
+}
+
+upm_result_t lcdks_backlight_on(const lcdks_context dev, bool on)
+{
+    assert(dev != NULL);
+
+    if (dev->gpio)
+    {
+        if (on)
+            mraa_gpio_write(dev->gpio, 1);
+        else
+            mraa_gpio_write(dev->gpio, 0);
+    }
+
+    return UPM_SUCCESS;
+}
+
+upm_result_t lcdks_scroll_display_left(const lcdks_context dev)
+{
+    assert(dev != NULL);
+
+    return lcm1602_scroll_display_left(dev->lcm1602);
+}
+
+upm_result_t lcdks_scroll_display_right(const lcdks_context dev)
+{
+    assert(dev != NULL);
+
+    return lcm1602_scroll_display_right(dev->lcm1602);
+}
+
+upm_result_t lcdks_entry_left_to_right(const lcdks_context dev, bool on)
+{
+    assert(dev != NULL);
+
+    return lcm1602_entry_left_to_right(dev->lcm1602, on);
+}
+
+upm_result_t lcdks_autoscroll_on(const lcdks_context dev, bool on)
+{
+    assert(dev != NULL);
+
+    return lcm1602_autoscroll_on(dev->lcm1602, on);
+}
+
+float lcdks_get_key_value(const lcdks_context dev)
+{
+    assert(dev != NULL);
+
+    return mraa_aio_read_float(dev->aio);
+}

src/lcdks/lcdks.cxx

@@ -0,0 +1,160 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2016 Intel Corporation.
+ *
+ * Based on UPM C++ drivers originally developed by:
+ * Author: Daniel Mosquera
+ * Copyright (c) 2013 Daniel Mosquera
+ *
+ * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
+ * Copyright (c) 2014 Intel Corporation.
+ *
+ * Contributions: Sergey Kiselev <sergey.kiselev@intel.com>
+ *
+ * The MIT License
+ *
+ * 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>
+#include <stdexcept>
+#include <unistd.h>
+
+#include "lcdks.hpp"
+
+using namespace upm;
+
+LCDKS::LCDKS(int rs, int enable,
+             int d0, int d1, int d2, int d3,
+             int keypad, int backlight) :
+    m_lcdks(lcdks_init(rs, enable, d0, d1, d2, d3, keypad, backlight))
+
+{
+    if (!m_lcdks)
+        throw std::runtime_error(std::string(__FUNCTION__) +
+                                 ": lcdks_init failed");
+}
+
+LCDKS::~LCDKS()
+{
+    lcdks_close(m_lcdks);
+}
+
+upm_result_t LCDKS::write(std::string msg)
+{
+    return lcdks_write(m_lcdks, (char *)msg.data(), msg.size());
+}
+
+upm_result_t LCDKS::setCursor(int row, int column)
+{
+    return lcdks_set_cursor(m_lcdks, row, column);
+}
+
+upm_result_t LCDKS::clear()
+{
+    return lcdks_clear(m_lcdks);
+}
+
+upm_result_t LCDKS::home()
+{
+    return lcdks_home(m_lcdks);
+}
+
+upm_result_t LCDKS::createChar(uint8_t charSlot,
+                                   std::vector<uint8_t> charData)
+{
+    return lcdks_create_char(m_lcdks, charSlot,
+                             (char *)charData.data());
+}
+
+upm_result_t LCDKS::displayOn()
+{
+    return lcdks_display_on(m_lcdks, true);
+}
+
+upm_result_t LCDKS::displayOff()
+{
+    return lcdks_display_on(m_lcdks, false);
+}
+
+upm_result_t LCDKS::cursorOn()
+{
+    return lcdks_cursor_on(m_lcdks, true);
+}
+
+upm_result_t LCDKS::cursorOff()
+{
+    return lcdks_cursor_on(m_lcdks, false);
+}
+
+upm_result_t LCDKS::cursorBlinkOn()
+{
+    return lcdks_cursor_blink_on(m_lcdks, true);
+}
+
+upm_result_t LCDKS::cursorBlinkOff()
+{
+    return lcdks_cursor_blink_on(m_lcdks, false);
+}
+
+upm_result_t LCDKS::backlightOn()
+{
+    return lcdks_backlight_on(m_lcdks, true);
+}
+
+upm_result_t LCDKS::backlightOff()
+{
+    return lcdks_backlight_on(m_lcdks, false);
+}
+
+upm_result_t LCDKS::scrollDisplayLeft()
+{
+    return lcdks_scroll_display_left(m_lcdks);
+}
+
+upm_result_t LCDKS::scrollDisplayRight()
+{
+    return lcdks_scroll_display_right(m_lcdks);
+}
+
+upm_result_t LCDKS::entryLeftToRight()
+{
+    return lcdks_entry_left_to_right(m_lcdks, true);
+}
+
+upm_result_t LCDKS::entryRightToLeft()
+{
+    return lcdks_entry_left_to_right(m_lcdks, false);
+}
+
+upm_result_t LCDKS::autoscrollOn()
+{
+    return lcdks_autoscroll_on(m_lcdks, true);
+}
+
+upm_result_t LCDKS::autoscrollOff()
+{
+    return lcdks_autoscroll_on(m_lcdks, false);
+}
+
+float LCDKS::getKeyValue()
+{
+    return lcdks_get_key_value(m_lcdks);
+}

src/lcdks/lcdks.h

@@ -0,0 +1,235 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2017 Intel Corporation.
+ *
+ * Based on UPM C++ drivers originally developed by:
+ * Author: Yevgeniy Kiveisha <yevgeniy.kiveisha@intel.com>
+ * Copyright (c) 2014 Intel Corporation.
+ *
+ * The MIT License
+ *
+ * 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 <unistd.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+#include <mraa/gpio.h>
+#include <mraa/aio.h>
+
+#include <upm.h>
+#include "lcm1602.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+    /**
+     * @file lcdks.h
+     * @library lcdks
+     * @brief C API for the LCDKS (LCD Keypad Shield) display family
+     *
+     * @include lcdks.c
+     */
+
+    /**
+     * Device context
+     */
+    typedef struct _lcdks_context {
+        // LCM1602 context - does most of the work
+        lcm1602_context lcm1602;
+        // aio context for keypad
+        mraa_aio_context aio;
+        // optional GPIO context for backlight pin
+        mraa_gpio_context gpio;
+    } *lcdks_context;
+
+    /**
+     * LCDKS initialization
+     *
+     * As this is a shield, you will not likely have any choice over
+     * the pins that are used.  For this reason, we provide defaults
+     * for all of them -- of course they can be changed if your device
+     * is different.
+     *
+     * @param rs Register select pin.
+     * @param enable Enable pin.
+     * @param d0 Data 0 pin.
+     * @param d1 Data 1 pin.
+     * @param d2 Data 2 pin.
+     * @param d3 Data 3 pin.
+     * @param keypad Analog pin of the keypad.
+     * @param backlight Optional GPIO backlight pin.  Specify -1 if
+     * not in use or not supported on your device.
+     * @return LCDKS context, or NULL if an error occurs.
+     */
+    lcdks_context lcdks_init(int rs, int enable,
+                             int d0, int d1, int d2, int d3,
+                             int keypad, int backlight);
+
+    /**
+     * LCDKS close.
+     *
+     * @param dev The device context.
+     */
+    void lcdks_close(lcdks_context dev);
+
+    /**
+     * Writes a string to the LCD.
+     *
+     * @param dev The device context.
+     * @param buffer Character buffer containing characters to write to
+     * the display; note: only ASCII characters are supported
+     * @param len The number of characters to write.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_write(const lcdks_context dev, char *buffer,
+                                 int len);
+
+    /**
+     * Sets the cursor to specified coordinates
+     *
+     * @param dev The device context.
+     * @param row Row to set the cursor to.
+     * @param column Column to set the cursor to.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_set_cursor(const lcdks_context dev,
+                                      unsigned int row, unsigned int column);
+
+    /**
+     * Clears the display of all characters.
+     *
+     * @param dev The device context.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_clear(const lcdks_context dev);
+
+    /**
+     * Returns to the home coordinates (0,0).
+     *
+     * @param dev The device context.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_home(const lcdks_context dev);
+
+    /**
+     * Create a custom character.
+     *
+     * @param dev The device context.
+     * @param slot The character slot to write, only 8 are available.
+     * @param data The character data (8 bytes) making up the character.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_create_char(const lcdks_context dev,
+                                       unsigned int slot,
+                                       char *data);
+
+    /**
+     * Turn the display on.
+     *
+     * @param dev The device context.
+     * @param on true to turn display on, false otherwise.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_display_on(const lcdks_context dev, bool on);
+
+    /**
+     * Turn the cursor on.
+     *
+     * @param dev The device context.
+     * @param on true to turn cursor on, false otherwise.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_cursor_on(const lcdks_context dev, bool on);
+
+    /**
+     * Turn cursor blink on.
+     *
+     * @param dev The device context.
+     * @param on true to turn cursor blink on, false otherwise.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_cursor_blink_on(const lcdks_context dev,
+                                           bool on);
+
+    /**
+     * Turn backlight on.
+     *
+     * @param dev The device context.
+     * @param on true to turn backlight on, false otherwise.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_backlight_on(const lcdks_context dev, bool on);
+
+    /**
+     * Scroll the display left, without changing the character RAM.
+     *
+     * @param dev The device context.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_scroll_display_left(const lcdks_context dev);
+
+    /**
+     * Scroll the display right, without changing the character RAM.
+     *
+     * @param dev The device context.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_scroll_display_right(const lcdks_context dev);
+
+    /**
+     * Set the entry mode so that characters are added left to right.
+     *
+     * @param dev The device context.
+     * @param on true to add characters left to right, false for right
+     * to left.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_entry_left_to_right(const lcdks_context dev,
+                                               bool on);
+
+    /**
+     * Right justify text entered from the cursor.
+     *
+     * @param dev The device context.
+     * @param on true right justify text, false to left justify text.
+     * @return UPM result.
+     */
+    upm_result_t lcdks_autoscroll_on(const lcdks_context dev, bool on);
+
+    /**
+     * Returns the floating point representation of the key that is
+     * being pushed.  Each key produces a different value between 0.0
+     * and 1.0, and only one key can be read at a time.
+     *
+     * @param dev The device context.
+     * @return the floating point value representing a key
+     */
+    float lcdks_get_key_value(const lcdks_context dev);
+
+
+#ifdef __cplusplus
+}
+#endif

src/lcdks/lcdks.hpp

@@ -0,0 +1,271 @@
+/*
+ * Author: Jon Trulson <jtrulson@ics.com>
+ * Copyright (c) 2016 Intel Corporation.
+ *
+ * Based on UPM C++ drivers originally developed by:
+ * Author: Daniel Mosquera
+ * Copyright (c) 2013 Daniel Mosquera
+ *
+ * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
+ * Copyright (c) 2014 Intel Corporation.
+ *
+ * Contributions: Sergey Kiselev <sergey.kiselev@intel.com>
+ *
+ * The MIT License
+ *
+ * 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 <vector>
+#include "lcdks.h"
+
+namespace upm
+{
+    /**
+     * @brief LCDKS (LCD Keypad Shield) Display library
+     * @defgroup lcdks libupm-lcdks
+     * @ingroup dfrobot sainsmart display
+     */
+
+    /**
+     * @library lcdks
+     * @sensor lcdks
+     * @comname LCD Keypad Shield
+     * @type display
+     * @man sainsmart dfrobot sparkfun
+     * @web http://www.sainsmart.com/sainsmart-1602-lcd-keypad-shield-for-arduino-duemilanove-uno-mega2560-mega1280.html
+     * @web http://www.dfrobot.com/index.php?route=product/product&product_id=51
+     * @web https://www.sparkfun.com/products/13293
+     * @con gpio analog
+     *
+     * @brief API for the generic LCD Keypad Shield
+     *
+     * The LCD Keypad Shield uses 7 digital outputs and 1 analog input
+     * (for the keypad). The outputs are used to drive an attached
+     * LCM1602 LCD controller. This driver should be compatible with
+     * the similar LCD keypad shields from Sainsmart, DFRobot and
+     * Sparkfun.
+     *
+     * @image html keypadlcd.jpg
+     * @snippet lcdks.cxx Interesting
+     */
+
+    class LCDKS
+    {
+    public:
+        /**
+         * LCDKS constructor
+         *
+         * As this is a shield, you will not likely have any choice over
+         * the pins that are used.  For this reason, we provide defaults
+         * for all of them -- of course they can be changed if your device
+         * is different.
+         *
+         * @param rs Register select pin.
+         * @param enable Enable pin.
+         * @param d0 Data 0 pin.
+         * @param d1 Data 1 pin.
+         * @param d2 Data 2 pin.
+         * @param d3 Data 3 pin.
+         * @param keypad Analog pin of the keypad.
+         * @param backlight Optional GPIO backlight pin.  Specify -1 if
+         * not in use or not supported on your device.
+         * @throws std::runtime_error on initialization error.
+         */
+        LCDKS(int rs=8, int enable=9,
+              int d0=4, int d1=5, int d2=6, int d3=7,
+              int keypad=0, int backlight=-1);
+        /**
+         * LCDKS destructor
+         */
+        ~LCDKS();
+
+        /**
+         * Writes a string to the LCD
+         *
+         * @param msg std::string to write to the display; note: only ASCII
+         * characters are supported
+         * @return Result of the operation
+         */
+        upm_result_t write(std::string msg);
+
+        /**
+         * Sets the cursor to specified coordinates
+         *
+         * @param row Row to set the cursor to
+         * @param column Column to set the cursor to
+         * @return Result of the operation
+         */
+        upm_result_t setCursor(int row, int column);
+
+        /**
+         * Clears the display of all characters
+         *
+         * @return Result of the operation
+         */
+        upm_result_t clear();
+
+        /**
+         * Returns to the original coordinates (0,0)
+         *
+         * @return Result of the operation
+         */
+        upm_result_t home();
+
+        /**
+         * Create a custom character
+         *
+         * @param charSlot the character slot to write, only 8 are available
+         * @param charData A vector containing 8 bytes making up the character
+         * @return Result of operation
+         */
+        upm_result_t createChar(uint8_t charSlot,
+                                std::vector<uint8_t> charData);
+
+        /**
+         * Turn the display on
+         *
+         * @return Result of operation
+         */
+        upm_result_t displayOn();
+
+        /**
+         * Turn the display off
+         *
+         * @return Result of operation
+         */
+        upm_result_t displayOff();
+
+        /**
+         * Turn the cursor on
+         *
+         * @return Result of operation
+         */
+        upm_result_t cursorOn();
+
+        /**
+         * Turn the cursor off
+         *
+         * @return Result of operation
+         */
+        upm_result_t cursorOff();
+
+        /**
+         * Turn cursor blink on
+         *
+         * @return Result of operation
+         */
+        upm_result_t cursorBlinkOn();
+
+        /**
+         * Turn cursor blink off
+         *
+         * @return Result of operation
+         */
+        upm_result_t cursorBlinkOff();
+
+        /**
+         * Turn backlight on
+         *
+         * @return Result of operation
+         */
+        upm_result_t backlightOn();
+
+        /**
+         * Turn backlight off
+         *
+         * @return Result of operation
+         */
+        upm_result_t backlightOff();
+
+        /**
+         * Scroll the display left, without changing the character RAM
+         *
+         * @return Result of operation
+         */
+        upm_result_t scrollDisplayLeft();
+
+        /**
+         * Scroll the display right, without changing the character RAM
+         *
+         * @return Result of operation
+         */
+        upm_result_t scrollDisplayRight();
+
+        /**
+         * set the entry mode so that characters are added left to right
+         *
+         * @return Result of operation
+         */
+        upm_result_t entryLeftToRight();
+
+        /**
+         * set the entry mode so that characters are added right to left
+         *
+         * @return Result of operation
+         */
+        upm_result_t entryRightToLeft();
+
+        /**
+         * Right justify text entered from the cursor
+         *
+         * @return Result of operation
+         */
+        upm_result_t autoscrollOn();
+
+        /**
+         * Left justify text entered from the cursor
+         *
+         * @return Result of operation
+         */
+        upm_result_t autoscrollOff();
+
+        /**
+         * Returns the floating point representation of the key that is
+         * being pushed.  Each key produces a different value between 0.0
+         * and 1.0, and only one key can be read at a time.
+         *
+         * @return The floating point value representing a key.
+         */
+        float getKeyValue();
+
+        /**
+         * Returns the floating point representation of the key that is
+         * being pushed.  Each key produces a different value between 0.0
+         * and 1.0, and only one key can be read at a time.
+         *
+         * @deprecated This function is deprecated. Use getKeyValue() instead.
+         * @return The floating point value representing a key.
+         */
+        float getRawKeyValue()
+        {
+            return getKeyValue();
+        }
+
+
+    protected:
+        lcdks_context m_lcdks;
+
+    private:
+    };
+}

src/lcdks/pyupm_lcdks.i

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