Skip to content

Latest commit

 

History

History
128 lines (74 loc) · 4.23 KB

README.md

File metadata and controls

128 lines (74 loc) · 4.23 KB
Raw

WHIMS

(Web Hyperspace Interface via MQTT over SockJS)

This project provides a web interface to a MQTT service. It also supplies a module for creating "things" that interact over MQTT.

A browser or other SockJS client communicates to a MQTT server over standard HTTP/1.1 protocols. The topic structure, messages and payload format are specified in the Meemplex specifications (to be announced).

At this point in time, JSON is used as payload format. e.g. { "value" : 2398, "unit" : "W", "timestamp" : "2013-09-13T13:49:39.000Z" }

The intention is that this can provide a gateway for "things" (e.g. devices, browsers, servers) to communicate with other things over standard web protocols.

This service provides the ability to add a layer of security to things communicating with the MQTT server.

How to Run

The server is implemented in Node.js and depends on a few external modules.

###Get Required Node.js Modules

> npm install

###Configure

Update setting.js to point configure the port for the web server to listen on and the connection details of your MQTT server.

Configuration for the UI is in html/ui.json. This specifies filters for determining which widgets to display on the screen as well as the set of widgets to display.

In the future, the widgets displayed will be determined by a "hyperspace category" which will relate to an MQTT topic.

###Optimise

To compile the client-side javascript app.

> ./node_modules/requirejs/bin/r.js -o app.build.js

This will optimise and bundle client files in the public-build folder. If you run the app with NODE_ENV=production file will be served from this directory.

###Run

Make sure an MQTT server is running on the host and port specified in settings.json.

To run, type the following in the root of the project

> npm start

or

> node whims.js

or

> nodemon

to automatically re-load the server after code changes, or

> forevever start whims.js

to start the server on the background.

Then navigate to

http://localhost:8000/

or if you are running on a different server or changed the "port" value in the configuration

http://yourhost:yourport/

TODO

Lifecycle: pass on health of subscribed topics. Track via last-will-and-testament of MQTT and lifecycle messages.

Hyperspace: maintain a hierarchy of categories corresdonding to topics

Security: subscribe and publish to only those topics that are allowed to the client.

Storage: for editing and storing widgets for devices of interest.

Web interface to

  • navigate categories and "things"
  • configure UI to "things"
  • register users
  • share topics

Instructions for setting up nginx reverse proxy allowing for websockets.

Credits

Node.js

Express web application framework for node.

mqtt.js MQTT module for Node.js.

SockJS for both server and client side of web communications.

Socket.IO for both server and client side of web communications (previous versions of Whims).

RequireJS for asynchronous module loading and for compiling/optimising (using r.js).

jQuery

Backbone and Underscore

EventEmitter2 replicating Node's EventEmitter behaviour on client-side.

Data-Driven Documents (D3) for graphs.

JS-quantities SI unit conversion.

Isotope for dynamic Javascript layout. This requires a license if you are to use it for commercial purposes.

iScroll for better scrolling with touch devices (no bounce-backs).

Jade for server page generation and client-widget templating.

Simplefly for icons on the demonstration UI.