sensortemplate: Added a template sensor

The purpose of the templatesensor is to get contributors up and running
faster when adding a new sensor.

    * Created library named 'sensortemplate'
    * Added C++ source
    * Added swig interface files for java, javascript, and python
    * Added sensortemplate image file
    * Added examples for c++, java, javascript, and python
    * Updated contributions.md with steps to create a new sensor from
      the sensortemplate library.

Signed-off-by: Noel Eck <noel.eck@intel.com>

docs/contributions.md

@@ -94,3 +94,40 @@ then you just add a line to each of your commits with `--signoff` saying
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
 Unsigned commits will not be accepted.
+
+
+Creating a new sensor library using the sensortemplate
+=======================================
+
+A stubbed-out sensor library is available which can be leveraged to get
+up-and-running quickly when writing a new sensor library.  Use the shell
+commands below to generate collateral files for your new sensor library.
+
+
+```shell
+# Set SensorName to your new library name, example: 'MyNewSensor1234'
+export SensorName=MyNewSensor1234
+
+# Copy/paste the below commands into a bash shell...
+# Get a lowercase version of the string
+export sensorname=${SensorName,,}
+# Copy sensortemplate files to ${sensorname}
+find docs/ examples/ src/ -name '*sensortemplate*' -exec bash -c 'cp -r $0 ${0/sensortemplate/${sensorname}}' {} \;
+# Copy SensorTemplate files to ${SensorName}
+find examples/ src/ -name '*SensorTemplate*' -exec bash -c 'cp -r $0 ${0/SensorTemplate/${SensorName}}' {} \;
+# Rename sernsortemplate src files
+rename "s/sensortemplate/${sensorname}/" src/${sensorname}/*
+# Search/replace the new files, replacing all instances of sensortemplate
+perl -p -i -e "s/SensorTemplate/${SensorName}/g" src/${sensorname}/* examples/*/*${sensorname}* examples/*/*${SensorName}*
+perl -p -i -e "s/sensortemplate/${sensorname}/g" src/${sensorname}/* examples/*/*${sensorname}* examples/*/*${SensorName}*
+# Add mynewmodule example target for c++
+perl -p -i -e "s/^((.*)sensortemplate(.*))/\1\n\2${sensorname}\3/g" examples/c++/CMakeLists.txt
+# Add mynewmodule example target for java
+perl -p -i -e "s/^((.*)SensorTemplateSample sensortemplate(.*))/\1\n\2${SensorName}Sample ${sensorname}\3/g" examples/java/CMakeLists.txt
+# Add mynewmodule example mappings for doxygen
+perl -p -i -e "s/^(.*SensorTemplateSample.*)$/\1\n${sensorname}.cxx\t${SensorName}Sample.java\t${sensorname}.js\t${sensorname}.py/g" doxy/samples.mapping.txt
+```
+
+Once all files have been created, they can be used as a starting-point for your
+new library.  They will need additional customization (your name/email address,
+documentation, sensor images, etc).

doxy/samples.mapping.txt

@@ -71,3 +71,4 @@ vdiv.cxx	VDivSample.java	vdiv.js	vdiv.py
 water.cxx	WaterSample.java	water.js	water.py
 wt5001.cxx	WT5001Sample.java	wt5001.js	wt5001.py
 yg1006.cxx	YG1006Sample.java	yg1006.js	yg1006.py
+sensortemplate.cxx	SensorTemplateSample.java	sensortemplate.js	sensortemplate.py

examples/c++/CMakeLists.txt

@@ -329,6 +329,7 @@ add_example (rf22-server)
 add_example (rf22-client)
 add_example (mcp2515)
 add_example (max30100)
+add_example (sensortemplate)
 
 # These are special cases where you specify example binary, source file and module(s)
 include_directories (${PROJECT_SOURCE_DIR}/src)

examples/c++/sensortemplate.cxx

@@ -0,0 +1,50 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Author: Your Full Name <your@email.address>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * Author: <contributing author full name - if applicable>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * 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 <unistd.h>
+
+#include "sensortemplate.hpp"
+
+int main ()
+{
+    //! [Interesting]
+    // Create an instance of SensorTemplate
+    upm::SensorTemplate sensor(0);
+
+    while(true)
+    {
+        std::cout << "SensorTemplate says: "
+            << sensor.helloWorld() << std::endl;
+
+        // Repeat every 2 seconds
+        usleep(2000000);
+    }
+    //! [Interesting]
+    return 0;
+}

