# ThingsJS

**Repository Path**: jiang_zeming/ThingsJS

## Basic Information

- **Project Name**: ThingsJS
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-06-29
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThingsJS

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. 


## Directory Structure

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

```
This repository is organized thus:

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


## Dependencies

* The ThingsJS framework uses MQTT Pub/Sub as its main communication mechanism and assumes the existence of an active MQTT service. Either **Mosquitto**, or **Mosca** will do. ThingsJS provides a basic Mosca server that can be started with `things-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
```

## Getting Started

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

### Installation

#### Option 1

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 put `sudo` 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
```

#### Option 2

1. Install via npm
```
~$ sudo npm install -g things-js
```
You may omit the `sudo` depending on your NodeJS install settings.


#### Using the CLI

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 commands [here](https://dependablesystemslab.github.io/ThingsJS/api/CLI.html).


1. To start the Dashboard Application:
```
~$ things-js dash

#OR

~$ things-js dashboard
```
By default it connects to MQTT at `localhost:1883`, MongoDB at `localhost:27017/things-js-fs`, and listens on `localhost: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:

<a href="http://ece.ubc.ca/~kumseok/assets/ThingsMigrate_201811.mp4" target="_blank"><img src="http://ece.ubc.ca/~kumseok/assets/ThingsJS_Migration.png" 
alt="Demo Screenshot" width="427" height="240" border="10" /><p>Click Image to see Demo Video</p></a>


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 the `things-js` module and any other npm modules that a ThingsJS user (developer) may require. If the worker cannot find a link to a `node_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
```


## License

MIT