Create Virtual Command

evasmolders edited this page Jan 15, 2017 · 15 revisions
Clone this wiki locally

In memory Virtual Commands are used to create virtual devices which help to control your home automation system. Amongst others, they can be used to construct abstract analog and binary sensors which reflect the present state of your system. Their major role is in the connection between OpenRemote and the rule engine Drools.

Create new Device

In "Building Modeler", create new device (New>New Device)

In this description we create one singular device that can be switched on/off. (Note: One could equally well define multiple virtual switches, sliders and sensors to control one device. For example a dishwasher.)

Create Command

The most basic function of the Virtual Command protocol is to create an in-memory key-value pair storage (a Map in java talk). The address is the key under which to store the value. It may only contain letters. The command property is "usually" the value that will get stored at the given address (unless when the command is linked to a sensor, then the value is not stored but read back and it is advised to use 'status' as the command). The value stored is usually the command property, except when:

  • the command is used as the set value of a slider, then the slider value is stored
  • the command is called from a rule, using the execute() method, with 2 parameters. In that case, the second parameter is used as the value to store.

Still in "Building Modeler", select the device that was created in step 1 and click on New>New Command Specify a name and select "In-memory Virtual Command" as protocol.

At the moment there are three basic commands to choose from : on, off, and status. Always use lower case for the commands!

Starting with Pro 1.2.0 release, any string can be used as a command, not only those 3 values. Any string besides those 3 is simply stored as the value at that address, similar to the behaviour of the execute() command within rules.

Next to these basic commands, the In memory Virtual Command needs an Address to be specified. The addresses must be unique for a device. So if you want to create a virtual binary switch you need to define respectively on, off, and status commands which all share the same address. In this example switcha. For further switches define addresses as switchb, switchc, ...

Nota Bene: a specific address can be shared by multiple commands that even are part of different devices. A binary switch is a typical example where the address must be shared. In principle several status commands (even from different devices) may share one single address as well. Be aware of unpredictable situations!

Create Sensor

Next use the status command to configure a sensor.

The status command associated to on/off commands needs to have a sensor of type:switch to make binary switches.

Create Switch

On the basis of the so far defined commands and sensor you configure a virtual binary switch as shown in the image below.

Virtual command for non binary devices

These Virtual Commands are also useful to set the value of variables. For example the time in hours when a certain event has to take place. In such cases you only need to configure a status command. Do make sure each of these commands does have a unique address! So again in "Building Modeler" configure a status command that can hold a deadline value. No further commands are needed as the value can be set with a slider, or via a rule.

Next configure a Sensor of type:range, which will make it possible to create a slider for this. Choose the range 0-24.

Other status commands can have a sensors of type:level (fixed range 0-100), or of type:custom. With rules, specific data types conversions can be done on custom type values (see Rules).

Use of in memory commands in rules

The following rule sets the deadline value on 17 as soon as the virtual binary switch is turned to on.

package org.openremote.controller.model.event

global org.openremote.controller.statuscache.CommandFacade execute;
global org.openremote.controller.statuscache.SwitchFacade switches;
global org.openremote.controller.statuscache.LevelFacade levels;
import org.openremote.controller.protocol.*;

rule "Set DeadlineHour"
when
  Switch(source == "SensorVirtualSwitch1", value == "on")
then
  execute.command("DeadlineHourValue", 17);
end

See also