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|
|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).
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.
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.
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
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).
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:
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:
With that the entry for the file .bash_profile using java_home looks like the following:
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.
-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
-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:
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
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:
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.
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).
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).
Figure 5.7 Selecting the Building Modeler
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.
Figure 5.9 First steps with OpenRemote Professional Designer
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
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.
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
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.
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.