upm: v1.5.0

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

.dockerignore

@@ -0,0 +1,3 @@
+Dockerfile
+docker-compose.yaml
+build

.gitignore

@@ -1,4 +1,4 @@
-build/
+build*/
 
 # Object files
 *.o
@@ -11,3 +11,6 @@ build/
 # Temp files
 *.swp
 *~
+
+# Node modules
+**/node_modules

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "doxy/doxygen2jsdoc"]
+	path = doxy/doxygen2jsdoc
+	url = https://github.com/intel-iot-devkit/doxygen2jsdoc
+[submodule "doxy/doxyport"]
+	path = doxy/doxyport
+	url = https://github.com/intel-iot-devkit/doxyport

.travis.yml

@@ -1,34 +1,81 @@
+dist: trusty
+sudo: required
+
 language: cpp
-env:
-  - CC=gcc CXX=gcc
-  - CC=clang CXX=clang++
-  - NODE4=true
-  - NODE5=true
-  - NODE012=true
-install:
-  - if [ "${NODE4}" ]; then export CC=gcc-4.8 CXX=g++-4.8; fi
-  - sudo add-apt-repository --yes ppa:kalakris/cmake
-  - sudo add-apt-repository --yes ppa:fenics-packages/fenics-exp/swig
-  - sudo apt-get update -qq
-  - sudo apt-get install -y -qq swig3.0 python git cmake
-  - sudo ln -s /usr/bin/swig3.0 /usr/bin/swig
-  - sudo update-java-alternatives -s java-8-oracle
-before_script:
-  - export NODE_ROOT_DIR="/home/travis/.nvm/v0.10.36"
-  - if [ "$CC" = "gcc" ]; then export BUILDJAVA=ON; else export BUILDJAVA=OFF; fi
-  - export JAVA_HOME=/usr/lib/jvm/java-8-oracle
-  - if [ "${NODE4}" ]; then nvm install 4.1; export CC=gcc-4.8; export CXX=g++-4.8; export NODE_ROOT_DIR="/home/travis/.nvm/versions/node/`nvm version`"; fi
-  - if [ "${NODE5}" ]; then nvm install 5; export CC=gcc-4.8; export CXX=g++-4.8; export NODE_ROOT_DIR="/home/travis/.nvm/versions/node/`nvm version`"; fi
-  - if [ "${NODE012}" ]; then nvm install 0.12; export NODE_ROOT_DIR="/home/travis/.nvm/versions/node/`nvm version`"; fi
-script:
-  - git clone https://github.com/intel-iot-devkit/mraa.git
-  - cd mraa && mkdir build && cd build && cmake -DBUILDSWIGJAVA=$BUILDJAVA -DBUILDSWIGNODE=OFF -DBUILDSWIGPYTHON=OFF -DFIRMATA=ON -DENABLEEXAMPLES=OFF -DCMAKE_INSTALL_PREFIX:PATH=/usr .. && make && sudo make install
-  - cd ../.. && mkdir build && cd build && cmake -DNODE_ROOT_DIR:PATH="${NODE_ROOT_DIR}" -DBUILDSWIGJAVA=$BUILDJAVA -DBUILDEXAMPLES=ON -DBUILDJAVAEXAMPLES=$BUILDJAVA .. && make
-addons:
-  apt:
-    sources:
-      - llvm-toolchain-precise-3.6
-      - ubuntu-toolchain-r-test
-    packages:
-      - clang-3.6
-      - g++-4.8
+
+services:
+  - docker
+
+before_install:
+  - sudo rm /usr/local/bin/docker-compose
+  - curl -L https://github.com/docker/compose/releases/download/1.9.0/docker-compose-`uname -s`-`uname -m` > docker-compose
+  - chmod +x docker-compose
+  - sudo mv docker-compose /usr/local/bin
+
+jobs:
+  fast_finish: true
+  allow_failures:
+    - env: TARGET=ipk
+  include:
+    - &run-with-clang
+      stage: Clang 3.8
+      env: TARGET=python
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=clang-3.8 CXX=clang++-3.8
+        - docker-compose run ${TARGET}
+    - <<: *run-with-clang
+      env: TARGET=node4
+    - <<: *run-with-clang
+      env: TARGET=node5
+    - <<: *run-with-clang
+      env: TARGET=node6
+    - <<: *run-with-clang
+      env: TARGET=java
+    - &run-with-gcc-5
+      stage: Gcc 5
+      env: TARGET=python
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=gcc-5 CXX=g++-5
+        - docker-compose run ${TARGET}
+    - <<: *run-with-gcc-5
+      env: TARGET=node4
+    - <<: *run-with-gcc-5
+      env: TARGET=node5
+    - <<: *run-with-gcc-5
+      env: TARGET=node6
+    - <<: *run-with-gcc-5
+      env: TARGET=java
+    - &run-with-gcc-6
+      stage: Gcc 6
+      env: TARGET=python
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=gcc-6 CXX=g++-6
+        - docker-compose run ${TARGET}
+    - <<: *run-with-gcc-6
+      env: TARGET=node4
+    - <<: *run-with-gcc-6
+      env: TARGET=node5
+    - <<: *run-with-gcc-6
+      env: TARGET=node6
+    - <<: *run-with-gcc-6
+      env: TARGET=java
+    - &run-additional-jobs
+      stage: Additional Jobs
+      env: TARGET=doc
+      before_script: docker-compose pull ${TARGET}
+      script:
+        - export CC=clang-3.8 CXX=clang++-3.8
+        - docker-compose run ${TARGET}
+    - <<: *run-additional-jobs
+      env: TARGET=android
+    - <<: *run-additional-jobs
+      env: TARGET=sonar-scan
+    - <<: *run-additional-jobs
+      env: TARGET=ipk
+    - <<: *run-additional-jobs
+      env: TARGET=rpm
+    - <<: *run-additional-jobs
+      env: TARGET=npm

CMakeLists.txt

@@ -1,34 +1,227 @@
 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++/JAVA examples" 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." ON)
+
+# 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 ()
 
+# Appends the cmake/modules path to MAKE_MODULE_PATH variable.
+set (CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules ${CMAKE_MODULE_PATH})
+
+# 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)
+  set (_TMP_COMPILER_FLAGS "")
+  # 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 "${CMAKE_${compiler}_FLAGS} ${_TMP_COMPILER_FLAGS}" PARENT_SCOPE)
+endfunction ()
+
+# Compiler flags common to both C and CXX
+# Enable -Wall
+# GCC-6 added -Wmisleading-indentation to -Wall, skip these for now
+set (C_CXX_WARNING_FLAGS -Wall -Wno-misleading-indentation -Wno-strict-aliasing)
+
+# Warnings as errors?
+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)
+
+# Allow exception error handling for Android C++
+if (ANDROID)
+  upm_add_compile_flags(CXX -fexceptions)
+endif (ANDROID)
+
 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)
-pkg_check_modules (MRAA REQUIRED mraa>=0.9.1)
-message (INFO " found mraa version: ${MRAA_VERSION}")
+set(MRAA_MINIMUM 1.8.0)
+pkg_check_modules (MRAA REQUIRED mraa>=${MRAA_MINIMUM})
+# Also, get full path to the mraa library
+find_library(MRAA_LIBRARY NAMES mraa HINTS ${MRAA_LIBDIR})
 
-# 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 "${CMAKE_INSTALL_LIBDIR}" CACHE PATH "Installation path for libraries")
+# Test MRAA for various compile options
+include (CheckLibraryExists)
+check_library_exists (${MRAA_LIBRARIES} mraa_iio_init "${MRAA_LIBDIR}" MRAA_IIO_FOUND)
+check_library_exists (${MRAA_LIBRARIES} mraa_firmata_init "${MRAA_LIBDIR}" MRAA_FIRMATA_FOUND)
+check_library_exists (${MRAA_LIBRARIES} mraa_uart_ow_init "${MRAA_LIBDIR}" MRAA_OW_FOUND)
 
-# Set CMAKE_LIB_INSTALL_DIR if not defined
+# 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)
+  if (BUILDTESTS)
+    find_package (Npm REQUIRED)
+    if(NPM_EXECUTABLE)
+        message(STATUS "NPM Executable found at: ${NPM_EXECUTABLE}")
+    else()
+        message(FATAL_ERROR "Please install NPM first, you can't run tests without it")
+    endif()
+  endif (BUILDTESTS)
+endif (BUILDSWIGNODE)
+
+# Find JAVA/JNI
+if (BUILDSWIGJAVA)
+  find_package (Java REQUIRED)
+  find_package (JNI REQUIRED)
+  pkg_check_modules (MRAAJAVA REQUIRED mraajava>=${MRAA_MINIMUM})
+  # Also, get full path to the mraajava library
+  find_library(MRAAJAVA_LIBRARY NAMES mraajava HINTS ${MRAA_LIBDIR})
+endif (BUILDSWIGJAVA)
+
+# 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" OR "x_${VERSION}" STREQUAL "x_-128-NOTFOUND")
-  message (WARNING " - Install git to compile a production UPM!")
-  set (VERSION "v0.5.1-dirty")
+# If git_describe fails, use a dirty version
+if (${VERSION} MATCHES -NOTFOUND)
+  set (VERSION "v1.5.0")
+  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.
 string (REGEX REPLACE "^v([0-9]+)\\..*" "\\1" VERSION_MAJOR "${VERSION}")