examples/java/CMakeLists.txt

@@ -164,6 +164,7 @@ add_example(MCP2515_Example mcp2515)
 add_example(Ads1015Sample ads1x15)
 add_example(MAX30100_Example max30100)
 add_example(Ads1115Sample ads1x15)
+add_example(SensorTemplateSample sensortemplate)
 
 add_example_with_path(Jhd1313m1_lcdSample lcd i2clcd)
 add_example_with_path(Jhd1313m1Sample lcd i2clcd)

examples/java/SensorTemplateSample.java

@@ -0,0 +1,44 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Author: Your Full Name <your@email.address>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * Author: <contributing author full name - if applicable>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * 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.
+ */
+
+
+public class SensorTemplateSample {
+    public static void main (String args[]) throws InterruptedException {
+        //! [Interesting]
+        // Instantiate new sensor instance
+        upm_sensortemplate.SensorTemplate sensor = new upm_sensortemplate.SensorTemplate(0);
+
+        while (true) {
+
+            System.out.println("SensorTemplate says: " + sensor.helloWorld());
+
+            // Repeate every 2 seconds
+            Thread.sleep(2000);
+        }
+        //! [Interesting]
+    }
+}

examples/javascript/sensortemplate.js

@@ -0,0 +1,43 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Author: Your Full Name <your@email.address>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * Author: <contributing author full name - if applicable>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * 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.
+ */
+
+
+var jsupm_sensortemplate = require('jsupm_sensortemplate');
+
+// Create an instance of the sensor
+var sensor = new upm_sensortemplate.SensorTemplate(0);
+
+loop();
+
+function loop()
+{
+    // Call a method from the sensortemplate
+    console.log("SensorTemplate says: " + sensor.helloWorld());
+
+    // Call loop every 2 seconds
+    setTimeout(loop, 2000);
+}

examples/python/sensortemplate.py

@@ -0,0 +1,42 @@
+# The MIT License (MIT)
+#
+# Author: Your Full Name <your@email.address>
+# Copyright (c) <year> <copyright holder>
+#
+# Author: <contributing author full name - if applicable>
+# Copyright (c) <year> <copyright holder>
+#
+# 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.
+
+
+from __future__ import print_function
+import time
+from upm import pyupm_sensortemplate
+
+def main():
+    # Create an instance of SensorTemplate
+    sensor = pyupm_sensortemplate.SensorTemplate(0)
+
+    while True:
+        print("SensorTemplate says: %s" % sensor.helloWorld)
+
+        # Repeat every 2 seconds
+        sleep(2)
+
+if __name__ == '__main__':
+    main()

src/sensortemplate/CMakeLists.txt

@@ -0,0 +1,5 @@
+upm_mixed_module_init (NAME sensortemplate
+    DESCRIPTION "Short, Title-Case Description from the SensorTemplate Datasheet"
+    CPP_HDR sensortemplate.hpp
+    CPP_SRC sensortemplate.cxx
+    REQUIRES mraa)

src/sensortemplate/common.i

@@ -0,0 +1,14 @@
+/* Include global UPM interface file */
+%include "../upm.i"
+
+/* Required for python documentation, ignored for others */
+%feature("autodoc", "3");
+
+%{
+    /* SWIG preprocessor copies this directly to the output wrapper*/
+    #include "sensortemplate.hpp"
+%}
+
+/* %include is a SWIG directive.  SWIG will wrap types exposed in this
+ * header to the target language. */
+%include "sensortemplate.hpp"

src/sensortemplate/javaupm_sensortemplate.i

@@ -0,0 +1,17 @@
+/* Specify the name of the target JAVA module */
+%module javaupm_sensortemplate
+
+/* Include the base sensor interface file */
+%include "common.i"
+
+/* Add the JAVA code to load the module */
+%pragma(java) jniclasscode=%{
+    static {
+        try {
+            System.loadLibrary("javaupm_sensortemplate");
+        } catch (UnsatisfiedLinkError e) {
+            System.err.println("Native code library failed to load. \n" + e);
+            System.exit(1);
+        }
+    }
+%}

src/sensortemplate/jsupm_sensortemplate.i

