upm: v1.0.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
+

.gitignore

@@ -1,4 +1,4 @@
-build/
+build*/
 
 # Object files
 *.o

.travis.yml

@@ -0,0 +1,48 @@
+language: cpp
+env:
+  global:
+    - MRAA_ROOT=/tmp/mraa
+    - MRAA_BUILD=$MRAA_ROOT/build
+    - UPM_ROOT=$TRAVIS_BUILD_DIR
+    - UPM_BUILD=$UPM_ROOT/build
+    - JAVA_HOME=/usr/lib/jvm/java-8-oracle
+  matrix:
+    - NODE010=true
+    - NODE012=true
+    - NODE4=true
+    - NODE5=true
+compiler:
+  - clang
+  - gcc
+install:
+  - sudo add-apt-repository --yes ppa:fenics-packages/fenics-dev/swig
+  - sudo apt-get update -qq
+  - sudo apt-get install -y --force-yes -qq swig3.0 git
+  - sudo ln -s /usr/bin/swig3.0 /usr/bin/swig
+  - sudo update-java-alternatives -s java-8-oracle
+before_script:
+  # Turn off JAVA SWIG for clang++, use 4.8 for all g++ builds
+  - if [ "$CC" == "gcc" ]; then export BUILDJAVA=ON; export CC=gcc-4.8; export CXX=g++-4.8; else export BUILDJAVA=OFF; fi
+  - if [ "${NODE012}" ]; then nvm install 0.12; fi
+  - if [ "${NODE4}" ]; then nvm install 4.1; fi
+  - if [ "${NODE5}" ]; then nvm install 5; fi
+  # Handle 0.10 NODE_ROOT_DIR differently than other versions
+  - if [ -z ${NODE010} ]; then export NODE_ROOT_DIR="/home/travis/.nvm/versions/node/`nvm version`"; else export NODE_ROOT_DIR=/home/travis/.nvm/v0.10.36; fi
+script:
+  # Build/install MRAA
+  - echo "CC=$CC BUILDJAVA=$BUILDJAVA NODE010=$NODE010 NODE012=$NODE012 NODE4=$NODE4 NODE5=$NODE5 NODE_ROOT_DIR=$NODE_ROOT_DIR"
+  - git clone https://github.com/intel-iot-devkit/mraa.git $MRAA_ROOT
+  - mkdir -p $MRAA_BUILD && cd $_ && cmake -DBUILDSWIGJAVA=$BUILDJAVA -DBUILDSWIGNODE=OFF -DBUILDSWIGPYTHON=ON -DFIRMATA=ON -DENABLEEXAMPLES=OFF $MRAA_ROOT
+  - sudo make install
+  - sudo ldconfig
+  # Build/install UPM
+  - cd $UPM_ROOT && mkdir $UPM_BUILD && cd $_ && cmake -DNODE_ROOT_DIR:PATH="${NODE_ROOT_DIR}" -DBUILDSWIGJAVA=$BUILDJAVA -DBUILDEXAMPLES=ON -DBUILDJAVAEXAMPLES=$BUILDJAVA -DBUILDTESTS=ON .. && sudo make install && sudo ldconfig && ctest --output-on-failure -E examplenames_js
+addons:
+  apt:
+    sources:
+      - ubuntu-toolchain-r-test
+      - george-edison55-precise-backports
+    packages:
+      - cmake
+      - cmake-data
+      - g++-4.8

CMakeLists.txt

@@ -1,39 +1,197 @@
 cmake_minimum_required (VERSION 2.8.11)
 project (upm)
 
+# Before going any further, define build options
+option (BUILDDOC "Build all doc" OFF)
+option (BUILDCPP "Build CPP sensor libraries" ON)
+option (BUILDFTI "Build Funtion Table Interface (FTI) in C sensor libraries" OFF)
+option (BUILDSWIGPYTHON "Build swig python modules" ON)
+option (BUILDSWIGNODE "Build swig node modules" ON)
+option (BUILDSWIGJAVA "Build swig java modules" OFF)
+option (BUILDEXAMPLES "Build C/C++ example binaries" OFF)
+option (BUILDJAVAEXAMPLES "Build java example jars" OFF)
+option (IPK "Generate IPK using CPack" OFF)
+option (RPM "Generate RPM using CPack" OFF)
+option (NPM "Generate NPM/GYP tarballs" OFF)
+option (BUILDTESTS "Generate check-ups for upm" OFF)
+option (WERROR "Make all warnings into errors." OFF)
+
+# Warn if building in source root
 if ("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
-message("WARNING: building into sources dir can be risky, prefer other directory")
+  message (WARNING "Building into sources dir can be risky, prefer other directory")
 endif ()
 
-find_package (SWIG)
-if (SWIG_FOUND)
-  include (${SWIG_USE_FILE})
-endif ()
-
-find_package (Threads REQUIRED)
-find_package (PkgConfig REQUIRED)
-# force the libmraa version to be the required version
-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
+# Check if provided compiler supports target flag
+# usage:
+#       compiler_flag_supported(C/CXX is_supported flag)
+#
+# The result of output_variable is set to the sanitized flag name if supported
+# or cleared if the flag is not supported.
+function (compiler_flag_supported compiler output_variable flag)
+  # Currently only C and CXX compile flags, clear and return if not supported
+  if (NOT ${compiler} MATCHES "C|CXX")
+    message (WARNING "Unknown compiler: ${compiler}")
+    set ("${output_variable}" "" PARENT_SCOPE)
+    return ()
+  endif (NOT ${compiler} MATCHES "C|CXX")
+
+  string (REPLACE "-" "_" SANITIZED_FLAG_NAME "${flag}")
+  string (REPLACE "/" "_" SANITIZED_FLAG_NAME "${SANITIZED_FLAG_NAME}")
+  string (REPLACE "=" "_" SANITIZED_FLAG_NAME "${SANITIZED_FLAG_NAME}")
+  string (REPLACE " " "_" SANITIZED_FLAG_NAME "${SANITIZED_FLAG_NAME}")
+
+  # Disable messages from CHECK_C/XX_COMPILER_FLAGS macros
+  set (CMAKE_REQUIRED_QUIET_SAVED ${CMAKE_REQUIRED_QUIET})
+  set (CMAKE_REQUIRED_QUIET ON)
+
+  # C or CXX?
+  if (${compiler} STREQUAL C)
+    CHECK_C_COMPILER_FLAG("${flag}" HAS_${SANITIZED_FLAG_NAME})
+  elseif (${compiler} STREQUAL CXX)
+    CHECK_CXX_COMPILER_FLAG("${flag}" HAS_${SANITIZED_FLAG_NAME})
+  endif ()
+
+  # Restore previous CMAKE_REQUIRED_QUIET state
+  set (CMAKE_REQUIRED_QUIET ${CMAKE_REQUIRED_QUIET_SAVED})
+
+  # Does the compiler support this flag?
+  if (HAS_${SANITIZED_FLAG_NAME})
+    set ("${output_variable}" "${SANITIZED_FLAG_NAME}" PARENT_SCOPE)
+  else ()
+    set ("${output_variable}" "" PARENT_SCOPE)
+  endif()
+endfunction ()
+
+include (CheckCCompilerFlag)
+include (CheckCXXCompilerFlag)
+# Add scoped compile flag/s using add_compile_options.
+# This function checks to see if each flag is supported
+# by the compiler before setting the compile option.
+function (upm_add_compile_flags compiler)
+  # Iterate the flags, check if supported
+  foreach (flag ${ARGN})
+    # Check if this compile flag is supported
+    compiler_flag_supported(${compiler} is_supported ${flag})
+
+    # Add if supported, warn and skip if not supported
+    if (is_supported)
+      set (_TMP_COMPILER_FLAGS "${_TMP_COMPILER_FLAGS} ${flag}")
+    else ()
+      message (WARNING "${compiler} compiler does not support flag \"${flag}\"")
+    endif ()
+  endforeach (flag ${ARGN})
+
+  # Set the variable in the parent scope
+  set (CMAKE_${compiler}_FLAGS ${_TMP_COMPILER_FLAGS} PARENT_SCOPE)
+endfunction ()
+
+# Compiler flags common to both C and CXX
+set (C_CXX_WARNING_FLAGS -Wall)
+
+# Errors as warnings?
+if (WERROR)
+  list (APPEND C_CXX_WARNING_FLAGS -Werror)
+  message (STATUS "Warnings as errors enabled (-Werror), disable with -DWERROR=off")
+endif (WERROR)
+
+# Set C compiler warning flags at top-level scope and emit a warning about
+# unsupported flags
+upm_add_compile_flags(C ${C_CXX_WARNING_FLAGS}
+  -Winit-self
+  -Wimplicit
+  -Wmissing-parameter-type)
+
+# Set CXX compiler warning flags at top-level scope and emit a warning about
+# unsupported flags
+upm_add_compile_flags(CXX ${C_CXX_WARNING_FLAGS}
+  -Wnon-virtual-dtor
+  -Woverloaded-virtual
+  -Wreorder)
+
+find_package (Threads REQUIRED)
+find_package (PkgConfig REQUIRED)
+
+# Force a libmraa search and minimum required version every time a config is generated
+unset(MRAA_FOUND CACHE)
+set(MRAA_MINIMUM 1.1.1)
+pkg_check_modules (MRAA REQUIRED mraa>=${MRAA_MINIMUM})
+
+# Check for BACNET
+pkg_check_modules (BACNET libbacnet)
+
+# Check for MODBUS
+pkg_check_modules (MODBUS libmodbus>=3.1.2)
+
+# Check for OPENZWAVE
+pkg_check_modules (OPENZWAVE libopenzwave)
+
+# Find JPEG
+find_package (JPEG)
+
+# Find nodejs
+if (BUILDSWIGNODE)
+  find_package (Node REQUIRED)
+endif (BUILDSWIGNODE)
+
+# Find swig if any wrapper is enabled
+if (BUILDSWIGPYTHON OR BUILDSWIGNODE OR BUILDSWIGJAVA)
+  find_package (SWIG 3.0.5 REQUIRED)
+  include (${SWIG_USE_FILE})
+endif ()
+
+# Python is required for swig generated python and for UPM tests.
+# The UPM build can generated modules for both python2 AND python3
+# with the corresponding PYTHONLIBS.  Currently, BUILDTESTS has a
+# hard dependency on the PYTHON2INTERP.
+# OpenCV python detect will attempt to find python2/3
+if (BUILDSWIGPYTHON OR BUILDTESTS)
+  include (cmake/modules/OpenCVDetectPython.cmake)
+
+  # Fail if building tests but no python interpreter was found
+  if (BUILDTESTS AND NOT PYTHON2INTERP_FOUND)
+      message(FATAL_ERROR "BUILDTESTS=ON requires the python2 interpreter")
+  endif (BUILDTESTS AND NOT PYTHON2INTERP_FOUND)
+
+  # Fail if no LIBS were found
+  if (NOT PYTHON2LIBS_FOUND AND NOT PYTHON3LIBS_FOUND)
+      message(FATAL_ERROR "At least one python lib is required")
+  endif (NOT PYTHON2LIBS_FOUND AND NOT PYTHON3LIBS_FOUND)
+endif (BUILDSWIGPYTHON OR BUILDTESTS)
+
+# Which versions of python were found?
+if (PYTHON2LIBS_FOUND AND BUILDSWIGPYTHON)
+  message(STATUS "Building python2 modules with python-${PYTHON2LIBS_VERSION_STRING}")
+endif (PYTHON2LIBS_FOUND AND BUILDSWIGPYTHON)
+if (PYTHON3LIBS_FOUND AND BUILDSWIGPYTHON)
+  message(STATUS "Building python3 modules with python-${PYTHON3LIBS_VERSION_STRING}")
+endif (PYTHON3LIBS_FOUND AND BUILDSWIGPYTHON)
+
+# Python2 is currently required for python documentation
+if (BUILDSWIGPYTHON AND BUILDDOC AND NOT PYTHON2INTERP_FOUND)
+  message(FATAL_ERROR "Failed to find python2 interpreter which is required "
+      "to build python documentation.")
+endif (BUILDSWIGPYTHON AND BUILDDOC AND NOT PYTHON2INTERP_FOUND)
+
+# Set CMAKE_INSTALL_LIBDIR if not defined
 include(GNUInstallDirs)
+set (LIB_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}" CACHE PATH "Installation path for libraries")
 
 # 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 libmraa!")
-  set (VERSION "v0.2.0-dirty")
+# If git_describe fails, use a dirty version
+if (${VERSION} MATCHES -NOTFOUND)
+  set (VERSION "v1.0.0-dirty")
+  message (WARNING "Failed to retrieve UPM version with 'git describe' (using "
+      "${VERSION}). Check that git is installed and this is a valid git repo.")
 endif ()
 
-message (INFO " - UPM Version ${VERSION}")
+message (STATUS "UPM Version ${VERSION}")
 
-#parse the version information into pieces.
+# Parse the version information into pieces.
 string (REGEX REPLACE "^v([0-9]+)\\..*" "\\1" VERSION_MAJOR "${VERSION}")
 string (REGEX REPLACE "^v[0-9]+\\.([0-9]+).*" "\\1" VERSION_MINOR "${VERSION}")
 string (REGEX REPLACE "^v[0-9]+\\.[0-9]+\\.([0-9]+).*" "\\1" VERSION_PATCH "${VERSION}")
@@ -49,34 +207,155 @@ set (upm_VERSION_MINOR ${VERSION_MINOR})
 set (upm_VERSION_PATCH ${VERSION_PATCH})
 set (upm_VERSION_STRING ${upm_VERSION_MAJOR}.${upm_VERSION_MINOR}.${upm_VERSION_PATCH})
 
-set (CMAKE_SWIG_FLAGS "")
+# Detect arch
+include (TargetArch)
+target_architecture (DETECTED_ARCH)
+message (STATUS "Target arch is ${DETECTED_ARCH}")
 
-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)
-
-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)
+#-march=native for ARM when not defined/forced
+if (DETECTED_ARCH MATCHES "arm.*" AND NOT CMAKE_CXX_FLAGS MATCHES "-march")
+  set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
 endif()
 
