Chapter 5

5 The Home Control Centre: Open Remote

We will start our project with the installation and configuration of OpenRemote. OpenRemote is a state of the art open source software platform for building automation and device control. It has been used for smart building and Internet of Things (IoT) projects around the world, and is supported by a large and active user community. Setting up and configuring the software is a bit more complex than clicking a few buttons, however you do not need programming skills. Still, the platform will allow you to build a fully custom, professional building control system, including a smartphone app, which will serve as the mobile control centre. The OpenRemote controller, which is supported on OS X, Linux, Windows and other platforms, will run the “always on” automation rules for our project.

All OpenRemote components with their full functionality are available free for private use, educational purposes and trials. Commercial users pay a one time fee of 150 US$. A former differentiation between a free and a pay for version was removed in early 2016. Since then, all users – private, educational and commercial – use the identical software.

5.1 OpenRemote Overview 

The OpenRemote platform consists of three software components:

  • The OpenRemote Controller, an always-on (24/7) Linux, Windows or OS X server application, which connects the mobile control devices (smartphones, tablets) to building automation systems and devices under control. Control devices can be building infrastructure (light switches, power outlets etc.), consumer electronic devices, or home appliances. The OpenRemote Controller can also run scripts, which are called rules. These rules are automation sequences, which are implemented based on the open Drools event processing language.
  • The second component consists of the OpenRemote mobile clients for iOS or Android. Graphical user interface and functionality of the OpenRemote App can be fully customized using the third component of OpenRemote, the OpenRemote Professional Designer.
  • OpenRemote Professional Designer is an online, cloud based application, providing a graphical user interface for crafting the mobile client interface and the related commands, sensors, and switches. Once user interface and control functions are designed, the Professional Designer configuration files are synchronized with the local controller installation. The smartphone client application is updated automatically, when connecting to the controller, immediately reflecting changes or updates made within the online Professional Designer project.

OpenRemote supports a large variety of building automation protocol standards. In addition, it provides API’s for the customization and extension of its capabilities. The current software release OpenRemote Controller 2.6 supports the following control protocols (Table 5.1).

1-Wire Protocol Low data rate communication bus for Maxim Integrated Products. www.maximintegrated.com
AMX Controller AMX Inc. proprietary device control protocol.
DateTime Protocol Display of date and time, including sunrise/sunset calculation.
Denon Serial AVR Protocol Protocol to control Denon / Marantz audio / video/ devices.
Domintell Protocol for Domintell building control infrastructure.
DSC IT-100 Serial Protocol Protocol for DSC (Digital Security Controls) systems.
EnOcean Energy harvesting wireless technology for device control ISO/IEC 14543-3-10. www.enocean.com
GlobalCache Infrared control devices by specialist GlobalCache. www.globalcache.com
HSC Z-WAVE IP Gateway Honeywell Z-Wave Gateway.
HTTP Hypertext Transfer Protocol
HTTP/MJEPEG Motion JPEG Video Streaming
HTTP/REST Representational State Transfer. Usage of HTTP for stateless client-server communication
Insteon Home automation system based on power line and radio frequency (RF). www.smartlabsinc.com
Integrated Control Technology (ICT) Protocol for the Protege Suite, an enterprise level building automation system
ISY-99 Control protocol for Universal Devices home automation solution.
Keene IR Anywhere Protocol Proprietary protocol to transmit Infrared (IR) Control Commands over IP or RS232
KNX International standard for industry grade wireline home automation. www.knx.org
Lutron HomeWorks Protocol for Lutron building control infrastructure.
Open Webnet Remote control protocol for Legrand My Home systems
panStamp Lagarto Open source protocol for PanStamp wireless modules. www.panstamp.com
Philips Hue Protocol HTTP/REST API to communicate with Philips Hue bridge devices
Russound RNET Protocol Protocol for distributed audio and video solutions from Russound.
Samsung TV Remote Protocol Protocol used to control Samsung TV systems.
Shell execution protocol Execution of shell scripts.
Shell execution protocol Execution of shell scripts.
TCP/IP Transmission Control Protocol
Telnet Telnet Protocol
UDP User Datagram Protocol
Velbus Protocol for Velbus home automation products www.velbus.eu
Wake-On-Lan Protocol Protocol activating networked systems in power save mode.
X10 Legacy standard for power line based home automation.
XBMC Open source media player platform. xbmc.org
xPL,IRTrans, VLC, FreeBox, MythTV Commercial and OpenSource home automation solutions.
Z-Wave Wireless communication protocol optimized for home automation. www.z-wavealliance.org

 Table 5.1 Communication protocols and automation standards supported by OpenRemote 

