upm: update to version 0.3.0

Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>

.clang-format

@@ -0,0 +1,122 @@
+Language: Cpp
+
+# Access modifiers in the middle
+AccessModifierOffset: -2
+
+# Align escaped newlines as far left as possible
+AlignEscapedNewlinesLeft: true
+
+# Align all trailing comments
+AlignTrailingComments: true
+
+# Don't allow parameters to be placed on the next line, even though BinPackParameters is false
+AllowAllParametersOfDeclarationOnNextLine: false
+
+# Do not allow short functions/if statements/loops on a single line
+AllowShortFunctionsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+
+# Don't force breaks before multiline strings
+AlwaysBreakBeforeMultilineStrings: false
+
+# Don't force breaks before template declarations
+AlwaysBreakTemplateDeclarations: false
+
+# Force breaks after definition return type
+AlwaysBreakAfterDefinitionReturnType: true
+
+# Arguments and parameters are either on one line or on one line each
+BinPackArguments: false
+BinPackParameters: false
+
+# Do not break before binary operators
+BreakBeforeBinaryOperators: None
+
+# Use the linux brace breaking style: Attach braces to context except for braces on functions,
+# namespaces and class definitions
+BreakBeforeBraces: Linux
+
+# Do not place ternary operators after line breaks
+BreakBeforeTernaryOperators: false
+
+# In the constructor initializers do not align the comma with the colon
+BreakConstructorInitializersBeforeComma: false
+
+# Force columns to be less than 100 characters
+ColumnLimit: 100
+
+# Constructor initializer all in one line or all on their own line
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+
+# Indent constructor initializers
+ConstructorInitializerIndentWidth: 8
+
+# Do not indent continuations
+ContinuationIndentWidth: 0
+
+# Do not use braced lists in c++11 style
+Cpp11BracedListStyle: false
+
+# Do not derive pointer alignment
+DerivePointerAlignment: false
+
+# Case labes are indented
+IndentCaseLabels: true
+
+# Do not indent function declarations
+IndentFunctionDeclarationAfterType: false
+
+# Indentation is 4 characters
+IndentWidth: 4
+
+# Do not keep empty lines at start of blocks
+KeepEmptyLinesAtTheStartOfBlocks: false
+
+# Keep at most 2 consecutive empty lines
+MaxEmptyLinesToKeep: 2
+
+# Do not indent namespaces
+NamespaceIndentation: None
+
+# Spaces for ObjC properties and protocol lists
+ObjCSpaceAfterProperty: true
+ObjCSpaceBeforeProtocolList: true
+
+# Penalties
+PenaltyBreakBeforeFirstCallParameter: 100
+PenaltyBreakComment: 10
+PenaltyBreakFirstLessLess: 0
+PenaltyBreakString: 100
+PenaltyExcessCharacter: 20
+PenaltyReturnTypeOnItsOwnLine: 20
+
+# Force pointers to typename (i.e. char* a instead of char *a)
+PointerAlignment: Left
+
+# Spaces after C-style casts and before assignments
+SpaceAfterCStyleCast: true
+SpaceBeforeAssignmentOperators: true
+
+# Only space before parentheses if they are control statements
+SpaceBeforeParens: ControlStatements
+
+# Single space before trailing comments
+SpacesBeforeTrailingComments: 1
+
+# No spaces in parentheses, angles, or square brackets
+SpaceInEmptyParentheses: false
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+
+# Use c++11 as the language standard
+Standard: Cpp11
+
+# Tabs are 4 characters wide
+TabWidth: 4
+
+# Don't use tabs for indentation :-(
+UseTab: Never
+

CMakeLists.txt

@@ -1,6 +1,10 @@
-cmake_minimum_required (VERSION 2.8)
+cmake_minimum_required (VERSION 2.8.11)
 project (upm)
 