-if (IPK)
-  include (TargetArch)
-  target_architecture (DETECTED_ARCH)
-  message( INFO " - Target arch is ${DETECTED_ARCH}")
+# enable c++11 standards support unconditionally
+include(CheckCXXCompilerFlag)
+if (CMAKE_VERSION VERSION_LESS "3.1")
+  CHECK_CXX_COMPILER_FLAG("-std=c++11" COMPILER_SUPPORTS_CXX11)
+  CHECK_CXX_COMPILER_FLAG("-std=c++0x" COMPILER_SUPPORTS_CXX0X)
+  if (COMPILER_SUPPORTS_CXX11)
+    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
+  elseif (COMPILER_SUPPORTS_CXX0X)
+    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++0x")
+  else()
+    message(FATAL_ERROR "A C++11 compliant compiler is required to build UPM.")
+  endif()
+else()
+  # 3.1+ uses this generic method to enable c++11
+  set (CMAKE_CXX_STANDARD 11)
+  set (CXX_STANDARD_REQUIRED ON)
+  set (CXX_EXTENSIONS OFF)
+endif()
 
-  set(CPACK_GENERATOR "DEB" "TGZ")
-  set(OPKG_ARCH ${DETECTED_ARCH})
+include(CheckCCompilerFlag)
+if (CMAKE_VERSION VERSION_LESS "3.1")
+  CHECK_C_COMPILER_FLAG("-std=c11" COMPILER_SUPPORTS_C11)
+  if (COMPILER_SUPPORTS_C11)
+    set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=c11")
+  else()
+    message(FATAL_ERROR "A C11 compliant C compiler is required to build UPM.")
+  endif()
+else()
+  # 3.1+ uses this generic method to enable c11
+  set (CMAKE_C_STANDARD 11)
+  set (C_STANDARD_REQUIRED ON)
+  set (C_EXTENSIONS OFF)
+endif()
+
+# The doc target depends on each sensor target
+#
+# doc
+#   ├──> libupm_sensor0
+#   ├──> libupm_sensor1
+#   ├──> libupm_sensor2
+#   └──> libupm_sensor_n
+#
+# The pydoc target builds documentation with sphinx via inspection by loading
+# each python module.  Those modules must include the CXX documentation via
+# a monolithic swig file generated by doxy2swig
+#
+# pydoc
+#  └──> _pyupm_sensor0_python2
+#        ├──────> libupm_sensor0
+#        └──────> doxy2swig
+#
+# The doxy2swig target is dependent upon the doc target IF BUILDDOC=ON,
+# otherwise doxy2swig uses an empty file.  Doxy2swig also depends on each
+# sensor target
+#
+# doxy2swig
+#  ├──> BUILDDOC=ON───> doc
+#  └──> libupm_sensor0
+#
+# The jsdoc target builds js documentation via yuidoc and only requires
+# the doc target
+#
+# jsdoc ─> doc
+#
+if (BUILDDOC)
+  # Add a target to generate API documentation with Doxygen
+  find_package (Doxygen REQUIRED)
+  configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+  if (BUILDSWIGJAVA)
+      configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/Doxyfile.java.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-java @ONLY)
+  endif()
+  file(GLOB PNG_FILES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}/docs docs/icons/*.png)
+  foreach(PNG_FILE ${PNG_FILES})
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docs/${PNG_FILE} ${CMAKE_CURRENT_BINARY_DIR}/html/docs/${PNG_FILE} COPYONLY)
+  endforeach()
+  add_custom_target (doc
+    ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    COMMAND tar -czf html/xml.tar.gz -C xml .
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating API documentation with Doxygen" VERBATIM
+  )
+
+  # Check if Sphinx is installed and add target to generate API documentationa
+  # Currently, the per-module documentation for python is generated from the
+  # python2 modules.
+  if(BUILDSWIGPYTHON)
+    find_package (Sphinx REQUIRED)
+    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:]][mM]odule</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(BUILDSWIGPYTHON)
+
+  # Check if Yuidoc is installed and add target for API documentation
+  if(BUILDSWIGNODE)
+    find_package(Yuidoc REQUIRED)
+    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 ${NODEJS_EXECUTABLE} docgen -m upm -i xml -t ${CMAKE_CURRENT_SOURCE_DIR}/src -g ../../
+      COMMAND ${YUIDOC_EXECUTABLE} -C --no-sort --helpers generators/yuidoc/helper.js --themedir generators/yuidoc/tmpl -o html/node jsdoc/yuidoc/upm
+      COMMAND ${NODEJS_EXECUTABLE} tolower -i html/node
+      DEPENDS doc
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Generating API documentation with Yuidoc" VERBATIM
+    )
+  endif(BUILDSWIGNODE)
+endif (BUILDDOC)
+
+if (IPK)
+ # Get target package arch from Yocto ADT sysroot if set or host OS, mapping to Ubuntu name if necessary
+  if (DEFINED ENV{OECORE_TARGET_SYSROOT})
+    GET_FILENAME_COMPONENT (DETECTED_SYSROOT $ENV{OECORE_TARGET_SYSROOT} NAME)
+    string (REGEX REPLACE "-poky-linux" "" TARGET_ARCH "${DETECTED_SYSROOT}")
+  else ()
+    # Debian uses amd64 to denote x86_64
+    if (DETECTED_ARCH STREQUAL "x86_64")
+      set (TARGET_ARCH "amd64")
+    else ()
+      set (TARGET_ARCH ${DETECTED_ARCH})
+    endif ()
+  endif ()
+  message (STATUS "Package arch is ${TARGET_ARCH}")
+
+  set(CPACK_GENERATOR "DEB")
+  set(OPKG_ARCH ${TARGET_ARCH})
   set(CPACK_BINARY_DIR ${CMAKE_BINARY_DIR})
   set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Intel IoT-Devkit") #required
   set(upm_PACKAGE_ON_TAG ".")
@@ -87,9 +366,9 @@ if (IPK)
       "${upm_VERSION_MAJOR}.${upm_VERSION_MINOR}.${upm_VERSION_PATCH}${upm_PACKAGE_ON_TAG}${VERSION_COMMIT}")
   set(CPACK_PACKAGE_NAME "upm")
   set(CPACK_DEBIAN_PACKAGE_SECTION "libs")
-  set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE ${DETECTED_ARCH})
-  set(CPACK_SYSTEM_NAME ${DETECTED_ARCH})
-  set(CPACK_DEBIAN_PACKAGE_DEPENDS "libmraa0 (>= ${MRAA_VERSION})")
+  set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE ${TARGET_ARCH})
+  set(CPACK_SYSTEM_NAME ${TARGET_ARCH})
+  set(CPACK_DEBIAN_PACKAGE_DEPENDS "mraa (>= ${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})
@@ -97,5 +376,55 @@ if (IPK)
   include (CPack)
 endif()
 
+if (RPM)
+  message (STATUS "RPM packaging enabled for ${DETECTED_ARCH}")
+  set(CPACK_PACKAGE_VERSION ${VERSION})
+  set(CPACK_GENERATOR "RPM")
+  set(CPACK_PACKAGE_NAME "upm")
+  set(upm_PACKAGE_ON_TAG ".")
+  if ("${VERSION_COMMIT}" STREQUAL "")
+    set(upm_PACKAGE_ON_TAG "")
+  endif()
+  set(CPACK_PACKAGE_VERSION
+      "${upm_VERSION_MAJOR}.${upm_VERSION_MINOR}.${upm_VERSION_PATCH}${upm_PACKAGE_ON_TAG}${VERSION_COMMIT}")
+  set(CPACK_PACKAGE_CONTACT "Intel IoT-Devkit")
+  set(CPACK_PACKAGE_VENDOR "Intel IoT-Devkit")
+  set(CPACK_RPM_PACKAGE_REQUIRES "mraa >= ${MRAA_VERSION}")
+  set(CPACK_RPM_PACKAGE_PROVIDES "${CPACK_PACKAGE_NAME}-devel")
+  set(CPACK_RPM_PACKAGE_LICENSE "MIT")
+  EXECUTE_PROCESS(COMMAND rpm --showrc
+    COMMAND grep -E "dist[[:space:]]*\\."
+    COMMAND sed -e "s/^.*dist\\s*\\.//"
+    COMMAND tr \\n \\t
+    COMMAND sed  -e s/\\t//
+    OUTPUT_VARIABLE DIST_TAG)
+  set(CPACK_PACKAGE_FILE_NAME "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}.${DIST_TAG}.${DETECTED_ARCH}")
+  include(CPack)
+endif()
+
+# UPM common headers
+set (UPM_COMMON_HEADER_DIRS
+    ${CMAKE_HOME_DIRECTORY}/include
+    ${CMAKE_HOME_DIRECTORY}/include/fti)
+
 add_subdirectory (src)
-add_subdirectory (examples/c++)
+if(BUILDEXAMPLES)
+  add_subdirectory (examples/c)
+  if(BUILDCPP)
+    add_subdirectory (examples/c++)
+  endif(BUILDCPP)
+endif()
+
+if(BUILDJAVAEXAMPLES)
+  add_subdirectory (examples/java)
+endif()
+
+# Python interp is previously found if BUILDTESTS=ON
+if (BUILDTESTS)
+  enable_testing ()
+  add_subdirectory (tests)
+endif()
+
+# Install C headers
+install(DIRECTORY include/ DESTINATION include/upm
+    FILES_MATCHING PATTERN "*.h")

LICENSE

@@ -1,4 +1,4 @@
-Copyright © 2014 Intel Corporation
+Copyright © 2014-2015 Intel Corporation
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -1,57 +1,131 @@
-UPM - Sensor/Actuator repository for libmraa
+UPM (Useful Packages & Modules) Sensor/Actuator repository for MRAA
 ==============
 
-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 UPM repository provides software drivers for a wide variety of commonly
+used sensors and actuators. These software drivers interact with the
+underlying hardware platform (or microcontroller), as well as with the attached
+sensors, through calls to [MRAA](https://github.com/intel-iot-devkit/mraa) APIs.
 
-The constructor is expected to initialise the sensor and parameters may be used
-to provide identification/pin location on the board.
+Programmers can access the interfaces for each sensor by including the sensor’s
+corresponding header file and instantiating the associated sensor class. In the
+typical use case, a constructor initializes the sensor based on parameters that
+identify the sensor, the I/O protocol used and the pin location of the sensor.
 
-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.
+C++ interfaces have been defined for the following sensor/actuator types, but
+they are subject to change:
+
+* Light controller 
+* Light sensor
+* Temperature sensor
+* Humidity sensor
+* Pressure sensor
+* Gas sensor
+* Analog to digital converter
+
+The developer community is encouraged to help expand the list of supported
+sensors and actuators and provide feedback on interface design.
 
 ### Example
 
-A sensor/actuator is expected to work as such (here is the servo ES08A API):
-@snippet es08a.cxx Interesting
+A sensor/actuator is expected to work as such (here is the MMA7660 accelerometer API):
+```C++
+  // Instantiate an MMA7660 on I2C bus 0
+  upm::MMA7660 *accel = new upm::MMA7660(MMA7660_I2C_BUS,
+                                         MMA7660_DEFAULT_I2C_ADDR);
 
-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.
+  // place device in standby mode so we can write registers
+  accel->setModeStandby();
+
+  // enable 64 samples per second
+  accel->setSampleRate(upm::MMA7660::AUTOSLEEP_64);
+  
+  // place device into active mode
+  accel->setModeActive();
+
+  while (shouldRun)
+    {
+      int x, y, z;
+      
+      accel->getRawValues(&x, &y, &z);
+      cout << "Raw values: x = " << x 
+           << " y = " << y
+           << " z = " << z
+           << endl;
+      
+      float ax, ay, az;
+      
+      accel->getAcceleration(&ax, &ay, &az);
+      cout << "Acceleration: x = " << ax 
+           << "g y = " << ay
+           << "g z = " << az
+           << "g" << endl;
+      
+      usleep(500000);
+    }
+```
 
 Browse through the list of all [examples](https://github.com/intel-iot-devkit/upm/tree/master/examples).
 
+Multi-sensor samples for the starter and specialized kits can be found in the
+[iot-devkit-samples](https://github.com/intel-iot-devkit/iot-devkit-samples) repository.
+
 ### 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).
+You can also refer to the [Intel® IoT Developer Zone](https://software.intel.com/iot/hardware/sensors).
+
+### IDE Integration
+
+If you would like to create projects and run the UPM samples using an Intel recommended IDE,
+please refer to the Intel Developer Zone IDE page.
+
+<a href="https://software.intel.com/iot/software/ide"><img src="docs/icons/allides.png"/></a>
 
 ### Building UPM
 
-See @ref building [here](docs/building.md).
+See building documentation [here](docs/building.md).
+
+[![Build Status](https://travis-ci.org/intel-iot-devkit/upm.svg?branch=master)](https://travis-ci.org/intel-iot-devkit/upm)
 
 ### Making your own UPM module
 
-@ref porting [link](docs/porting.md) has more information on making new UPM modules.
+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).
+There is also an example available gfor max31855 [sensor](docs/max31855.md).
+
+Guide on creating Java [bindings](docs/creating_java_bindings.md).
 
 ### Naming conventions and rules for new UPM contributions
 
-Before you begin development, take a look at our @ref naming [conventions](docs/naming.md).
+Before you begin development, take a look at our naming [conventions](docs/naming.md).
 
-Also, please read the guidelines for @ref contributions [to UPM](docs/contributions.md).
+Also, please read the guidelines for contributions [to UPM](docs/contributions.md).
 
-Don't forget to check the @ref documentation [section](docs/documentation.md).
+Don't forget to check the 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
+API Documentation
 ==============
 
-The C/C++ documentation is available [here](http://iotdk.intel.com/docs/master/upm/).
+<a href="http://iotdk.intel.com/docs/master/upm"><img src="docs/icons/c++.png"/></a>
+<a href="http://iotdk.intel.com/docs/master/upm/java"><img src="docs/icons/java.png"/></a>
+<a href="http://iotdk.intel.com/docs/master/upm/python"><img src="docs/icons/python.png"/></a>
+<a href="http://iotdk.intel.com/docs/master/upm/node"><img src="docs/icons/node.png"/></a>
+
+### API Compatibility
+Even if we try our best not to, every once in a while we are forced to modify
+our API in a way that will break backwards compatibility. If you find yourself
+unable to compile code that was working fine before a library update, make sure
+you check the [API changes](docs/apichanges.md) section first.
+
+**NOTE** - Our **C++ header files** changed extension from *.h* to *.hpp*!
+
+### Changelog
+Version changelog [here](docs/changelog.md).
+
+### Known Limitations
+List of known limitations [here](docs/knownlimitations.md).

cmake/Toolchains/oe-sdk_cross.cmake

@@ -0,0 +1,25 @@
+# this toolchain file comes from gnuradio project
+
+set( CMAKE_SYSTEM_NAME Linux )
+#set( CMAKE_C_COMPILER  $ENV{CC} )
+#set( CMAKE_CXX_COMPILER  $ENV{CXX} )
+string(REGEX MATCH "sysroots/([a-zA-Z0-9]+)" CMAKE_SYSTEM_PROCESSOR $ENV{SDKTARGETSYSROOT})
+string(REGEX REPLACE "sysroots/" "" CMAKE_SYSTEM_PROCESSOR ${CMAKE_SYSTEM_PROCESSOR})
+set( CMAKE_CXX_FLAGS $ENV{CXXFLAGS}  CACHE STRING "" FORCE )
+set( CMAKE_C_FLAGS $ENV{CFLAGS} CACHE STRING "" FORCE ) #same flags for C sources
+set( CMAKE_LDFLAGS_FLAGS ${CMAKE_CXX_FLAGS} CACHE STRING "" FORCE ) #same flags for C sources
+set( CMAKE_LIBRARY_PATH ${OECORE_TARGET_SYSROOT}/usr/lib )
+set( CMAKE_FIND_ROOT_PATH $ENV{OECORE_TARGET_SYSROOT} $ENV{OECORE_NATIVE_SYSROOT} )
+set( CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER )
+set( CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY )
+set( CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY )
+set( CMAKE_INSTALL_PREFIX $ENV{OECORE_TARGET_SYSROOT}/usr CACHE STRING "" FORCE)
+set( ORC_INCLUDE_DIRS $ENV{OECORE_TARGET_SYSROOT}/usr/include/orc-0.4 )
+set( ORC_LIBRARY_DIRS $ENV{OECORE_TARGET_SYSROOT}/usr/lib )
+
+# for java
+set( JAVA_AWT_INCLUDE_PATH $ENV{JAVA_HOME}/include CACHE PATH "" FORCE)
+set( JAVA_AWT_LIBRARY $ENV{JAVA_HOME}/jre/lib/amd64/libjawt.so CACHE FILEPATH "" FORCE)
+set( JAVA_INCLUDE_PATH $ENV{JAVA_HOME}/include CACHE PATH "" FORCE)
+set( JAVA_INCLUDE_PATH2 $ENV{JAVA_HOME}/include/linux CACHE PATH "" FORCE)
+set( JAVA_JVM_LIBRARY $ENV{JAVA_HOME}/jre/lib/amd64/libjvm.so CACHE FILEPATH "" FORCE)

cmake/modules/CPackDeb.cmake

@@ -95,7 +95,7 @@ IF(NOT CPACK_DEBIAN_PACKAGE_ARCHITECTURE)
   # $ dpkg --print-architecture
   FIND_PROGRAM(DPKG_CMD dpkg)
   IF(NOT DPKG_CMD)
-    MESSAGE(STATUS "Can not find dpkg in your path, default to i386.")
+    MESSAGE(WARNING "Can not find dpkg in your path, default to i386.")
     SET(CPACK_DEBIAN_PACKAGE_ARCHITECTURE i386)
   ENDIF(NOT DPKG_CMD)
   EXECUTE_PROCESS(COMMAND "${DPKG_CMD}" --print-architecture

cmake/modules/FindNode.cmake

@@ -0,0 +1,97 @@
+ # Macro to add directory to NODEJS_INCLUDE_DIRS if it exists and is not /usr/include
+ macro(add_include_dir dir)
+    if (IS_DIRECTORY ${dir} AND NOT ${dir} STREQUAL "/usr/include")
+      set(NODEJS_INCLUDE_DIRS ${NODEJS_INCLUDE_DIRS} ${dir})
+    endif()
+endmacro()
+
+
+find_program (NODEJS_EXECUTABLE NAMES node nodejs
+    HINTS
+    $ENV{NODE_DIR}
+    PATH_SUFFIXES bin
+    DOC "Node.js interpreter"
+)
+
+include (FindPackageHandleStandardArgs)
+
+# If compat-libuv package exists, it must be at start of include path
+find_path (UV_ROOT_DIR "uv.h" PATHS /usr/include/compat-libuv010 NO_DEFAULT_PATH)
+if (UV_ROOT_DIR)
+  # set (NODEJS_INCLUDE_DIRS ${UV_ROOT_DIR})
+  add_include_dir(${UV_ROOT_DIR})
+endif()
+
+# Now look for node. Flag an error if not found
+find_path (NODE_ROOT_DIR "include/node/node.h" "include/src/node.h"
+  PATHS /usr/include/nodejs /usr/local/include/nodejs /usr/local/include)
+if (NODE_ROOT_DIR)
+  add_include_dir(${NODE_ROOT_DIR}/include/src)
+  add_include_dir(${NODE_ROOT_DIR}/include/node)
+  add_include_dir(${NODE_ROOT_DIR}/include/deps/v8/include)
+  add_include_dir(${NODE_ROOT_DIR}/include/deps/uv/include)
+else()
+  unset(NODEJS_INCLUDE_DIRS)
+  message(ERROR " - node.h not found")
+endif()
+
+# Check that v8.h is in NODEJS_INCLUDE_DIRS
+find_path (V8_ROOT_DIR "v8.h" PATHS ${NODEJS_INCLUDE_DIRS})
+if (NOT V8_ROOT_DIR)
+  unset(NODEJS_INCLUDE_DIRS)
+  message(ERROR " - v8.h not found")
+endif()
+
+# Check that uv.h is in NODEJS_INCLUDE_DIRS
+find_path (UV_ROOT_DIR "uv.h" PATHS ${NODEJS_INCLUDE_DIRS})
+if (NOT UV_ROOT_DIR)
+  unset(NODEJS_INCLUDE_DIRS)
+  message(ERROR " - uv.h not found")
+endif()
+
+find_package_handle_standard_args (Nodejs DEFAULT_MSG
+    NODEJS_EXECUTABLE
+    NODEJS_INCLUDE_DIRS
+)
+
+if (NODEJS_EXECUTABLE)
+    execute_process(COMMAND ${NODEJS_EXECUTABLE} --version
+                    OUTPUT_VARIABLE _VERSION
+                    RESULT_VARIABLE _NODE_VERSION_RESULT)
+    execute_process(COMMAND ${NODEJS_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}")
+        string (STRIP ${V8_DEFINE_STRING} V8_DEFINE_STRING)
+        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_MINOR "28")
+        set (V8_VERSION_PATCH "72")
+        set (V8_VERSION_STRING "3.28.72")
+        message ("defaulted to node 0.10.30")
+    endif ()
+    string (REGEX REPLACE "\n" "" NODE_VERSION_STRING ${NODE_VERSION_STRING})
+    string (REGEX REPLACE "\n" "" V8_VERSION_STRING ${V8_VERSION_STRING})
+    message (STATUS "Node version is ${NODE_VERSION_STRING}")
+    message (STATUS "Node using v8 ${V8_VERSION_STRING}")
+    mark_as_advanced (NODEJS_EXECUTABLE)
+endif ()
+
+mark_as_advanced (NODEJS_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 (STATUS "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,25 @@
+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
+                    OUTPUT_STRIP_TRAILING_WHITESPACE
+                    ERROR_STRIP_TRAILING_WHITESPACE)
+    if(YUIDOC_VERSION)
+      message (STATUS "Yuidoc version is ${YUIDOC_VERSION}")
+    endif()
+endif ()
+
+mark_as_advanced (YUIDOC_EXECUTABLE)

cmake/modules/OpenCVDetectPython.cmake

@@ -0,0 +1,160 @@
+# Find specified Python version
+# Arguments:
+#   preferred_version (value): Version to check for first
+#   min_version (value): Minimum supported version
+#   library_env (value): Name of Python library ENV variable to check
+#   include_dir_env (value): Name of Python include directory ENV variable to check
+#   found (variable): Set if interpreter found
+#   executable (variable): Output of executable found
+#   version_string (variable): Output of found version
+#   version_major (variable): Output of found major version
+#   version_minor (variable): Output of found minor version
+#   libs_found (variable): Set if libs found
+#   libs_version_string (variable): Output of found libs version
+#   libraries (variable): Output of found Python libraries
+#   library (variable): Output of found Python library
+#   debug_libraries (variable): Output of found Python debug libraries
+#   debug_library (variable): Output of found Python debug library
+#   include_path (variable): Output of found Python include path
+#   include_dir (variable): Output of found Python include dir
+#   include_dir2 (variable): Output of found Python include dir2
+#   packages_path (variable): Output of found Python packages path
+function(find_python preferred_version min_version library_env include_dir_env
+         found executable version_string version_major version_minor
+         libs_found libs_version_string libraries library debug_libraries
+         debug_library include_path include_dir include_dir2 packages_path)
+if(NOT ${found})
+  if(${executable})
+    set(PYTHON_EXECUTABLE "${${executable}}")
+  endif()
+
+  find_package(PythonInterp "${preferred_version}")
+  if(NOT PYTHONINTERP_FOUND)
+    find_package(PythonInterp "${min_version}")
+  endif()
+
+  if(PYTHONINTERP_FOUND)
+    # Copy outputs
+    set(_found ${PYTHONINTERP_FOUND})
+    set(_executable ${PYTHON_EXECUTABLE})
+    set(_version_string ${PYTHON_VERSION_STRING})
+    set(_version_major ${PYTHON_VERSION_MAJOR})
+    set(_version_minor ${PYTHON_VERSION_MINOR})
+    set(_version_patch ${PYTHON_VERSION_PATCH})
+
+    # Clear find_host_package side effects
+    unset(PYTHONINTERP_FOUND)
+    unset(PYTHON_EXECUTABLE CACHE)
+    unset(PYTHON_VERSION_STRING)
+    unset(PYTHON_VERSION_MAJOR)
+    unset(PYTHON_VERSION_MINOR)
+    unset(PYTHON_VERSION_PATCH)
+  endif()
+
+  if(_found)
+    set(_version_major_minor "${_version_major}.${_version_minor}")
+
+    if(NOT ANDROID AND NOT APPLE_FRAMEWORK)
+      # not using _version_string here, because it might not conform to the CMake version format
+      if(CMAKE_CROSSCOMPILING)
+        # builder version can differ from target, matching base version (e.g. 2.7)
+        find_package(PythonLibs "${_version_major_minor}")
+      else()
+        find_package(PythonLibs "${_version_major_minor}.${_version_patch}" EXACT)
+      endif()
+
+      if(PYTHONLIBS_FOUND)
+        # Copy outputs
+        set(_libs_found ${PYTHONLIBS_FOUND})
+        set(_libraries ${PYTHON_LIBRARIES})
+        set(_include_path ${PYTHON_INCLUDE_PATH})
+        set(_include_dirs ${PYTHON_INCLUDE_DIRS})
+        set(_debug_libraries ${PYTHON_DEBUG_LIBRARIES})
+        set(_libs_version_string ${PYTHONLIBS_VERSION_STRING})
+        set(_debug_library ${PYTHON_DEBUG_LIBRARY})
+        set(_library ${PYTHON_LIBRARY})
+        set(_library_debug ${PYTHON_LIBRARY_DEBUG})
+        set(_library_release ${PYTHON_LIBRARY_RELEASE})
+        set(_include_dir ${PYTHON_INCLUDE_DIR})
+        set(_include_dir2 ${PYTHON_INCLUDE_DIR2})
+
+        # Clear find_package side effects
+        unset(PYTHONLIBS_FOUND)
+        unset(PYTHON_LIBRARIES)
+        unset(PYTHON_INCLUDE_PATH)
+        unset(PYTHON_INCLUDE_DIRS)
+        unset(PYTHON_DEBUG_LIBRARIES)
+        unset(PYTHONLIBS_VERSION_STRING)
+        unset(PYTHON_DEBUG_LIBRARY CACHE)
+        unset(PYTHON_LIBRARY)
+        unset(PYTHON_LIBRARY_DEBUG)
+        unset(PYTHON_LIBRARY_RELEASE)
+        unset(PYTHON_LIBRARY CACHE)
+        unset(PYTHON_LIBRARY_DEBUG CACHE)
+        unset(PYTHON_LIBRARY_RELEASE CACHE)
+        unset(PYTHON_INCLUDE_DIR CACHE)
+        unset(PYTHON_INCLUDE_DIR2 CACHE)
+      endif()
+    endif()
+
+    execute_process(COMMAND ${_executable} -c "from distutils.sysconfig import *; print(get_python_lib())"
+                    RESULT_VARIABLE _cvpy_process
+                    OUTPUT_VARIABLE _std_packages_path
+                    OUTPUT_STRIP_TRAILING_WHITESPACE)
+    if("${_std_packages_path}" MATCHES "site-packages")
+      set(_packages_path "python${_version_major_minor}/site-packages")
+    else() #debian based assumed, install to the dist-packages.
+      set(_packages_path "python${_version_major_minor}/dist-packages")
+    endif()
+      if(EXISTS "${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX}/${${packages_path}}")
+        set(_packages_path "lib${LIB_SUFFIX}/${_packages_path}")
+      else()
+        set(_packages_path "lib/${_packages_path}")
+    endif()
+  endif()
+
+  # Export return values
+  set(${found} "${_found}" CACHE INTERNAL "")
+  set(${executable} "${_executable}" CACHE FILEPATH "Path to Python interpretor")
+  set(${version_string} "${_version_string}" CACHE INTERNAL "")
+  set(${version_major} "${_version_major}" CACHE INTERNAL "")
+  set(${version_minor} "${_version_minor}" CACHE INTERNAL "")
+  set(${libs_found} "${_libs_found}" CACHE INTERNAL "")
+  set(${libs_version_string} "${_libs_version_string}" CACHE INTERNAL "")
+  set(${libraries} "${_libraries}" CACHE INTERNAL "Python libraries")
+  set(${library} "${_library}" CACHE FILEPATH "Path to Python library")
+  set(${debug_libraries} "${_debug_libraries}" CACHE INTERNAL "")
+  set(${debug_library} "${_debug_library}" CACHE FILEPATH "Path to Python debug")
+  set(${include_path} "${_include_path}" CACHE INTERNAL "")
+  set(${include_dir} "${_include_dir}" CACHE PATH "Python include dir")
+  set(${include_dir2} "${_include_dir2}" CACHE PATH "Python include dir 2")
+  set(${packages_path} "${_packages_path}" CACHE PATH "Where to install the python packages.")
+endif()
+endfunction(find_python)
+
+set(MIN_VER_PYTHON2 2.7)
+set(MIN_VER_PYTHON3 3.2)
+
+find_python(2.7 "${MIN_VER_PYTHON2}" PYTHON2_LIBRARY PYTHON2_INCLUDE_DIR
+    PYTHON2INTERP_FOUND PYTHON2_EXECUTABLE PYTHON2_VERSION_STRING
+    PYTHON2_VERSION_MAJOR PYTHON2_VERSION_MINOR PYTHON2LIBS_FOUND
+    PYTHON2LIBS_VERSION_STRING PYTHON2_LIBRARIES PYTHON2_LIBRARY
+    PYTHON2_DEBUG_LIBRARIES PYTHON2_LIBRARY_DEBUG PYTHON2_INCLUDE_PATH
+    PYTHON2_INCLUDE_DIR PYTHON2_INCLUDE_DIR2 PYTHON2_PACKAGES_PATH)
+
+find_python(3 "${MIN_VER_PYTHON3}" PYTHON3_LIBRARY PYTHON3_INCLUDE_DIR
+    PYTHON3INTERP_FOUND PYTHON3_EXECUTABLE PYTHON3_VERSION_STRING
+    PYTHON3_VERSION_MAJOR PYTHON3_VERSION_MINOR PYTHON3LIBS_FOUND
+    PYTHON3LIBS_VERSION_STRING PYTHON3_LIBRARIES PYTHON3_LIBRARY
+    PYTHON3_DEBUG_LIBRARIES PYTHON3_LIBRARY_DEBUG PYTHON3_INCLUDE_PATH
+    PYTHON3_INCLUDE_DIR PYTHON3_INCLUDE_DIR2 PYTHON3_PACKAGES_PATH)
+
+if(PYTHON_DEFAULT_EXECUTABLE)
+    set(PYTHON_DEFAULT_AVAILABLE "TRUE")
+elseif(PYTHON2INTERP_FOUND) # Use Python 2 as default Python interpreter
+    set(PYTHON_DEFAULT_AVAILABLE "TRUE")
+    set(PYTHON_DEFAULT_EXECUTABLE "${PYTHON2_EXECUTABLE}")
+elseif(PYTHON3INTERP_FOUND) # Use Python 2 as fallback Python interpreter (if there is no Python 2)
+    set(PYTHON_DEFAULT_AVAILABLE "TRUE")
+    set(PYTHON_DEFAULT_EXECUTABLE "${PYTHON3_EXECUTABLE}")
+endif()

docs/apichanges.md

@@ -0,0 +1,37 @@
+API Changes                       {#apichanges}
+===============
+
+Here's a list of other API changes made to the library that break source/binary
+compatibility between releases:
+
+ * **grove<name>** Starting with UPM 1.0 the Grove libraries have been renamed
+ from *upm-grove<name>* to simply *upm-<name>*. Class names also match this new
+ format, with old classes marked as deprecated throughout the documentation.
+ List of affected libraries: grovecollision, groveehr, groveeldriver,
+ groveelectromagnet, groveemg, grovegprs, grovegsr, grovelinefinder, grovemd,
+ grovemoisture, groveo2, grovescam, grovespeaker, groveultrasonic, grovevdiv,
+ grovewater, grovewfs.
+ * **grove** As of UPM 1.0 the Grove classes for sensors in the starter kit are
+ being separated into individual libraries. The old classes will be deprecated
+ over time and eventually removed. Corresponding libraries have the grove
+ prefix removed. Affected classes are GroveButton, GroveLed, GroveLight,
+ GroveRelay, GroveRotary, GroveSlide and GroveTemp.
+ * The **ublox6** driver has been replaced with a generic implementation called
+ nmea_gps as of UPM 1.0. This driver should handle all generic serial GPS
+ devices that output NMEA data going forward.  This new driver has been tested
+ with ublox6, DFRobot VK2828U7 (ublox7) and ublox LEA-6H GPS devices.
+ * **grove** Binary compatibility was broken for the GroveTemp class as of UPM
+ v0.7.3. C++ code using this class has to be recompiled.
+ * There were frequent misspellings of the word *Celsius* in the UPM
+ code.  In some cases, these were in method names, which will cause
+ some API compatibility issues.  These have all been corrected for UPM
+ versions after v.0.7.2.
+ * Our **C++ header files** changed their extension from *.h* to *.hpp* in
+ version 0.7.0, Intel provided examples and code samples also reflect this
+ change but you will need to modify your `#include` directives in existing
+ code.
+ * **my9221**, **groveledbar** and **grovecircularled** are now all part of the
+ same library (my9221) and new functionality was added going to v.0.5.1.
+ * **stepmotor** driver API was changed significantly from v.0.4.1 to v.0.5.0.
+ * **eboled** library was greatly improved in version 0.4.0 and the `draw()`
+ function was removed in favor of a more complete GFX library implementation.

docs/building.md

@@ -3,15 +3,23 @@ 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.
+directory.
 
-This project depends on libmraa, so that needs to be installed first. Use the
-following environment variables to configure the paths:
+**Dependencies**
+ * basic: libmraa, cmake, swig, pkgconfig, pthreads, librt
+ * bindings: python-dev, nodejs-dev, openjdk
+ * documentation: doxygen, graphviz, sphinx, yuidoc
+ * sensor specific: bacnet-mstp, modbus, openzwave, jpeg
 
-    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
+This project depends on libmraa, so that needs to be installed first. Append
+the install location of mraa pkgconfig to the following environment variable:
+
+~~~~~~~~~~~~~
+PKG_CONFIG_PATH=$PKG_CONFIG_PATH:.../mraa/build/lib/pkgconfig
+~~~~~~~~~~~~~
+
+If you are building the Java or Node.js bindings make sure you set the
+`JAVA_HOME` and `NODE_PATH` environment variables respectively.
 
 UPM will attempt to build all directories inside src/ and they must contain
 individual CMakeLists.txt files.
@@ -21,8 +29,13 @@ 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. Note that
+doing an out-of-source build may cause issues when rebuilding later on.
+
 Our cmake configure has a number of options, *cmake-gui* or *ccmake* can show
 you all the options. The interesting ones are detailed below:
 
@@ -43,10 +56,18 @@ Cross-compiling on a different system:
 -DCMAKE_CXX_FLAGS:STRING=-m32 -march=i586
 -DCMAKE_C_FLAGS:STRING=-m32 -march=i586
 ~~~~~~~~~~~~~
+Enabling Java module building
+~~~~~~~~~~~~~
+-DBUILDSWIGJAVA=ON
+~~~~~~~~~~~~~
 Building with an older version of swig (swig 2.0+) requires the disabling of javascript:
 ~~~~~~~~~~~~~
 -DBUILDSWIGNODE=OFF
 ~~~~~~~~~~~~~
+Generating python3 modules instead of python2.7
+~~~~~~~~~~~~~
+-DBUILDPYTHON3=ON
+~~~~~~~~~~~~~
 Disabling python module building
 ~~~~~~~~~~~~~
 -DBUILDSWIGPYTHON=OFF
@@ -55,16 +76,24 @@ Setting the python library to use:
 ~~~~~~~~~~~~~
 -DPYTHON_LIBRARY:FILEPATH=/usr/lib/libpython2.7.so.1.0
 ~~~~~~~~~~~~~
-Building doxygen doc
+Building documentation
 ~~~~~~~~~~~~~
--BUILDDOC=ON
+-DBUILDDOC=ON
+~~~~~~~~~~~~~
+Build C++ example binaries
+~~~~~~~~~~~~~
+-DBUILDEXAMPLES=ON
+~~~~~~~~~~~~~
+Build Java examples
+~~~~~~~~~~~~~
+-DBUILDJAVAEXAMPLES=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.
+If you intend to turn on all the options and build everything at once
+(C++, Java, 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

docs/changelog.md

@@ -0,0 +1,270 @@
+Changelog                         {#changelog}
+===============
+
+Here's a list summarizing some of the key undergoing changes to our library
+from earlier versions:
+
+### v1.0.0
+
+ * Added approximately 50 C sources for UPM drivers that can be used on both
+ Unix and RTOS boards
+ * Provided generic alternatives to the Grove set of classes as they will be
+ deprecated over time and eventually removed
+ * UPM modules are now being packed and published on NPM as sources rather than
+ binaries to enhance compatibility with various boards and systems
+ * Build both python2 and python3 modules if the corresponding python libs are
+ available and removed cmake BUILDPYTHON3 switch
+ * Converted python examples to run on both python2 and python3
+ * Added 'upm' hierarchy to python module install path which changes the way
+ UPM modules are imported
+    Example:
+        old: import pyupm_dfrph
+        new: from upm import pyupm_dfrph
+             or
+             import upm.pyupm_dfrph
+ * Added ctests for consistancy checking UPM repo as well as sanity checking
+ for python2/3 modules and examples
+ * Various documentation and driver fixes throughout
+ * New sensors: nmea_gps, mma7361, bh1750, hka5, dfrorp, dfrec, sht1x
+
+### v0.8.0
+
+ * Extended l3gd20 driver to support I2C connections in addition to IIO
+ * Updated ads1x15, mcp9808 and ssd1306 I2C drivers to not throw a fatal
+ exception if they fail to set a different I2C speed
+ * Added extra functionality to apa102 driver, backlight control to jhd1313m1
+ LCDs and fixed htu21d
+ * Improved documentation with build dependencies, refreshed the list of known
+ limitations and simplified the component name for a few sensors
+
+### v0.7.3
+
+ * Fixed several existing drivers and updated Grove Temperature sensor to use
+ new formula for v1.1+ by default
+ * Separated codebase for upm_grove module that bundles some of the starter kit
+ sensors into individual source files
+ * Documentation and doxygen tag updates with correct spelling for Celsius in
+ several places, this also affects API compatibility
+ * Removed superfluous BUILDSWIG option, some build recipes might be impacted
+ * New sensor: ms5611
+
+### v0.7.2
+
+ * Mraa 1.1.1 required changes to UPM drivers and examples for IIO core
+ kernel support
+ * Rev'ed libmraa requirement to 1.1.1
+
+### v0.7.1
+
+ * Fix for building python2 vs python3 bindings
+ * Fixes for jhd1313m1 row/font size and reset
+ * Added bacnet utility class
+ * New sensors: bmx055, bmi055, bmc160, bma250e, bmg150, bmm150, t8100, tb7300
+
+### v0.7.0
+
+ * C++ header files have been renamed from *.h to *.hpp along with all Intel
+ provided examples and code samples to allow for native C drivers
+ * Updated driver compatibility to new MRAA 1.0 API
+ * First sensor implementations for our newly added Dallas One Wire support
+ * Several fixes based on issues reported on Github
+ * Changed SWIG linking strategy, more robust Travis CI build checks
+ * New sensors: ds2413, ds18b20, bmp280, bno055, l3gd20
+
+### v0.6.2
+
+ * Added a generic driver for taking snapshots from an USB camera device
+ * New API changes section in documentation to let users know when the UPM API
+ gets modified
+ * Fixed some spelling errors and improved JavaScript documentation builds with
+ newer versions of YUI and Node
+ * Enhanced Cmake scripts and the build process
+ * New sensors: vcap, e50hx
+
+### v0.6.1
+
+ * Fixed library build process for different configurations across multiple
+ environments reported by users.
+ * Fixed multiple GFX library header clash and improved SSD1351 compatibility
+ by changing SPI mode
+ * Added Node and Python array typemaps for nrf24l01
+ * Added 2 new JAVA examples
+
+### v0.6.0
+
+ * Introduced C++ Interfaces for several sensor categories that will help
+ consolidate the sensor APIs with uniform function names upon implementation
+ * Greatly improved Node.js detection and handling during build and install,
+ and should be now compatible with all major versions
+ * Added a driver for the Curie IMU (accelerometer + gyroscope) that works with
+ the new Firmata support implemented by MRAA
+ * Continued to provide several JAVA fixes and examples
+ * Many new industrial and maker sensors: cwlsxxa, teams, tex00, h803x, apa102,
+ smartdrive, bmi160, bme280, ds1808lc, hlg150, lp8860, max44009, si1132, t6713,
+ si7005, ssd1351
+
+### v0.5.1
+
+ * Updated the API and added new functionality for the MY9221 class and derived
+ sensors: grovecircularled and groveledbar, along with new code samples that
+ show these changes
+ * Provided a fix for one JAVA example that uses interrupts and updated library
+ install paths
+ * Several documentation improvements and pictures were added for new sensors
+ * A few other sensors received minor patches
+
+### v0.5.0
+
+ * First implementations for industrial grade Modbus sensors, along with first
+ sensor examples that use the new iio system driver in MRAA
+ * Significant improvements to the stepmotor driver that will now allow precise
+ control using any GPIO pin and extended the API with new functionality
+ * Further improved JAVA bindings and sensor ISRs have been modified to
+ implement Runnable objects
+ * Improved Python typemaps and error checking, documentation now includes
+ detailed function descriptions
+ * Simplified the build process by eliminating the need to define redundant
+ MRAA related environment variables
+ * New sensors: nlgpio16, ads1x15, t3311, hdxxvxta, hwxpxx, rhusb, ili9341,
+ apds9930, kxcjk1013
+
+### v0.4.1
+
+ * Over 150 supported sensor drivers including some industrial grade devices
+ * Improved the JAVA bindings, added a large number of examples for sensors,
+ enabled JAVA builds in Travis CI, and introduced automatic loading for the
+ JAVA shared libraries
+ * Continued to improve existing sensor drivers and to enhance them with the
+ new C++ coding style and exception types
+ * Several cmake improvements to allow building on various Linux distributions
+ and with a newer version of Node.JS
+ * Simplified adding and building of C++ sensor examples via cmake
+ * New sensors: micsv89, xbee, urm37, adxrs610, bma220, dfrph, mcp9808, sx1276,
+ groveultrasonic, ozw
+
+### v0.4.0
+
+ * Fully functional and documented JAVA language bindings for sensors with
+ several examples also available
+ * Added standardized exception handling support across all language bindings
+ and updated sensors to use this feature
+ * Sensor drivers are now available and can be installed individually using NPM
+ for Node.js users
+ * Continuous Integration with Travis CI ensures new contributions are built
+ automatically once they are received
+ * API rewrite and improvements for hcsr04, sm130, eboled, loudness
+ * Documentation improvements and code style changes from C to C++
+ * New sensors: hyld9767, mg811, wheelencoder, grovegprs, mpu9250, ssd1306,
+ es9257, lm35, mq4, mq6, mq7, mq8
+
+### v0.3.2
+
+ * Introduced RPM package generation feature from cmake via cpack
+ * Performed a thorough documentation review and merged resulting changes,
+ includes last remaining images and grouping sensors by kits
+ * Added support for Sparkfun Sensor Blocks (OLED & IMU)
+ * Fully reworked API for at42qt1070, mpu9150 and lcd classes, while
+ maintaining backwards compatibility for existing lcd displays
+ * Extended doxygen tags for better integration with automated documentation
+ generators
+ * New sensors: rgbringcoder, hp20x, pn532, sainsmartks, lsm9ds0, eboled
+
+### v0.3.1
+
+ * Updated index pages for API documentation and cross-linked them
+ * More images were added for Grove, Adafruit and Sparkfun sensors along with
+ licensing information
+ * Applied a set of patches to improve code robustness
+ * Added support for Grove NFC Tag sensor
+ * Fixed several typos in library and sensor names
+ * New sensor: m24lr64e
+
+### v0.3.0
+
+ * Provided automated, updated and comprehensive sensor API documentation for
+ C++, Python and JavaScript
+ * Edited sensor names, library descriptions and doxygen tags for consistency
+ * Fixed the TH02 sensor driver and made major improvements to i2clcd driver
+ * Added new and updated images for numerous new and existing sensors
+ * Started this changelog
+ * New sensors: sx6119, si114x, maxsonarez, hm11, ht9170, h3lis331dl, ad8232,
+ grovescam
+
+### 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
+ * New sensors: mma7660, cjq4435, adxl335, hmtrp, nunchuck, otp538u, l298,
+ groveelectromagnet, grovecollision, adis16448, at42qt1070, grovemd, ina132,
+ grovegsr, groveo2, groveemg, pca9685, pca9685ss, adafruitms1438, hx711, flex,
+ groveeldriver, mhz16, apds9002, waterlevel, zfm20, uln200xa, grovewfs, isd1820
+
+### 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
+ * New sensors: rpr220, rotaryencoder, biss0001, rfr359f, grovespeaker, mq303a,
+ ppd42ns, wt5001, yg1006, ublox6, mpr121, groveloudness, guvas12d, grovewater,
+ grovevdiv, grovelinefinder, ta12200, groveehr, grovemoisture, gp2y0a, a110x,
+ ds1307, adc121c021, enc03r, ttp223, itg3200, am2315, tp401, ldt0028, htu21d,
+ mpl3115a2, lsm303, joystick12, tsl2561, groverotary, groveslider, adxl345,
+ grovebutton, lol, groverelay
+
+### 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/creating_java_bindings.md

@@ -0,0 +1,353 @@
+Creating Java Bindings Guide
+==============
+* [Overview](#overview)
+* [Tools of trade](#tools-of-trade)
+* [Recommendations for the native API](#recommendations-for-the-native-api)
+  * [Pointers](#pointers)
+  * [Throwing Exceptions in Java](#throwing-exceptions-in-java)
+* [Caveats & Challenges](#caveats--challenges)
+  * [Wrapping C arrays with Java arrays](#wrapping-c-arrays-with-java-arrays)
+  * [Wrapping unbound C arrays with Java arrays if array is output](#wrapping-unbound-c-arrays-with-java-arrays-if-array-is-output)
+  * [Wrapping unbound C arrays with Java arrays if array is input](#wrapping-unbound-c-arrays-with-java-arrays-if-array-is-input)
+  * [Implementing callbacks in Java](#implementing-callbacks-in-java)
+
+
+##Overview
+
+The "Creating Java Bindings Guide" serves as a basic tutorial for using the SWIG software development tool to create 'glue code' required for Java to call into C/C++ code. It contains: guides for dealing with type conversions, exception handling, callbacks; recommendations on how to write/modify the native API to avoid issues on the Java side, and also workarounds for those issues that can't be avoided.
+
+This guide was created with the [upm](https://github.com/intel-iot-devkit/upm/) and [mraa](https://github.com/intel-iot-devkit/mraa) libraries in mind, and uses examples taken from these sources, but its usage can be extended to any project of creating Java bindings for C/C++ libraries.
+
+##Tools of trade
+
+[SWIG General Documentation](http://www.swig.org/Doc3.0/SWIGDocumentation.html)
+
+[SWIG Java-specific Documentation](http://www.swig.org/Doc3.0/Java.html)
+
+
+##Recommendations for the native API
+
+###Pointers
+As much as possible, avoid passing values/returning values through pointers given as as arguments to methods. As the Java language does not have pointers, SWIG provides a [workaround](http://www.swig.org/Doc3.0/Java.html#Java_tips_techniques) in the typemaps.i library.
+
+####Alternatives:
+1. Functions that read data from a driver, return it through a pointer given as argument, and return a bool value, should be __replaced by__ functions that return the value directly and throw a std::runtime_error if a read error occurs. E.g.:
+  ```c++
+  /*  
+   * Function reads from sensor, places read value in variable bar and  
+   * returns true if succesful. Function returns false if read failed.  
+   */  
+  bool func(int *bar); 
+  ```
+  __Replaced by:__
+  ```c++
+  /*  
+   * Function reads from sensor and returns read value.  
+   * Or throws std::runtime_error if a read error occurs  
+   */  
+  int func();  
+  ```
+
+2. Functions that return multiple values through pointers, that make sense to be grouped together into an array<sup>1</sup> (e.g. speed values, acceleration values), should be __replaced by__ functions that return a pointer to an array in which the elements are the returned values. Afterwards, [wrap the C array with a Java array](#wrapping-unbound-c-arrays-with-java-arrays-if-array-is-output). E.g.:
+  ```c++
+  /*  
+  * Function returns the acceleration on the three  
+  * axis in the given variables.  
+  */  
+  void getAccel(int *accelX, int *accelY, int *accelZ);  
+  ```
+
+  __Replaced by:__  
+  ```c++
+  /*  
+   * Function returns the acceleration on the three  
+   * axis as elements of a 3-element array.  
+   */  
+  int *getAccel();  
+  ```
+
+3. Functions that return N values through pointers, that do not make sense to grouped together (e.g. a general purpose function that returns both the light intensity and air pollution), should be __replaced by__ N functions (one for each value) that read only one specific value. E.g.:
+
+  ```c++
+  /*  
+   * Function returns the light intensity and air pollution  
+   */  
+  void getData(int *light, int *air);  
+  ```
+
+  __Replaced by:__  
+  ```c++
+  int getLight();  
+  int getAir();  
+  ```
+
+4. Functions that return N values through pointers; values that do not make sense to be grouped together, but are time dependent, and make sense to be read at the same time. For example, a sensor that reads air humidity and temperature. A user may want to know the temperature value _temp_ read at the exact moment the humidity value _humid_ was read. These should be __replaced by__ N+1 functions: a _getData()_ function that reads all values at the same time and stores them in global variables; and N getter functions, one for each value. E.g.
+
+  ```c++
+  /*  
+   * Function returns the light intensity and air pollution  
+   */  
+  void getData(int *temp, int *humid);  
+  ```
+
+  __Replaced by:__  
+  ```c++
+  void getData();  
+  int getTemp();  
+  int getHumid();   
+  ```
+
+  <sup>1</sup>this depends on the interpretation of the returned data. For example, arguments that return the temperature and light intensity, don't make sense to be grouped into an array of size 2. But acceleration on the three axis can be grouped together in an array of size 3. where accelX is accel[0], accelY is accel[1], accelZ is accel[2].
+
+__Notice:__
+Sometimes, you may be required to write JNI code. Be aware of the difference between the C JNI calling syntax and the C++ JNI calling syntax.The C++ calling syntax will not compile as C and also vice versa. It is however possible to write JNI calls which will compile under both C and C++ and is covered in the [Typemaps for both C and C++ compilation](http://www.swig.org/Doc3.0/Java.html#Java_typemaps_for_c_and_cpp) section of the SWIG Documentation.
+
+
+###Throwing Exceptions in Java
+####Language independent:
+The %exception directive allows you to define a general purpose exception handler. For example, you can specify the following:
+
+```c++
+%exception [method_name] {
+    try {
+        $action
+    }
+    catch (std::invalid_argument& e) {
+        ... handle error ...
+    }
+}
+```
+
+If [method_name] is not specified then the directive is applied to all methods in its scope.
+
+The usual thing you'd want to do is catch the C++ exception and throw an equivalent exception in your language.
+
+The exception.i library file provides support for creating language independent exceptions in your interfaces. To use it, simply put an "%include exception.i" in your interface file. This provides a function SWIG_exception() that can be used to raise common language exceptions in a portable manner. For example :
+
+
+```c++
+// Language independent exception handler  
+%include exception.i  
+
+%exception {  
+    try {  
+            $action  
+        } catch(OutOfMemory) {  
+            SWIG_exception(SWIG_MemoryError, "Out of memory");  
+    } catch(...) {  
+            SWIG_exception(SWIG_RuntimeError,"Unknown exception");  
+    }  
+}  
+```
+
+In the upm library, the upm_exception.i interface file provides the functionality to catch common exceptions and propagate them through SWIG. It uses the exception.i library file and is language independent.
+
+The upm_exception.i interface file is included in the upm.i file, therefor SWIG wraps all generated methods' body in a try-catch statement for the following exceptions:
+
+* std::invalid_argument
+* std::domain_error
+* std::overflow_error
+* std::out_of_range
+* std::length_error
+* std::logic_error
+* std::bad_alloc
+* std::runtime_error
+* std::exception
+
+
+####Java specific:
+To throw a specific Java exception:
+
+```c++
+%exception {  
+    try {  
+        $action  
+    } catch (std::out_of_range &e) {  
+        jclass clazz = jenv->FindClass("java/lang/Exception");  
+        jenv->ThrowNew(clazz, "Range error");  
+        return $null;  
+    }  
+}  
+```
+
+Where FindClass and ThrowNew are [JNI functions](http://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/functions.html).
+
+Java defines two tipes of exceptions: checked exception and unchecked exceptions (errors and runtime exceptions). Checked exceptions are subject to the [Catch or Specify Requirement](https://docs.oracle.com/javase/tutorial/essential/exceptions/catchOrDeclare.html).
+
+The C++ compiler does not force the code to catch any exception.
+
+The %exception directive does not specify if a method throws a checked exception (does not add classes to the throws clause). For this, the  %javaexception(classes) directive is used; where classes is a string containing one or more comma separated Java classes.
+
+```c++
+%javaexception("java.lang.Exception") {  
+    try {  
+        $action  
+    } catch (std::out_of_range &e) {  
+        jclass clazz = jenv->FindClass("java/lang/Exception");  
+        jenv->ThrowNew(clazz, "Range error");  
+        return $null;  
+    }  
+}  
+```
+
+In the upm library, the java_exceptions.i library file provides the functionality to catch exceptions and propagate them through SWIG as Java checked exceptions. The file provides SWIG wrappers, in the form of macros, that can be applied to methods.E.g. use the __READDATA_EXCEPTION(function)__ macro for functions that read data from a sensor and throw a std::runtime_error in case of a read failure. This will result in:
+
+```java
+void function throws IOException ();  
+```
+
+##Caveats & Challenges
+
+###Wrapping C arrays with Java arrays
+SWIG can wrap arrays in a more natural Java manner than the default by using the arrays_java.i library file. Just include this file into your SWIG interface file.
+
+###Wrapping unbound C arrays with Java arrays if array is output
+Functions that return arrays, return a pointer to that array. E.g.:
+
+```c++
+/*  
+ * Function returns the acceleration on the three  
+ * axis as elements of a 3-element array.  
+ */  
+
+int *getAccel();  
+```
+
+__SWIG:__  
+```c++
+%typemap(jni) int* "jintArray"  
+%typemap(jstype) int* "int[]"  
+%typemap(jtype) int* "int[]"  
+
+%typemap(javaout) int* {  
+    return $jnicall;  
+}  
+
+%typemap(out) int *getAccel {  
+    $result = JCALL1(NewIntArray, jenv, 3);  
+    JCALL4(SetIntArrayRegion, jenv, $result, 0, 3, (const signed int*)$1);  
+}  
+```
+
+###Wrapping unbound C arrays with Java arrays if array is input
+In C, arrays are tipically passed as pointers, with an integer value representig the length of the array. In Java, the length of an array is always known, so the length argument is redundant. This example shows how to wrap the C array and also get rid the length argument. E.g.:
+
+```c++
+void func(uint8_t *buffer, int length);  
+```
+
+__SWIG:__  
+```c++
+%typemap(jtype) (uint8_t *buffer, int length) "byte[]"  
+%typemap(jstype) (uint8_t *buffer, int length) "byte[]"  
+%typemap(jni) (uint8_t *buffer, int length) "jbyteArray"  
+%typemap(javain) (uint8_t *buffer, int length) "$javainput"  
+
+%typemap(in,numinputs=1) (uint8_t *buffer, int length) {  
+	$1 = JCALL2(GetByteArrayElements, jenv, $input, NULL);  
+	$2 = JCALL1(GetArrayLength, jenv, $input);  
+}  
+```
+
+!!!! There is a difference between TYPE *name and TYPE * name in typemaps!!!!!
+
+
+###Implementing callbacks in Java
+Callbacks in the UPM Java library (as well as the MRAA Java library) make use of the _void mraa\_java\_isr\_callback(void\* data\)_ method from MRAA.  
+
+__Callbacks in the UPM Java library are implemented as follows (we use the a110x Hall Effect sensors as example):__
+
+We extend the sensor class with another method, _installISR\(jobject runnable\)_, which is a wrapper over the original _installISR\(void \(\*isr\)\(void \*\), void \*arg\)_ method. This will install the _mraa\_java\_isr\_callback\(\)_ method as the interrupt service routine \(ISR\) to be called, with _jobject runnable_ as argument.
+
+SWIGJAVA is a symbol that is always defined by SWIG when using Java. We enclose the _installISR\(jobject runnable\)_ method in a _\#if defined(SWIGJAVA)_ check, to ensure the code only exists when creating a wrapper for Java.
+
+```c++
+#if defined(SWIGJAVA)
+void A110X::installISR(jobject runnable)
+{
+    installISR(mraa_java_isr_callback, runnable);
+}
+#endif
+```
+
+We hide the underlying method, _installISR\(void \(\*isr\)\(void \*\), void \*arg\)_ , and expose only the _installISR\(jobject runnable\)_ to SWIG, through the use of the SWIGJAVA symbol. When SWIGJAVA is defined, we change the access modifier of the underlying method to private.
+
+```c++
+public:
+#if defined(SWIGJAVA)
+    void installISR(jobject runnable);
+#else
+    void installISR(void (*isr)(void *), void *arg);
+#endif
+private:
+#if defined(SWIGJAVA)
+    void installISR(void (*isr)(void *), void *arg);
+#endif
+```
+
+To use callback in java, we create a ISR class, which implements the Java Runnable interface, and we override the _run\(\)_ method with the code to be executed when the interrupt is received. An example for the a110x Hall sensor that increments a counter each time an interrupt is received:
+
+```java
+public class A110X_intrSample {
+    public static int counter=0;
+        
+    public static void main(String[] args) throws InterruptedException {
+        upm_a110x.A110X hall = new upm_a110x.A110X(2);
+
+        A110XISR callback = new A110XISR();
+        hall.installISR(callback);
+        
+        while(true){
+            System.out.println("Counter: " + counter);
+            Thread.sleep(1000);
+        }
+    }
+}
+
+class A110XISR implements Runnable {
+    public A110XISR(){
+        super();
+    }
+    public void run(){
+        A110X_intrSample.counter++;
+    }
+}
+```
+####Issues with java callbacks and workarounds
+
+__SWIGJAVA not defined at compile time__
+
+Consider the following files:
+* example.h - Header file for our source file
+* example.cxx - Source file containing the class Example, for which we build java bindings
+* example.i - The SWIG interface, that includes the example.h header file
+
+The build process of a java module using SWIG is split into two steps:
+
+1. Generating the intermediate files, from the SWIG interface file. This will produce the java class file (Example.java), the JNI file (exampleJNI.java) and wrapper file (example_wrap.cxx). The source file (example.cxx) is not needed in the first step.
+
+  ```
+swig -c++ -java example.i
+  ```
+
+2. Generating the shared library from the C++ sources and wrapper file
+  ```
+g++ -fPIC -c example.cxx example_wrap.cxx -I/usr/lib/jvm/java-1.8.0/include -I/usr/lib/jvm/java-1.8.0/include/linux
+g++ -shared example_wrap.o sensor.o -o libexample.so
+  ```
+
+
+SWIGJAVA is always defined when SWIG parses the interface file, meaning it will be defined when it parses the header file (example.h) that is included in the interface file (example.i).
+SWIG also adds the "#define SWIGJAVA" directive in the wrapper file (example_wrap.cxx).
+However, in generating the shared library the SWIGJAVA symbol is only defined in the example_wrap.cxx file, because of the added "#define SWIGJAVA" directive. But we have also used the "#if defined(SWIGJAVA)" check in the source file (example.cxx), and thus need to define SWIGJAVA for it too. If we define the SWIGJAVA symbol as a compile flag, when compiling the source code to object code, the SWIGJAVA compile flag and #define SWIGJAVA" directive will clash and give a double definition warning (only a warning).
+
+In this example it is simple to compile the two source codes separately, one with the compile flag, the other without, and then create the shared library (libexample.so).
+But in a big automatic build like the java upm libraries, this may prove too hard or too complicated to do. A workaround to this would be to define a custom symbol (e.q. JAVACALLBACK in the upm library) and also test for it. In short, replace:
+```c++
+#if defined(SWIGJAVA)
+```
+by
+```c++
+#if defined(SWIGJAVA) || defined(JAVACALLBACK)
+```
+

docs/documentation.md

@@ -28,6 +28,7 @@ Here's an example (disregard the "@verbatim" tags in your actual code):
  * @sensor <chip-id>
  * @comname <component-name>
  * @altname <alt-name>
+ * @altid <alt-id>
  * @type <component-category>
  * @man <component-manufacturer>
  * @web <component-weblinks>
@@ -49,11 +50,13 @@ Here's an example (disregard the "@verbatim" tags in your actual code):
   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*
+  available or relevant, use a unique descriptor that makes sense. Must match
+  class name. *Mandatory*
+- `<component-name>` A short name for your sensor, try to avoid including the
+  manufacturer's name here. *Mandatory*
+- `<alt-name>` Alternative names that your sensor driver might have. This may
+  include manufacturer's name. *Optional*
+- `<alt-id>` Alternative chip-ids that your sensor driver supports. *Optional*
 - `<component-category>` Mention one or more categories the sensor fits in. Can
   be 'other'. *Mandatory*
 - `<component-manufacturer>` Sensor manufacturer. Can be 'generic'. *Mandatory*
@@ -63,7 +66,7 @@ Here's an example (disregard the "@verbatim" tags in your actual code):
 - `<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.