@@ -46,41 +239,79 @@ 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 "")
-
-option (BUILDDOC "Build all doc." OFF)
-option (BUILDSWIG "Build swig modules." ON)
-option (BUILDSWIGPYTHON "Build swig python modules." ON)
-option (BUILDPYTHON3 "Use python3 for building/installing/testing" OFF)
-option (BUILDSWIGNODE "Build swig node modules." ON)
-option (BUILDEXAMPLES "Build C++ example binaries" OFF)
-option (BUILDJAVAEXAMPLES "Build java example jars" OFF)
-option (BUILDSWIGJAVA "Build swig java modules" OFF)
-option (IPK "Generate IPK using CPack" OFF)
-option (RPM "Generate RPM using CPack" OFF)
-option (BUILDTESTS "Generate check-ups for upm" OFF)
-
-# Find swig
-if (BUILDSWIG)
-    if (BUILDSWIGNODE)
-        find_package (SWIG 3.0.5 REQUIRED)
-    else ()
-        find_package (SWIG REQUIRED)
-    endif ()
-    if (SWIG_FOUND)
-        include (${SWIG_USE_FILE})
-    endif ()
-endif ()
-
 # Detect arch
 include (TargetArch)
 target_architecture (DETECTED_ARCH)
-message( INFO " - Target arch is ${DETECTED_ARCH}")
+message (STATUS "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()
+
+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)
-  if (DOXYGEN_FOUND)
+  find_package (Doxygen 1.8 REQUIRED)
+  if (DOXYGEN_FOUND AND DOXYGEN_VERSION VERSION_GREATER "1.8")
     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)
@@ -95,54 +326,55 @@ if (BUILDDOC)
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
       COMMENT "Generating API documentation with Doxygen" VERBATIM
     )
-  endif (DOXYGEN_FOUND)
+  else ()
+    message (SEND_ERROR "ERROR - Failed to find a compatible version of Doxygen. API doc will not be generated")
+  endif (DOXYGEN_FOUND AND DOXYGEN_VERSION VERSION_GREATER "1.8")
+
   # Check if Sphinx is installed and add target to generate API documentation