+if ("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
+message("WARNING: building into sources dir can be risky, prefer other directory")
+endif ()
+
 find_package (SWIG)
 if (SWIG_FOUND)
   include (${SWIG_USE_FILE})
@@ -8,19 +12,25 @@ endif ()
 
 find_package (Threads REQUIRED)
 find_package (PkgConfig REQUIRED)
-# force the libmaa version to be the required version
-pkg_check_modules (MAA REQUIRED maa>=0.2.6)
-message (INFO " found libmaa version: ${MAA_VERSION}")
+
+# force a libmraa search and minimum required version every time a config is generated
+unset(MRAA_FOUND CACHE)
+pkg_check_modules (MRAA REQUIRED mraa>=0.6.0)
+message (INFO " found libmraa version: ${MRAA_VERSION}")
 
 # Appends the cmake/modules path to MAKE_MODULE_PATH variable.
 set (CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules ${CMAKE_MODULE_PATH})
+set (LIB_INSTALL_DIR "lib${LIB_SUFFIX}" CACHE PATH "Installation path for libraries")
+
+# Set CMAKE_LIB_INSTALL_DIR if not defined
+include(GNUInstallDirs)
 
 # Make a version file containing the current version from git.
 include (GetGitRevisionDescription)
 git_describe (VERSION "--tags")
 if ("x_${VERSION}" STREQUAL "x_GIT-NOTFOUND")
-  message (WARNING " - Install git to compile a production libmaa!")
-  set (VERSION "v0.1.2-dirty")
+  message (WARNING " - Install git to compile a production libmraa!")
+  set (VERSION "v0.3.0-dirty")
 endif ()
 
 message (INFO " - UPM Version ${VERSION}")
@@ -39,29 +49,79 @@ endif()
 set (upm_VERSION_MAJOR ${VERSION_MAJOR})
 set (upm_VERSION_MINOR ${VERSION_MINOR})
 set (upm_VERSION_PATCH ${VERSION_PATCH})
-set (upm_VERSION_STRING ${maa_VERSION_MAJOR}.${maa_VERSION_MINOR}.${maa_VERSION_PATCH})
+set (upm_VERSION_STRING ${upm_VERSION_MAJOR}.${upm_VERSION_MINOR}.${upm_VERSION_PATCH})
 
 set (CMAKE_SWIG_FLAGS "")
 
 option (IPK "Generate IPK using CPack" OFF)
+option (BUILDDOC "Build all doc." OFF)
+option (BUILDSWIG "Build swig modules." ON)
+option (BUILDSWIGPYTHON "Build swig python modules." ON)
+option (BUILDSWIGNODE "Build swig node modules." ON)
+option (BUILDEXAMPLES "Build C++ example binaries" OFF)
 
-# add a target to generate API documentation with Doxygen
-find_package (Doxygen)
-if (DOXYGEN_FOUND)
-  configure_file (${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
-  add_custom_target (doc
-    ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-    COMMENT "Generating API documentation with Doxygen" VERBATIM
-  )
-endif (DOXYGEN_FOUND)
+if (BUILDDOC)
+  # add a target to generate API documentation with Doxygen
+  find_package (Doxygen)
+  if (DOXYGEN_FOUND)
+    configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+    add_custom_target (doc
+      ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Generating API documentation with Doxygen" VERBATIM
+    )
+  endif (DOXYGEN_FOUND)
+  # check if Sphinx is installed and add target to generate API documentation
+  find_package (Sphinx)
+  if(SPHINX_FOUND AND BUILDSWIG AND BUILDSWIGPYTHON)
+    # python required for Sphinx build
+    find_package (PythonLibs)
+    string (REPLACE "." ";" PYTHON_VERSION_LIST ${PYTHONLIBS_VERSION_STRING})
+    list (GET PYTHON_VERSION_LIST 0 PYTHON_VERSION_MAJOR)
+    list (GET PYTHON_VERSION_LIST 1 PYTHON_VERSION_MINOR)
+    set (SITE_PACKAGES ${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}/python${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR}/site-packages)
+    configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/pydoc/conf.py @ONLY)
+    configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/index.rst ${CMAKE_CURRENT_BINARY_DIR}/pydoc/index.rst COPYONLY)
+    add_custom_target (pydoc ALL
+      COMMAND rm -r -f ${CMAKE_BINARY_DIR}/pyupm && mkdir -p ${CMAKE_BINARY_DIR}/pyupm
+      COMMAND find ${CMAKE_BINARY_DIR}/src -name "_pyupm_*.so" -exec cp {} ${CMAKE_BINARY_DIR}/pyupm \;
+      COMMAND find ${CMAKE_BINARY_DIR}/src -name "pyupm_*.py" -exec cp {} ${CMAKE_BINARY_DIR}/pyupm \;
+      COMMAND ${SPHINX_API_EXECUTABLE} -f -o pydoc  ${CMAKE_BINARY_DIR}/pyupm
+      # todo: use a separate cmake FILE module for string replacement instead
+      COMMAND ${SPHINX_EXECUTABLE} -b html pydoc html/python
+      COMMAND sed -i.bak s|\">pyupm_|\">|g html/python/index.html html/python/modules.html
+      COMMAND sed -i.bak s|[[:space:]]module</a>|</a>|g html/python/index.html html/python/modules.html
+      DEPENDS doc
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Generating API documentation with Sphinx" VERBATIM
+    )
+  endif ()
+  # check if Yuidoc is installed and add target for API documentation
+  find_package(Yuidoc)
+  if(YUIDOC_FOUND AND BUILDSWIGNODE)
+    # node required for Yuidoc documentation
+    find_package(Node)
+    file(GLOB_RECURSE JSDOC_FILES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}/doxy/node doxy/node/*)
+    foreach(JSDOC_FILE ${JSDOC_FILES})
+      configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxy/node/${JSDOC_FILE} ${CMAKE_CURRENT_BINARY_DIR}/${JSDOC_FILE} COPYONLY)
+    endforeach()
+    add_custom_target(jsdoc ALL
+      COMMAND ${NODE_EXECUTABLE} docgen -m upm -i xml -t ${CMAKE_CURRENT_SOURCE_DIR}/src -g ../../../../docs/images/
+      COMMAND ${YUIDOC_EXECUTABLE} -C --no-sort --helpers generators/yuidoc/helper.js --themedir generators/yuidoc/tmpl -o html/node jsdoc/yuidoc/upm
+      COMMAND ${NODE_EXECUTABLE} tolower -i html/node
+      DEPENDS doc
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Generating API documentation with Yuidoc" VERBATIM
+    )
+  endif()
+endif()
 
 if (IPK)
   include (TargetArch)
   target_architecture (DETECTED_ARCH)
   message( INFO " - Target arch is ${DETECTED_ARCH}")
 
-  set(CPACK_GENERATOR "DEB")
+  set(CPACK_GENERATOR "DEB" "TGZ")
   set(OPKG_ARCH ${DETECTED_ARCH})
   set(CPACK_BINARY_DIR ${CMAKE_BINARY_DIR})
   set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Intel IoT-Devkit") #required
@@ -75,7 +135,7 @@ if (IPK)
   set(CPACK_DEBIAN_PACKAGE_SECTION "libs")
   set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE ${DETECTED_ARCH})
   set(CPACK_SYSTEM_NAME ${DETECTED_ARCH})
-  set(CPACK_DEBIAN_PACKAGE_DEPENDS "libmaa0 (>= ${MAA_VERSION})")
+  set(CPACK_DEBIAN_PACKAGE_DEPENDS "libmraa0 (>= ${MRAA_VERSION})")
   set(CPACK_DEBIAN_PACKAGE_PROVIDES "upm-dev, upm-dbg, upm-doc")
   set(CPACK_DEBIAN_PACKAGE_REPLACES ${CPACK_DEBIAN_PACKAGE_PROVIDES})
   set(CPACK_DEBIAN_PACKAGE_CONFLICTS ${CPACK_DEBIAN_PACKAGE_PROVIDES})
@@ -84,4 +144,7 @@ if (IPK)
 endif()
 
 add_subdirectory (src)
-add_subdirectory (examples)
+
+if(BUILDEXAMPLES)
+  add_subdirectory (examples/c++)
+endif()

README.md

@@ -1,26 +1,67 @@
-UPM - Sensor/Actuator repository for Maa
+UPM - Sensor/Actuator repository for libmraa
 ==============
 
-UPM is a high level repository for sensors that use maa. Each sensor links to
-libmaa and are not meant to be interlinked although some groups of sensors may
-be. Each sensor contains a header which allows to interface with it. Typically
-a sensor is represented as a class and instanciated.
+UPM is a high level repository for sensors that use libmraa. Each sensor links
+to libmraa and are not meant to be interlinked although some groups of sensors
+may be. Each sensor contains a header which allows to interface with it.
+Typically a sensor is represented as a class and instantiated.
 
-The constructor is expected to initialise the sensor and paramters may be used
+The constructor is expected to initialise the sensor and parameters may be used
 to provide identification/pin location on the board.
 
 Typically an update() function will be called in order to get new data from the
 sensor in order to reduce load when doing multiple reads to sensor data.
 
-A basic sensor is expected to work as such:
-s = new sensor();
-print(sensor->read());
-sleep(1);
-s->update();
-print(sensor->read();
+### Example
 
-However implementation and API design is compeltely up to the developer, some
-enumerable sensors for example may provide much clever instanciation. Displays
+A sensor/actuator is expected to work as such (here is the servo ES08A API):
+@snippet es08a.cxx Interesting
+
+However implementation and API design is completely up to the developer, some
+enumerable sensors for example may provide much clever instantiation. Displays
 may also create more complex structures in order to interface with them.
 
-For more information on maa, see the maa documentation
+Browse through the list of all [examples](https://github.com/intel-iot-devkit/upm/tree/master/examples).
+
+### Supported Sensors
+
+Supported [sensor list](http://iotdk.intel.com/docs/master/upm/modules.html) from API documentation.
+
+You can also refer to the [Intel® IoT Developer Zone](https://software.intel.com/iot/sensors).
+
+### IDE Integration
+
+If you would like to create Eclipse IDE projects using the UPM C++ samples,
+please follow the instructions posted [here](https://software.intel.com/en-us/node/551014).
+This will show you how to import the code and configure your project.
+
+### Building UPM
+
+See @ref building [here](docs/building.md).
+
+### Making your own UPM module
+
+@ref porting [link](docs/porting.md) has more information on making new UPM modules.
+
+There is also an example available for @ref max31855 [sensor](docs/max31855.md).
+
+### Naming conventions and rules for new UPM contributions
+
+Before you begin development, take a look at our @ref naming [conventions](docs/naming.md).
+
+Also, please read the guidelines for @ref contributions [to UPM](docs/contributions.md).
+
+Don't forget to check the @ref documentation [section](docs/documentation.md).
+
+Make sure you add yourself as an author on every new code file submitted.
+If you are providing a fix with significant changes, feel free to add yourself
+as a contributor. Signing-off your commits is mandatory.
+
+C/C++ API Documentation
+==============
+
+The C/C++ documentation is available [here](http://iotdk.intel.com/docs/master/upm/).
+
+Version @ref changelog [here](docs/changelog.md).
+
+List of @ref knownlimitations [here](docs/knownlimitations.md).

cmake/modules/FindNode.cmake

@@ -0,0 +1,60 @@
+find_program (NODE_EXECUTABLE NAMES node
+    HINTS
+    $ENV{NODE_DIR}
+    PATH_SUFFIXES bin
+    DOC "Node.js interpreter"
+)
+
+include (FindPackageHandleStandardArgs)
+
+find_path (NODE_ROOT_DIR "node/node.h" "src/node.h"
+  PATHS /usr/include/nodejs /usr/local/include/nodejs)
+
+set (NODE_INCLUDE_DIRS
+  ${NODE_ROOT_DIR}/src
+  ${NODE_ROOT_DIR}/node
+  ${NODE_ROOT_DIR}/deps/v8/include
+  ${NODE_ROOT_DIR}/deps/uv/include
+)
+
+find_package_handle_standard_args (Node DEFAULT_MSG
+    NODE_EXECUTABLE
+    NODE_INCLUDE_DIRS
+)
+
+if (NODE_EXECUTABLE)
+    execute_process(COMMAND ${NODE_EXECUTABLE} --version
+                    OUTPUT_VARIABLE _VERSION
+                    RESULT_VARIABLE _NODE_VERSION_RESULT)
+    execute_process(COMMAND ${NODE_EXECUTABLE} -e "console.log(process.versions.v8)"
+                    OUTPUT_VARIABLE _V8_VERSION
+                    RESULT_VARIABLE _V8_RESULT)
+    if (NOT _NODE_VERSION_RESULT AND NOT _V8_RESULT)
+        string (REPLACE "v" "" NODE_VERSION_STRING "${_VERSION}")
+        string (REPLACE "." ";" _VERSION_LIST "${NODE_VERSION_STRING}")
+        list (GET _VERSION_LIST 0 NODE_VERSION_MAJOR)
+        list (GET _VERSION_LIST 1 NODE_VERSION_MINOR)
+        list (GET _VERSION_LIST 2 NODE_VERSION_PATCH)
+        set (V8_VERSION_STRING ${_V8_VERSION})
+        string (REPLACE "." ";" _V8_VERSION_LIST "${_V8_VERSION}")
+        string (REPLACE "." "" V8_DEFINE_STRING "${_V8_VERSION}")
+        list (GET _V8_VERSION_LIST 0 V8_VERSION_MAJOR)
+        list (GET _V8_VERSION_LIST 1 V8_VERSION_MINOR)
+        list (GET _V8_VERSION_LIST 2 V8_VERSION_PATCH)
+        # we end up with a nasty newline so strip everything that isn't a number
+        string (REGEX MATCH "^[0-9]*" V8_VERSION_PATCH ${V8_VERSION_PATCH})
+    else ()
+        set (NODE_VERSION_STRING "0.10.30")
+        set (NODE_VERSION_MAJOR "0")
+        set (NODE_VERSION_MINOR "10")
+        set (NODE_VERSION_PATCH "30")
+        set (V8_VERSION_MAJOR "3")
+        set (V8_VERSION_MAJOR "14")
+        set (V8_VERSION_MAJOR "5")
+        set (V8_VERSION_STRING "3.28.72")
+        message ("defaulted to node 0.10.30")
+    endif ()
+    message ("INFO - Node version is " ${NODE_VERSION_STRING} "INFO - Node using v8 " ${V8_VERSION_STRING})
+endif ()
+
+mark_as_advanced (NODE_EXECUTABLE)

cmake/modules/FindSphinx.cmake

@@ -0,0 +1,31 @@
+find_program (SPHINX_EXECUTABLE NAMES sphinx-build
+    HINTS $ENV{SPHINX_DIR}
+    PATH_SUFFIXES bin
+    DOC "Sphinx documentation html generator"
+)
+
+find_program (SPHINX_API_EXECUTABLE NAMES sphinx-apidoc
+    HINTS $ENV{SPHINX_DIR}
+    PATH_SUFFIXES bin
+    DOC "Sphinx documentation rst generator"
+)
+
+include (FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args (Sphinx DEFAULT_MSG
+    SPHINX_EXECUTABLE
+    SPHINX_API_EXECUTABLE
+)
+
+# Get Sphinx version
+if (SPHINX_EXECUTABLE)
+    execute_process(COMMAND ${SPHINX_EXECUTABLE} --version
+                    OUTPUT_VARIABLE SPHINX_VERSION)
+    if(SPHINX_VERSION)
+      string(REGEX MATCH "([0-9]\\.[0-9]\\.[0-9])" SPHINX_VERSION_STR ${SPHINX_VERSION})
+      message ("INFO - Sphinx version is " ${SPHINX_VERSION_STR})
+    endif()
+endif ()
+
+mark_as_advanced (SPHINX_EXECUTABLE)
+mark_as_advanced (SPHINX_API_EXECUTABLE)

cmake/modules/FindYuidoc.cmake

@@ -0,0 +1,23 @@
+find_program (YUIDOC_EXECUTABLE NAMES yuidoc
+    HINTS $ENV{YUIDOC_DIR}
+    PATHS usr usr/local
+    PATH_SUFFIXES bin
+    DOC "Yuidoc documentation generator"
+)
+
+include (FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args (Yuidoc DEFAULT_MSG
+    YUIDOC_EXECUTABLE
+)
+
+# Get Yuidoc version
+if (YUIDOC_EXECUTABLE)
+    execute_process(COMMAND ${YUIDOC_EXECUTABLE} --version
+                    ERROR_VARIABLE YUIDOC_VERSION)
+    if(YUIDOC_VERSION)
+      message ("INFO - Yuidoc version is " ${YUIDOC_VERSION})
+    endif()
+endif ()
+
+mark_as_advanced (YUIDOC_EXECUTABLE)

docs/building.md

@@ -0,0 +1,111 @@
+Building UPM                         {#building}
+============
+
+UPM uses cmake in order to make compilation relatively painless. Cmake runs
+build out of tree so the recommended way is to clone from git and make a build/
+directory. Failure to do an out-of-source build may cause issues when
+rebuilding later on.
+
+This project depends on libmraa, so that needs to be installed first. Use the
+following environment variables to configure the paths:
+
+    PKG_CONFIG_PATH=$PKG_CONFIG_PATH:.../mraa/build/lib/pkgconfig
+    CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:.../mraa/build/include
+    LIBRARY_PATH=$LIBRARY_PATH:.../mraa/build/lib
+
+UPM will attempt to build all directories inside src/ and they must contain
+individual CMakeLists.txt files.
+
+~~~~~~~~~~~~~{.sh}
+mkdir build
+cd build
+cmake ..
+make
+make install
+~~~~~~~~~~~~~
+
+The last command will create the include/ and lib/ directories with a copy of
+the headers and library objects respectively in your build location.
+
+Our cmake configure has a number of options, *cmake-gui* or *ccmake* can show
+you all the options. The interesting ones are detailed below:
+
+Changing install path from /usr/local to /usr
+~~~~~~~~~~~~~
+-DCMAKE_INSTALL_PREFIX:PATH=/usr
+~~~~~~~~~~~~~
+Building debug build:
+~~~~~~~~~~~~~
+-DCMAKE_BUILD_TYPE=DEBUG
+~~~~~~~~~~~~~
+Using clang instead of gcc:
+~~~~~~~~~~~~~
+-DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
+~~~~~~~~~~~~~
+Cross-compiling on a different system:
+~~~~~~~~~~~~~
+-DCMAKE_CXX_FLAGS:STRING=-m32 -march=i586
+-DCMAKE_C_FLAGS:STRING=-m32 -march=i586
+~~~~~~~~~~~~~
+Building with an older version of swig (swig 2.0+) requires the disabling of javascript:
+~~~~~~~~~~~~~
+-DBUILDSWIGNODE=OFF
+~~~~~~~~~~~~~
+Disabling python module building
+~~~~~~~~~~~~~
+-DBUILDSWIGPYTHON=OFF
+~~~~~~~~~~~~~
+Setting the python library to use:
+~~~~~~~~~~~~~
+-DPYTHON_LIBRARY:FILEPATH=/usr/lib/libpython2.7.so.1.0
+~~~~~~~~~~~~~
+Building doxygen doc
+~~~~~~~~~~~~~
+-BUILDDOC=ON
+~~~~~~~~~~~~~
+
+If you intend to turn on all the options and build everything at once (C++,
+Node, Python and Documentation) you will have to edit the src/doxy2swig.py file
+and change the line endings from Windows style to Linux format. This has to be
+repeated every time to sync with the master branch since our Github repository
+stores files using CR LF line breaks.
+
+You can also generate the include and lib directories containing all the sensor
+headers and library files respectively with *make install*. Further, you may
+choose to generate these only for a specific sensor you modified, and this can
+be achieved by building from the individual makefile of the sensor. Assuming
+you're in the build directory, to make the lcd module you would:
+
+~~~~~~~~~~~~~
+cd src/lcd
+make install
+~~~~~~~~~~~~~
+
+Often developers are only interested in building one module or even just the
+python/node module to do some quick testing using scripting. In order to do
+this you need to use the target name for the python or node module you want to
+rebuild. For example the lcd module target name is i2clcd. Therefore the python
+module target name will be prefixed by _pyupm_. Just do the following to build
+only that module. Modules not using the UPM cmake macros may have different
+naming.
+
+~~~~~~~~~~~~~
+make _pyupm_i2clcd
+~~~~~~~~~~~~~
+
+Sometimes you want to build a small C++ example against an installed library.
+This is fairly easy if installed system-wide. Just link against the correct
+library (in this case libupm-i2clcd) and then add /usr/include/upm to the
+loader path:
+
+~~~~~~~~~~~~
+g++ test.cxx -lupm-i2clcd -I/usr/include/upm
+~~~~~~~~~~~~
+
+You can also use pkg-config to return the information to you, which is
+considered the correct way if including UPM in a build system like cmake or
+autotools on linux.
+
+~~~~~~~~~~~
+pkg-config --cflags --libs upm-i2clcd
+~~~~~~~~~~~

docs/changelog.md

@@ -0,0 +1,84 @@
+Changelog                         {#changelog}
+===============
+
+Here's a list summarizing some of the key undergoing changes to our library
+from earlier versions:
+
+### v0.3.0
+
+ * New CMake targets to build python and node documentation with Sphinx and
+ Yuidoc
+ * Edited sensor names, library descriptions and doxygen tags for consistency
+ * Added support for several new sensors
+ * Fixed the TH02 sensor driver and made major improvements to i2clcd driver
+ * Updated and added new images for a lot of the existing sensors
+ * Added this changelog
+
+### v0.2.0
+
+ * Passed 100 supported sensor drivers
+ * Updated header files with new doxygen tags for improved API documentation
+ generation
+ * Added python examples for sensors
+ * Fixed the buzzer and servo drivers for the Intel Edison
+ * Renamed bmp and gp2y sensor classes to be more generic
+ * Completely revamped implementation for tm1637
+
+### v0.1.9
+
+ * Passed 50 supported sensor drivers
+ * Starter Kit and Additional Roadshow and Hackaton sensors added
+ * Several examples and documentation updates submitted
+ * Wrote new proper SWIG typemaps for arrays
+ * Fixed the i2clcd write function, improved several other sensors
+
+### v0.1.8
+
+ * Added MQ series gas sensors and a few others
+ * Generated Doxygen layout file to improve API look and feel
+ * Several sensor documentation updates
+
+### v0.1.7
+
+ * Fixed SWIG node build issues
+ * Added lpd8806 digital led strip
+
+### v0.1.6
+
+ * Fixed SWIG python builds
+ * Extended i2clcd devices with new functions
+ * Made SWIG interface improvements and added extra types
+ * Added nrf8001 BLE support
+ * Few other sensor additions and fixes
+
+### v0.1.5
+
+ * New drivers for microphone and mpu9150
+ * Added generic driver for stepper motors
+ * Updated all code to use MRAA and version dependency
+
+### v0.1.4
+
+ * Added new bmp/gy pressure sensor and updated servo
+ * Started UPM documentation and related pages
+ * Updated MRAA dependencies
+
+### v0.1.3
+
+ * Updated SWIG support for some sensors
+ * New sensor support for mma7455 accelerometer
+
+### v0.1.2
+
+ * Several new sensors added
+ * Documentation fixes
+ * IPK generation
+
+### v0.1.1
+
+ * Updated MRAA dependency
+
+### v0.1.0
+
+ * Initial release with some basic grove sensors and hmc5883
+ * Doxygen and SWIG support implemented

docs/contributions.md

@@ -0,0 +1,96 @@
+Contributing a module                         {#contributions}
+=====================
+
+Here are the rules of contribution:
+- Your new module must have an example that builds against your UPM library.
+- Each commit must have a sign-off line by everyone who authored or reviewed
+  them.
+- Commits must be named `<file/module>: Some decent description`.
+- You must license your module under a FOSS license. The recommended license
+  is MIT but any permissive license is fine. Please consider that people using
+  UPM may want to write proprietary programs with your sensors so we like to
+  avoid GPL. If your license is not MIT please include a LICENSE file in
+  src/mymodule/.
+- The top of each source file must contain a comment block containing the
+  license information.
+- Please test your module builds before contributing and make sure it works on
+  the latest version of libmraa. If you tested on a specific board/platform
+  please tell us what this was in your PR.
+- Try not to break master. In any commit.
+- Attempt to have some decent API documentation as described in the the @ref
+  documentation [guide](documentation.md).
+
+Including the MIT license
+=========================
+Choosing the [MIT license](http://opensource.org/licenses/MIT) is preferred for
+the UPM repository.  Below is the comment block needed at the top each source
+file:
+
+        /*
+         * The MIT License (MIT)
+         *
+         * Author: <your full name> 
+         * 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.
+         */
+
+
+Code signing
+============
+
+The sign-off is a simple line at the end of the explanation for the
+patch, which certifies that you wrote it or otherwise have the right to pass it
+on as an open-source patch.  The rules are pretty simple: if you can certify
+the below:
+
+        Developer's Certificate of Origin 1.1
+
+        By making a contribution to this project, I certify that:
+
+        (a) The contribution was created in whole or in part by me and I
+            have the right to submit it under the open source license
+            indicated in the file; or
+
+        (b) The contribution is based upon previous work that, to the best
+            of my knowledge, is covered under an appropriate open source
+            license and I have the right under that license to submit that
+            work with modifications, whether created in whole or in part
+            by me, under the same open source license (unless I am
+            permitted to submit under a different license), as indicated
+            in the file; or
+
+        (c) The contribution was provided directly to me by some other
+            person who certified (a), (b) or (c) and I have not modified
+            it.
+
+        (d) I understand and agree that this project and the contribution
+            are public and that a record of the contribution (including all
+            personal information I submit with it, including my sign-off) is
+            maintained indefinitely and may be redistributed consistent with
+            this project or the open source license(s) involved.
+
+then you just add a line to each of your commits with `--signoff` saying
+
+        Signed-off-by: Random J Developer <random@developer.example.org>
+
+using your real name (sorry, no pseudonyms or anonymous contributions.)
+Unsigned commits will not be accepted.

docs/documentation.md

@@ -0,0 +1,114 @@
+Writing sensor documentation                        {#documentation}
+=====================
+
+It is highly encouraged to provide at least some basic documentation for the
+sensors that you want to add to UPM:
+
+- If you don't add documentation, the code review will take very long and 
+  your contribution could be rejected.
+- Try to have no warnings in doxygen, this is generally fairly easy.
+- Have the specific sensor manufacturer/model & version that you used, if you
+  support multiple versions please list.
+- Simple comments do not need full stops.
+- Stick to <80 chars per line even in comments.
+- No text is allowed on the same line as the start or end of a comment /** */.
+
+####The sensor block
+
+This is added just before the class declaration in your header(.h) file and has 
+mandatory fields. For single sensor libraries, this block will actually
+follow immediately after the library block. If you have multiple physical
+sensors, add this to every one.
+Here's an example (disregard the "@verbatim" tags in your actual code):
+
+```
+@verbatim
+/**
+ * @library <lib-name>
+ * @sensor <chip-id>
+ * @comname <component-name>
+ * @altname <alt-name>
+ * @type <component-category>
+ * @man <component-manufacturer>
+ * @web <component-weblinks>
+ * @con <connection-type>
+ * @kit <component-kit>
+ *
+ * @brief Short class/sensor description
+ * 
+ *   Then add a longer
+ *   description here.
+ *
+ * @image html <component-img.jpeg>
+ * @snippet <example-name.cxx> Interesting
+ */
+@endverbatim
+```
+
+- `<lib-name>` When adding to an existing library this needs to match that
+  library's "@defgroup", otherwise this is a new library name, generally the
+  same as chip id. *Mandatory*
+- `<chip-id>` Usually the chip number used by the sensor. When this is not
+  available or relevant, use a unique descriptor that makes sense. *Mandatory*
+- `<component-name>` A short name for your sensor, can include manufacturer
+  name. *Mandatory*
+- `<alt-name>` Alternative names or chip-ids that your sensor driver might
+  have or support respectively. *Optional*
+- `<component-category>` Mention one or more categories the sensor fits in. Can
+  be 'other'. *Mandatory*
+- `<component-manufacturer>` Sensor manufacturer. Can be 'generic'. *Mandatory*
+- `<component-weblinks>` Links to vendors or data-sheets. *Optional*
+- `<connection-type>` Specifies how does the sensor connect to the board
+  *Mandatory*
+- `<component-kit>` Specifies if the sensor is part of a kit. *Optional*
+
+Existing groups that can be used for the manufacturer, connection, category and
+kit tags are found in the src/upm.h file.
+
+Optionally, a small representative image can be placed in the "docs/images"
+subfolder and linked with the "@image" tag.
+**Please do not use existing, copyrighted images with your sensors!**
+
+The example should have an 'Interesting' section which will be highlighted as
+a code sample in doxygen. Everything in between such tags will show up in the
+class documentation when "@snippet" is added at the end of a class docstring.
+Tags use this format (in "example-name.cxx"):
+
+```
+@verbatim
+ //! [Interesting]
+
+    ...example code here...
+
+ //! [Interesting]
+@endverbatim
+```
+
+For more examples take a look at the existing headers in our github repository.
+
+####The library block
+
+New libraries must have the "@brief", "@defgroup" and "@ingroup" tags in one
+block. This usually follows the namespace and it is common to have one sensor
+per library.
+
+You should end up with something like this:
+
+```
+@verbatim
+/**
+ * @brief Short description for entire library
+ *
+ * Optional longer description.
+ *
+ * @defgroup <lib-name> libupm-<lib-name>
+ * @ingroup <manufacturer> <connection> <category> (<kit>)
+ */
+@endverbatim
+```
+
+In "@defgroup" use the same `<lib-name>` used in the sensor block. Multiple
+sensors can be added to the same library this way.
+For "@ingroup" add the same values as in the sensor block for manufacturer,
+category, connection type and kit. If you have multiple classes or sensors
+per library, only use the "@ingroup" tags that are common for all of them.