Installation

Option 1 – Raspberry Pi (Best Option)

This is by far my favorite and the strongly preferred option. This is the only option that supports the ability to update things on the panel in real time when things change. Raspberry Pi single board hobby computers are perfect for projects like HousePanel. This is because they take up very little space, use a small amount of energy, and they are relatively easy to configure. Unlike a dedicated computer, a Raspberry Pi can be neatly tucked away just about anywhere and go un-noticed. To use this option you will need to first of all own a Raspberry Pi and you will need to know how to manipulate it and program it. There are many web tutorials out there that show you how to do this. When you install a rPi for use with HousePanel I recommend that you use a fixed IP address so that you know where to find it every time. This can be accomplished in several ways. The easiest way is to use your router to tell it to give your rPi a fixed IP based on its Mac address. Next you will need to have the Apache web server installed on the rPi. The recipe below will point you in the right direction but if you get stuck please refer to any number of online tutorials about how to set up a rPi and install both Apache and PHP.

Start by either connecting your rPi to a monitor and keyboard, or logging into it remotely using SSH. If you are using a PC I recommend using the “putty” program for SSH. It can be downloaded for free. You may need to first use a monitor and keyboard to enable SSH. Once you are logged into your rPi use the following commands to configure Apache with PHP.

sudo raspi-config
> Interfacing Options > SSH then enable
> Change the default timezone.

I recommend changing the default password from “raspberry” to whatever you want. Then you should “ssh” into your rPi as username = pi and password = your-password modify /etc/defaults/keyboard to be a “us” keyboard and not the default “gb” unless of course you are from the UK.

A new install script is available. To use this, log into your rPI with SSH and enter this:

cd ~ 
wget https://raw.githubusercontent.com/kewashi/HousePanel/master/install.sh
bash ./install.sh

This should configure Apache, PHP, cURL, download HousePanel, set permissions, and restart Apache. Once you do this you should be all set and ready to run HousePanel. The script will also ask you if you already have an active install and if so it will only update your files to the latest version. This is the best way to update HP when new versions are released.

You can also do a manual install following the steps below. To do this, enter the next several lines to install the Apache and PHP applications onto the rPi. For PHP 5 use the following commands:

sudo apt-get update 
sudo apt-get -y upgrade
sudo apt-get -y install apache2 libapache2-mod-php5 php5 php5-gd wiringpi raspi-gpio rpi-update --fix-missing
sudo apt-get -y install curl
sudo apt-get -y install php5-curl
sudo rpi-update

For PHP 7 use the following:

sudo apt-get update 
sudo apt-get -y upgrade
sudo apt-get -y install apache2 libapache2-mod-php php php-gd wiringpi raspi-gpio rpi-update --fix-missing
sudo apt-get -y install curl
sudo apt-get -y install php-curl
sudo rpi-update

Next, you need to confirm that PHP is setup to use cUrl. This should be on by default because of the install lines above, but check php.ini to be sure. Look for your php.ini file and then edit it using nano or vim. Within php.ini search for “curl”. You should find a line that loads the curl library. Sometimes that line is commented out with a “#” in the first column. If your file has this, activate the loading of the curl library by uncommenting that line.

Finally, restart Apache using:

sudo service apache2 restart

Another reason I like the rPI option is because you can run a number of other services on a rPI that enhance the functionality of HousePanel. For example, I have KuKu Harmony and Homebridge both running on my rPI side by side with HousePanel. installing those apps are beyond the scope of this doc.

Option 2 – Dedicated computer on your LAN

This option has great flexibility and speed. It is secure because it runs on your LAN and is typically not exposed to the Internet. Your home router shields all computers from the Internet from outside access unless you bypass that using either DMZ or port forwarding. The disadvantage is you can’t access this server unless you are at home
and on the same network. This can be a big restriction but many people don’t control their smart homes using a panel when they are away, so I personally don’t think this is a major limitation. To use this option you will need to have a web server installed on your dedicated computer, and you will need to leave that computer on at all times that you want the panel to work. Instructions for installing Apache on a dedicated home PC or Mac can be found at http://www.apache.org

You will then need to install PHP on your web server and enable cUrl. Instructions for doing this are beyond the scope of this Wiki. You can find excellent instructions and examples for how to do this all over the Internet. As with the public web server option, you will also need to set the permissions of the directory where you want to install
HousePanel. Since this is a local computer you can do this using standard methods for your local computer. On a PC this involves right-clicking on the directory and setting permissions. But first you will need to create the directory within your web hosting area. For example, make a directory called “housepanel” under c:\htdocs on a standard Apache install. I have not tested HousePanel on IIS but it should work fine.

