Automation modules

Gregory Sitnin edited this page Sep 27, 2013 · 4 revisions

Automation Module package consists of two files, in minimum: index.js which is a particular module class definition and module.json which is a meta-definition of an automation module. Both files must be in the same folder named exactly as the module's class and places into the modules/ subfolder. In addition, module package can consists of any number of scripts, resources and so on.

module.json

Module meta-definition used by the AutomationController. Must be a valid JSON object with this field (all of them are required):

  • autoload — Boolean, defines will this module automatically instantiated during Home Automation startup.

  • autoloadPriority — (optional) Integer, defines automatic module instantiation order (lower -- sooner, default is 1000).

  • skip — (optional) Boolean, if true, module will not be automatically loaded if autoload is set.

  • singleton — Boolean, defines this module can be instantiated more than one time or not.

  • defaults — Object, default module instance settings. This object will be patched with the particular config object from the controller's configuration and resulting object will be passed to the initializer.

Configuration fields are required (if otherwise isn't pointed directly). Types of the object must equals definition in every case. For instance, if module doesn't export any metric corresponding key value should be and empty object “{}”.

index.js

This script defines an automation module class which is descendant of AutomationModule base class.

During initialization, module script should define a variable _module which must reget the particular module class.

Example of a minimal automation module

function SampleModule (id, controller) {
    SampleModule.super_.call(this, id, controller);
}

inherits(SampleModule, AutomationModule);
_module = SampleModule;

SampleModule.prototype.init = function (config) {
    SampleModule.super_.prototype.init.call(this, config);
}

First part of the code illustrates how to define class function named SampleModule which should call superclass' constructor.

It is highly recommended not to initialize module instance inside the constructor. It should work completely and return a new instance regardless of environment state. It is absolutely correct to create an instance variables and fill them with the default values.

The second part of the code is almost immutable for any module. It calls prototypal inheritance support routine and fills in _module variable.

The last (third) part of the sample code defines module's init() method which is an instance initializer. This initializer must cal superclass's initializer prior to all other tasks.

In the initializer module can setup it's private environment, subscribe to the events and do any other stuff.

Sometimes, whole module code can be placed withing the initializer woithout creation of other class's methods. As the reference of such approach you can examine AutoOff module source code.