Repository files navigation

ThingsJS is a framework for running JavaScript applications on IoT devices such as Raspberry PIs

• NOTE: This repository is currently under active development and its contents are subject to breaking changes.

/bin/docs/lib    /core    /util/util    /dashboard/samples

This repository is organized thus:

1. bin contains thethings-js CLI (shell script) that is installed with the package. Also contains default config files.
2. docs contains the API documentations generated by JSDoc.
3. lib contains the core ThingsJS code
   1. core contains the main ThingsJS objects such asCode,CodeEngine,Pubsub,Dispatcher.
   2. util contains general-purpose utility modules used in the system.
4. util contains supplementary apps and debug tools
   1. dashboard contains the ThingsJS Dashboard application; it is anexpress web-application
5. samples contains raw JavaScript sample code (non-instrumented) that can be dispatched to ThingsJS workers.

• The ThingsJS framework uses MQTT Pub/Sub as its main communication mechanism and assumes the existence of an active MQTT service. EitherMosquitto, orMosca will do. ThingsJS provides a basic Mosca server that can be started withthings-js pubsub command. The Pub/Sub service is referenced only by the URL (e.g.mqtt://localhost) within the ThingsJS framework and does not assume any specific implementation of the service.

~$ things-js pubsub

• For running the Dashboard web-application,MongoDB is required as the Dashboard uses it to store the end-user code.

~$ service mongod start

For trying out the framework, you can follow the steps below:

1. git clone this repository

~$ git clone https://github.com/DependableSystemsLab/ThingsJS.git

2. npm install -g to install the package. (download all the npm dependencies and link the CLI tool)You may need to putsudo depending on your installation of NodeJS.You need the-g (global installation) option for using the CLI. If you don't plan on using the CLI, you can omit the-g option.

~$ cd ThingsJS~/ThingsJS$ npm install -g

1. Install via npm

~$ sudo npm install -g things-js

You may omit thesudo depending on your NodeJS install settings.

Along with the API provided, CLI is included for easy use.Here are some of the commands:* things-js pubsub* things-js dashboard* things-js worker {config}* things-js instrument {code}You can find the full list of commandshere.

1. To start the Dashboard Application:

~$ things-js dash#OR~$ things-js dashboard

By default it connects to MQTT atlocalhost:1883, MongoDB atlocalhost:27017/things-js-fs, and listens onlocalhost:3000.To start the dashboard with a different configuration, you can use the-c or--config options with the config file path provided as an argument.e.g.

~$ things-js dash -c my_config.conf

This will start a web-application served at the specified port.You can watch the demo of the Dashboard here:

Click Image to see Demo Video

2. Running a ThingsJS worker:

To start a ThingsJS worker, first you need to create a directory that will provide the NodeJS environment. This is because the worker needs to have a reference to thethings-js module and any other npm modules that a ThingsJS user (developer) may require. If the worker cannot find a link to anode_modules directory, it will throw an error.

~$ mkdir hello_things~$ cd hello_things~$ npm link things-js#create a config file for the worker first (e.g. node_00.conf) ~/hello_things$ things-js worker node_00.conf

The configuration file is a required argument for starting the worker. It should contain the following information:

{    "pubsub_url": "mqtt://localhost",    "id": "node_00",    "device": "raspberry-pi3"}

3. To instrument raw JavaScript code into a "ThingJS-compatible" code:

~$ things-js inst my_code.js#OR~$ things-js instrument my_code.js

By default the output file will have the same file name, with the extension.things.js.To specify the output file name, provide the optional argument with-o or--output.e.g.

~$ things-js inst my_code.js -o my_code.instrumented.js

MIT