Option 3 – A public facing hosted web server

This option is perhaps the simplest but has major security issues than the other two options. It will also respond much slower because all commands including polling to keep your panel current requires messages to be sent over the Internet. Using this option is STRONLY DISCOURAGED for these reasons. If you must use this option you should protect your website with some type of security such as a password and a robots file to prevent it from being discovered by search engines. HousePanel now has a simple built in password feature that should help here, but it is not industrial strength so caution should still be exercised with using this option.

To use this option you need to create a directory on the server that hosts your public-facing web pages, such as “housepanel”. For the purposes of this documentation we will assume that the directory name is “housepanel”. You can use any method you like to do this but the easiest is probably using a full-featured FTP program. An important step before proceeding is to set the permissions of that directory to enable write access. How this is done depends a lot on what type of server you are using. Most public web servers are Linux and Apache based in which case you can use chmod 777 on the directory. Some FTP programs will support this, others won’t. You may need to use the file browser function of your web hosting service to change the permissions to “777” which means the owner, groups, and the world can read and write to the folder.

Testing your PHP Web Server

Before proceeding I highly recommend that you test your web server and confirm that it works with PHP and cUrl. To do that load the file phpinfo.php into a browser window. This file is included in the primary repo folder. For example, let’s assume you are using a rPi on static IP address 192.168.1.50 and your HP is installed in /housepanel then you would browse over to: http://192.168.1.50/housepanel/phpinfo.php

If things are working you should see a PHP information page returned. Scroll down and look for a section named cUrl to see if it is activated. The HP distribution files that we will download later includes a phpinfo.php file so if you prefer you can wait and perform this test after uploading the files, in which case you won’t have to worry about creating this file.

If loading this page generates an error, then you know your web server was not installed correctly and it will need to be addressed before you can proceed. Detailed troubleshooting of the install steps for Apache, PHP, and cUrl are beyond the scope of this Wiki but there are ample resources on the web that can help you troubleshoot this and get it working before you proceed.

Installing the HousePanel Groovy Application

The hub application called HousePanel.groovy must be installed on your hub. There used to be separate versions for SmartThings and Hubitat, but now there is only one file. The same file is installed on both hubs. Installation instructions differ for SmartThings and Hubitat. Follow the section below that applies to your hub type. Note that HousePanel works great with both installed side by side. If you have this then follow both sections to install the groovy file on both hubs.

SmartThings SmartApp Installation

Unfortunately I was not able to get the SmartThings IDE option to work with my account so you will have to install this manually. First, open the HousePanel.groovy file from the following GitHub account:

https://github.com/kewashi/HousePanel

With this file open click on the “raw” icon in the upper right corner. This will open a window showing just the “raw” lines of code. Copy the entire file to the clipboard using Control-A or Command-A on mac, then Control-C or Command-C on a mac. Navigate back to your ST IDE at graph.api.smartthings.com. Make sure you are logged in. Then go to the SmartApps section using the top menu. Click on create new SmartApp then select “from code”. In the blank window that opens, paste the code that you copied to the clipboard here using Control-V or Command-V on a mac. Then select Save then Publish “for me”.

If you are an experienced GitHub user you can also feel free to just clone or fork your own copy into your GitHub account and work with it from there. The advantage of this is you can track and manage any local edits you make and GitHub will do all of the work of managing your changes for you as usual. The other advantage of that approach is if you make improvements, you can contribute them to the Open-Dash movement by making a pull request. I would appreciate seeing such community contributions that will of course help make HousePanel get much better over time.

IMPORTANT
Before you leave the ST IDE, you will need to enable OAUTH2 in the IDE app settings. To do this, select App Settings and turn on OAUTH2 in the options. This will reveal two long strings of data called CLIENT_ID and CLIENT_SECRET. These values are important and must be copied and saved for use in the next step when you are configuring your web server.

After you have installed HousePanel.groovy in the IDE, you need to load an instance of the app on your smartphone using the SmartThings app on your smart phone. You must use the legacy SmartThings app to install HousePanel. When you load the app you will be presented with a few options, followed by a list of things to select. You can select them here or you can wait and select them when you authenticate the hub from the main application side.

