What is Domapic?
Domapic is an open source home automation system. It is developed using Node.js, and distributed through NPM, and anyone with a minimum knowledge in these technologies should be able to install it and make it work on his own local network.
It is based on small microservices at charge of simple tasks. All microservices communicates with a central Controller using REST protocol. The Controller provides a web interface for controlling all of them, and making them interact ones with anothers through automatic tasks defined on it.
The system is easily extensible installing or developing new microservices at charge of new accessories, or even Controller plugins. Microservices controlling accessories in the system could be developed using any other technology apart of Node.js (as long as the API interface is respected), but, for the moment, only a Node.js package is provided as a base.
The Domapic Controller, by default, never sends information outside your local network (unless you explicity install accessories or plugins performing requests to external services). It can work completely disconnected from the Internet.
A plugin is available to provide remote access to your Domapic Controller. The cloud-domapic-plugin connects to your Controller and sends to the Domapic Cloud service information about the email addresses of your users, and your current external IP address. This information is never used for any purpose different to allow you and your users connect remotely to the Controller, and, of course, it will never be shared with third parties.
How does Domapic work?
Three main pieces conform the system: Controller, Accessories and Plugins:
Each independent piece, or microservice, expose a RESTful API interface in order to communicate with the other ones. Each one includes its own authentication, storage, proccess management, etc.
Accessories and plugins are intended to communicate directly only with the Controller (even though it is possible to consume directly their api, using correspondant api-keys)
Accessories are the pieces making the important tasks in a Domapic system, such as switching on a relay, emitting an event when the wheather changes, etc. Each accessory should be only at charge of a single and simple task in order to mantain the system scalable. Interactions between accessories (what we call "Automatisms") can be defined using the Controller Web Interface.
We will call "Ability" to this single task that an accessory is capable to do (for example, switching on a relay).
Each ability has its own API interface, which consists of:
- State: Returns the current state of the ability (the relay is currently ON/OFF)
- Action: Performs an specific action (switches on the relay)
- Event: Sends information to the Controller about changes in the ability state (the relay state has changed from ON to OFF)
Actions, states and events can receive and send data, which type is defined in the ability definition and validated in every request (for example, our relay example should have a boolean data type defined. It will switch on the relay when receiving true, and will switch off the relay when receiving false). Available data types are boolean, string andnumber, and each one can have its own specific subtypes and validations.
Each accessory should be at charge only of a single task, but that having more than one ability in the same accessory can be very useful. For example, our relay accessory could have one ability for switching on/off the relay, another one for toggling it, and another one for toggling it during a short period of time (emulating a button press).This is not a bad practice at all, so we could say that accessories should be at charge of a single task, but could have different abilities performing that task in different ways.
All accessories are paired with the Controller once they are started. Then, the Controller API acts as a proxy that is able to redirect requests to the correspondant Accessory and Ability.
Users can control all accessories using the Controller web application, where interfaces for all paired abilities are available. A different interface is created for each ability, depending of its data type.
In the image, two examples of ability interfaces where the user can see:
- At the right, the current state of the ability.
- At the bottom, the action buttons, which will be different depending of the ability data type.
The states will be refreshed at real time in the interface, as Accessories send events with the changes to the Controller, and the user interface is connected with the Controller using web sockets.
The interface also includes logs of received events, displays information about paired accessories, allows to manage Controller users, etc.
The Controller includes a role-based users management. Administrator users can create any other type of users, assigning to them an email, user name and password, which can be changed afterwards by users themself once they are logged in.
All communications are secured using JWT, in the case of human users, or Api Keys, in the case of all other system users, such as Accessories, Plugins, etc.
Security can be disabled for an specific range of ips, or for the whole local network, but this is not recommended. By default, it is only disabled for localhost, which make easier to access the first time and setup your administrator user.
All pieces of the system can be started using SSL protocol to improve the security if correspondant certificates are provided. The certificates could be self-signed, as the other pieces can be configured to accept them. Anyway, the unique piece that should be exposed to the Internet is the Controller, and, in that case, using SSL is highly recommended.
Plugins are able to extend the funcionality of the system, connecting it with third-party applications, etc. To do that, they first are paired to the Controller as in the case of Accessories, but plugins also receive events from the Controller. Those events inform continuosly about what is happening in the Controller and in the Accesories, and plugins are also able to send actions to the Controller.
The "homebridge-domapic-plugin", for example, registers automatically all Domapic Accessories as Apple's Homekit Accessories too, making able to control them with Siri, while they are also available at your Domapic Controller interface.
Current release notes
Current beta versions of Domapic packages still are not compliant with some details described in this document:
- "Accessories" are still called "Modules" in current versions.
- Controller Automatisms feature is not released yet. Check the roadmap for further details.