PicoGW

Japanese document

PicoGW is a Home Automation and Building Automation devices gateway server, developed by Kanagawa Institute of Technology, Smart House Research Center, released under MIT license. PicoGW converts protocols between device-specific ones and our REST/WebSocket API.

Since this is implemented by simple node.js, it works on various unix-based platforms including Linux, MacOS, Windows (using Bash on Ubuntu on Windows), Android (using Termux), and FreeBSD.

New trial feature! IPv6 ECHONET is now possible by enabling IPv6 from echonet plugin's setting dialog. Now you can access smart meters!

Installation

The following command installs PicoGW and all necessary plugins, with one addition of echonet lite plugin.

$ npm install -g picogw

Note that a part of our system prefers npm global install be executed without sudo. For this reason, we strongly recommend to use nvm (Node Version Manager) to install node.

Other plugins installation

$ npm install -g picogw-plugin-XXXX

XXXX : plugin name.

Running

$ picogw

with API port number

$ picogw -p 12345 

By default, dynamic files are written into ~/.picogw directory. If you want to change the directory, copy config.json.sample to config.json and modify the ingredient. config.json is read from picogw root directory by default. if you want to load from the different location, you can also specify the path by picogw argument.

$ picogw -c /path/to/config/file.json 

Supplying plugin-specific argument:

$ picogw --plugin-arg-myplugin A=B

If you supply multiple arguments for a plugin, use the option multiple times.

$ picogw --plugin-arg-myplugin A=B --plugin-arg-myplugin C=D

Public plugins

• admin, web, db (mandatory, automatically installed)
• macro : Runs JS codes. Automatically installed.
• echonet : ECHONET Lite is home automation protocol that supports more than 100 kinds of home applicances. Automatcally installed.
• openweathermap : OpenWeatherMap is a weather db and forecasting API
• slack
• healbe : Acccess GoBe's coud API. GoBe is a wearable device developed by Healbe.

Documents

Partial documents in Japanese.

How to develop your own PicoGW plugin in Japanese. No English documents yet..sorry.

Remarks

• Even if your Linux has multiple network interfaces, ECHONET Lite communication is available for only one of them. It is because NetworkManager (the tool we use to setup network configuration) sets only one default gateway (which is used for ECHONET Lite multicasting) per machine. By default, NetworkManager sets wired Ethernet as the default gateway network interface. If no wired ethernet connection is available, wlan0 (or other wireless network) will become the default.

Web API

The Web API hosted by PicoGW is a developing version of Housing API by Daiwa House Industry. The API design is mainly done by Shigeru Owada@Kanagawa Instuitute of Technology. If you have any criticisms, requests, or questions, please feel free to post your opinion to the Issues page.

Design concept

The concept of this API is as follows:

1. Simple and easy. The API basically follows the concept of REST. At the same time, we tried not to be too strict to the concept. The API can violate the conceptual correctness to achieve easiness. For example, our PubSub model is implemented as a new method of REST.
2. Extensible. The API should support the forthcoming IoT devices without drastically changing the basic calling styles. We adopt plugin architecture to achieve this.
3. Independent from device-specific operations. This is our goal. /v1/ API is really device-dependent, but we try to develop /v2/ API as device-independent one.

Calling convention

The API call is a simple HTTP access to the PicoGW server's 8080 port by default. The result is always given as a JSON object. Most APIs exist under /v1/ (The root / access shows the control panel.)

API directory

The API has a directory structure as follows. The directories right under root (admin / echonet) are the name of plugins. This can increase if new plugin is added to the system.

The structures under a plugin name is a responsibility of the plugin. However, each subdirectory API follows the rule that the resulting JSON object contains further subdirectory name or leaf node name (which is associated with a function).

PubSub

Connection-based API transports (named pipe and websocket) support PubSub model.

Subscribe

Send the following JSON to the transport. (wildcard is not supported now)

{"method":"SUB","path":"/v1/echonet/airConditioner_1/operatingstate"}

Then a value change is asynchronously notified by a PUB JSON object.

Unsubscribe

{"method":"UNSUB","path":"/v1/echonet/airconditioner_1/operatingstate"}

API payloads

API payloads are defined by each plugin. Please refer to each plugin's README.

Licenses

MIT

Browser
JSON Editor
jsTree
jQuery
jQuery UI
marked
spin.js

npm
arped
body-parser
botkit
echonet-lite
express
inpath
ipmask
mime
node-localstorage
opts
pidof
ping
read
sudo

Apache 2

npm
websocket

No license

cryptico