search

intel / iotivity-node

Node.js bindings for IoTivity
https://www.iotivity.org/
42 stars 44 forks source link

readme

iotivity-node

DISCONTINUATION OF PROJECT. This project will no longer be maintained by Intel. Intel will not provide or guarantee development of or support for this project, including but not limited to, maintenance, bug fixes, new releases or updates. Patches to this project are no longer accepted by Intel. If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the community, please create your own fork of the project.

To create a fork of this project it is best not to use GitHub's "Fork" feature, because that restricts one's ability to maintain issues and a Wiki. Nevertheless, these steps may be followed:

  1. Create a new, empty GitHub repository of which you are the owner.
  2. Clone this archived repository.
  3. Change directories into the clone. 
    cd iotivity-node
  4. Push to the empty repository you created: 
    git push -f git@github.com:<your-organization>/<your-repository> master
  5. Maintain your fork at `https://github.com// complete with issues, PRs, and a Wiki.

Description

This project provides a Javascript API for OCF functionality. The API follows a maintained specification and is implemented as a native addon using iotivity as its backend.

Status

Windows Build Status Posix Build Status

Coverage Status

Installation

  1. Make sure node version 0.12 or later is up and running. This means that
    1. the command node runs node version 0.12 or later, and that
    2. the directory in which the node binary can be found is listed in the PATH environment variable so that the command node somescript.js is enough to execute somescript.js using node version 0.12 or later.
  2. Install the following packages, which your distribution should provide:
    1. unzip, scons (version 2.51), git, and make
    2. Development headers for libuuid, and glib2
    3. A C compiler and a C++ compiler (gcc-5 or later)
  3. Clone this repository.
  4. cd iotivity-node
  5. Run npm install.
  1. Install node 4 or later. As with Linux and OSX, make sure that node is called node and that it is on your PATH.
  2. In a PowerShell running as Administrator, run npm install -g --production windows-build-tools. This will install Python and the toolchain necessary for building iotivity-node. While this command runs, you can perform some of the following steps.
  3. Install git
  4. Install 7-Zip
  5. The installation of the windows-build-tools package eventually indicates that it has installed Python. After that message appears, you can perform some of the steps below.

  6. In a command prompt, append the python folder, the python scripts folder, and the 7-Zip folder to your PATH. The paths you append are based on your Windows user name, so replace "yourusernamehere" in the example below with your actual Windows user name.

      setx PATH "%PATH%;c:\Users\yourusernamehere\.windows-build-tools\python27;c:\Users\yourusernamehere\.windows-build-tools\python27\scripts;c:\Program Files\7-Zip"
  7. Close the command prompt and reopen it.
  8. In the command prompt, run pip install --egg "scons<3.0.0" to install scons (a python package)
  9. Wait for the installation of the windows-build-tools to complete. Afterwards, you can perform the remaining steps.
  10. Clone this repository and the change directory into it
  11. Run npm install to build iotivity-node.
  12. After the successful completion of the above command, you are ready to use iotivity-node. You can use the usual npm process of adding iotivity-node to the dependencies section of your package's package.json file.

After installation using the steps above, you may want to run the iotivity-node test suite. To do so, perform the following steps from the iotivity-node repository root. The steps apply to all platforms:

  1. Run npm -g install grunt-cli
  2. Run grunt test

The file appveyor.yml provides an example of the commands necessary for setting up a Windows environment, and the file .travis.yml provides an example of the commands necessary for setting up the Linux and OSX environments.

In more detail:

iotivity-node depends on iotivity proper. It has been tested against 1.3.0. The above installation instructions cover the dependencies for both iotivity-node and iotivity.

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:

  1. Grab a snapshot of iotivity from its git repository and unpack it locally.

  2. Make sure a build toolchain, scons (a build tool), and the headers for the above-mentioned library dependencies are installed. Your distribution should provide all these tools and libraries.

  3. cd iotivity

  4. If you're building against version 1.3.0 of iotivity on OSX or Windows, you will first need to apply all the downstream patches which iotivity-node provides in the patches/ subdirectory except the patch which removes the boost dependency. The latter patch serves only to improve build time by eliminating the ability to build targets which require boost. You can apply the patches with git apply <path-to-patch>. All these patches except the boost elmination patch are on track to appear in later versions of iotivity, so they will disappear from later versions of iotivity-node.

  5. 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 targets you need for the node.js bindings are octbstack and json2cbor if you are building in SECURED=1 mode. Thus, run scons SECURED=1 json2cbor octbstack to build these targets or scons octbstack if you do not require SECURED=1 mode.

    On OSX you need more targets than just octbstack and json2cbor because on that platform iotivity does not build octbstack 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:

    • c_common
    • coap
    • connectivity_abstraction
    • logger
    • ocsrm
    • octbstack
    • routingmanager

  6. Now that iotivity is built, clone this repository and change directory into it.

  7. 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 variable 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.

  8. Run npm install with these environment variables set.

Provisioning and device ID persistence

The high-level JS API provides a means for persisting the device ID across instantiations of a script according to the iotivity wiki. This mechanism is also responsible for initially creating the configuration file that stores security-related information for a given script. 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.dat. 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, and using the json2cbor tool. The tool is located in iotivity-installed/bin off the root of this repository, or, if you have chosen to build iotivity externally, then in the output directory created by the iotivity build process.

Examples

The JavaScript examples are located in 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 and especially multicast traffic) on the machine(s) where these applications are running.