-  find_package (Sphinx)
-  if(SPHINX_FOUND AND BUILDSWIG AND BUILDSWIGPYTHON)
-    # Python required for Sphinx build
-    find_package (PythonLibs)
-    string (REPLACE "." ";" PYTHON_VERSION_LIST ${PYTHONLIBS_VERSION_STRING})
-    list (GET PYTHON_VERSION_LIST 0 PYTHON_VERSION_MAJOR)
-    list (GET PYTHON_VERSION_LIST 1 PYTHON_VERSION_MINOR)
-    set (SITE_PACKAGES ${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}/python${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR}/site-packages)
-    configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/pydoc/conf.py @ONLY)
-    configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/index.rst ${CMAKE_CURRENT_BINARY_DIR}/pydoc/index.rst COPYONLY)
-    add_custom_target (pydoc ALL
-      COMMAND rm -r -f ${CMAKE_BINARY_DIR}/pyupm && mkdir -p ${CMAKE_BINARY_DIR}/pyupm
-      COMMAND find ${CMAKE_BINARY_DIR}/src -name "_pyupm_*.so" -exec cp {} ${CMAKE_BINARY_DIR}/pyupm \;
-      COMMAND find ${CMAKE_BINARY_DIR}/src -name "pyupm_*.py" -exec cp {} ${CMAKE_BINARY_DIR}/pyupm \;
-      COMMAND ${SPHINX_API_EXECUTABLE} -f -o pydoc  ${CMAKE_BINARY_DIR}/pyupm
-      # TODO: use a separate cmake FILE module for string replacement instead
-      COMMAND ${SPHINX_EXECUTABLE} -b html pydoc html/python
-      COMMAND sed -i.bak s|\">pyupm_|\">|g html/python/index.html html/python/modules.html
-      COMMAND sed -i.bak s|[[:space:]][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 ()
+  # Currently, the per-module documentation for python is generated from the
+  # python2 modules.
+  if(BUILDSWIGPYTHON)
+    find_package (Sphinx 1.3 REQUIRED)
+    if (SPHINX_FOUND AND SPHINX_VERSION VERSION_GREATER "1.3")
+      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
+      )
+    else ()
+      message (SEND_ERROR "ERROR - Failed to find a compatible version of Sphinx. Python API doc will not be generated")
+    endif ()
+  endif(BUILDSWIGPYTHON)
+
   # Check if Yuidoc is installed and add target for API documentation
-  find_package(Yuidoc)
-  if(YUIDOC_FOUND AND BUILDSWIGNODE)
-    # Node required for Yuidoc documentation
-    find_package(Node)
-    file(GLOB_RECURSE JSDOC_FILES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}/doxy/node doxy/node/*)
-    foreach(JSDOC_FILE ${JSDOC_FILES})
-      configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxy/node/${JSDOC_FILE} ${CMAKE_CURRENT_BINARY_DIR}/${JSDOC_FILE} COPYONLY)
-    endforeach()
-    add_custom_target(jsdoc ALL
-      COMMAND ${NODE_EXECUTABLE} docgen -m upm -i xml -t ${CMAKE_CURRENT_SOURCE_DIR}/src -g ../../
-      COMMAND ${YUIDOC_EXECUTABLE} -C --no-sort --helpers generators/yuidoc/helper.js --themedir generators/yuidoc/tmpl -o html/node jsdoc/yuidoc/upm
-      COMMAND ${NODE_EXECUTABLE} tolower -i html/node
-      DEPENDS doc
-      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-      COMMENT "Generating API documentation with Yuidoc" VERBATIM
-    )
-  endif()
-endif()
+  if(BUILDSWIGNODE)
+    find_package (Yuidoc 0.10 REQUIRED)
+    if (YUIDOC_FOUND AND YUIDOC_VERSION VERSION_GREATER "0.10")
+      add_custom_target (jsdoc ALL
+        COMMAND ${CMAKE_SOURCE_DIR}/doxy/doxygen2jsdoc/docgen.js -m upm -i xml -o jsdoc -t ${CMAKE_CURRENT_SOURCE_DIR}/src -g ../../
+        COMMAND ${YUIDOC_EXECUTABLE} -C --no-sort --helpers ${CMAKE_SOURCE_DIR}/doxy/node/generators/yuidoc/helper.js --themedir ${CMAKE_SOURCE_DIR}/doxy/node/generators/yuidoc/tmpl -o html/node jsdoc/yuidoc/upm
+        COMMAND ${CMAKE_SOURCE_DIR}/doxy/doxygen2jsdoc/tolower.js -i html/node
+        DEPENDS doc
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating API documentation with Yuidoc" VERBATIM
+      )
+    else ()
+      message (SEND_ERROR "ERROR - Failed to find a compatible version of Yuidoc. Node.js API doc will not be generated")
+    endif ()
+  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)
@@ -155,7 +387,7 @@ if (IPK)
       set (TARGET_ARCH ${DETECTED_ARCH})
     endif ()
   endif ()
-  message (INFO " - Package arch is ${TARGET_ARCH}")
+  message (STATUS "Package arch is ${TARGET_ARCH}")
 
   set(CPACK_GENERATOR "DEB")
   set(OPKG_ARCH ${TARGET_ARCH})
@@ -180,49 +412,48 @@ if (IPK)
 endif()
 
 if (RPM)
-  message (INFO " - RPM packaging enabled for ${DETECTED_ARCH}")
-  set(CPACK_PACKAGE_VERSION ${VERSION})
+  message (STATUS "RPM packaging enabled for ${DETECTED_ARCH}")
   set(CPACK_GENERATOR "RPM")
-  set(CPACK_PACKAGE_NAME "libupm${upm_VERSION_MAJOR}")
-  set(CPACK_PACKAGE_RELEASE 1)
+  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}")
+      "${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}-${CPACK_PACKAGE_RELEASE}.${DIST_TAG}.${DETECTED_ARCH}")
+  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)
+
+# Generate a build-only C++ header to add functionality to SWIG'ed modules
+configure_file (${PROJECT_SOURCE_DIR}/cmake/modules/version.hpp.in ${PROJECT_BINARY_DIR}/src/version.hpp @ONLY)
+
+# UPM source
 add_subdirectory (src)
 
-if(BUILDEXAMPLES)
-  add_subdirectory (examples/c++)
-endif()
-
-if(BUILDJAVAEXAMPLES)
-  add_subdirectory (examples/java)
-endif()
-
-if (BUILDSWIGPYTHON OR BUILDTESTS)
-  if (BUILDPYTHON3)
-    set (PYTHONBUILD_VERSION 3)
-  else ()
-    set (PYTHONBUILD_VERSION 2.7)
-  endif ()
-  find_package (PythonInterp ${PYTHONBUILD_VERSION} REQUIRED)
-  find_package (PythonLibs ${PYTHONBUILD_VERSION} REQUIRED)
-  include_directories(${PYTHON_INCLUDE_PATH})
-endif ()
+# UPM examples
+add_subdirectory (examples)
 
+# 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,5 @@
-Copyright © 2014-2015 Intel Corporation
+The MIT License (MIT)
+Copyright © 2014-2016 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,60 +1,66 @@
+<p align="center">
+  <img src="https://github.com/intel-iot-devkit/upm/blob/master/docs/icons/upm_logo.png" height="150px" width="auto" algt="UPM Logo"/>
+</p>
+
 UPM (Useful Packages & Modules) Sensor/Actuator repository for MRAA
 ==============
 
-UPM is a high level repository for sensors that use MRAA. Each sensor links
-to MRAA 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.
+We endorse additions that implement the generic C and C++ interfaces provided
+with the libraries. Multiple sensor and actuator types have been defined, for
+instance:
+
+* Light controller 
+* Light sensor
+* Temperature sensor
+* Humidity sensor
+* Pressure sensor
+* Gas sensor
+* Analog to digital converter
+
+The developer community is welcome to submit feedback on existing categories or
+suggest new ones.
 
 ### Example
 
 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,
+  upm::MMA7660 *accel = new upm::MMA7660(MMA7660_DEFAULT_I2C_BUS,
                                          MMA7660_DEFAULT_I2C_ADDR);
 
   // place device in standby mode so we can write registers
   accel->setModeStandby();
 
   // enable 64 samples per second
-  accel->setSampleRate(upm::MMA7660::AUTOSLEEP_64);
-  
+  accel->setSampleRate(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 
+      cout << "Acceleration: x = " << ax
            << "g y = " << ay
            << "g z = " << az
            << "g" << endl;
-      
+
       usleep(500000);
     }
 ```
 
-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.
-
 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
@@ -64,39 +70,59 @@ Multi-sensor samples for the starter and specialized kits can be found in the
 
 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
+### IDE Support
 
-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.
+The UPM sensor libraries are directly supported by the IDEs listed on the Intel®
+Developer Zone Tools & IDEs page.
 
-<a href="https://software.intel.com/iot/software/ide"><img src="docs/icons/allides.png"/></a>
+<a href="https://software.intel.com/iot/tools"><img src="docs/icons/iss.png"/></a>
+
+Intel® System Studio integration offers IoT specific features such as a sensor explorer,
+library sync tools and the ability to easily import existing projects and samples that
+use the UPM libraries. For further details please refer to the IoT User Guides on IDZ.
+
+### Installing UPM
+
+Find notes on how to install UPM on various OS'es on this [page](docs/installing.md).
 
 ### Building UPM
 
 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
 
-Porting [link](docs/porting.md) has more information on making new UPM modules.
+A quick way to add a new sensor driver is to port existing code from another
+platform (e.g. Arduino) and swap the IO calls to the MRAA API. This of course
+assumes either ownership of the original code or licensing that allows
+unrestricted redistribution.
 
-There is also an example available for max31855 [sensor](docs/max31855.md).
+The [porting](docs/porting.md) section has more information on this process,
+and there is an example available based on the max31855 [sensor](docs/max31855.md).
 
-Guide on creating Java [bindings](docs/creating_java_bindings.md).
+Read more on creating Java [bindings](docs/creating_java_bindings.md) for your
+new driver.
 
-### Naming conventions and rules for new UPM contributions
+### Guidelines and rules for new UPM contributions
 
 Before you begin development, take a look at our naming [conventions](docs/naming.md).
+The name you pick for a newly added sensor needs to be unique in the UPM library.
 
-Also, please read the guidelines for contributions [to UPM](docs/contributions.md).
-
-Don't forget to check the documentation [section](docs/documentation.md).
-
+Then, please go over this short set of rules for new [contributions](docs/contributions.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.
 
+Documenting your code is also a big part of the task. We have a strict set of
+tags used to classify our sensors and their capabilities. You can find out more
+about this in our [section](docs/documentation.md) on documenting a sensor API.
+Finally, if you really want to ensure consistency with the rest of the library,
+and the intel-iot-devkit repositories in general, take a look at our extensive
+[author guide](docs/guidelines.md).
+
 API Documentation
 ==============
 
@@ -105,6 +131,15 @@ API Documentation
 <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** - Several important API changes are currently underway for some of our
+widely used libraries including `libupm-grove` and `libupm-i2clcd`!
+
 ### Changelog
 Version changelog [here](docs/changelog.md).
 

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

@@ -23,13 +23,16 @@ if (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"
+find_path (NODE_ROOT_DIR "include/node/node.h" "include/src/node.h" "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}/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}/deps/v8/include)
   add_include_dir(${NODE_ROOT_DIR}/include/deps/uv/include)
+  add_include_dir(${NODE_ROOT_DIR}/deps/uv/include)
 else()
   unset(NODEJS_INCLUDE_DIRS)
   message(ERROR " - node.h not found")
@@ -89,9 +92,9 @@ if (NODEJS_EXECUTABLE)
     endif ()
     string (REGEX REPLACE "\n" "" NODE_VERSION_STRING ${NODE_VERSION_STRING})
     string (REGEX REPLACE "\n" "" V8_VERSION_STRING ${V8_VERSION_STRING})
-    message ("INFO - Node version is " ${NODE_VERSION_STRING})
-    message ("INFO - Node using v8 " ${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 (NODE_EXECUTABLE)
+mark_as_advanced (NODEJS_EXECUTABLE)

cmake/modules/FindNpm.cmake

@@ -0,0 +1,13 @@
+# Finding and pointing a variable to the npm executable if found
+# Only works on Linux systems as of now
+
+find_program(NPM_EXECUTABLE NAMES npm
+    HINTS
+    /usr
+)
+
+if(NPM_EXECUTABLE)
+    message(STATUS "NPM Executable found at ${NPM_EXECUTABLE}")
+else()
+    message(ERROR "Unable to find NPM installation, please install NPM")
+endif()

cmake/modules/FindSphinx.cmake

@@ -17,14 +17,16 @@ find_package_handle_standard_args (Sphinx DEFAULT_MSG
     SPHINX_API_EXECUTABLE
 )
 
-# Get Sphinx version
+# Get Sphinx Version
 if (SPHINX_EXECUTABLE)
     execute_process(COMMAND ${SPHINX_EXECUTABLE} --version
-                    OUTPUT_VARIABLE SPHINX_VERSION)
-    if(SPHINX_VERSION)
-      string(REGEX MATCH "([0-9]\\.[0-9]\\.[0-9])" SPHINX_VERSION_STR ${SPHINX_VERSION})
-      message ("INFO - Sphinx version is " ${SPHINX_VERSION_STR})
-    endif()
+                    OUTPUT_VARIABLE SPHINX_VERSION_STRING
+                    OUTPUT_STRIP_TRAILING_WHITESPACE
+                    ERROR_STRIP_TRAILING_WHITESPACE)
+    if (SPHINX_VERSION_STRING)
+        string(REPLACE "Sphinx (sphinx-build) " "" SPHINX_VERSION ${SPHINX_VERSION_STRING})
+        message (STATUS "Sphinx version is ${SPHINX_VERSION}")
+    endif ()
 endif ()
 
 mark_as_advanced (SPHINX_EXECUTABLE)

cmake/modules/FindYuidoc.cmake

@@ -14,9 +14,11 @@ find_package_handle_standard_args (Yuidoc DEFAULT_MSG
 # Get Yuidoc version
 if (YUIDOC_EXECUTABLE)
     execute_process(COMMAND ${YUIDOC_EXECUTABLE} --version
-                    ERROR_VARIABLE YUIDOC_VERSION)
+                    ERROR_VARIABLE YUIDOC_VERSION
+                    OUTPUT_STRIP_TRAILING_WHITESPACE
+                    ERROR_STRIP_TRAILING_WHITESPACE)
     if(YUIDOC_VERSION)
-      message ("INFO - Yuidoc version is " ${YUIDOC_VERSION})
+      message (STATUS "Yuidoc version is ${YUIDOC_VERSION}")
     endif()
 endif ()
 

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()

cmake/modules/version.c.in

@@ -1,4 +0,0 @@
-#include "version.h"
-
-const char* gVERSION = "@VERSION@";
-const char* gVERSION_SHORT = "@VERSION_SHORT@";

cmake/modules/version.hpp.in

@@ -0,0 +1,6 @@
+#include <string>
+
+inline std::string getVersion()
+{
+    return "@upm_VERSION_STRING@";
+}

docker-compose.yaml

@@ -0,0 +1,112 @@
+version: '2.1'
+
+services:
+
+  base:
+    image: dnoliver/upm-base
+    environment:
+      - http_proxy
+      - https_proxy
+      - no_proxy
+      - BUILDDOC=${BUILDDOC:-OFF}
+      - BUILDCPP=${BUILDCPP:-ON}
+      - BUILDFTI=${BUILDFTI:-ON}
+      - BUILDSWIGPYTHON=${BUILDSWIGPYTHON:-OFF}
+      - BUILDSWIGJAVA=${BUILDSWIGJAVA:-OFF}
+      - BUILDSWIGNODE=${BUILDSWIGNODE:-OFF}
+      - BUILDEXAMPLES=${BUILDEXAMPLES:-ON}
+      - IPK=${IPK:-OFF}
+      - RPM=${RPM:-OFF}
+      - NPM=${NPM:-OFF}
+      - BUILDTESTS=${BUILDTESTS:-ON}
+      - CC=${CC:-clang-3.8}
+      - CXX=${CXX:-clang++-3.8}
+      - NODE_VERSION=${NODE_VERSION:-v4.4.7}
+      - WERROR=${WERROR:-ON}
+    volumes:
+      - .:${UPM_SRC_DIR:-/usr/src/app}
+
+  doc:
+    extends: base
+    image: dnoliver/upm-all
+    environment:
+      - BUILDSWIGPYTHON=ON
+      - BUILDSWIGJAVA=ON
+      - BUILDSWIGNODE=ON
+      - BUILDDOC=ON
+    command: bash -c "./scripts/run-cmake.sh && ./scripts/build-doc.sh"
+
+  ipk:
+    extends: base
+    environment:
+      - IPK=ON
+      - BUILDDOC=OFF
+    command: bash -c "./scripts/run-cmake.sh && make -Cbuild -j8 package"
+
+  rpm:
+    extends: doc
+    environment:
+      - RPM=ON
+      - BUILDDOC=OFF
+    command: bash -c "./scripts/run-cmake.sh && make -Cbuild -j8 package"
+
+  npm:
+    extends: doc
+    environment:
+      - NPM=ON
+      - BUILDDOC=OFF
+    command: bash -c "./scripts/run-cmake.sh && make -Cbuild -j8 npmpkg"
+
+  sonar-scan:
+    extends: base
+    image: dnoliver/upm-all
+    environment:
+      - BUILDSWIGPYTHON=ON
+      - BUILDSWIGNODE=ON
+      - BUILDSWIGJAVA=ON
+      - BUILDSWIGEXAMPLES=ON
+      - SONAR_TOKEN
+      - SONAR_ORG
+      - SONAR_PROJ_KEY
+      - TRAVIS_BRANCH
+      - TRAVIS_PULL_REQUEST
+      - TRAVIS_REPO_SLUG
+      - TRAVIS_PULL_REQUEST_SLUG
+      - GITHUB_TOKEN
+    command: bash -c "./scripts/run-cmake.sh && cd build && ../scripts/sonar-scan.sh"
+
+  python:
+    extends: base
+    image: dnoliver/upm-python
+    environment:
+      - BUILDSWIGPYTHON=ON
+    command: bash -c "./scripts/run-cmake.sh && cd build && make -j8 && make -j8 install && ldconfig && ctest --output-on-failure"
+
+  java:
+    extends: base
+    image: dnoliver/upm-java
+    environment:
+      - BUILDSWIGJAVA=ON
+    command: bash -c "./scripts/run-cmake.sh && cd build && make -j8 && make -j8 install && ldconfig && ctest --output-on-failure"
+
+  android:
+    extends: java
+    image: dnoliver/upm-android
+    environment:
+      - BUILDTESTS=OFF
+    command: bash -c "./scripts/build-android.sh"
+
+  node4:
+    extends: base
+    image: dnoliver/upm-node4
+    environment:
+      - BUILDSWIGNODE=ON
+    command: bash -c "./scripts/run-cmake.sh && cd build && make -j8 && make -j8 install && ldconfig && ctest --output-on-failure -E examplenames_js"
+
+  node5:
+    extends: node4
+    image: dnoliver/upm-node5
+
+  node6:
+    extends: node4
+    image: dnoliver/upm-node6

docs/apichanges.md

@@ -0,0 +1,248 @@
+API Changes                       {#apichanges}
+===============
+
+Here's a list of other API changes made to the library that break source/binary
+compatibility between releases:
+
+# v1.5.0
+
+ * **VEML6070** This sensor class no longer needs an I2C address when
+ initialized, since they are fixed. Only the I2C bus number needs to
+ be provided.
+
+# v1.3.0
+
+ * **The lsm303 driver has been renamed** There are a variety of
+ LSM303 devices out there with various incompatibilities and differing
+ capabilities.  The current lsm303 driver in UPM only supports the
+ LSM303DLH variant, so it has been renamed to lsm303dlh to avoid
+ confusion and to make it clear which variant is actually supported.
+
+    All examples and source files have been renamed, including header
+    files.  In addition, the class name, LSM303, has been renamed to
+    LSM303DLH.  No other functionality or behavior has been changed.
+
+# v1.2.0
+
+ * **Note for all drivers ported to C** As a general note concerning
+ all of the drivers that have been ported to C: **external constants
+ have likely been renamed**.  Previously in C++, most of these constants
+ were defined as enums in the *upm::classname* namespace.
+
+    For drivers written in C, all of these constants are no longer in
+    a class (or UPM) namespace, and instead have the driver name
+    prefixed to the original value.
+
+    The driver name is prefixed to these constants to avoid name
+    collisions when using multiple drivers in a given application, and
+    to make it clear which constants belong to which driver.
+
+    For drivers that used *#define* for constants, only the prefix has
+    been added if not already present.  In some cases, names that were
+    not very descriptive were changed, for example *ADDR* renamed to
+    *BMPX8X_DEFAULT_I2C_ADDR*.
+
+    So for example, a constant that might once have been referred to
+    in a C++ example as *upm::MMA7660::AUTOSLEEP_64*, would now be
+    referenced as *MMA7660_AUTOSLEEP_64*.
+
+    This holds true for most, if not all drivers that have been ported
+    to C.  Not all of these changes are listed in this file due to the
+    sheer number of them.
+
+    If you run into problems with constants that were working
+    previously, and now cannot be found, this is likely the reason.
+    Check the driver documentation and the source code to see what the
+    new name is.
+
+    In C, constants are now usually implemented in a separate header
+    file named *drivername_defs.h* or *drivername_regs.h*, for easier
+    integration into the SWIG languages, and shared use between C++ and
+    C implementations.
+
+ * **bmpx8x** This driver has been rewritten from scratch in C, with a
+ C++ wrapper.
+
+    All exported symbols have been renamed for consistency and to
+    avoid symbol collisions by having a *BMPX8X_* prefix. As an example,
+    *ADDR* has been renamed to *BMPX8X_DEFAULT_I2C_ADDR*.  Most C
+    ported drivers follow this rule.
+
+    The *getPressureRaw()* and *getTemperatureRaw()* functions have
+    been removed.  This functionality was only needed internally to
+    the driver.
+
+    The constructor no longer accepts a mode argument.  Only the I2C
+    bus and I2C address are accepted.  By default, the device will be
+    configured for it's maximum resolution *BMPX8X_OSS_ULTRAHIGHRES*,
+    the previous default.  You can use the new method
+    *setOversampling()* to change the mode to something else if
+    desired.
+
+    The methods related to calibration, like *computeB5()* are no
+    longer exposed.
+
+    New methods, *init()* and *reset()* have been added.  *reset()*
+    resets the device to a freshly powered up state.  *init()* can be
+    used to re-initialize the device after a reset (reload calibration
+    data) and set a default oversampling mode.
+
+    A new method, *update()* has been added.  This method will update
+    all internal state from the device, and **must** be called before
+    querying the pressure, temperature, sea level and altitude values.
+
+    The *getSeaLevelPressure()* method has been split into two
+    overloaded methods.  One which **requires** an argument in meters
+    (previously, a default was provided), and another which does not
+    accept arguments at all and computes the sea level pressure based
+    on current altitude.
+
+    The *i2cReadReg_16()*, *i2CWriteReg()* and *i2cReadReg_8()* have
+    been replaced with *readReg()*, *readRegs()*, and *writeReg()*, in
+    line with other I2C/SPI drivers of this type.  They are marked
+    protected (in C++) now as well.  Please see the updated
+    documentation and examples for this driver.
+
+ * **mma7660** This driver has been rewritten in C.  Some exported
+ symbols have been changed, for example, *MMA7660_I2C_BUS* was renamed
+ to *MMA7660_DEFAULT_I2C_BUS*.
+
+    See updated documentation and examples for other changes.
+
+ * **bmx055, bmi055, bmc150, bma250e, bmg160, bmm150** This driver has
+ been split up.  The *bma250e*, *bmg160*, *bmm150* drivers have been
+ rewritten in C (with C++ wrappers) and now reside in their own
+ libraries.  The versions of these drivers that used to be present in
+ *bmx055* have been removed, and *bmx055* now uses the new libraries
+ for it's functionality.  The other two composite devices, *bmi055*,
+ and *bmc150* are still contained within the *bmx055* library, and
+ also use the new libraries for their functionality.
+
+    In addition, for all of these drivers some private methods are no
+    longer exposed (such as the compensation routines).
+
+    The C++ driver methods that once returned pointers to a floating
+    point array now return *std::vectors* of the appropriate type.
+    The SWIG language examples for these drivers have been modified to
+    use these methods instead of the C pointer based SWIG methods
+    previously used.
+
+ * **sainsmartks** This driver has been renamed to *lcdks* (LCD Keypad
+ Shield) and moved into it's own library.  It uses the *lcm1602*
+ library to do most of it's work.  In addition, an additional argument
+ was added to the constructor to optionally allow specifying a GPIO
+ pin to be used to control the backlight.  This driver supports the
+ SainsmartKS and DFRobot LCD Keypad Shields.  Similar devices from
+ other manufacturers should also work with this driver.
+
+ * **lcm1602/jhd1313m1** These drivers had been rewritten in C, with
+ C++ wrappers and placed into their own libraries in the previous
+ version of UPM, however, the original C++ implementation was kept in
+ the lcd/i2clcd library for compatibility reasons with existing code.
+ To avoid collisions with the header files, the new *lcm1602* and
+ *jhd1313m1* drivers had their C++ headers renamed to use a **.hxx**
+ suffix.
+
+    In this version of UPM, the *lcm1602* and *jhd1313m1* drivers have
+    been removed from the lcd/i2clcd library.  In addition, the header
+    files for the new implementation have been renamed from their
+    **.hxx** suffix to the normal **.hpp** suffix.
+
+    A change was also made to the new *lcm1602* and *jhd1313m1* C++
+    drivers.  The *createChar()* function now accepts a byte vector
+    *std::vector<uint8_t>* rather than the *char ** pointer that was
+    used previously.  This should make it easier to use with the SWIG
+    language bindings (Python, JavaScript, and especially Java).
+
+ * **bmp280/bme280** Some private methods are no longer exposed (such
+ as the calibration and compensation routines).  In addition,
+ the *getHumidity()* method no longer accepts an argument representing
+ pressure at sea level.  A separate method is provided to set this now.
+
+ * **bno055** This module no longer uses std::strings to pass around
+ binary data (*read/writeCalibrationData()*).  Rather, now *std::vectors* of
+ the appropriate type are used.  In addition, methods that previously
+ returned certain data in the form of an array, like *getEulerAngles()*,
+ now return a *std::vector* instead.  This simplifies the Python,
+ JavaScript, and Java bindings considerably, and leads to more
+ "natural" looking Python/JavaScript/Java code.  For JavaScript, Java,
+ and Python, the examples have been modified to use these methods
+ rather than the methods that return data in argument pointers or
+ arrays.
+
+ * **lpd8806** The constructor for this driver was updated to allow specifying
+ a SPI bus number. This is now the first parameter, the number of LEDs on the
+ strip is now the last (3rd) parameter instead.
+
+ * **max31723** The constructor for this driver was updated to allow specifying
+ a SPI bus number. This is now the first parameter, CS pin second.
+
+ * **tcs3414cs** The constructor for this can now accept an I2C bus and
+ address.
+
+# v1.1.0 and prior
+
+ * **i2clcd/jhd1313m1/lcm1602** LCD devices supported by the i2clcd module are
+ being separated into individual libraries. The APIs will be preserved, but
+ we recommend changing your code to use the new libraries as they become
+ available. Once this transition is complete, the i2clcd module will be
+ deprecated. So far, the following libraries have been made available
+ separately: jhd1313m1, lcm1602.
+
+ * **nunchuck** This driver no longer supports the init() function.
+ All initialization is now done in the C nunchuck_init() function,
+ or the C++ constructor.  In addition, the *NUNCHUCK_I2C_ADDR*
+ define is no longer exposed, as it is not possible to use any other
+ I2C address than *0x52*.  The readBytes() and writeByte() functions
+ are also no longer exposed, since aside from what the driver does
+ to initialize and read data, there are no other options available.
+
+ * **enc03r** This driver no longer supports the value() function.  In
+ addition, an update() function has been added.  This function must be
+ called prior to calling angularVelocity().  angularVelocity() no
+ longer accepts an argument.  Additional functions have been added,
+ however they do not affect compatibility with previous versions.
+
+ * **ds18b20** The C++ interface init() function has been deprecated.
+ It is still present, but currently does nothing.  It will be removed
+ in a future release.
+
+ * **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

@@ -5,10 +5,21 @@ 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.
 
+**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
+
 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
+~~~~~~~~~~~~~
+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.
@@ -23,7 +34,12 @@ 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.
+doing an out-of-source build may cause issues when rebuilding later on. In many
+cases you'll need elevated permissions to install:
+
+~~~~~~~~~~~~~{.sh}
+sudo make install
+~~~~~~~~~~~~~
 
 Our cmake configure has a number of options, *cmake-gui* or *ccmake* can show
 you all the options. The interesting ones are detailed below:
@@ -45,6 +61,10 @@ 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
@@ -57,20 +77,20 @@ Setting the python library to use:
 ~~~~~~~~~~~~~
 -DPYTHON_LIBRARY:FILEPATH=/usr/lib/libpython2.7.so.1.0
 ~~~~~~~~~~~~~
-Building doxygen doc
+Building documentation
 ~~~~~~~~~~~~~
 -DBUILDDOC=ON
 ~~~~~~~~~~~~~
-Build C++ example binaries
+Build C/C++/JAVA examples
 ~~~~~~~~~~~~~
 -DBUILDEXAMPLES=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
@@ -111,3 +131,101 @@ autotools on linux.
 ~~~~~~~~~~~
 pkg-config --cflags --libs upm-i2clcd
 ~~~~~~~~~~~
+
+## Building with Docker
+
+You can use `docker` and `docker-compose` to generate a complete build environment
+for upm without having to install any other tool.
+
+Requirements:
+* [docker](https://www.docker.com/get-docker) >= 1.12.6
+* [docker-compose](https://docs.docker.com/compose/install/) >= 1.9.0
+
+**NOTE:** docker-compose is an optional requirement. It actually make running complex
+docker build and run command easier. But you can just use docker to build and run.
+
+### Using Docker Images to build Upm
+
+**tl;dr:** Just use this commands to build upm:
+
+```sh
+# Build upm documentation
+$ docker-compose run doc
+# Build upm python2 and python3 packages and run python tests
+$ docker-compose run python
+# Build upm java package and run java tests
+$ docker-compose run java
+# Build upm node4 package and run node tests
+$ docker-compose run node4
+# Build upm node5 package and run node tests
+$ docker-compose run node5
+# Build upm node6 package and run node tests
+$ docker-compose run node6
+# Build upm for android things package
+$ docker-compose run android
+```
+
+**docker-compose** will take a look at the `docker-compose.yaml` file in the repository
+root directory, and run an specific command to build upm for the requested target.
+Once the build is completed, you will have a `build/` folder in the repository root with all
+the compiled code. This `build/` folder is created by using a docker volume. The `build\`
+folder contents is reused each time you execute `docker-compose run [TARGET]`.
+To know more about volumes in Docker, visit the [Docker Volume Documentation](https://docs.docker.com/engine/tutorials/dockervolumes/).
+
+You can also start an interactive session inside the docker container if you need to run some
+custom build commands:
+
+```sh
+# Start an interactive bash  shell inside the container
+$ docker-compose run python bash
+# From now, all the commands are executed inside the container
+$ cd build && cmake -DBUILDSWIGPYTHON=ON .. && make clean all
+```
+
+If you don't want to use docker-compose, you can also use `docker run` to build upm.
+For example, to build upm for python, you can do:
+
+```sh
+# From the repository root folder
+$ docker run \
+      --volume=$(pwd):/usr/src/app \
+      --env BUILDSWIGPYTHON=ON \
+      --env BUILDSWIGJAVA=OFF \
+      --env BUILDSWIGNODE=OFF \
+      dnoliver/upm-python \
+      bash -c "./scripts/run-cmake.sh && make -Cbuild"
+```
+
+### Proxy considerations
+
+If, for some reason, you are behind a proxy, find below a list of common problems related
+to proxy settings:
+
+**docker cannot pull images from docker.io**
+
+ Visit [this link](https://docs.docker.com/engine/admin/systemd/#httphttps-proxy)
+ to configure docker daemon behind a proxy.
+
+**docker run fails to access the internet**
+
+docker-compose will automatically take `http_proxy`, `https_proxy`, and `no_proxy`
+environment variables and use it as build arguments. Be sure to properly configure
+this variables before building.
+
+docker, unlinke docker-compose, do not take the proxy settings from the environment
+automatically. You need to send them as environment arguments:
+
+```sh
+# From the repository root folder
+$ docker run \
+    --volume=$(pwd):/usr/src/app \
+    --env BUILDSWIG=ON \
+    --env BUILDSWIGPYTHON=ON \
+    --env BUILDSWIGJAVA=OFF \
+    --env BUILDSWIGNODE=OFF \
+    --env http_proxy=$http_proxy \
+    --env https_proxy=$https_proxy \
+    --env no_proxy=$no_proxy \
+    dnoliver/upm-python \
+    bash -c "./scripts/run-cmake.sh && make -Cbuild"
+```

docs/changelog.md

@@ -4,6 +4,171 @@ Changelog                         {#changelog}
 Here's a list summarizing some of the key undergoing changes to our library
 from earlier versions:
 
+### v1.5.0
+
+ * Introduced a flexible JSON format for technical sensor specifications, notes
+ and classification. This is also used by our [new UPM website](http://upm.mraa.io)
+ * Revised all C++ sensor examples and switched to stack allocations where
+ possible along with other code and formatting clean-up
+ * Significantly improved docker workflow, CI integration, sanity and
+ consistency tests, static code scans and documentation generation
+ * Several improvements to a couple of existing sensor drivers and better
+ compatibility with subplatforms
+ * Added new std::vector to AbstractList<> typemap for Java bindings and
+ examples
+ * New sensors: lis2ds12, lsm6ds3h, lsm6dsl, lidarlitev3
+
+### v1.3.0
+
+ * Finalized all required build system and JAVA binding changes to release the
+ UPM libraries for Android Things targets
+ * Enhanced the modules for lsm303 and tmp006 to support newer variants of the
+ chips
+ * Fixed Node.js detection on Ubuntu when installed with apt using official
+ packages
+ * Minor documentation changes
+ * New sensors: lsm303agr, lsm303d, veml6070, tca9548a, rn2903
+
+### v1.2.0
+
+ * Improved JAVA binding compiler compatibility and added JAVA interfaces that
+ match existing C++ interfaces
+ * Ported Bosch drivers to C thus now they can be used on supported MCUs
+ * Completely redesigned C/C++ example handling by cmake to avoid maintaining
+ a list by hand
+ * Fixed several existing drivers, mostly based on static code analysis reports
+ * Added a sensor driver template plus bash script that can be easily used by
+ developers to start writing their own sensor driver
+ * Numerous documentation improvements
+ * New sensors: p9813, abp, rsc, mmc35240, tcs37727, tmp006, mma8x6x, mag3110,
+ hdc1000
+
+### v1.1.0
+
+ * Reworked cmake handling of internal and external dependencies
+ * Documentation improvements for sensor names, sensor descriptions, external
+ contributor guides and added new section on installing UPM on a supported OS
+ * Fixed issues with C11 builds on some WRLinux gateways and Debian systems
+ * New examples and functionality for speaker and ads1x15 modules
+ * Modified JAVA builds to ensure the SWIG generated wrappers include all
+ functionality and typemaps
+ * New sensors: mcp2515, max30100, uartat, le910
+
+### v1.0.2
+
+ * Minor cmake changes for Java builds and Java examples are now toggled with
+ the same BUILDEXAMPLES cmake switch
+ * Made some improvements in the utilities class for our C drivers
+ * Fixed issue with some drivers not being usable on subplatforms due to pin
+ numbers using uint8 type
+ * New sensors: ims, ecezo, mb704x, rf22
+
+### v1.0.1
+
+ * Warnings as errors enabled for C/CXX (fixed warnings from -Wall and others)
+ * Fix for C/CXX compile flag append issue #485
+ * C sensor libraries for: my9221, otp538u, guvas12d, ppd42ns
+ * New sensor: ms5803
+
+### 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

docs/contributions.md

@@ -94,3 +94,56 @@ then you just add a line to each of your commits with `--signoff` saying
 
 using your real name (sorry, no pseudonyms or anonymous contributions.)
 Unsigned commits will not be accepted.
+
+
+Creating a new sensor library using the sensortemplate
+=======================================
+
+A stubbed-out sensor library is available which can be leveraged to get
+up-and-running quickly when writing a new sensor library.  Use the shell
+commands below to generate collateral files for your new sensor library.
+
+
+```shell
+#!/bin/bash
+
+function make_new_sensor {
+    export SensorName=$1
+    # Get a lowercase version of the string
+    export sensorname=${SensorName,,}
+
+    # Make sure this is run from the root UPM directory
+    if ! grep -q 'UPM ' README.md; then echo "Please run from the root UPM directory"; return -1; fi
+
+    printf "Generating new sensor: ${SensorName}\n"
+    # Copy sensortemplate files to ${sensorname}
+    find docs/ examples/ src/ -name '*sensortemplate*' -exec bash -c 'cp -r $0 ${0/sensortemplate/${sensorname}}' {} \;
+    # Copy SensorTemplate files to ${SensorName}
+    find examples/ src/ -name '*SensorTemplate*' -exec bash -c 'cp -r $0 ${0/SensorTemplate/${SensorName}}' {} \;
+    # Rename sernsortemplate src files
+    rename "s/sensortemplate/${sensorname}/" src/${sensorname}/*
+    # Search/replace the new files, replacing all instances of sensortemplate
+    perl -p -i -e "s/SensorTemplate/${SensorName}/g" src/${sensorname}/* examples/*/*${sensorname}* examples/*/*${SensorName}*
+    perl -p -i -e "s/sensortemplate/${sensorname}/g" src/${sensorname}/* examples/*/*${sensorname}* examples/*/*${SensorName}*
+    # Add mynewmodule example target for java
+    perl -p -i -e "s/^((.*)SensorTemplateSample sensortemplate(.*))/\1\n\2${SensorName}Sample ${sensorname}\3/g" examples/java/CMakeLists.txt
+    # Add mynewmodule example mappings for doxygen
+    perl -p -i -e "s/^(.*SensorTemplateSample.*)$/\1\n${sensorname}.cxx\t${SensorName}Sample.java\t${sensorname}.js\t${sensorname}.py/g" doxy/samples.mapping.txt
+    # Display TODO's
+    printf "Generation complete for sensor library: ${SensorName}\n"
+    printf "TODO's:\n"
+    printf "\t1. Update src/hdr files: src/${sensorname}/${sensorname}.hpp src/${sensorname}/${sensorname}.cxx\n"
+    printf "\t\tChange the Author\n"
+    printf "\t\tChange the Copyright\n"
+    printf "\t\tUpdate all doxygen tags (follow directions for @tags)\n"
+    printf "\t2. Update examples: examples/*/${sensorname}.* examples/java/*${SensorName}*.java\n"
+    printf "\t3. Overwrite docs/images/${sensorname}.png with a valid image of your sensor\n"
+}
+
+# Call make_new_sensor with your new sensor name, example: 'MyNewSensor1234'
+make_new_sensor MyNewSensor1234
+```
+
+Once all files have been created, they can be used as a starting-point for your
+new library.  They will need additional customization (your name/email address,
+documentation, sensor images, etc).

docs/creating_java_bindings.md

@@ -12,25 +12,25 @@ Creating Java Bindings Guide
   * [Implementing callbacks in Java](#implementing-callbacks-in-java)
 
 
-##Overview
+## 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
+## 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
+## Recommendations for the native API
 
-###Pointers
+### 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:
+#### 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++
   /*  
@@ -67,7 +67,6 @@ As much as possible, avoid passing values/returning values through pointers give
   ```
 
 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  
@@ -82,7 +81,6 @@ As much as possible, avoid passing values/returning values through pointers give
   ```
 
 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  
@@ -103,8 +101,8 @@ __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:
+### 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++
@@ -155,7 +153,7 @@ The upm_exception.i interface file is included in the upm.i file, therefor SWIG
 * std::exception
 
 
-####Java specific:
+#### Java specific:
 To throw a specific Java exception:
 
 ```c++
@@ -196,12 +194,12 @@ In the upm library, the java_exceptions.i library file provides the functionalit
 void function throws IOException ();  
 ```
 
-##Caveats & Challenges
+## Caveats & Challenges
 
-###Wrapping C arrays with Java arrays
+### 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
+### Wrapping unbound C arrays with Java arrays if array is output
 Functions that return arrays, return a pointer to that array. E.g.:
 
 ```c++
@@ -229,7 +227,7 @@ __SWIG:__
 }  
 ```
 
-###Wrapping unbound C arrays with Java arrays if array is input
+### 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++
@@ -252,7 +250,7 @@ __SWIG:__
 !!!! There is a difference between TYPE *name and TYPE * name in typemaps!!!!!
 
 
-###Implementing callbacks in Java
+### 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):__
@@ -313,7 +311,7 @@ class A110XISR implements Runnable {
     }
 }
 ```
-####Issues with java callbacks and workarounds
+#### Issues with java callbacks and workarounds
 
 __SWIGJAVA not defined at compile time__
 
@@ -325,18 +323,16 @@ Consider the following files:
 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
+  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
+  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).

docs/documentation.md

@@ -4,98 +4,138 @@ Writing sensor documentation                        {#documentation}
 It is highly encouraged to provide at least some basic documentation for the
 sensors that you want to add to UPM:
 
-- If you don't add documentation, the code review will take very long and 
+- If you don't add documentation, the code review will take very long and
   your contribution could be rejected.
 - Try to have no warnings in doxygen, this is generally fairly easy.
 - Have the specific sensor manufacturer/model & version that you used, if you
   support multiple versions please list.
 - Simple comments do not need full stops.
-- Stick to <80 chars per line even in comments.
+- Stick to <80 chars per line where possible.
 - No text is allowed on the same line as the start or end of a comment /** */.
 
-####The sensor block
+We currently document our libraries in the following way:
 
-This is added just before the class declaration in your header(.h) file and has 
-mandatory fields. For single sensor libraries, this block will actually
-follow immediately after the library block. If you have multiple physical
-sensors, add this to every one.
-Here's an example (disregard the "@verbatim" tags in your actual code):
+* **Doxygen** is used for documenting the API and generating the categories on
+  the [UPM Libraries page](https://iotdk.intel.com/docs/master/upm/modules.html).
+  You can learn more about the Doxygen syntax [here](http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html).
+* **JSON** is used to provide sensor specifications, descriptions, supported
+  platforms, links and other details.
 
-```
-@verbatim
-/**
- * @library <lib-name>
- * @sensor <chip-id>
- * @comname <component-name>
- * @altname <alt-name>
- * @altid <alt-id>
- * @type <component-category>
- * @man <component-manufacturer>
- * @web <component-weblinks>
- * @con <connection-type>
- * @kit <component-kit>
- *
- * @brief Short class/sensor description
- * 
- *   Then add a longer
- *   description here.
- *
- * @image html <component-img.jpeg>
- * @snippet <example-name.cxx> Interesting
- */
-@endverbatim
+When submitting a new driver, you will have to at least fill out the mandatory
+fields as described below.
+
+### The library JSON file
+
+Let's use the BME280 class snippet from the bmp280.json file as an example:
+
+```json
+{
+    "Library": "bmp280",
+    "Description": "Bosch Atmospheric Sensor Library",
+    "Sensor Class":
+    {
+        "BME280":
+        {
+            "Name": "Digital Humidity, Pressure, and Temperature Sensor",
+            "Description": "The BME280 is as combined digital humidity, pressure and temperature sensor based on proven sensing principles. The sensor module is housed in an extremely compact metal-lid LGA package with a footprint of only 2.5 * 2.5 mm2 with a height of 0.93 mm. Its small dimensions and its low power consumption allow the implementation in battery driven devices such as handsets, GPS modules or watches. The BME280 is register and performance compatible to the Bosch Sensortec BMP280 digital pressure sensor",
+            "Aliases": ["bme280", "Grove - Barometer Sensor(BME280)"],
+            "Categories": ["pressure", "humidity", "temperature"],
+            "Connections": ["gpio", "i2c", "spi"],
+            "Project Type": ["prototyping", "industrial"],
+            "Manufacturers": ["adafruit", "seeed", "bosch"],
+            "Examples":
+            {
+                "Java": ["BMP280_Example.java"],
+                "Python": ["bmp280.py"],
+                "Node.js": ["bmp280.js"],
+                "C++": ["bmp280.cxx"],
+                "C": ["bmp280.c"]
+            },
+            "Specifications":
+            {
+                "Vdd": {"unit": "v", "low" : 1.7, "high": 3.6},
+                "Ioff" : {"unit": "mA", "low" : 0.0, "high": 0.0},
+                "Iavg": {"unit": "mA", "low" : 1, "high": 2},
+                "Pressure Range": {"unit": "hpA", "low" : 300, "high": 1100},
+                "Temperature Range": {"unit": "C", "low" : -40, "high": 85}
+            },
+            "Platforms":
+            {
+                "Intel Joule Module":
+                {
+                    "Notes": ["Requires pull-up resistors with carrier board"]
+                }
+            },
+            "Urls" :
+            {
+                "Product Pages": ["https://www.adafruit.com/products/2652"],
+                "Datasheets": ["https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-11.pdf"],
+                "Schematics": ["https://learn.adafruit.com/assets/26693"]
+            }
+        }
+    }
+}
 ```
 
-- `<lib-name>` When adding to an existing library this needs to match that
-  library's "@defgroup", otherwise this is a new library name, generally the
-  same as chip id. *Mandatory*
-- `<chip-id>` Usually the chip number used by the sensor. When this is not
-  available or relevant, use a unique descriptor that makes sense. 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*
-- `<component-weblinks>` Links to vendors or data-sheets. *Optional*
-- `<connection-type>` Specifies how does the sensor connect to the board
-  *Mandatory*
-- `<component-kit>` Specifies if the sensor is part of a kit. *Optional*
+#### Mandatory fields:
 
-Existing groups that can be used for the manufacturer, connection, category and
-kit tags are found in the src/upm.h file.
+For the library:
 
-Optionally, a small representative image can be placed in the "docs/images"
-subfolder and linked with the "@image" tag.
-**Please do not use existing, copyrighted images with your sensors!**
+- `Library` The name of the library. This is appended to the upm prefix during
+  a build.
+- `Description` A short description of the library and what it contains.
 
-The example should have an 'Interesting' section which will be highlighted as
-a code sample in doxygen. Everything in between such tags will show up in the
-class documentation when "@snippet" is added at the end of a class docstring.
-Tags use this format (in "example-name.cxx"):
+For the sensor classes:
 
-```
-@verbatim
- //! [Interesting]
+- `Sensor Class` This is the object containing the sensor class(es) within the
+  library. Class objects need to match the name used in code.
+- `Name` Title Case descriptive names for your sensor. Multiple values can be
+  used to capture the chip name, generic name, or specific name for a vendor.
+  Examples: Digital Pressure Sensor, Serial MP3 Module
+- `Description` A more detailed explanation what the sensor does and how it
+  works.
+- `Categories` Mention one or more categories the sensor fits in. Accepted
+  values are listed in the groups.md file.
+- `Connections` Specifies how does the sensor connect to the board. Accepted
+  values are listed in the groups.md file.
+- `Project Type` What time of projects is the sensor suited for. For example:
+  prototyping, industrial, commercial.
+- `Manufacturers` List of sensor manufacturers or vendors. Can be 'generic',
+  other accepted values in groups.md.
+- `Examples` Names of the example files provided with the library. At a minimum,
+  the `C++` example needs to be provided.
+- `Urls` At least one link for `Product Pages` needs to be provided. Additional
+  links to `Datasheets` or `Schematics` can be added.
 
-    ...example code here...
+#### Optional and customizable fields
 
- //! [Interesting]
-@endverbatim
-```
+- `Kits` Specifies if the sensor is part of a kit. Accepted values are listed
+ in the groups.md file.
+- `Image` Name of the image file provided with the sensor class.
+- `Specifications` Relevant sensor specifications as listed in the datasheet.
+- `Platforms` Platform specific notes or known limitations and workarounds.
 
-For more examples take a look at the existing headers in our github repository.
+As mentioned, accepted values for some of the fields are listed under the
+[groups.md](../src/groups.md) file. If needed, you can add new categories
+for your sensor library following the existing format.
 
-####The library block
+JSON files are automatically checked for correctness and required fields on
+code submissions.
+
+**Please do not use copyrighted images with your sensors!**
+
+Images from Seeed, DFRobot, Sparkfun or Adafruit are permitted.
+
+### Doxygen tags
+
+#### The library doxygen block
 
 New libraries must have the "@brief", "@defgroup" and "@ingroup" tags in one
 block. This usually follows the namespace and it is common to have one sensor
 per library.
 
-You should end up with something like this:
+You should end up with something like this (disregard the "@verbatim" tags in
+your actual code):
 
 ```
 @verbatim
@@ -110,8 +150,43 @@ You should end up with something like this:
 @endverbatim
 ```
 
-In "@defgroup" use the same `<lib-name>` used in the sensor block. Multiple
-sensors can be added to the same library this way.
+Use `<lib-name>` to name the library.
+
 For "@ingroup" add the same values as in the sensor block for manufacturer,
 category, connection type and kit. If you have multiple classes or sensors
 per library, only use the "@ingroup" tags that are common for all of them.
+
+Existing groups that can be used for the manufacturer, connection, category and
+kit tags are found in the *src/groups.md* file.
+
+#### The sensor doxygen block
+
+This is added just before the class declaration in your header(.hpp) file and has
+one mandatory field. For single sensor libraries, this block will actually follow
+immediately after the library block. If you have multiple sensor classes, add
+this to every one.
+
+Here's an example:
+
+```
+@verbatim
+/**
+ * @library <lib-name>
+ * @brief Short class/sensor description
+ *
+ *   Then add a longer
+ *   description here.
+ */
+@endverbatim
+```
+
+When adding to an existing library, `<lib-name>` needs to match that library's
+"@defgroup".
+
+For more examples take a look at the existing headers in our github repository.
+Also, make sure to check our [sensortemplate](contributions.md#creating-a-new-sensor-library-using-the-sensortemplate)
+as it can facilitate new sensor additions.
+
+Existing header files might have additional fields under the sensor block. These
+have been used in the past to generate sensor pages outside of doxygen, but they
+are now deprecated and not required for new additions.

docs/guidelines.md

@@ -0,0 +1,348 @@
+# Code Commenting And Documentation Authoring Guidelines
+
+#### [Part I. Code Commenting](#code-commenting)
+
+[Grammar](#grammar)
+
+- [Active vs passive voice](#voice)
+
+- [Capitalization](#capitalization)
+
+- [No possessive case](#possessive-case)
+
+- [Present tense](#present-tense)
+
+- [Second person vs the user / reader / programmer / engineer](#second-person)
+
+- [Third person vs infinitive](#third-person)
+
+[Punctuation](#punctuation)
+
+- [Comma in enumerations](#comma)
+
+- [No period at the end of description](#period)
+
+[Specific word usage](#word-usage)
+
+- [Abbreviations and acronyms](#abbr-acr)
+
+- [Adjectives containing numbers](#adj-num)
+
+- [App vs application](#app)
+
+- [Function vs method](#func-meth)
+
+- [Onboard vs on-board](#onboard)
+
+- [Sensor name vs sensor model](#name-model)
+
+- [Setup vs set up](#setup)
+
+- [Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi](#setup)
+
+[Trademarks](#trademarks)
+
+- [Intel products](#intel-prod)
+
+- [Third-party technology](#third-party)
+
+- [Trademark + noun](#tm-noun)
+
+#### [Part II. Documentation Authoring](#doc-authoring)
+
+[Grammar](#da-grammar)
+
+- [Capitalization](#da-capitalization)
+
+[Styling](#da-styling)
+
+- [Bolding](#da-bolding)
+
+- [Backticks](#da-backticks)
+
+- [Links](#da-links)
+
+- [Numbered list vs bullet points](#da-lists)
+
+[Specific word usage](#da-word-usage)
+
+- [Login vs log in](#da-login)
+
+- [Click](#da-click)
+
+- [SSH](#da-ssh)
+
+# <a name="code-commenting"></a>Code Commenting Guidelines
+
+## <a name="grammar"></a>Grammar
+
+### <a name="voice"></a>Active vs passive voice
+
+Where possible, prefer active voice over passive.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| It can be put into the configuration mode by grounding the CONFIG pin on the transceiver. | - You can put it into the configuration mode by grounding the CONFIG pin on the transceiver.<br>- To put it into the configuration mode, ground the CONFIG pin on the transceiver.<br>- Put it into the configuration mode by grounding the CONFIG pin on the transceiver. |
+
+### <a name="capitalization"></a>Capitalization
+
+- Capitalize the first word in the description of an entity.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| checks to see if there is data available for reading | Checks to see if there is data available for reading |
+| @param len length of the buffer | @param len Length of the buffer |
+
+- Be consistent with the capitalization of boolean values.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Returns True on success, false otherwise | - Returns true on success, false otherwise<br>- Returns True on success, False otherwise |
+
+### <a name="possessive-case"></a>No possessive case
+
+Do not use possessive case to avoid unnecessary personalization.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| method's output | - method output<br>- output of the method |
+
+### <a name="present-tense"></a>Present tense
+
+Use the present simple tense instead of future, past, or present perfect.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| When specified, this value will be used in computing the voltage. | When specified, this value is used in computing the voltage. |
+| Once the data has been read… | Once the data is read… |
+
+### <a name="second-person"></a>Second person vs the user / reader / programmer / engineer
+
+Use second person when addressing the target reader of your comment.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| The user can easily override this method. | You can easily override this method. |
+
+### <a name="third-person"></a>Third person vs infinitive
+
+Use third-person verb forms in short descriptions of classes, methods, functions, etc., not infinitive.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Get the proximity value from the sensor | Gets the proximity value from the sensor |
+
+## <a name="punctuation"></a>Punctuation
+
+### <a name="comma"></a>Comma in enumerations
+
+Add an extra comma before the last item in a list joined by **and** / **or**.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Returns raw values for the X, Y and Z axes. | Returns raw values for the X, Y, and Z axes. |
+
+### <a name="period"></a>No period at the end of description
+
+Do not put a period if the description of an entity is one sentence long.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Returns the name of the sensor. | Returns the name of the sensor |
+| Sets the frequency modulation<br>Valid values are between 10 and 160 (in kHz) | Sets the frequency modulation. Valid values are between 10 and 160 (in kHz). |
+| @param millis Maximum time in milliseconds to wait for the input<br>-1 means waiting forever (default) | @param millis Maximum time in milliseconds to wait for the input. -1 means waiting forever (default). |
+
+<font color="purple">**Exception:**</font> if the description contains more than one sentence, put periods after each sentence.
+
+## <a name="word-usage"></a>Specific word usage
+
+### <a name="abbr-acr"></a>Abbreviations and acronyms
+
+- Spell out the first occurrence or the first prominent use of an abbreviation or acronym, followed by a shortened form.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| @brief API for the GP2Y0A family of IR Proximity Sensors | @brief API for the GP2Y0A family of infrared (IR) Proximity Sensors |
+
+- Do not use Latin abbreviations.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Works best with halved values; e.g., 1.0, 0.5, 0.25, etc. | Works best with halved values; for example, 1.0, 0.5, 0.25, and so on. |
+
+- Know exactly what the abbreviation or acronym means to avoid unnecessary duplication.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| - LCD display<br>- ISR routine | - LCD / liquid-crystal display<br>- ISR / interrupt service routine |
+
+### <a name="adj-num"></a>Adjectives containing numbers
+
+Adjectives of the form **number + noun / participle** should be hyphenated. It does not matter if a number is represented by one or more digits or spelled out.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| - 4 wire stepper motor<br>- 3 axis gyroscope<br>- zero based indexing<br>- one byte register | - 4-wire stepper motor<br>- 3-axis gyroscope<br>- zero-based indexing<br>- one-byte register |
+
+### <a name="app"></a>App vs application
+
+Use **app** when referring to a program running on a device, and **application** when referring to a program running on a desktop / laptop computer.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| The wiki page for this device includes a link to an Android\* application that can be used to read the device via NFC. | The wiki page for this device includes a link to an Android\* app that can be used to read the device via NFC. |
+
+### <a name="func-meth"></a>Function vs method
+
+If a function is associated with a class, use **method** instead.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| class WheelEncoder {<br>...<br>/**<br>* Starts the counter. This function also clears<br>* the current count and resets the clock.<br>*/<br>void startCounter(); | class WheelEncoder {<br>...<br>/**<br>* Starts the counter. This method also clears<br>* the current count and resets the clock.<br>*/<br>void startCounter(); |
+
+### <a name="onboard"></a>Onboard vs on-board
+
+Use **onboard**.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| This ADC features an on-board reference and oscillator. | This ADC features an onboard reference and oscillator. |
+
+### <a name="name-model"></a>Sensor name vs sensor model
+
+Use a sensor name alone or a sensor model followed by a sensor name, not a sensor model alone.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| ADXL345 is compatible with… | - The ADXL345 3-axis digital accelerometer is compatible with…<br>- The accelerometer is compatible with… |
+
+<font color="purple">**Exception:**</font> you can use a sensor model alone when introducing a
+sensor for the first time:
+
+ADXL345 is a 3-axis digital accelerometer…
+
+### <a name="setup"></a>Setup vs set up
+
+**Setup** is a noun, **set up** is a verb.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| It does not require any additional set up. | It does not require any additional setup. |
+| For instructions on how to setup…, refer to... | For instructions on how to set up…, refer to... |
+
+### <a name="wi-fi"></a>Wi-Fi vs WiFi / Wifi / Wi-fi / wifi / wi-fi
+
+Use **Wi-Fi**.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| It was tested with the XBee\* S6B WiFi module. | It is tested with the XBee\* S6B Wi-Fi\* module. |
+
+## <a name="trademarks"></a>Trademarks
+
+### <a name="intel-prod"></a>Intel products
+
+Use the correct official names of Intel products. When in doubt, check the TM names database.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| It is a 64x48 pixel OLED display that connects directly to an edison via its 80-pin connector. | It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector. |
+
+**Note:** if an Intel product has a legally approved short name, you may use it in subsequent instances, after spelling it out the first time.
+
+### <a name="third-party"></a>Third-party technology
+
+Add an asterisk (\*) after a name to indicate a third-party trademark or registered intellectual property. If you are not sure whether an asterisk is necessary after a particular name, the rule of thumb is to put one, to be on the safe side.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| The Grove MQ2 Gas Sensor module is useful for gas leakage detection. | The Grove\* MQ2 Gas Sensor module is useful for gas leakage detection. |
+
+### <a name="tm-noun"></a>Trademark + noun
+
+Always follow trademarks by an appropriate noun. For a list of approved nouns for a particular trademark, check the TM names database.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison via its 80-pin connector. | It is a 64x48 pixel OLED display that connects directly to an Intel(R) Edison board via its 80-pin connector. |
+
+# <a name="doc-authoring"></a>Documentation Authoring Guidelines
+
+## <a name="da-grammar"></a>Grammar
+
+### <a name="da-capitalization"></a>Capitalization
+
+For titles, use sentence capitalization.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Add a New Device | Add a new device |
+
+## <a name="da-styling"></a>Styling
+
+### <a name="da-bolding"></a>Bolding
+
+For GUI elements and file names, use bolding instead of quotes.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| In the “Environment Variables” window, click “OK”. | In the **Environment Variables** window, click **OK**. |
+| Copy the “example.zip” archive into the installation directory. | Copy the **example.zip** archive into the installation directory. |
+
+### <a name="da-backticks"></a>Backticks
+
+Enclose program commands, code blocks, and file paths in backticks (\`).
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| To create a new device, use the **create-thing** command. | To create a new device, use the \`create-thing\` (rendered as `create-thing`) command. |
+| Go to **C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws**. | Go to \`C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws\` (rendered as `C:\Users\me\Documents\GitHub\intel-iot-examples-mqtt\support\aws`). |
+
+### <a name="da-links"></a>Links
+
+Do not use embedded links to third-party websites.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Create an account on [Microsoft Azure](https://azure.microsoft.com/en-us), if you do not yet have one. | Create an account on [https://azure.microsoft.com/en-us](https://azure.microsoft.com/en-us), if you do not yet have one. |
+
+### <a name="da-lists"></a>Numbered list vs bullet points
+
+- For a logical sequence of steps, use a numbered list.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| When running your C++ code on the Edison, you need to set the MQTT parameters in Eclipse. Go to "Run configurations", and change the "Commands to execute before application" to the following:<br>…<br>Click on the "Apply" button to save these settings.<br>Click on the "Run" button to run the code on the Edison. | When running your C++ code on the Intel® Edison board, you need to set the MQTT\* client parameters in Eclipse\*. To do that:<br>1. Go to **Run configurations** and, in the **Commands to execute before application** field, type the following:<br>…<br>2. Click the **Apply** button to save these settings.<br>3. Click the **Run** button to run the code on your board. |
+
+- For a list of equally important options, use a bulleted list.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| From this exercise, developers will learn how to:<br>1. Connect the Intel® Edison board...<br>2. Run these code samples in the Intel® System Studio IoT Edition...<br>3. Set up a web application server... | From this exercise, developers will learn how to:<br>- Connect the Intel® Edison board…<br>- Run these code samples in the Intel® System Studio IoT Edition…<br>- Set up a web application server… |
+
+## <a name="da-word-usage"></a>Specific word usage
+
+### <a name="da-login"></a>Login vs log in
+
+**Login** is a noun, **log in** is a verb.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Provide your log in and password. | Provide your login and password. |
+| Login to your account. | Log in( )to your account. |
+
+### <a name="da-click"></a>Click
+
+Omit **on** after **click**.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| Click on **Advanced system settings**. | Click **Advanced system settings**. |
+
+### <a name="da-ssh"></a>SSH
+
+Do not use SSH as a verb. It is considered slang and is to be avoided.
+
+| <font color="red">**Incorrect**</font> | <font color="green">**Correct**</font> |
+| --- | --- |
+| SSH into your Intel® Edison board. | Establish an SSH connection to your Intel® Edison board. |