/thingweb.node-wot

thingweb.node-wot

Primary LanguageTypeScriptOtherNOASSERTION

Eclipse Thingweb node-wot

W3C Web of Things implementation on NodeJS

Build Status

License

Dual-licensed under both

Pick one of these two licenses that fits your needs. Please also see the additional notices and how to contribute.

Prerequisites

All systems require:

  • NodeJS version 8+ (e.g., 8.11.3 LTS)
  • NodeJS version 10+ will not require certain polyfills, but is not LTS (long-term stable)

Linux

Meet the node-gyp requirements:

  • Python 2.7 (v3.x.x is not supported)
  • make
  • A proper C/C++ compiler toolchain, like GCC

Windows

Install the Windows build tools through a CMD shell as administrator:

npm install -g --production windows-build-tools

Mac OS

Meet the node-gyp requirements:

xcode-select --install

How to get ready for coding

Clone the repository:

git clone https://github.com/eclipse/thingweb.node-wot

Go into the repository:

cd thingweb.node-wot

Install root dependencies (locally installs tools such as typescript and lerna):

npm install

Use tsc to transcompile TS code to JS in dist directory for each package: Note: This step automatically calls npm run bootstrap.

npm run build

Optional

Link Packages

Make all packages available on your local machine (as symlinks). You can then use each paket in its local version via npm link <module> instead of npm install <module> (see also https://docs.npmjs.com/cli/link).

sudo npm run link

(On Windows omit sudo)

Link Local wot-typescript-definitions

To evolve the Scripting API in development, you need to use a locally changed version of the wot-typescript-definitions. Use npm link for this as well:

git clone https://github.com/thingweb/wot-typescript-definitions.git
cd wot-typescript-definitions
sudo npm link

(On Windows omit sudo)

In each node-wot package, link the local version made available in the previous step:

sudo npm link wot-typescript-definitions

(On Windows omit sudo)

Trouble shooting

  • Build error around node-aead-crypto
    • node-gyp has been seen failing on MacOS
    • try node 10+, which does not require the crypto polyfill
  • sudo npm run link does not work
    • try npm run unlock before calling [sudo] npm run link
    • try npm link in each package directory in this order: td-tools, core, binding-*, cli, demo-servients

No time for explanations - I want to start from something running!

Run all the steps above including "Link Packages" and then run this:

wot-servient -h
cd examples/scripts
wot-servient

Without the "Link Packages" step, the wot-servient command is not available and node needs to be used (e.g., Windows CMD shell):

# expose
node packages\cli\dist\cli.js examples\scripts\counter.js
# consume
node packages\cli\dist\cli.js examples\scripts\counter-client.js

How to use the library

This library implements the WoT Scripting API:

You can also see examples/scripts to have a feeling of how to script a Thing.

Protocol Support

  • HTTP ✔️
  • HTTPS ✔️
  • CoAP ✔️
  • CoAPS ✔️
  • Websocket ➕ (server only)
  • MQTT ➕ (in dev branch)

Note: More protocols can be easily added by implementing ProtocolClient, ProtocolClientFactory, and ProtocolServer interface.

MediaType Support

  • JSON ✔️
  • Plain text ✔️
  • CBOR ✖️

Note: More mediaTyes can be easily added by implementing ContentCodec interface.

Logging

We used to have a node-wot-logger package to allow fine-grained logging (by means of Winston). It turned out though that depending on the actual use-case other logging libraries might be better suited. Hence we do not want to prescribe which logging library to use. Having said that, we use console statements which can be easily overriden to use the prefered logging library if needed (see here).