Hubitat App Installation

If you are a Hubitat user, you will need to install the file HousePanel.groovy into the app section of the Hubitat webpage. Open the HousePanel.groovy file from the following GitHub account:

https://github.com/kewashi/HousePanel

With this file open click on the “raw” icon in the upper right corner. This will open a window showing just the “raw” lines of code. Copy the entire file to the clipboard using Control-A or Command-A on mac, then Control-C or Command-C on a mac. Navigate back to your Hubitat IDE on your local LAN. Create a new App “from code” and name it HousePanel.groovy. In the blank window that opens, paste the code that you copied to the clipboard here using Control-V or Command-V on a Mac. Then select Save.

Before you leave the Hubitat Apps Code page, you will need to enable OAUTH2. To do this, click on the OAUTH button in the upper right corner of the Hubitat IDE page. This will open a window showing two long strings of data called Client ID and Client Secret. These values are important and must be copied and saved for use in the next step when you are configuring your web server.

After you have installed HousePanel.groovy in the Apps Code area, you need to load an instance of the app in the Apps area near the top. When you load the app you will be presented with a few options, followed by a list of things to select. With Hubitat hubs you must select the things you want to include in your dashboard at this time. When you authenticate the hub later, you will only be asked if you want to give permission to HousePanel to access Hubitat. With some Hubitat hub versions you will not be given the option of hanging what things you permit during the authentication step. Newer hubs appear to have fixed this issue so you can select things at either point.

Multiple Hub Considerations

You can install either the SmartThings or Hubitat hub or both of them. They play nice with each other so you can use both together or one or the other. This feature is a great way to make a gradual transition from SmartThings over to Hubitat. As of Version 1.80, any number of Hubitat and SmartThings hubs can be connected to the panel. Hooks are there for Wink and OpenHab support which will come with time. I’m excited about this because I wrote this generally enough to make future hub bindings easy to add. As of this writing, HousePanel has not been tested to work with multiple SmartThings hubs on the same account. Users have reported problems with trying to do this. However, multiple SmartThings hubs on different accounts appear to work fine. Also, multiple Hubitat hubs work properly.

Install PHP Code on Web Server

In this step you will install the PHP application by copying the files from the following GitHub into a directory of your choice. Note that if you used the new install script to set up your rPI, then this step is already done and should be skipped.

    https://github.com/kewashi/HousePanel
    

A typical place to install HP is in its own directory called “housepanel” within your html folder, typically located at /var/www/html. Be sure to preserve the directory structure when you upload the files to your web server. Also, make sure you copy ALL of the files to your web server. The .groovy files, python examples, LICENSE, and README files are not needed but it won’t hurt to have them on your web server as a backup copy, so I would just copy all the files. You also can skip copying the “docs” sub-directory but again, it won’t hurt to be there. If there, you will be able to pull up a local copy of this doc file from your dashboard. If you are using FTP to transfer files, please be sure to use a binary transfer protocol.

Again, you can also fork this to your own GitHub space and then clone it down to your local PC or Mac if you are familiar with using GitHub. If you are using Git on your local PC I recommend this approach since it will allow you to make local edits and pull requests for any improvements you want to be considered. As a bonus, if you are using NetBeans editor that editor talks nicely to Git to tell you what edits have been made using visual cues.

Earlier versions of HousePanel required the creation of a file named “clientinfo.php”. If you have this file in your setup, please delete it as it is no longer used.

Hub Push Node.js Installation

This section describes how to install the optional Node.js hub push middleman feature. You should install the rest of HousePanel and authenticate your hubs before attempting to install this feature. For this feature to work you must have Node and Npm installed. If your server is a rPi, log into it using ssh and enter the following commands to install Node and NPM.

wget http://node-arm.herokuapp.com/node_latest_armhf.deb 
sudo dpkg -i node_latest_armhf.deb

Alternative instructions for installing Node.js and npm are here:

https://www.instructables.com/id/Install-Nodejs-and-Npm-on-Raspberry-Pi/

Regardless of which method you use, you should check to make sure you have Node.js installed properly by running the following command:

node -v

Next, you will configure the app called housepanel-push.js The main GitHub repository contains a version of housepanel-push.js in the housepanel-push sub-folder. To use this you must first configure it using the npm package manager to load all of the required dependencies. Navigate to the housepanel-push subfolder and enter:

npm install

Test your application by running it on the console:

node housepanel-push.js

If successful the app will read your hmoptions.cfg file and report statistics about your setup. If you have not yet installed the rest of HousePanel this will indicate that and hibernate until it finds a valid config file. Either way, this flags that you have the app working so you should stop it by hitting “Control-C”. Next you will install it as a service. To do that start by editing the provided housepanel-push.service file and change the WorkingDirectory and Execstart lines to point to the location where you have HousePanel installed on this server.

WorkingDirectory=/var/www/html/smartthings/housepanel-push/
ExecStart=node /var/www/html/smartthings/housepanel-push/housepanel-push.js

In the above line, for example, you should change “smartthings” to “housepanel” if you installed HousePanel in the /var/www/html/housepanel folder. Save this file, change its permissions, and launch the service as follows:

sudo chmod 777 housepanel-push.service 
sudo chmod 777 housepanel-push.js
sudo systemctl enable housepanel-push
sudo systemctl restart housepanel-push

Sometimes the Node.js setup is stubborn and refuses to load. You should check to make sure that housepanel-push is running in the background after you install it as service. That can be done by doing:

ps -aux | grep housepanel

You should see the housepanel-push service running. If not, something went wrong and you will have to do some troubleshooting. Detailed troubleshooting is beyond the scope of this documentation. Please visit the forum for further assistance. If you see it running in the background, then congratulations, you have it set up properly and it will push status over to HousePanel.

I realize this is a lot of configuration to deal with. The install.sh script attempts to automate this for you. It works for some people but it is not completely robust so it might fail, in which case the details above should help. Over time I will continue improving the install.sh script to make it more robust and foolproof.

Set Server Permissions

This step ensures that your web server can create and update as needed an options file that is generated dynamically when you run HousePanel. To do this you will need to either SSH into your server or use a FTP program that allows file permissions to be established and edited. If you are using Option 3 then FTP is your best bet. Alternatively some web hosting services provide separate tools for setting permissions. Whichever method you use, the directory where you installed all the files must be set to read/write. In Linux/Unix terminology this is done using “chmod 777 /housepanel” assuming your directory name is /housepanel. If you are using Option 2
then your local web server configuration tool should be used to set the directory to read/write. If you are using Option 1 – Raspberry Pi – then your best option is to SSH over to the Raspberry Pi and then use the Linux command “chmod 777 /var/www/html/housepanel”. Replace the directory name here with where your Apache stores html files and the name of the directory where you installed the HousePanel files.

Final Check

If you have made it this far, you are ready to do an initial test. Before you do, let’s review things to confirm that you have the following set up. A lot of people have forgotten the cURL step, so don’t forget that. If you are missing anything, you should go back to the relevant section and complete that step:

  • Web server set up with PHP configured
  • Confirmed that cUrl is activated in your PHP
  • either… HousePanel.groovy installed in your SmartThings IDE with OAUTH activated
  • and/or… HousePanel.groovy installed in your Hubitat IDE with OAUTH activated
  • known values of Client ID and Client Secret for all hubs you want to activate
  • known value of Host URL for all hubs you want to activate
  • HousePanel files from https://github.com/kewashi/HousePanel uploaded to its own directory on your web server
  • the directory above configured to read/write using “chmod 777 yourdirectory”
  • HTML5 capable Web browser with javascrpt and cookies enabled
  • Node middleman running, tested using ps -aux | grep housepanel

If all of the above is true, you are ready to run HousePanel for the first time. Before trying this on your Tablet or Cell phone, confirm that it loads properly in a desktop browser. I have tested HousePanel with Chrome (on a PC, iPhone, iPad, and Android tablet), Microsoft Edge (on a Windows 10 PC), IE 11 (on a Windows 7 and Windows 10 PC), Safari (on a Mac and iPhone), Silk on an Amazon Fire table, and Fully Kiosk Browser (on PC, an Android tablet, and an Amazon Fire tablet). All have been confirmed to work but others are likely to work as well. Fire tablets work as well if you use the APK to load Fully Kiosk Browser. The Silk browser works but it lacks a full screen mode and videos don’t load properly.

Fully Kiosk, Chrome, and Edge work the best in my experience. Before testing make sure Cookies and Javascript are enabled. Browse to the web server that you installed in the first step and the directory where you stored HousePanel. Using the same name examples we have been using throughout this guide, that would be:

    http://192.168.1.50/housepanel/housepanel.php