@@ -0,0 +1,5 @@
+/* Specify the name of the target JavaScript module */
+%module jsupm_sensortemplate
+
+/* Include the base sensor interface file */
+%include "common.i"

src/sensortemplate/pyupm_sensortemplate.i

@@ -0,0 +1,9 @@
+/* Specify the name of the target JAVA module */
+%module pyupm_sensortemplate
+
+/* If documentation is enabled, a full "pyupm_doxy2swig.i file will be
+ * generated and used...  Otherwise, use a stub */
+%include "pyupm_doxy2swig.i"
+
+/* Include the base sensor interface file */
+%include "common.i"

src/sensortemplate/sensortemplate.cxx

@@ -0,0 +1,35 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Author: Your Full Name <your@email.address>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * Author: <contributing author full name - if applicable>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * 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 "sensortemplate.hpp"
+
+using namespace upm;
+
+SensorTemplate::SensorTemplate(int i2c_bus): _i2c(i2c_bus) {}
+
+std::string SensorTemplate::helloWorld() { return "Hello World";}

src/sensortemplate/sensortemplate.hpp

@@ -0,0 +1,98 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Author: Your Full Name <your@email.address>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * Author: <contributing author full name - if applicable>
+ * Copyright (c) <year> <copyright holder>
+ *
+ * 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 "mraa/i2c.hpp"
+
+namespace upm
+{
+/**
+ * @brief Library block provides a short library description
+ * @defgroup sensortemplate libupm-sensortemplate
+ * @ingroup <manufacturer: adafruit,aeon,amphenol,avago,bosch,catnip,comet,dfrobot,emax,epict,freescale,generic,honeywell,kionix,maxbotix,maxbotix,maxim,meas,mouser,numatolabs,omega,openelectrons,sainsmart,seeed,semtech,silabs,sparkfun,stmicro,ti,trane,veris> <connection: analog,gpio,i2c,pwm,spi,uart> <category: accelerometer,ainput,button,color,compass,digipot,display,electric,flexfor,gaseous,gps,led,light,liquid,medical,motor,other,pressure,relay,rfid,serial,servos,sound,temp,time,touch,video,wifi> (<kit>: eak,gsk,hak,robok,tsk)
+ */
+
+/**
+ * @library sensortemplate
+ * @sensor Usually the chip number used by the sensor. When this is not
+ *         available or relevant, use a unique descriptor that makes sense.
+ *         Must match class name. *Mandatory*
+ * @comname Short, Title-Case Description from Datasheet. *Manditory*
+ * @altname Alternative names that your sensor driver might have. This may
+ *          include manufacturer's name. *Optional*
+ * @altid Alternative chip-ids that your sensor driver supports. *Optional*
+ * @type One or more of: accelerometer,ainput,button,color,compass,digipot,
+ *       display,electric,flexfor,gaseous,gps,led,light,liquid,medical,motor,other,pressure,relay,rfid,serial,servos,sound,temp,time,touch,video,wifi *Manditory*
+ * @man One or more of: Sensor manufacturer. Can be 'generic'. *Mandatory*
+ * @web Links to vendors or data-sheets. *Optional*
+ * @con One or more of: analog,gpio,i2c,pwm,spi,uart *Manditory*
+ * @kit One of: gsk, hak, eak, tsk, robok *Optional*
+ *
+ * @brief Short class/sensor description
+ *
+ * Then add a much more detailed description here.  Include items such as
+ * board-specifics, testing, etc...
+ *
+ * @image html sensortemplate.png
+ * @snippet <example-name.cxx> Interesting
+ */
+
+class SensorTemplate
+{
+    public:
+        /**
+         * @brief Default constructor for SensorTemplate
+         *
+         * This creates an instance of SensorTemplate given an I2C bus
+         * number.
+         *
+         * @param i2c_bus Target I2C bus
+         * @return sensor context pointer
+         * @throws std::runtime_error on failure to initialize I2C
+         */
+        SensorTemplate(int i2c_bus);
+
+        /**
+         * SensorTemplate destructor
+         */
+        virtual ~SensorTemplate() {};
+
+        /**
+         * @brief Hello world method
+         *
+         * Provides an example method which returns 'Hello world'
+         */
+        std::string helloWorld();
+    private:
+        /* Private I2c instance */
+        mraa::I2c _i2c;
+};
+}