With its intuitive user interface, OpenRemote allows for designing a fully customizable building and home control solution without the need to actually write code. This is not to say that home automation is becoming as easy as an off the shelf software installation. With components from different vendors having to play together, there will often be the need for iterations of testing, troubleshooting, and fine-tuning. However, with OpenRemote, we have a powerful platform at hand, which allows for professional results and comprehensive functionality. In addition, the large and helpful OpenRemote user community of building automation professionals and home automation hobbyists provide help and support.

5.2 OpenRemote Controller Installation 

Getting OpenRemote downloaded, installed, and running should take less than one hour. First we need to register for an OpenRemote account. Open https://designer.openremote.com/login.jsp and select Don’t have an account?, then Order Now. Fill out the fields for email and address. If you are a private or educational user, or if you want to trial the software as a company, on the right hand side of the window, under Order Summary, select Add Coupon and enter PRIVUNIV. Then select APPLY , which reduces your order total to 0 US$, then select SUBMIT YOUR ORDER (Figure 5.1).

5.1 Setting up a free account ProfDesigner account

Figure 5.1 Setting up a free account for OpenRemote Professional Designer

With the user name and password, which you will receive in an email after registration, you login to your new account at https://designer.openremote.com/login.jsp. A window with the OpenRemote Professional Designer GUI will open. Now you can install OpenRemote Controller. Select the Download Resources button at the upper right corner of the user interface, and a GitHub window with the latest binary and source code files for OpenRemote Controller will open (Figure 5.2). In the section of the most recent release (at the time of this writing 2.6) you go to Downloads and select the file OpenRemote_Controller.zip.

5.2 Downloading the OpenRemote Controller

Figure 5.2 The OpenRemote Professional Designer GUI with the Download Resources button

After downloading the compressed file, which has a size of around 30 Mbytes, move it to a local project directory (e.g. shproject) under your home directory and extract it. You will now see the directory tree of the software with the startup files openremote.sh (OS X, Linux) and openremote.bat (MS Windows) in the /bin directory (Figure 5.3).

Under Windows, as as well as under OS X, the home directory is the one you are in when opening a terminal window. To make moving around directories from a terminal window easier, you should rename the top level OpenRemote directory, which is called something like OpenRemote-Controller-2.6.0 to something  simpler such as ORC260.

5.3 OpenRemote Controller Directories

Figure 5.3 The OpenRemote Professional Designer directory tree

Since OpenRemote Controller is a Java application, before you are actually able to start it, you need to install Java on your computer. I will cover this in separate sections for OS X and Windows. If you are working under Windows move on to section 5.4 now.

5.3 Java Installation and Configuration under Mac OS X

On a Mac you start by opening an OS X Terminal window selecting Applications – Utilities. If you have not worked with the terminal application before, there are a few commands you need to know in order to survive at the beginning:

ls -l display listing with the option – l (l for long), displays the content of the current directory, including hidden files and permissions
ls -a display listing with the option -a also shows hidden files (e.g. all files starting with a period such as .bash profile are hidden)
pwd print working directory – displays the path of the current directory
cd .. change directory followed by a space and two dots – gets us one directory hierarchy up
cd just typing cd gets us back to our home directory
cd /target changes to the specified directory
mkdir name create (make) directory
man mdc show the manual entry for a command

Table 5.1 Basic OS X Terminal commands

First you need to verify if you have Java installed. To do this use the command

java -version

