Skip to content
This repository has been archived by the owner on Jun 13, 2019. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
All: Initial commit
Change-Id: Ifb5314718568318a831dea8b8ff78746586ea007
Signed-off-by: Gabriel Schulhof <gabriel.schulhof@intel.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/7535
  • Loading branch information
Gabriel Schulhof committed Apr 1, 2016
1 parent 848fa7d commit 25dc3db
Show file tree
Hide file tree
Showing 147 changed files with 13,412 additions and 0 deletions.
3 changes: 3 additions & 0 deletions .jscsrc
@@ -0,0 +1,3 @@
{
"preset": "jquery"
}
82 changes: 82 additions & 0 deletions .travis.yml
@@ -0,0 +1,82 @@
sudo: false

language: cpp

matrix:
fast_finish: true
include:
- env: NODE_VERSION=0.10 TEST_SCRIPT=ci
os: linux
addons: &buildpackages
apt:
sources:
- ubuntu-toolchain-r-test
packages:
- libboost-all-dev
- libcurl4-openssl-dev
- uuid-dev
- g++-4.8

- env: NODE_VERSION=0.12 TEST_SCRIPT=ci
os: linux
addons: *buildpackages

- env: NODE_VERSION=4.0 TEST_SCRIPT=ci
os: linux
addons: *buildpackages

- env: NODE_VERSION=4.4 TEST_SCRIPT=ci
os: linux
addons: *buildpackages

- env: NODE_VERSION=4.0 TEST_SCRIPT=ci-lint
os: linux

- env: NODE_VERSION=0.12 TEST_SCRIPT=ci-basic
os: osx

# Allowed failures must be specified twice - once in "include" to have them
# run, and again in "allowed_failures" to not have them break the build.
# Below are the allowed failures:

- env: NODE_VERSION=0.10 TEST_SCRIPT=ci
os: osx

- env: NODE_VERSION=0.12 TEST_SCRIPT=ci
os: osx

- env: NODE_VERSION=4.0 TEST_SCRIPT=ci
os: osx

allow_failures:
- env: NODE_VERSION=0.10 TEST_SCRIPT=ci
os: osx

- env: NODE_VERSION=0.12 TEST_SCRIPT=ci
os: osx

- env: NODE_VERSION=4.0 TEST_SCRIPT=ci
os: osx

install:
- >
if test "x${TRAVIS_OS_NAME}x" = "xlinuxx"; then
export CXX="g++-4.8" CC="gcc-4.8"
fi
- rm -rf ~/.nvm
- wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.26.1/install.sh | bash
- source ~/.nvm/nvm.sh
- nvm install "${NODE_VERSION}"
- npm install -g npm@^2.14.2
- >
if test "x${TRAVIS_OS_NAME}x" = "xosxx"; then
brew install scons
fi
- npm install -g grunt-cli

script: npm run-script "${TEST_SCRIPT}"

notifications:
irc:
channels:
- "chat.freenode.net#iotivity-node"
6 changes: 6 additions & 0 deletions AUTHORS.txt
@@ -0,0 +1,6 @@
Gabriel Schulhof <gabriel.schulhof@intel.com>
Sakari Poussa <sakari.poussa@intel.com>
Srinivasa Ragavan <srinivasa.ragavan.venkateswaran@intel.com>
Sudarsana Nagineni <sudarsana.nagineni@intel.com>
Zhiqiang Zhang <zhiqiang.zhang@intel.com>
Zoltan Kis <zoltan.kis@intel.com>
71 changes: 71 additions & 0 deletions CONTRIBUTING.md
@@ -0,0 +1,71 @@
## Maintenance

### Coding Style And Principles
Please follow the [jQuery][] coding style for the JavaScript files. You can format all JS and C++ files with the following command:
```
grunt format
```

When writing the bindings, data arriving from Javascript is considered unreliable and must be validated. If it does not validate correctly, an exception must be thrown immediately after the failed check, and the function must return immediately. Data arriving from C is considered reliable and can be assigned to Javascript immediately.

Functions converting Javascript structures to C structures are named ```c_CStructureName``` and have the following signature:

```C++
bool c_CStructureName( Local<Object> jsStructureName, CStructureName **p_putStructurePointerHere );
```
This signature allows us to throw an exception and return false if any part of ```jsStructureName``` fails validation. The caller can then also return false immediately, and the binding can ultimately return undefined immediately.
As a general principle, if a Javascript value fails validation, throw an exception immediately. Do not return false and expect the caller to throw the exception. Call it exception-at-the-point-of-failure.
Pointers to structures received from the C API may always be null. The functions converting those pointers to Javascript objects (```js_CStructureName()```) assume that they are not null. So, wrap the call to such a function in a null-check.
When filling out a C structure in a function ```c_CStructureName()```, create a local structure first, and only if all validations pass, ```memcpy()``` the local structure into the structure passed in.
### Additional dependencies
```clang-format``` is required for formatting the C++ source code. Your distribution should provide this utility.
### Tests
To run the tests, simply run ```grunt test```. A script called ```dist.sh``` is also provided. It runs ```npm install```, runs the tests, then runs ```npm prune --production``` to remove all sources, headers, and build dependencies. After that, it copies relevant files to ```dist/``` and creates a tarball from them. This is followed by running ```npm install``` again to restore the development environment.
The ```dist.sh``` script accepts the optional command line argument ```--testonly```. This will cause the script to exit after having run the tests.
A crude way of estimating which functions still need to be tested is this:
```
diff -u \
<( find tests/tests -type f | zerosep | xargs -0 grep -E 'iotivity\.[_a-zA-Z0-9]*\(' | sed -r 's/^.*iotivity\.([_A-Za-z0-9]*)\(.*$/\1/' | sort -u ) \
<( cat src/functions.cc | grep '^ SET_FUNCTION' | sed 's/);$//' | awk '{ print $2;}' | sort )
```
### Releasing
0. The version number in ```package.json``` is structured as described [below](#version-number-structure). Increment the suffix by one.
0. Edit README.md and increment the suffix in all references containing the package version.
0. Make sure the build passes for the commitid you wish to tag.
0. Tag the commit. The name of the tag is identical to the ```version``` field in ```package.json```.
0. git push origin --tags
0. npm publish
### To build against a new upstream version:
0. Modify the ```"version"``` field in ```package.json```, setting it to the version of iotivity against which you're building.
If <a name="version-number-structure"></a>you're building against a released version, set the version as that version. Otherwise, set the version to the next patchlevel release and append ```-pre-<commitid>``` where ```<commitid>``` is the commitid of the revision against which you're building. Add the suffix ```-n``` where ```n``` is a number starting at 0. This number represents the number of times the package has been released for a given version of iotivity. Examples of version numbers are ```0.8.0-5``` and ```0.8.1-pre-1057bc0fbad1a6fee15bad6e75f00dca5ec105ed-0```. Use the resulting version number in ```README.md``` as well as ```octbstack.pc.in```.
0. Modify the references to the version in ```README.md``` and the platform info of the high-level servers located in ```js/```.
0. Modify the value of the variable ```version``` in ```octbstack.pc.in```.
0. Build and optionally install the new version of iotivity.
0. If you haven't installed iotivity in the previous step, you must now export environment variables ```OCTBSTACK_CFLAGS``` and ```OCTBSTACK_LIBS```, because the next step needs them.
0. If the ```CFLAGS``` and/or ```LIBS``` have changed, modify ```install.sh``` and/or ```octbstack.pc.in``` and make the same modifications in ```binding.gyp```.
0. Test the build with both built-in iotivity and with iotivity via pkgconfig:
```sh
nvm use 4.0 && git clean -x -d -f -f && npm run-script ci && \
nvm use 0.12 && git clean -x -d -f -f && npm run-script ci && \
nvm use 0.10 && git clean -x -d -f -f && npm run-script ci && \
nvm use 4.0 && git clean -x -d -f -f && ./dist.sh --testonly && \
nvm use 0.12 && git clean -x -d -f -f && ./dist.sh --testonly && \
nvm use 0.10 && git clean -x -d -f -f && ./dist.sh --testonly
```

[jQuery]: http://contribute.jquery.org/style-guide/js/
31 changes: 31 additions & 0 deletions Gruntfile.js
@@ -0,0 +1,31 @@
//
// Copyright 2016 Intel Corporation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
module.exports = function( grunt ) {
"use strict";

var path = require( "path" );

require( "load-grunt-config" )( grunt, {
configPath: [
path.join( __dirname, "grunt-build", "tasks", "options" ),
path.join( __dirname, "grunt-build", "tasks" )
],
init: true
} );

require( "load-grunt-tasks" )( grunt );

};
112 changes: 112 additions & 0 deletions README.md
@@ -0,0 +1,112 @@
# iotivity-node

## Description
This project provides [iotivity][] node.js bindings.

## Build status
<a href="https://travis-ci.org/otcshare/iotivity-node">
<img alt="Build Status" src="https://travis-ci.org/otcshare/iotivity-node.svg?branch=master"></img>
</a>

## Installation

### For the impatient:
0. Make sure [node][] is up and running
0. Install the following packages, which your distribution should provide:
0. unzip, scons, and make
0. Development headers for boost, libuuid, glib2, and libcurl

boost and libcurl are needed during the build process, but iotivity-node does not ultimately depend on either.
0. A C compiler and a C++ compiler
0. Run ```npm install```

Alternatively, there's a [video][] showing how to prepare a pristine Fedora 23 Cloud image for iotivity-node.

iotivity-node provides two interfaces: The low-level interface is a close mapping of the iotivity C API.
```JS
var iotivity = require( "iotivity-node/lowlevel" );
```
will give you access to the low-level interface.

There is also a high-level interface which implements the [JS API spec](./spec/iot-js-spec.md). This interface requires the ```Promise``` object which is only available starting node.js 4.0.
```JS
var device = require( "iotivity-node" )();
```
will give you an instance of OicDevice as described in the JS API spec.

### In more detail:
iotivity-node depends on [iotivity][] proper. It has been tested against [1.0.1][] on Linux. iotivity depends on development headers for libuuid and boost.

iotivity-node requires a compiler that implements the C++11 standard.

During compilation, iotivity-node downloads iotivity from its git repository, builds it, and links against it. If you wish to build iotivity separately, set the environment variable OCTBSTACK_CFLAGS to contain the compiler arguments necessary for building against iotivity, and also set the environment variable OCTBSTACK_LIBS to contain the linker arguments necessary for linking against iotivity. If both variables are set to non-empty values, iotivity-node will skip the step of downloading and building iotivity from sources. If you choose to build iotivity separately, you can use the following procedure, which is known to work on Linux:

0. Grab a [snapshot][] of iotivity from its git repository and unpack it locally.
0. Make sure a compiler, make, [scons][] (a build tool), and the headers for the above-mentioned library dependencies (boost and libuuid) are installed. Your distribution should provide all these tools and libraries.
0. ```cd iotivity```
0. scons has the concept of targets just like make. You can get a list of targets contained in the iotivity repository, as well as a listing of recognized build flags via ```scons --help```. The only target you need for the node.js bindings is ```liboctbstack```. Thus, run ```scons liboctbstack``` to build this target.

On OSX you need more targets than just ```liboctbstack``` because on that platform iotivity does not build ```liboctbstack``` as a shared library, but rather as an archive. Thus, you need to build all targets that correspond to archives that go into the Linux ```liboctbstack``` shared library:
* ```libconnectivity_abstraction```
* ```libcoap```
* ```c_common```
* ```libocsrm```
0. Now that iotivity is built, clone this repository, and change directory into it.
0. Set the following environment variables:
* ```OCTBSTACK_CFLAGS``` - this should contain the compiler flags for locating the iotivity include files. For example, the value of this variables can be ```-I/home/nix/iot/iotivity/resource/csdk/stack/include```.
* ```OCTBSTACK_LIBS``` - this should contain the linker flags necessary for locating ```liboctbstack.so``` both at compile time and at runtime. Its value can be as simple as ```-loctbstack``` if liboctbstack is in /usr/lib, but may need to be as complex as ```-L/home/nix/iot/iotivity/out/linux/x86/release -loctbstack -Wl,-rpath=/home/nix/iot/iotivity/out/linux/x86/release``` if liboctbstack.so is located on an unusual path.
0. Run ```npm install``` with these environment variables set.

<a name="install-scripts"></a>Alternatively, you can use some rudimentary install scripts for both iotivity and this repository. Using them will help you avoid having to set the environment variables ```OCTBSTACK_CFLAGS``` and ```OCTBSTACK_LIBS```, because the scripts will supply them to the build process.

0. Grab [install.sh][] and [octbstack.pc.in][] and place them in the root of the iotivity repository.
0. As root, change directory to the iotivity repository and run ```./install.sh```. The script recognizes the following environment variables:
0. ```PREFIX``` is set to ```/usr``` by default
0. ```DESTDIR``` is unset.
0. ```INSTALL_PC``` is unset. Setting it to ```true``` will cause ```install.sh``` to also copy the file ```octbstack.pc``` into ```${DESTDIR}/${PREFIX}/lib/pkgconfig```.

Use ```PREFIX``` to install to a location other than ```/usr``` and use ```DESTDIR``` to set an additional prefix where to put the files. This latter option is especially useful for packaging. Examples:

```PREFIX=/usr/local ./install.sh``` will install the files into ```/usr/local``` instead.

```PREFIX=/usr/local DESTDIR=/home/username/iotivity-installation ./install.sh``` will install the files into ```/home/username/iotivity-installation/usr/local```, but will configure liboctbstack to work when loaded from ```/usr/local```.
0. After having installed iotivity using the above script, you can run ```./dist.sh``` from the root of this repository without first having to set any environment variables. The script will grab the environment via ```pkg-config``` from the file installed above, and will build, test, and create a directory structure under ```dist/``` which is suitable for deployment on a target device. See ```./dist.sh --help``` for more options.

## Placing the binaries onto a device
The distribution scripts ```dist.sh``` and ```install.sh``` when used together make it easy to create a binary tarball which can be unpacked into the root directory of a device:

0. Change directory to the root of the ```iotivity``` repository and run ```DESTDIR=/tmp/iotivity-installation ./install.sh```
0. ```mkdir -p /tmp/iotivity-installation/usr/lib/node_modules```
0. Change directory to the root of the ```iotivity-node``` repository.
0. ```./dist.sh```
0. ```cd dist```
0. ```cp -a iotivity /tmp/iotivity-installation/usr/lib/node_modules```
0. ```cd /tmp/iotivity-installation```
0. ```rm -rf usr/include usr/lib/pkgconfig```
0. ```tar cvjf iotivity.bin.tar.bz2 *```

You can now transfer iotivity.bin.tar.bz2 to the device and then unpack it into the root directory.

## Persistence

The high-level JS API provides a means for persisting the device ID across instantiations of a process according to the [iotivity wiki][]. It does so by creating a directory ```${HOME}/.iotivity-node```. Thereunder, it creates directories whose name is the sha256 checksum of the absolute path of the given script. Thus, if you write a script located in ```/home/user/myscript.js``` that uses the high-level JS API, its persistent state will be stored in the directory
```
/home/user/.iotivity-node/1abfb1b70eaa1ccc17a42990723b153a0d4b913a8b15161f8043411fc7f24fb1
```
in a file named ```oic_svr_db.json```. The file initially contains enough information to persist the device ID used whenever you run ```/home/user/myscript.js```. You can add more information to the file in accordance with the [iotivity wiki][].

## Examples

The JavaScript examples are located in [js/](./js/) and come in pairs of one client and one server, each illustrating a basic aspect of iotivity. To run them, open two terminals and change directory to the root of the iotivity-node repository in both. Always launch the server before the client. For example, in one terminal you can run ```node js/server.discoverable.js``` and in the other terminal you can run ```node js/client.discovery.js```.

Make sure no firewall is running (or one is properly configured to allow iotivity-related traffic) on the machine(s) where these applications are running.

[iotivity]: http://iotivity.org/
[node]: https://nodejs.org/
[1.0.1]: https://gerrit.iotivity.org/gerrit/gitweb?p=iotivity.git;a=tree;hb=1.0.1
[snapshot]: https://gerrit.iotivity.org/gerrit/gitweb?p=iotivity.git;a=snapshot;h=1.0.1;sf=tgz
[scons]: http://www.scons.org/
[install.sh]: https://raw.githubusercontent.com/otcshare/iotivity-node/1.0.1-1/install.sh
[octbstack.pc.in]: https://raw.githubusercontent.com/otcshare/iotivity-node/1.0.1-1/octbstack.pc.in
[iotivity wiki]: https://wiki.iotivity.org/faq_s
[video]: https://www.youtube.com/watch?v=S3vcm-ox4Z4

0 comments on commit 25dc3db

Please sign in to comment.