Home Automation and Building Automation Devices Gateway Server
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
bin
lib
res
test
.eslintignore
.eslintrc.json
.gitignore
Device
LICENSE
PluginDevelopment.jp.md
README.md
clearcache.sh
config.json.sample
debug.sh
main.js
package.json

README.md

PicoGW

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.

The old repository will remain public for a while, but not actively maintained any more. It will be deleted soon.

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 

Public plugins

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 basecally 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