Since quite some time my home automation is build around a core app made in Java EE. As part of this challenge I’m improving the core and integrating it more tightly through MQTT. The core is responsible for coordinating all nodes and enforcing the business rules for our home.

Introduction

Thuis ArchitectureThe Thuis core runs on the Raspberry Pi 3 in a WildFly container. Like all nodes it’s connected to the MQTT broker for communication with the rest of the system. It also takes care of communication with some external applications, like Plex (media server) and Netatmo (weather station). In this blog I’ll focus on the integration of MQTT, Z-Way devices and the rules.

The building blocks of the application are as follows:

  • Model:
    • Devices
    • Rooms
    • Scenes
    • Rules
  • Commands
  • Controller
  • MQTT-CDI

Each of these will be described in this blog. Currently all models and rules are defined as static objects in Java code, the goal is to put this in the database at some point and make it editable through a UI, that will however be after the challenge ends.

Device Model

The two base models are Device and  Room. To be combined with  Device there are different types of Actuator and Sensor. The following image and table show the interfaces. There are several implementations, for example there is  MqttSwitch which implements Device and  Switch and defines a switch which can be controlled through MQTT.

Device, Actuator and Sensor class diagram

Interface Description
Device General definition of a (virtual) device: an identifier and it's status (type will be overridden by more specific interfaces)
Actuator A device with controls
Switch
extends Actuator
A switch with on/off and toggle features
Dimmer
extends Switch
A switch which also has can have values between 0 and 100, where 0 is off
Thermostat
extends Switch
A thermostat supporting a set point for the temperature. It can be turned on/off, which will put it on predefined on and off temperatures
Sensor A device that provides a (single) value of a sensor
BinarySensor
extends Sensor
A sensor with a value that can be true or false
MultilevelSensor
extends Sensor
A sensor with an arbitrary value and a configurable unit of measurement

All devices are virtual devices, each with a single function. For example a sensor that can measure both temperature and trigger on movement will be implemented as two sensors: a MultilevelSensor and a BinarySensor.

In this blog post we’ll describe two of our rooms: the living room and the kitchen. This gives us the following definitions:

Command Model

As you might have noticed in the interfaces above, several methods return Command. A command is a runnable class that can be executed to fulfill a task, for example turning on a Switch with Switch.on(). For each type of command there is an implementation. The one used most by the devices defined above is the MqttCommand which publishes a MQTT message, so for example Z-Way will receive it and take action. The implementation is quite straight forward:

Command class diagram

Commands can be encapsulated in other commands. By encapsulating you can either compose several commands into a single one, or add a condition to the command. The following commands of this type exist:

Command Description
ConditionalCommand  A command that executes the encapsulated command when a certain condition is met. The condition is defined using a Predicate lambda. Three default conditions are available:
illuminance – shortcut for predicates based on illuminance, for example execute when illuminance is below 100lux
whenOn/ whenOff – execute a command when a given device is turned on/off
ListCommand execute several commands in order
PrioritizedCommand execute a command with a different priority, for example USER_INITIATED: the highest priority which will let the command jump in front of the execution queue
WaitForCommand wait for a condition to be true before executing another command. Two default conditions are available: waitForOn and waitForOff which wait for the status of a device to turn on or off before executing another command

Another way of combining commands is using a Scene. This is an object that contains two ListCommand, one for activating the scene and one for deactivating it. A scene for turning on and off the mood lighting in the living room is defined like:

Observing MQTT messages

The Core observes MQTT messages arriving on basically any topic. It then checks if there are any devices (or better ObserveMqttStatus implementations) matching this topic. The status of these devices is then updated. When a sensor gets a new value an event is emitted. These events (and individual MQTT messages) can triggered rules. This all happens in the MqttObserverBean. This bean also takes care of updating the status of any scenes or rooms including this device.

The connection with the MQTT broker is handled by the MQTT-CDI extension made by Alexis Hassler, to which I contributed some improvements in the past. This CDI extension abstracts the actual connection away. When MQTT messages arrive on a subscribed topic they are fired as CDI events which can be observed using the @MqttTopic annotation. This way you can very easily observe any messages arriving:

For publishing messages a service method is available.

Rules

To enable sensors (or other events) to trigger commands there are rules. A rule is an Observer of either an MQTT topic or a  SensorChanged event. As result one or more commands are executed. An example of a rule is the following:

This example covers most of the basic options. It observes the movement sensor in the kitchen. When it’s status becomes  true and it’s not very light it will check 3 timeframes. Depending in which timeframe the current time fits a combination of lights is turned on. This way you always have the most useful lights for the task ahead. The timing might need some optimization, but this is a good start.

Controller

Taking care of the actual execution of commands and scenes are the Controller and the CommandExecutor. Take the example rule above: it triggers several lights to be turned on or off. These commands are passed on to the controller. The controller takes the command, determines it’s priority and then puts it on a JMS queue:

(for the purpose of this blogpost the code is simplified a bit)

A JMS MessageListener, the CommandExecutor, is used to listen to the commands which are added to the queue and execute them. Because of the way the JMS queue works, commands are executed in chronological order while respecting the priorities. This means that all commands with the same priority are executed exactly in order they were added (FIFO), but when a command of a higher priority is added to the queue it’s moved in front. This is used for situations where for example the home theater is starting up (which takes a few minutes in total) and someone triggers a motion sensor. This command gets the USER_INITIATED priority and is therefore executed at the first possible moment, in front of all other steps of starting up the home theater. Something that’s not time sensitive (for example automatically turning off the heating at night) gets a LOW priority and will therefore never block any more important commands.

Some commands can take a long time and you don’t want them to block the queue. For example a WaitForCommand takes until the condition becomes true. In this case the condition is tested once and when the result isn’t true yet the command is added to the queue again with a small timeout.

Concluding

The most important part of the Core is now done, but most rules still have to be implemented. In a later stage some more external systems will be added to the core, for example for controlling the Home Theatre. I’m also aware that, to keep this blog post from growing too much, I have simplified some code samples and didn’t cover every detail. If you’re interested in a certain detail, please let me know and I’ll explain it more!

Core v2: A Java EE application
Tagged on:                 

3 thoughts on “Core v2: A Java EE application

Leave a Reply

Your email address will not be published. Required fields are marked *