Home automation engine
Posted: 24 Sep 2013 04:16
We know that all of you are waiting for Home Automation engine with impation. We are working to make it real! But please do not be too excited before we have finished. So far it is more for geeks that for real life.I'll describe three concepts of Home Automation we are developing. Most of you will use the third one, but some will still use the low level approach.Low level work with Z-Way JS APIThis approach is based on direct access to zway object and usage of bind() calls on each dataholder. Here is an example:Z-Way.JS tricks
// Blink with some devices (flashStart() to start blinking, flashStop() to stop)
var flashTmr = null;
var flashStart = function () {
if (flashTmr) clearTimeout(flashTmr);
flashTmr = setInterval(flashBlink, 5 * 1000)
}
var flashStop = function () {
clearTimeout(flashTmr);
zway.devices[4].SwitchBinary.Set(255);
zway.devices[3].SwitchMultilevel.Set(20);
zway.devices[14].SwitchMultilevel.Set(20);
zway.devices[20].SwitchMultilevel.Set(20);
}
var flashBlink = function () {
zway.devices[4].instances[1].SwitchBinary.Set(zway.devices[4].instances[1].SwitchBinary.data.level.value ? 0 : 255);
zway.devices[3].SwitchMultilevel.Set(zway.devices[3].SwitchMultilevel.data.level.value ? 0 : 99);
zway.devices[14].SwitchMultilevel.Set(zway.devices[14].SwitchMultilevel.data.level.value ? 0 : 99);
zway.devices[20].SwitchMultilevel.Set(zway.devices[20].SwitchMultilevel.data.level.value ? 0 : 99);
}
// All Off on Fob double click 1 and Dimmer 3 double click (will come as MultichannelAssociation to controller instance 2)
zway.devices[1].instances[2].Basic.data.level.bind(function() {
if (this.value == 0) {
zway.devices[4].SwitchBinary.Set(0);
zway.devices[3].SwitchMultilevel.Set(0);
zway.devices[7].instances[1].SwitchBinary.Set(0);
zway.devices[9].SwitchMultilevel.Set(0);
zway.devices[14].SwitchMultilevel.Set(0);
zway.devices[20].SwitchMultilevel.Set(0);
}
});
// Alarm on Fob double click 2(on)/4(off) (will come as MultichannelAssociation to controller instance 4)
zway.devices[1].instances[4].Basic.data.level.bind(function() {
if (this.value > 0)
flashStart();
else
flashStop();
});
// Auto Off
var autoOff4 = null;
zway.devices[4].instances[1].SwitchBinary.data.level.bind(function() {
if (autoOff4)
clearTimeout(autoOff4);
if (this.value > 0)
autoOff4 = setTimeout(function() {
zway.devices[4].instances[1].SwitchBinary.Set(0)
}, 30*1000);
});
// Smooth dimming on Wall Controller double click (will come as SceneActivation)
zway.devices[11].instances[0].SceneActivation.data.currentScene.bind(function() {
if (this.value == 12) {
zway.devices[14].SwitchMultilevel.Set(0, 129); // With Duration
zway.devices[20].SwitchMultilevel.Set(0, 129); // With Duration
}
});
// Scenes on Wall Controller click (will come as 1:5. Direct associations are with 14 an 20)
var sceneState = 0;
zway.devices[1].instances[5].Basic.data.level.bind(function() {
if (this.value)
switch(sceneState) {
case 0:
case 3:
sceneState = 1;
zway.devices[14].SwitchMultilevel.Set(30);
zway.devices[20].SwitchMultilevel.Set(30);
break;
case 1:
sceneState = 2;
zway.devices[14].SwitchMultilevel.Set(0);
zway.devices[20].SwitchMultilevel.Set(30);
break;
case 2:
sceneState = 3;
zway.devices[14].SwitchMultilevel.Set(30);
zway.devices[20].SwitchMultilevel.Set(0);
break;
}
else
sceneState = 0;
}); Of course this code needs to be placed in a file and executed from main.js (or even placed in main.js itself). On startup Z-Way executes main.js contained in the folder listed under automation-dir tag in config.xml. This approach is extremely flexible, but quite hard to extend and share with others.Modules based usage of Z-Way APIThis approach is way better, since separates different functions into modules. Modules are easy to share and extend. Z-Way is shipped with module system. Advanced users can write their own modules and/or modify existing.New module should be placed in automation/modules folder. Each module consist of a folder named exactly as the module's class and at last two files inside: index.js and module.json.index.js must contain the declaration of the module object (in this example BatteryPolling, stored in the folder also called BatteryPolling), some mandatory lines to register the object and init prototype. function BatteryPolling (id, controller) {
// Call superconstructor first (AutomationModule), do not remove this line
BatteryPolling.super_.call(this, id, controller);
// From here you can write your own constructor
}
// This is needed to correctly register the module
inherits(BatteryPolling, AutomationModule);
_module = BatteryPolling;
// This is initializer function, called for each instance of the module with a specific config for the particular instance
BatteryPolling.prototype.init = function (config) {
// Call superclass' init (this will process config argument and so on), don't remove this line
BatteryPolling.super_.prototype.init.call(this, config);
// From here modules specific code
this.controller.emit("cron.addTask", "batteryPolling.poll", {
minute: 0,
hour: 0,
weekDay: this.config.launchWeekDay,
day: null,
month: null
});
// Setup event listener
this.controller.on('batteryPolling.poll', function () {
for (var id in zway.devices) {
zway.devices[id].Battery && zway.devices[id].Battery.Get();
}
});
};
One can see that this module dirrectly access to zway object to make polling of batteries charge values.module.json contains module metadata and default configuration. singleton means that the module can be instanciated only once, autoload can instruct Home Automation engine to load it at startup (even if not listed in the list of instances in config.json) {
"autoload": true,
"singleton": false,
"defaults": {
"launchWeekDay": 0,
"warningLevel": 20
}
} Here we are not only introducing a specification how to write modules, but also provide "events" system: a way to emit and trap different events.Event is named by a string (event name), which should be specified as <module_name>.<event_name>. Any module can trap events with any name using controller.on() call and emit them using controller.emit() call. Each module is supposed to provide (emit) some events and to listen (subscribe) events. Each event can be accompained by some additional parameters.Using this even system we have implemented all releations between modules. For example cron module listens for cron.addTask event and set up scheduler. As a parameters this event contains schedule definition and event name to fire periodically. The callee is supposed to listen for these events and perform some task once triggered by scheduler (in our example it is batteryPolling.poll).Module based system with Virtual DevicesWe understand, that direct access to Z-Way API is cool, but too difficult to make own home automation system flexible.To make life easier we provide Virtual Devices concept. A Virtual Device can be generated based on Z-Wave device, some other data (wheather or finantial quotes) or even in future from another Home Automation protocol such as X10/EnOcean/KNX/....Let's look on another module called AutoOff. It is supposed to turn off a device after it was turned on.function AutoOff (id, controller) {
// Call superconstructor first (AutomationModule), do not remove this line
AutoOff.super_.call(this, id, controller);
// From here you can write your own constructor
// Create instance variables
this.timer = null;
}
// This is needed to correctly register the module
inherits(AutoOff, AutomationModule);
_module = AutoOff;
// This is initializer function, called for each instance of the module with a specific config for the particular instance
AutoOff.prototype.init = function (config) {
// Call superclass' init (this will process config argument and so on), don't remove this line
AutoOff.super_.prototype.init.call(this, config);
// From here modules specific code
// Check VirtualDevice existence
if (!this.controller.devices.hasOwnProperty(this.config.device)) {
// Exit initializer due to lack of the device
console.log("ERROR", "AutoOff Device", this.config.device, "doesn't exist.");
return;
}
var device = this.controller.devices[this.config.device];
// Check if device is a switch
if ("switch" !== device.deviceType) {
// Exit initializer due to invalid device type
console.log("ERROR", "AutoOff Device", this.config.device, "isn't switch", "("+device.deviceType+").");
return;
}
// Remember "this" for detached callbacks (such as event listener callbacks)
var self = this;
// Setup metric update event listener
this.controller.on('metricUpdate.'+this.config.device, function (metric, value) {
if ("level" === metric) {
if (self.timer) {
// Timer is set, so we destroy it
clearTimeout(self.timer);
}
if (255 === value) {
// Device reported "on", set (or reset) timer to new timeout
// Notice: self.config.timeout set in seconds
self.timer = setTimeout(function () {
// Timeout fired, so we send "off" command to the virtual device
// (every switch device should handle it)
device.performCommand("off");
// And clearing out this.timer variable
self.timer = null;
}, self.config.timeout*1000);
}
}
});
};controller.devices is a list of all Virtual Devices registered in our engine. Usually hey are named like ZWavDev_6:0:38. Don't care much about the name, but take in mind that the name can help you to find the real deivce ID in Z-Wave network. String 6:0:38 in the name means ID 6, instance 0, Command Class 38 (Switch Multilevel). But this is just an internal name and MUST NOT be used to get real Z-Wave ID using parsing of this string.Each Virtual Device will receive metricUpdate event on it's values change. As a parameter it's value is passed. You can also call performCommand() on the Virtual Device to turn it on/off. Full list of available commands will be published soon. This list depends on Virtual Device type, stored in deviceType and deviceSubType properties of Virtual Device object.The configuration for such a module would look like the code below. The name of the Virtual Device can be obtained from the new UI (we print it temporary for convenience) or in logs. "config": {
"device": "ZWayVDev_6:0:38",
"timeout": 3
}
On startup a lot of Virtual Devices are created: for each device capability. sensors, switches, dimmers, thermostats, ... all provide it's own Virtual Device.Note that the new UI is based on Virtual Devices only! It has no idea about Z-Wave internals, all widgets are rendered based on Virtual Devices. In future we will demonstrate how to make your own widget in the UI based on own Virtual Device.How to configure modules?All configuration of modules is done from a single place: automation/config.json file. Here is a typical content:{
"controller": {
"modules": [
"EventLog",
"ZWaveGate",
"Cron",
"BatteryPolling",
"AutoOff",
"CustomUserCode",
"BasicReactions"
],
"instances": {
"EventLog" : {
"module": "EventLog",
"config": {}
},
"ZWave" : {
"module": "ZWaveGate",
"config": {
"basicsEnabled": true
}
},
"BasicReactor": {
"module": "BasicReactions",
"config": {
"map": [
{
"channel": 1,
"level": 255,
"reactions": {
"tempOn": {
"vDev": "ZWayVDev_6:0:38",
"timeout": 5
}
}
},
{
"channel": 3,
"level": 255,
"reactions": {
"tempOn": {
"vDev": "ZWayVDev_3:0:37",
"timeout": 3
}
}
}
]
}
}
}
}
}Modules part contains the list of all modules to load. This part will disappear soon: modules will be scanned from automation/modules folder and automatically loaded. Instences part contains the list of instance for each module you want. Some modules MUST be instanciated to make the whole subsystem to work: EventLog, ZWave. Some are optional, like Cron, AutoOff. The name of the instance can be any (make sure to have different names for different instances - these never appears in any place). Module name is refered in module parameter, while config parameter defines individual parameters for each instance.In next release we are planing to add visial editor for this config.json file, so you will not need anymore to edit it manually using vi
Which way to choose for you?We believe that the most efficient way is to use Virtual Devices approach. But for some small and straightforward tasks direct access to Z-Way JS API is way better. You can even mix both approaches without any problem.Run custom codeInstead of altering the content of main.js file to run your own code we propose a CustomCode module. It just requires one parameter with the list of files to execute. These files will be executed during Home Automation engine startup. We suggest to move all custom code into separate files and execute it form here.Get more infoPlease check sources and documentation on GitHub.Also have a look on user manual and developers guide.ParticipateWe welcome everyone to contribute to this project. Source codes of Home Automation engine are available on GitHub. You are free to write your own modules and commit them bak into GitHub. Make pull requests if you feel your feature to bee cool and important for our project!See more about your commitment on https://github.com/Z-Wave-Me/home-autom ... stallation.
// Blink with some devices (flashStart() to start blinking, flashStop() to stop)
var flashTmr = null;
var flashStart = function () {
if (flashTmr) clearTimeout(flashTmr);
flashTmr = setInterval(flashBlink, 5 * 1000)
}
var flashStop = function () {
clearTimeout(flashTmr);
zway.devices[4].SwitchBinary.Set(255);
zway.devices[3].SwitchMultilevel.Set(20);
zway.devices[14].SwitchMultilevel.Set(20);
zway.devices[20].SwitchMultilevel.Set(20);
}
var flashBlink = function () {
zway.devices[4].instances[1].SwitchBinary.Set(zway.devices[4].instances[1].SwitchBinary.data.level.value ? 0 : 255);
zway.devices[3].SwitchMultilevel.Set(zway.devices[3].SwitchMultilevel.data.level.value ? 0 : 99);
zway.devices[14].SwitchMultilevel.Set(zway.devices[14].SwitchMultilevel.data.level.value ? 0 : 99);
zway.devices[20].SwitchMultilevel.Set(zway.devices[20].SwitchMultilevel.data.level.value ? 0 : 99);
}
// All Off on Fob double click 1 and Dimmer 3 double click (will come as MultichannelAssociation to controller instance 2)
zway.devices[1].instances[2].Basic.data.level.bind(function() {
if (this.value == 0) {
zway.devices[4].SwitchBinary.Set(0);
zway.devices[3].SwitchMultilevel.Set(0);
zway.devices[7].instances[1].SwitchBinary.Set(0);
zway.devices[9].SwitchMultilevel.Set(0);
zway.devices[14].SwitchMultilevel.Set(0);
zway.devices[20].SwitchMultilevel.Set(0);
}
});
// Alarm on Fob double click 2(on)/4(off) (will come as MultichannelAssociation to controller instance 4)
zway.devices[1].instances[4].Basic.data.level.bind(function() {
if (this.value > 0)
flashStart();
else
flashStop();
});
// Auto Off
var autoOff4 = null;
zway.devices[4].instances[1].SwitchBinary.data.level.bind(function() {
if (autoOff4)
clearTimeout(autoOff4);
if (this.value > 0)
autoOff4 = setTimeout(function() {
zway.devices[4].instances[1].SwitchBinary.Set(0)
}, 30*1000);
});
// Smooth dimming on Wall Controller double click (will come as SceneActivation)
zway.devices[11].instances[0].SceneActivation.data.currentScene.bind(function() {
if (this.value == 12) {
zway.devices[14].SwitchMultilevel.Set(0, 129); // With Duration
zway.devices[20].SwitchMultilevel.Set(0, 129); // With Duration
}
});
// Scenes on Wall Controller click (will come as 1:5. Direct associations are with 14 an 20)
var sceneState = 0;
zway.devices[1].instances[5].Basic.data.level.bind(function() {
if (this.value)
switch(sceneState) {
case 0:
case 3:
sceneState = 1;
zway.devices[14].SwitchMultilevel.Set(30);
zway.devices[20].SwitchMultilevel.Set(30);
break;
case 1:
sceneState = 2;
zway.devices[14].SwitchMultilevel.Set(0);
zway.devices[20].SwitchMultilevel.Set(30);
break;
case 2:
sceneState = 3;
zway.devices[14].SwitchMultilevel.Set(30);
zway.devices[20].SwitchMultilevel.Set(0);
break;
}
else
sceneState = 0;
}); Of course this code needs to be placed in a file and executed from main.js (or even placed in main.js itself). On startup Z-Way executes main.js contained in the folder listed under automation-dir tag in config.xml. This approach is extremely flexible, but quite hard to extend and share with others.Modules based usage of Z-Way APIThis approach is way better, since separates different functions into modules. Modules are easy to share and extend. Z-Way is shipped with module system. Advanced users can write their own modules and/or modify existing.New module should be placed in automation/modules folder. Each module consist of a folder named exactly as the module's class and at last two files inside: index.js and module.json.index.js must contain the declaration of the module object (in this example BatteryPolling, stored in the folder also called BatteryPolling), some mandatory lines to register the object and init prototype. function BatteryPolling (id, controller) {
// Call superconstructor first (AutomationModule), do not remove this line
BatteryPolling.super_.call(this, id, controller);
// From here you can write your own constructor
}
// This is needed to correctly register the module
inherits(BatteryPolling, AutomationModule);
_module = BatteryPolling;
// This is initializer function, called for each instance of the module with a specific config for the particular instance
BatteryPolling.prototype.init = function (config) {
// Call superclass' init (this will process config argument and so on), don't remove this line
BatteryPolling.super_.prototype.init.call(this, config);
// From here modules specific code
this.controller.emit("cron.addTask", "batteryPolling.poll", {
minute: 0,
hour: 0,
weekDay: this.config.launchWeekDay,
day: null,
month: null
});
// Setup event listener
this.controller.on('batteryPolling.poll', function () {
for (var id in zway.devices) {
zway.devices[id].Battery && zway.devices[id].Battery.Get();
}
});
};
One can see that this module dirrectly access to zway object to make polling of batteries charge values.module.json contains module metadata and default configuration. singleton means that the module can be instanciated only once, autoload can instruct Home Automation engine to load it at startup (even if not listed in the list of instances in config.json) {
"autoload": true,
"singleton": false,
"defaults": {
"launchWeekDay": 0,
"warningLevel": 20
}
} Here we are not only introducing a specification how to write modules, but also provide "events" system: a way to emit and trap different events.Event is named by a string (event name), which should be specified as <module_name>.<event_name>. Any module can trap events with any name using controller.on() call and emit them using controller.emit() call. Each module is supposed to provide (emit) some events and to listen (subscribe) events. Each event can be accompained by some additional parameters.Using this even system we have implemented all releations between modules. For example cron module listens for cron.addTask event and set up scheduler. As a parameters this event contains schedule definition and event name to fire periodically. The callee is supposed to listen for these events and perform some task once triggered by scheduler (in our example it is batteryPolling.poll).Module based system with Virtual DevicesWe understand, that direct access to Z-Way API is cool, but too difficult to make own home automation system flexible.To make life easier we provide Virtual Devices concept. A Virtual Device can be generated based on Z-Wave device, some other data (wheather or finantial quotes) or even in future from another Home Automation protocol such as X10/EnOcean/KNX/....Let's look on another module called AutoOff. It is supposed to turn off a device after it was turned on.function AutoOff (id, controller) {
// Call superconstructor first (AutomationModule), do not remove this line
AutoOff.super_.call(this, id, controller);
// From here you can write your own constructor
// Create instance variables
this.timer = null;
}
// This is needed to correctly register the module
inherits(AutoOff, AutomationModule);
_module = AutoOff;
// This is initializer function, called for each instance of the module with a specific config for the particular instance
AutoOff.prototype.init = function (config) {
// Call superclass' init (this will process config argument and so on), don't remove this line
AutoOff.super_.prototype.init.call(this, config);
// From here modules specific code
// Check VirtualDevice existence
if (!this.controller.devices.hasOwnProperty(this.config.device)) {
// Exit initializer due to lack of the device
console.log("ERROR", "AutoOff Device", this.config.device, "doesn't exist.");
return;
}
var device = this.controller.devices[this.config.device];
// Check if device is a switch
if ("switch" !== device.deviceType) {
// Exit initializer due to invalid device type
console.log("ERROR", "AutoOff Device", this.config.device, "isn't switch", "("+device.deviceType+").");
return;
}
// Remember "this" for detached callbacks (such as event listener callbacks)
var self = this;
// Setup metric update event listener
this.controller.on('metricUpdate.'+this.config.device, function (metric, value) {
if ("level" === metric) {
if (self.timer) {
// Timer is set, so we destroy it
clearTimeout(self.timer);
}
if (255 === value) {
// Device reported "on", set (or reset) timer to new timeout
// Notice: self.config.timeout set in seconds
self.timer = setTimeout(function () {
// Timeout fired, so we send "off" command to the virtual device
// (every switch device should handle it)
device.performCommand("off");
// And clearing out this.timer variable
self.timer = null;
}, self.config.timeout*1000);
}
}
});
};controller.devices is a list of all Virtual Devices registered in our engine. Usually hey are named like ZWavDev_6:0:38. Don't care much about the name, but take in mind that the name can help you to find the real deivce ID in Z-Wave network. String 6:0:38 in the name means ID 6, instance 0, Command Class 38 (Switch Multilevel). But this is just an internal name and MUST NOT be used to get real Z-Wave ID using parsing of this string.Each Virtual Device will receive metricUpdate event on it's values change. As a parameter it's value is passed. You can also call performCommand() on the Virtual Device to turn it on/off. Full list of available commands will be published soon. This list depends on Virtual Device type, stored in deviceType and deviceSubType properties of Virtual Device object.The configuration for such a module would look like the code below. The name of the Virtual Device can be obtained from the new UI (we print it temporary for convenience) or in logs. "config": {
"device": "ZWayVDev_6:0:38",
"timeout": 3
}
On startup a lot of Virtual Devices are created: for each device capability. sensors, switches, dimmers, thermostats, ... all provide it's own Virtual Device.Note that the new UI is based on Virtual Devices only! It has no idea about Z-Wave internals, all widgets are rendered based on Virtual Devices. In future we will demonstrate how to make your own widget in the UI based on own Virtual Device.How to configure modules?All configuration of modules is done from a single place: automation/config.json file. Here is a typical content:{
"controller": {
"modules": [
"EventLog",
"ZWaveGate",
"Cron",
"BatteryPolling",
"AutoOff",
"CustomUserCode",
"BasicReactions"
],
"instances": {
"EventLog" : {
"module": "EventLog",
"config": {}
},
"ZWave" : {
"module": "ZWaveGate",
"config": {
"basicsEnabled": true
}
},
"BasicReactor": {
"module": "BasicReactions",
"config": {
"map": [
{
"channel": 1,
"level": 255,
"reactions": {
"tempOn": {
"vDev": "ZWayVDev_6:0:38",
"timeout": 5
}
}
},
{
"channel": 3,
"level": 255,
"reactions": {
"tempOn": {
"vDev": "ZWayVDev_3:0:37",
"timeout": 3
}
}
}
]
}
}
}
}
}Modules part contains the list of all modules to load. This part will disappear soon: modules will be scanned from automation/modules folder and automatically loaded. Instences part contains the list of instance for each module you want. Some modules MUST be instanciated to make the whole subsystem to work: EventLog, ZWave. Some are optional, like Cron, AutoOff. The name of the instance can be any (make sure to have different names for different instances - these never appears in any place). Module name is refered in module parameter, while config parameter defines individual parameters for each instance.In next release we are planing to add visial editor for this config.json file, so you will not need anymore to edit it manually using vi
Which way to choose for you?We believe that the most efficient way is to use Virtual Devices approach. But for some small and straightforward tasks direct access to Z-Way JS API is way better. You can even mix both approaches without any problem.Run custom codeInstead of altering the content of main.js file to run your own code we propose a CustomCode module. It just requires one parameter with the list of files to execute. These files will be executed during Home Automation engine startup. We suggest to move all custom code into separate files and execute it form here.Get more infoPlease check sources and documentation on GitHub.Also have a look on user manual and developers guide.ParticipateWe welcome everyone to contribute to this project. Source codes of Home Automation engine are available on GitHub. You are free to write your own modules and commit them bak into GitHub. Make pull requests if you feel your feature to bee cool and important for our project!See more about your commitment on https://github.com/Z-Wave-Me/home-autom ... stallation.