+kit tags are found in the *src/groups.md* file.
 
 Optionally, a small representative image can be placed in the "docs/images"
 subfolder and linked with the "@image" tag.

docs/images/LICENSE_CC_3_0.txt

@@ -0,0 +1,361 @@
+Creative Commons Legal Code
+
+Attribution-NonCommercial-ShareAlike 3.0 Unported
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR
+    DAMAGES RESULTING FROM ITS USE.
+
+License
+
+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
+COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
+COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
+AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
+
+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
+TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY
+BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS
+CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND
+CONDITIONS.
+
+1. Definitions
+
+ a. "Adaptation" means a work based upon the Work, or upon the Work and
+    other pre-existing works, such as a translation, adaptation,
+    derivative work, arrangement of music or other alterations of a
+    literary or artistic work, or phonogram or performance and includes
+    cinematographic adaptations or any other form in which the Work may be
+    recast, transformed, or adapted including in any form recognizably
+    derived from the original, except that a work that constitutes a
+    Collection will not be considered an Adaptation for the purpose of
+    this License. For the avoidance of doubt, where the Work is a musical
+    work, performance or phonogram, the synchronization of the Work in
+    timed-relation with a moving image ("synching") will be considered an
+    Adaptation for the purpose of this License.
+ b. "Collection" means a collection of literary or artistic works, such as
+    encyclopedias and anthologies, or performances, phonograms or
+    broadcasts, or other works or subject matter other than works listed
+    in Section 1(g) below, which, by reason of the selection and
+    arrangement of their contents, constitute intellectual creations, in
+    which the Work is included in its entirety in unmodified form along
+    with one or more other contributions, each constituting separate and
+    independent works in themselves, which together are assembled into a
+    collective whole. A work that constitutes a Collection will not be
+    considered an Adaptation (as defined above) for the purposes of this
+    License.
+ c. "Distribute" means to make available to the public the original and
+    copies of the Work or Adaptation, as appropriate, through sale or
+    other transfer of ownership.
+ d. "License Elements" means the following high-level license attributes
+    as selected by Licensor and indicated in the title of this License:
+    Attribution, Noncommercial, ShareAlike.
+ e. "Licensor" means the individual, individuals, entity or entities that
+    offer(s) the Work under the terms of this License.
+ f. "Original Author" means, in the case of a literary or artistic work,
+    the individual, individuals, entity or entities who created the Work
+    or if no individual or entity can be identified, the publisher; and in
+    addition (i) in the case of a performance the actors, singers,
+    musicians, dancers, and other persons who act, sing, deliver, declaim,
+    play in, interpret or otherwise perform literary or artistic works or
+    expressions of folklore; (ii) in the case of a phonogram the producer
+    being the person or legal entity who first fixes the sounds of a
+    performance or other sounds; and, (iii) in the case of broadcasts, the
+    organization that transmits the broadcast.
+ g. "Work" means the literary and/or artistic work offered under the terms
+    of this License including without limitation any production in the
+    literary, scientific and artistic domain, whatever may be the mode or
+    form of its expression including digital form, such as a book,
+    pamphlet and other writing; a lecture, address, sermon or other work
+    of the same nature; a dramatic or dramatico-musical work; a
+    choreographic work or entertainment in dumb show; a musical
+    composition with or without words; a cinematographic work to which are
+    assimilated works expressed by a process analogous to cinematography;
+    a work of drawing, painting, architecture, sculpture, engraving or
+    lithography; a photographic work to which are assimilated works
+    expressed by a process analogous to photography; a work of applied
+    art; an illustration, map, plan, sketch or three-dimensional work
+    relative to geography, topography, architecture or science; a
+    performance; a broadcast; a phonogram; a compilation of data to the
+    extent it is protected as a copyrightable work; or a work performed by
+    a variety or circus performer to the extent it is not otherwise
+    considered a literary or artistic work.
+ h. "You" means an individual or entity exercising rights under this
+    License who has not previously violated the terms of this License with
+    respect to the Work, or who has received express permission from the
+    Licensor to exercise rights under this License despite a previous
+    violation.
+ i. "Publicly Perform" means to perform public recitations of the Work and
+    to communicate to the public those public recitations, by any means or
+    process, including by wire or wireless means or public digital
+    performances; to make available to the public Works in such a way that
+    members of the public may access these Works from a place and at a
+    place individually chosen by them; to perform the Work to the public
+    by any means or process and the communication to the public of the
+    performances of the Work, including by public digital performance; to
+    broadcast and rebroadcast the Work by any means including signs,
+    sounds or images.
+ j. "Reproduce" means to make copies of the Work by any means including
+    without limitation by sound or visual recordings and the right of
+    fixation and reproducing fixations of the Work, including storage of a
+    protected performance or phonogram in digital form or other electronic
+    medium.
+
+2. Fair Dealing Rights. Nothing in this License is intended to reduce,
+limit, or restrict any uses free from copyright or rights arising from
+limitations or exceptions that are provided for in connection with the
+copyright protection under copyright law or other applicable laws.
+
+3. License Grant. Subject to the terms and conditions of this License,
+Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+perpetual (for the duration of the applicable copyright) license to
+exercise the rights in the Work as stated below:
+
+ a. to Reproduce the Work, to incorporate the Work into one or more
+    Collections, and to Reproduce the Work as incorporated in the
+    Collections;
+ b. to create and Reproduce Adaptations provided that any such Adaptation,
+    including any translation in any medium, takes reasonable steps to
+    clearly label, demarcate or otherwise identify that changes were made
+    to the original Work. For example, a translation could be marked "The
+    original work was translated from English to Spanish," or a
+    modification could indicate "The original work has been modified.";
+ c. to Distribute and Publicly Perform the Work including as incorporated
+    in Collections; and,
+ d. to Distribute and Publicly Perform Adaptations.
+
+The above rights may be exercised in all media and formats whether now
+known or hereafter devised. The above rights include the right to make
+such modifications as are technically necessary to exercise the rights in
+other media and formats. Subject to Section 8(f), all rights not expressly
+granted by Licensor are hereby reserved, including but not limited to the
+rights described in Section 4(e).
+
+4. Restrictions. The license granted in Section 3 above is expressly made
+subject to and limited by the following restrictions:
+
+ a. You may Distribute or Publicly Perform the Work only under the terms
+    of this License. You must include a copy of, or the Uniform Resource
+    Identifier (URI) for, this License with every copy of the Work You
+    Distribute or Publicly Perform. You may not offer or impose any terms
+    on the Work that restrict the terms of this License or the ability of
+    the recipient of the Work to exercise the rights granted to that
+    recipient under the terms of the License. You may not sublicense the
+    Work. You must keep intact all notices that refer to this License and
+    to the disclaimer of warranties with every copy of the Work You
+    Distribute or Publicly Perform. When You Distribute or Publicly
+    Perform the Work, You may not impose any effective technological
+    measures on the Work that restrict the ability of a recipient of the
+    Work from You to exercise the rights granted to that recipient under
+    the terms of the License. This Section 4(a) applies to the Work as
+    incorporated in a Collection, but this does not require the Collection
+    apart from the Work itself to be made subject to the terms of this
+    License. If You create a Collection, upon notice from any Licensor You
+    must, to the extent practicable, remove from the Collection any credit
+    as required by Section 4(d), as requested. If You create an
+    Adaptation, upon notice from any Licensor You must, to the extent
+    practicable, remove from the Adaptation any credit as required by
+    Section 4(d), as requested.
+ b. You may Distribute or Publicly Perform an Adaptation only under: (i)
+    the terms of this License; (ii) a later version of this License with
+    the same License Elements as this License; (iii) a Creative Commons
+    jurisdiction license (either this or a later license version) that
+    contains the same License Elements as this License (e.g.,
+    Attribution-NonCommercial-ShareAlike 3.0 US) ("Applicable License").
+    You must include a copy of, or the URI, for Applicable License with
+    every copy of each Adaptation You Distribute or Publicly Perform. You
+    may not offer or impose any terms on the Adaptation that restrict the
+    terms of the Applicable License or the ability of the recipient of the
+    Adaptation to exercise the rights granted to that recipient under the
+    terms of the Applicable License. You must keep intact all notices that
+    refer to the Applicable License and to the disclaimer of warranties
+    with every copy of the Work as included in the Adaptation You
+    Distribute or Publicly Perform. When You Distribute or Publicly
+    Perform the Adaptation, You may not impose any effective technological
+    measures on the Adaptation that restrict the ability of a recipient of
+    the Adaptation from You to exercise the rights granted to that
+    recipient under the terms of the Applicable License. This Section 4(b)
+    applies to the Adaptation as incorporated in a Collection, but this
+    does not require the Collection apart from the Adaptation itself to be
+    made subject to the terms of the Applicable License.
+ c. You may not exercise any of the rights granted to You in Section 3
+    above in any manner that is primarily intended for or directed toward
+    commercial advantage or private monetary compensation. The exchange of
+    the Work for other copyrighted works by means of digital file-sharing
+    or otherwise shall not be considered to be intended for or directed
+    toward commercial advantage or private monetary compensation, provided
+    there is no payment of any monetary compensation in con-nection with
+    the exchange of copyrighted works.
+ d. If You Distribute, or Publicly Perform the Work or any Adaptations or
+    Collections, You must, unless a request has been made pursuant to
+    Section 4(a), keep intact all copyright notices for the Work and
+    provide, reasonable to the medium or means You are utilizing: (i) the
+    name of the Original Author (or pseudonym, if applicable) if supplied,
+    and/or if the Original Author and/or Licensor designate another party
+    or parties (e.g., a sponsor institute, publishing entity, journal) for
+    attribution ("Attribution Parties") in Licensor's copyright notice,
+    terms of service or by other reasonable means, the name of such party
+    or parties; (ii) the title of the Work if supplied; (iii) to the
+    extent reasonably practicable, the URI, if any, that Licensor
+    specifies to be associated with the Work, unless such URI does not
+    refer to the copyright notice or licensing information for the Work;
+    and, (iv) consistent with Section 3(b), in the case of an Adaptation,
+    a credit identifying the use of the Work in the Adaptation (e.g.,
+    "French translation of the Work by Original Author," or "Screenplay
+    based on original Work by Original Author"). The credit required by
+    this Section 4(d) may be implemented in any reasonable manner;
+    provided, however, that in the case of a Adaptation or Collection, at
+    a minimum such credit will appear, if a credit for all contributing
+    authors of the Adaptation or Collection appears, then as part of these
+    credits and in a manner at least as prominent as the credits for the
+    other contributing authors. For the avoidance of doubt, You may only
+    use the credit required by this Section for the purpose of attribution
+    in the manner set out above and, by exercising Your rights under this
+    License, You may not implicitly or explicitly assert or imply any
+    connection with, sponsorship or endorsement by the Original Author,
+    Licensor and/or Attribution Parties, as appropriate, of You or Your
+    use of the Work, without the separate, express prior written
+    permission of the Original Author, Licensor and/or Attribution
+    Parties.
+ e. For the avoidance of doubt:
+
+     i. Non-waivable Compulsory License Schemes. In those jurisdictions in
+        which the right to collect royalties through any statutory or
+        compulsory licensing scheme cannot be waived, the Licensor
+        reserves the exclusive right to collect such royalties for any
+        exercise by You of the rights granted under this License;
+    ii. Waivable Compulsory License Schemes. In those jurisdictions in
+        which the right to collect royalties through any statutory or
+        compulsory licensing scheme can be waived, the Licensor reserves
+        the exclusive right to collect such royalties for any exercise by
+        You of the rights granted under this License if Your exercise of
+        such rights is for a purpose or use which is otherwise than
+        noncommercial as permitted under Section 4(c) and otherwise waives
+        the right to collect royalties through any statutory or compulsory
+        licensing scheme; and,
+   iii. Voluntary License Schemes. The Licensor reserves the right to
+        collect royalties, whether individually or, in the event that the
+        Licensor is a member of a collecting society that administers
+        voluntary licensing schemes, via that society, from any exercise
+        by You of the rights granted under this License that is for a
+        purpose or use which is otherwise than noncommercial as permitted
+        under Section 4(c).
+ f. Except as otherwise agreed in writing by the Licensor or as may be
+    otherwise permitted by applicable law, if You Reproduce, Distribute or
+    Publicly Perform the Work either by itself or as part of any
+    Adaptations or Collections, You must not distort, mutilate, modify or
+    take other derogatory action in relation to the Work which would be
+    prejudicial to the Original Author's honor or reputation. Licensor
+    agrees that in those jurisdictions (e.g. Japan), in which any exercise
+    of the right granted in Section 3(b) of this License (the right to
+    make Adaptations) would be deemed to be a distortion, mutilation,
+    modification or other derogatory action prejudicial to the Original
+    Author's honor and reputation, the Licensor will waive or not assert,
+    as appropriate, this Section, to the fullest extent permitted by the
+    applicable national law, to enable You to reasonably exercise Your
+    right under Section 3(b) of this License (right to make Adaptations)
+    but not otherwise.
+
+5. Representations, Warranties and Disclaimer
+
+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING AND TO THE
+FULLEST EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR OFFERS THE WORK AS-IS
+AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE
+WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT
+LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS,
+ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT
+DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED
+WARRANTIES, SO THIS EXCLUSION MAY NOT APPLY TO YOU.
+
+6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE
+LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR
+ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES
+ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Termination
+
+ a. This License and the rights granted hereunder will terminate
+    automatically upon any breach by You of the terms of this License.
+    Individuals or entities who have received Adaptations or Collections
+    from You under this License, however, will not have their licenses
+    terminated provided such individuals or entities remain in full
+    compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
+    survive any termination of this License.
+ b. Subject to the above terms and conditions, the license granted here is
+    perpetual (for the duration of the applicable copyright in the Work).
+    Notwithstanding the above, Licensor reserves the right to release the
+    Work under different license terms or to stop distributing the Work at
+    any time; provided, however that any such election will not serve to
+    withdraw this License (or any other license that has been, or is
+    required to be, granted under the terms of this License), and this
+    License will continue in full force and effect unless terminated as
+    stated above.
+
+8. Miscellaneous
+
+ a. Each time You Distribute or Publicly Perform the Work or a Collection,
+    the Licensor offers to the recipient a license to the Work on the same
+    terms and conditions as the license granted to You under this License.
+ b. Each time You Distribute or Publicly Perform an Adaptation, Licensor
+    offers to the recipient a license to the original Work on the same
+    terms and conditions as the license granted to You under this License.
+ c. If any provision of this License is invalid or unenforceable under
+    applicable law, it shall not affect the validity or enforceability of
+    the remainder of the terms of this License, and without further action
+    by the parties to this agreement, such provision shall be reformed to
+    the minimum extent necessary to make such provision valid and
+    enforceable.
+ d. No term or provision of this License shall be deemed waived and no
+    breach consented to unless such waiver or consent shall be in writing
+    and signed by the party to be charged with such waiver or consent.
+ e. This License constitutes the entire agreement between the parties with
+    respect to the Work licensed here. There are no understandings,
+    agreements or representations with respect to the Work not specified
+    here. Licensor shall not be bound by any additional provisions that
+    may appear in any communication from You. This License may not be
+    modified without the mutual written agreement of the Licensor and You.
+ f. The rights granted under, and the subject matter referenced, in this
+    License were drafted utilizing the terminology of the Berne Convention
+    for the Protection of Literary and Artistic Works (as amended on
+    September 28, 1979), the Rome Convention of 1961, the WIPO Copyright
+    Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996
+    and the Universal Copyright Convention (as revised on July 24, 1971).
+    These rights and subject matter take effect in the relevant
+    jurisdiction in which the License terms are sought to be enforced
+    according to the corresponding provisions of the implementation of
+    those treaty provisions in the applicable national law. If the
+    standard suite of rights granted under applicable copyright law
+    includes additional rights not granted under this License, such
+    additional rights are deemed to be included in the License; this
+    License is not intended to restrict the license of any rights under
+    applicable law.
+
+
+Creative Commons Notice
+
+    Creative Commons is not a party to this License, and makes no warranty
+    whatsoever in connection with the Work. Creative Commons will not be
+    liable to You or any party on any legal theory for any damages
+    whatsoever, including without limitation any general, special,
+    incidental or consequential damages arising in connection to this
+    license. Notwithstanding the foregoing two (2) sentences, if Creative
+    Commons has expressly identified itself as the Licensor hereunder, it
+    shall have all rights and obligations of Licensor.
+
+    Except for the limited purpose of indicating to the public that the
+    Work is licensed under the CCPL, Creative Commons does not authorize
+    the use by either party of the trademark "Creative Commons" or any
+    related trademark or logo of Creative Commons without the prior
+    written consent of Creative Commons. Any permitted use will be in
+    compliance with Creative Commons' then-current trademark usage
+    guidelines, as may be published on its website or otherwise made
+    available upon request from time to time. For the avoidance of doubt,
+    this trademark restriction does not form part of this License.
+
+    Creative Commons may be contacted at https://creativecommons.org/.
+