Installing HP V2

Hub “groovy” Code Installation

HousePanel is designed to work with SmartThings, Hubitat, and Universal Devices ISY hubs. If you have multiple hubs you can link all of them to your HousePanel setup. For SmartThings and Hubitat hubs, installation begins with installing HousePanel.groovy file into your account. You will find the HousePanel.groovy file in the main hpserver GitHub repository. For Universal Devices ISY you do not need to install anything additional but you need to know the IP address and login credentials for your ISY hub.

To install the groovy app into SmartThings or Hubitat, begin by opening the source from GitHub found here.

https://github.com/kewashi/hpserver/blob/master/HousePanel.groovy

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).

SmartThings Hub Configuration

For SmartThings, log into the SmartThings web API to install the HousePanel groovy application. The SmartThings IDE is located at https://graph.api.smartthings.com. 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 above using Control-V (or Command-V on a mac). Then select Save and then “Publish for me”.

Before you leave the 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 the Node.js 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. 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 panel. Either works with SmartThings.

Hubitat Hub Configuration

If you know your Hubitat hub IP, you can log into it directly, or you can locate it by navigating to

https://portal.hubitat.com/ 

Once you are logged into your hub, select “Apps Code” from the menu on the left. Then click on “New App”. A blank page will open where you paste in the raw source copied above from GitHub using Control-V (or Command-V on a mac). Select save and give it the name HousePanel.

Next click on Apps and select the “Add User App” button in the upper right corner. You should see “HousePanel” on the list. After selecting this option, you can then pick the things in your home to include on your panel.

As with SmartThings, you must turn on OAUTH for your groovy app. To do this, click the OAUTH button in the upper right corner of the Hubitat IDE page. This will open a window revealing 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 the Node.js server.

Multiple Hubs

You can install any number of SmartThings, Hubitat, and ISY hubs. This feature is a great way to make a gradual transition from one hub to another. 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. Multiple Hubitat hubs on any account work properly.

Node Server Installation

Unlike prior versions of HP, HP V2 only has one viable installation option. The good news is this one and only option is significantly simpler than any of the options available for the original HP version written in PHP. Because HP V2 is written in the modern Node.js language, installing it on any server platform is basically identical.

I will skip explaining how to set up and configure a standard Linux or Raspberry Pi server. This guide assumes you know how to do this and that you have this already set up. The first step you must take is to confirm that you have NPM and Node.js installed on your server of choice. HP V2 has been installed and tested successfully on a Raspberry Pi, Free BSD Unix, and Windows 10 using Git Bash.

Node.js Installation

HousePanel V2 requires that you have NPM and Node.js both installed. The best place to start for installing both is here:

 https://www.npmjs.com/get-npm 

Another option for Raspberry Pi users is to log into your rPI using ssh and enter the following commands:

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

Another alternative 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 commands:

npm -v
node -v

This should return NPM version of at least 6.0.0 and Node version of at least 10.0.0. If not you will need to upgrade.

Installing HousePanel V2

Installation of HP V2 involves cloning the HP V2 GitHub repository into a sub-folder of your home directory and install the modules using the following commands:

cd ~
git clone https://github.com/kewashi/hpserver.git
cd hpserver
npm install

If you do not have Git installed, it will also work fine to download the source files from the GitHub website as a zip file or other means. The only important thing to remember is to ensure you keep all files in their respective sub-folders, and that you run “npm install” in the main hpserver directory once the files are in place.

Starting HousePanel V2 Server

Next, you need to launch the HP V2 server in background mode, piping all debug and error outputs to a log file using the following command:

node hpserver.js >& hpserver.log &

The server will launch and silently prepare all steps required view your HP V2 dashboard in your browser. The first variant will send any debug output to the file named “hpserver.log” and the second variant will send debug output to the console. It is important to note that ANY number of browsers can point to this same server and render HP V2 dashboards, so this is the only server instance you need. It is also worth noting that none of the permission issues that plagued the prior version of HousePanel apply to this version.

You should now be ready to launch your panel in a browser. Before you do, let’s review a few things to confirm you are ready to go.

First, confirm that the server is running using the standard ps command. This should return a list of active processes, including node running hpserver.js. Next, display the contents of the log file using: cat hpserver.log. If the server is running correctly, you should see something like:

Finally, confirm the following:

  • For SmartThings or Hubitat hubs, HousePanel.groovy is installed in the hub’s IDE with OAUTH activated
  • Client ID and Client Secret are known for all SmartThings and Hubitat hubs you want to activate
  • Login credentials are known for your ISY hubs
  • The IP or web URL is known for all hubs you want to activate
  • HousePanel files from https://github.com/kewashi/hpserver are uploaded to its own directory on your server
  • You are using a HTML5 capable Web browser with javascrpt and cookies enabled

Launching HousePanel in Browser

Before trying HousePanel on your Tablet or Cell phone, confirm that it loads properly in a desktop browser. Using HP on a computer is by far the easiest way to configure your panel anyway, so starting with a PC is a must. HousePanel has been tested 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. Browse to the server that you installed above and use the default port “3080” to display your dashboard. Lets assume your server is at 192.168.1.50, then you would enter:

    http://192.168.1.50:3080

The default port of 3080 can be changed from the options page as explained later; however, the server will need to be stopped and restarted for a port change to take effect.

To stop and restart the server, you have to find the process ID for the active server. This is done using the standard Linux/Unix command:

ps ax | grep hpserver | grep -v grep
kill -9 <pid>
node hpserver.js >& hpserver.log &

where <pid> is the process ID returned by the first statement. For most rPI setups the following variant will do this for you automatically:

hpid=$(ps ax | grep hpserver | grep -v grep | cut -c1-6)
kill -9 $hpid
node hpserver.js >& hpserver.log &

On Windows in a Git Bash session, the following will usually work:

hpid=$(ps ax | grep nodejs | cut -c4-12)
kill -9 $hpid
node hpserver.js >& hpserver.log &

Feel free to write your own scripts to stop and/or restart your HousePanel server. You may also want to install it as a service. Instructions for doing this are beyond the scope of this document.