diff --git a/docs/contributions.md b/docs/contributions.md index d362c9a3..ba43b608 100644 --- a/docs/contributions.md +++ b/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). diff --git a/docs/images/sensortemplate.png b/docs/images/sensortemplate.png new file mode 100644 index 00000000..9fdaac84 Binary files /dev/null and b/docs/images/sensortemplate.png differ diff --git a/doxy/samples.mapping.txt b/doxy/samples.mapping.txt index 492c9673..e6026fa2 100644 --- a/doxy/samples.mapping.txt +++ b/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 diff --git a/examples/c++/CMakeLists.txt b/examples/c++/CMakeLists.txt index e19b67c0..8e10b8d6 100644 --- a/examples/c++/CMakeLists.txt +++ b/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) diff --git a/examples/c++/sensortemplate.cxx b/examples/c++/sensortemplate.cxx new file mode 100644 index 00000000..98ba3a97 --- /dev/null +++ b/examples/c++/sensortemplate.cxx @@ -0,0 +1,50 @@ +/* + * The MIT License (MIT) + * + * Author: Your Full Name + * Copyright (c) + * + * Author: + * Copyright (c) + * + * 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 +#include + +#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; +} diff --git a/examples/java/CMakeLists.txt b/examples/java/CMakeLists.txt index 484850aa..f3a239c4 100644 --- a/examples/java/CMakeLists.txt +++ b/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) diff --git a/examples/java/SensorTemplateSample.java b/examples/java/SensorTemplateSample.java new file mode 100644 index 00000000..050eef9e --- /dev/null +++ b/examples/java/SensorTemplateSample.java @@ -0,0 +1,44 @@ +/* + * The MIT License (MIT) + * + * Author: Your Full Name + * Copyright (c) + * + * Author: + * Copyright (c) + * + * 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] + } +} diff --git a/examples/javascript/sensortemplate.js b/examples/javascript/sensortemplate.js new file mode 100644 index 00000000..67fa0bcb --- /dev/null +++ b/examples/javascript/sensortemplate.js @@ -0,0 +1,43 @@ +/* + * The MIT License (MIT) + * + * Author: Your Full Name + * Copyright (c) + * + * Author: + * Copyright (c) + * + * 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); +} diff --git a/examples/python/sensortemplate.py b/examples/python/sensortemplate.py new file mode 100755 index 00000000..237f8977 --- /dev/null +++ b/examples/python/sensortemplate.py @@ -0,0 +1,42 @@ +# The MIT License (MIT) +# +# Author: Your Full Name +# Copyright (c) +# +# Author: +# Copyright (c) +# +# 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() diff --git a/src/sensortemplate/CMakeLists.txt b/src/sensortemplate/CMakeLists.txt new file mode 100644 index 00000000..b6f97540 --- /dev/null +++ b/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) diff --git a/src/sensortemplate/common.i b/src/sensortemplate/common.i new file mode 100644 index 00000000..7fa4b099 --- /dev/null +++ b/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" diff --git a/src/sensortemplate/javaupm_sensortemplate.i b/src/sensortemplate/javaupm_sensortemplate.i new file mode 100644 index 00000000..8f23abf0 --- /dev/null +++ b/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); + } + } +%} diff --git a/src/sensortemplate/jsupm_sensortemplate.i b/src/sensortemplate/jsupm_sensortemplate.i new file mode 100644 index 00000000..3f505167 --- /dev/null +++ b/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" diff --git a/src/sensortemplate/pyupm_sensortemplate.i b/src/sensortemplate/pyupm_sensortemplate.i new file mode 100644 index 00000000..af557b4e --- /dev/null +++ b/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" diff --git a/src/sensortemplate/sensortemplate.cxx b/src/sensortemplate/sensortemplate.cxx new file mode 100644 index 00000000..6c9f9cb4 --- /dev/null +++ b/src/sensortemplate/sensortemplate.cxx @@ -0,0 +1,35 @@ +/* + * The MIT License (MIT) + * + * Author: Your Full Name + * Copyright (c) + * + * Author: + * Copyright (c) + * + * 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";} diff --git a/src/sensortemplate/sensortemplate.hpp b/src/sensortemplate/sensortemplate.hpp new file mode 100644 index 00000000..8d466633 --- /dev/null +++ b/src/sensortemplate/sensortemplate.hpp @@ -0,0 +1,98 @@ +/* + * The MIT License (MIT) + * + * Author: Your Full Name + * Copyright (c) + * + * Author: + * Copyright (c) + * + * 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 + +#include "mraa/i2c.hpp" + +namespace upm +{ +/** + * @brief Library block provides a short library description + * @defgroup sensortemplate libupm-sensortemplate + * @ingroup (: 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 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; +}; +}