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.
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.
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
- 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
- healbe : Acccess GoBe's coud API. GoBe is a wearable device developed by Healbe.
How to develop your own PicoGW plugin in Japanese. No English documents yet..sorry.
- 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.
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.
The concept of this API is as follows:
- 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.
- Extensible. The API should support the forthcoming IoT devices without drastically changing the basic calling styles. We adopt plugin architecture to achieve this.
- 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.
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.)
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).
Connection-based API transports (named pipe and websocket) support PubSub model.
Send the following JSON to the transport. (wildcard is not supported now)
Then a value change is asynchronously notified by a PUB JSON object.
API payloads are defined by each plugin. Please refer to each plugin's README.