On a new Mac, you will not find Java installed, because since version 10.8 it is no more part of OS X. In response to the above command OS X will alert you that you need to download Java in order to execute this command. If you select more information in the alert window, you will be taken to to the Oracle Java website. There you select JDK Download, and after accepting the Oracle License Agreement you can download and install the JDK version for Mac OS X. While you will not conduct Java development work, just installing the Java Runtime Environment (JRE) is not sufficient for the instructions to follow and for the integrated rules environment Drools. So do install  the JDK (Java Development Kit) package and not the JRE (Java Runtime Environment) software.

When you now open System Preferences on your Mac, you will see a Java icon, the Java Control Panel. If you select General and About the Java version you have installed is being displayed (Figure 5.4).

5.4 Java Control Panel

Figure 5.4 The Java Control Panel on Mac OS X

If you are using Safari as your browser, make sure to also enable Java by selecting Preferences and Security. Then open Plug-in Setttings… and add Java to the list of approved Plug-ins. You will now be able to verify your installed Java version with Safari using the link https://www.java.com/en/download/installed.jsp.

Apple also offers a legacy Java version (Java 1.6 http://support.apple.com/kb/DL1572) for download from its support website, which was the last Java version, officially supported by Apple. There are still some older OS X applications out, which do require this legacy version, however in most cases going with the latest Java version from Oracle is the best choice, which today is also being recommended by Apple on its Java support page. Since controller version 2.6 and higher Open Remote includes the latest Drools version (6.4) and is fully compatible with the latest Java release, which at the time of this writing is 1.8.

After the successful installation of the JDK you can verify the installed version using the java -version command. The JDK will report the version number of its integrated JRE environment:

java version “1.8.0_25″

Java(TM) SE Runtime Environment (build 1.8.0_25-b17)

Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

5.3.1 Setting $JAVA_HOME on a Mac

There is one more thing we need to do before we can start the OpenRemote controller, which is setting the $JAVA_HOME variable. $JAVA_HOME is used by Java programs to find the path of the Java files and needs to contain the full path to the Java installation.

Under OS X and Linux, the list of locations or paths, which a program uses to search for executables, is stored in the $PATH variable. There is a system wide and a user specific $PATH definition. We will just use the user specific $PATH variable at this point. The user specific $PATH definitions under OS X are contained in the file .bash_profile file in the user home directory. The (hidden) file .bash_profile might not exist yet in your home directory, which is why you probably will need to create it. To list the hidden files in your home directory use the command ls -a. Then enter the following two commands in the terminal window:

touch ~/.bash_profile

open ~/.bash_profile

You can enter the tilde character (~) by typing alt N. The command touch along with a filename creates an empty file and the command open plus a filename opens the specified file in the default text editor, which on a Mac is TextEdit. Now you need to add the line that sets $JAVA_HOME to contain the directory of your JDK installation. The best way to do this is to use the command java_home, which automatically returns a path suitable for the $JAVA_HOME environment variable. The command can be found in the directory /usr/libexec/. If you open a Terminal window, move to /usr/libexec/ and enter the command ./java_home, you will get something like:

/Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home

With that the entry for the file .bash_profile using java_home looks like the following:

export JAVA_HOME=$(/usr/libexec/java_home)

You enter the above line and save .bash_profile in TextEdit, close the terminal window and open it up again (which forces the system to process the new $PATH definition), and test your work by entering echo $PATH and echo $JAVA_HOME.

$JAVA_HOME

-bash: /Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home: is a directory

5.3.2 Starting OpenRemote Controller for the First Time

The OS X start script for OpenRemote Controller is openremote.sh in /shProject/ORC260/bin/. When we do a long listing (ls -l) of the files in the ORC260/bin/ directory we can see that we do not have the execution right for the file yet. In case you are new to file permissions: File permissions in OS X and Linux are set in three groups (owner, group, everyone) with three symbols for each group receiving permissions. The symbols can contain:

- no permission
r read permission
w write permission
x execute permission

Table 5.2 File permissions under OS X

The first letter of the file listing is not a permission, but shows whether the line entry references a file (-) or a directory (d). So the permissions start actually at the second letter of the below listing:

ls -l ./shProject/ORC260/bin

total 48

-rw-r–r–@  9854 10 Mar 2016 openremote.bat

-rw-r–r–@  12039 10 Mar 2016 openremote.sh

We see that we have only read and write rights for openremote.sh. With the command chmod +x we can set the execution rights:

chmod +x ./shProject/ORC260/bin/openremote.sh

and can now start the OpenRemote controller by entering:

./openremote.sh run

The dot slash sequence references to the current directory in Unix type systems. For security reasons it is not part of the $PATH definition. So for commands to be executed in the current directory you always have to start with dot slash (./).

In the terminal window, you will now see a lot of text running by, which eventually will stop, displaying something like

INFO: Server startup in 3159 ms

Your OpenRemote Controller is now up and running for the first time.

5.3.3 Curly or straight, this is the question!

Finally, before you get started with scripting or entering terminal commands, an important hint. Quotation marks in scripts and terminal commands have an important function. However, the quotes used need to be the straight quotation marks, rather than the curly quotation marks, which are used by word processor software. It can happen, that when you copy a command line from a text document or when you edit a shell script or an AppleScript using TextEdit or another word processor, that the straight quotes are converted to curly quotes resulting in runtime errors, which at first sight are hard to detect. So always take a close look at the quotation marks. I will repeat this hint several more times throughout the book, since it is a common problem for people not so close to software development, working along a book. Mac users can now move on to section 5.5.

5.4 Java Installation and Configuration under Windows

Also under MS Windows (XP/7/8/10) at first you need to make sure you have a Java Development Kit (JDK) package installed. To find out if you have an installation on your computer, select Start – Control Panel – Add or Remove Programs. If you do not have Java installed, you need to download the JDK package from the Oracle Java website. After installing the JDK determine the exact directory path of your Java installation. It should be something like

C:\Program Files\Java\jdk1.8.0_45\

Next go to the Windows menu for environment variables. Open System in Control Panel. (or simply type advanced system in the search bar). Open the Advanced tab, select Environment Variables. Select New to add a new variable name and value. Enter JAVA_HOME as variable name and the path to your Java directory. Be very careful to make no mistakes when setting the environment variable. The controller will not start up if the environment variable does not point to the correct directory. With the command set from a terminal window you can validate the settings of your environment variable:

set

JAVA_HOME=C:\Program Files\Java\jdk1.8.0_45

To open a terminal window under Windows 10 simply type command in the search bar. Now you can start up the controller for the first time. In the terminal window change to the directory /shProject/ORC260/bin/ and enter openremote.bat run

You will now see a lot of text running by, which eventually will stop displaying something like:

INFO: Server startup in 3159 ms

Your OpenRemote controller is now up and running for the first time.

5.5 First Synchronization between Designer and Controller

Now you need to validate your installation and synchronize the local controller installation with your online Designer account for the first time. First access the controller web interface by opening the URL http://controller-machine-IP:8688/controller in an Internet browser window. For the part of this URL, which says controller-machine-IP, you insert the IP address of the hardware, your controller is running on. If you run the controller on your local machine, the IP address you need to use is simply 127.0.0.1 or localhost, in which case you open the URL http://localhost:8688/controller.

5.5 alternativ ControllerSynchwolinking

Figure 5.5 The OpenRemote Professional Designer controller synchronization window

Now the OpenRemote Professional Designer controller synchronization window will open, showing the MAC address of your controller hardware in the upper half of the window. Ignore the message Use Controller management in OpenRemote designer to create link. Controller management will be activated in a later release of OpenRemote Controller and provide auto detection of the controller IP address. For now directly proceed by entering your Professional Designer login details, and select the button Sync with Online Designer (Figure 5.5). A few seconds later the synchronization window will show the message Sync complete (Figure 5.6).

5.6 Controller Synch Complete

Figure 5.6 Successful synchronization between an OpenRemote Professional Designer Account and a local controller

5.5.4 The Importance of Systematic Directory and File Management

A last advice before we move on. I recommend to place all custom scripts and files, which you develop throughout this project, in the root directory of your project (in our case the directory shProject), rather than in the OpenRemote directory (in our case ORC260). Otherwise you will have to manually move your custom scripts and files from your old to your new OpenRemote installation in case of a software upgrade, which then might become a source of problems.

5.6 OpenRemote Professional Designer 

We now will take a closer look at our OpenRemote Professional Designer account. We open https://designer.openremote.com/login.jsp and log into our Designer account. The Designer GUI consists of two main elements. The Building Modeler and the UI Designer. The Building Modeler (Figure 5.7) is used for defining commands, sensors, switches and sliders, and for selecting and configuring the associated protocols. In the UI Designer, we create the graphical user interface for our smartphone or tablet control app, linking its functional elements to the commands in the Building Modeler. (Figure 5.8).

5.7 Building Modeler Icon

Figure 5.7 Selecting the Building Modeler

5.8 UI Designer Icon

Fig. 5.8 Selecting the UI Designer

5.7 The “Hello World” App 

As a first step and in order to understand the workflow of OpenRemote we want to display “Hello World” on our smartphone or tablet. For that in the UI designer window we click on New –New Panel, select our mobile device (Android, iPhone, iPad) and enter our project name (e.g. shome), as the name under panel property on the right hand menu bar. The default name for the screen, which is Starting Screen, we rename to Remote. Next, from the right hand menu, we drag an abc label element onto the smartphone panel and enter Hello World in its text field on the right hand side of the GUI. As the last step, we click on the save button in the upper left corner. Our OpenRemote UI Designer screen should now look similar to the one in Figure 5.9.

5.9 First Steps with Designer Hello World

Figure 5.9 First steps with OpenRemote Professional Designer

5.10 Downloading the OpenRemote App

Figure 5.10 Downloading the OpenRemote client app for iOS

Now we download the mobile client app, the OpenRemote Panel, onto our tablet or smartphone. Do not get confused by multiple OpenRemote client versions. You need the one which is described as: “Universal version of the OpenRemote 2 console” (Figure 5.10). When you start the OpenRemote app for the first time, it opens with a configuration screen. Later, access to the configuration screen is gained by shaking the phone (Figure 5.11). For the time being leave Auto Discovery mode deactivated and manually set the IP address of your computer hosting the controller. To find your Mac’s IP address under OS X it is easiest to open the Network Utility application. To find it, simply enter the term Network Utility in the Mac Spotlight search.

Under Windows you open a terminal window and type

ipconfig /all

To configure the controller IP address you now enter the IP address of your computer followed by 8688/controller in the configuration screen of your OpenRemote app. The entry should look similar to http://192.168.178.41:8688/controller.

5.11 The OpenRemote app’s configuration screen

Figure 5.11 The OpenRemote app’s configuration screen (shake phone for access) 

Next, at the bottom of the configuration screen, select the Panel Identity of your Designer layout, which in our case is shome. The app now automatically connects to your local Open Remote Controller and retrieves the application you just designed on your OpenRemote Professional Designer account. Make sure to synchronize your local controller with your OpenRemote Professional Designer account after every change of your Designer project. You should now see the “Hello World” message on your smartphone or tablet app.

In case you see an error message from the client app or the OpenRemote controller such as controller.xml not found or panel.xml not found, don’t panic. These files (controller.xml, panel.xml) are only downloaded to your local controller and your smartphone client after the first synchronization with your OpenRemote Professional Designer account. You probably have not synchronized Designer and Controller yet. Make sure to synchronize Designer and Controller again by opening up

http://localhost:8688/controller

and clicking on Sync with Online Designer. The controller will then connect to your online OpenRemote Professional Designer account and synchronize with the latest changes to your project. The local copy of your design will be updated in the file panel.xml in the directory ../shProject/ORC260/webapps/controller/. After a restart of your smartphone app, you should finally see “Hello World” on the screen of your smartphone.

Congratulations!

Since you now have successfully installed and configured the home automation control platform for our project, we can get started with the implementation of our first feature.