House Panel

House Panel Open Source Web App for SmartThings and Hubitat
Ken Washington (@kewashi) (c) 2017, 2018, 2019
Version 2.020 as of March 14, 2019



Introduction

HousePanel (HP) is a user-hosted (typically local) highly customizable open source web application dashboard for accessing and controlling a SmartThings or Hubitat equipped smart home from a Tablet, Computer, or even Smart Phone.

Download a copy of HousePanel from the HousePanel GitHub repository here.

HP is designed to give the user full control over the look and feel of their panel controller. It does require some effort to install and configure, but once set up, making fine tunings and adjustments are relatively simple. Most customizations can be done from within the built-in web-based user interface, which includes a full featured tile editor and a tile customizer for modifying content shown on any tile. Power users can also make major modifications by editing a CSS file using industry standard protocols.

HousePanel now supports multiple user configurations. Any number of users can be defined with their own password. Each user's setup can be customized individually to meet their needs. When a user logs in, only their configuration will be shown on the tablet.

HP runs on a customer-provided web server and does not expose your personal data nor any details about your environment to the developer or any other party. You are in total control. The default settings were designed by a professional web designer to create a highly acceptable user interface for non-technical people. It is designed to not look and feel "geeky". By default the tiles are large and colorful, placed on beautiful full color backgrounds. There is also a modern skin that makes HousePanel look very similar to other popular dashboards. Finally, the user can create any number of custom skins to make HousePanel look however they desire.

As of version 1.990, HousePanel also includes a helper Node.js application that pushes the status of things to your dashboard in real time as they change due to user control outside of the panel. This feature requires installation of HousePanel on server located on the same network as your hub. Typically this will be a Raspberry PI but it can be any server that supports Node.js and that can be accessed locally by the smart hub. If activated this feature will provide immediate updates to your dashboard as opposed to waiting for the once-a-minute poll to update it.

An advanced feature of HP is that it can be used as a text-based web service to return json strings of status about your home to any other web application. This advanced feature is mostly for developers and can be safely ignored, but if you are a developer then you should read the final section of this Wiki on Advanced Applications of HP.

Features

HousePanel can display and/or control most types of things in a smart home ecosystem, including: A number of special tiles are also supported, including: Images can be any still or dynamically updated graphic that can be referenced via the Internet in the CSS file. Blanks are spacers and can take any form or size, giving the user maximum flexibility in the layout of the pages. A relatively new capability of HP is the ability to include user-defined iFrame tiles. These are tiles that can contain any content from anywhere on the web using iFrame browser capabilities. To use this feature you will need to create a local "html" file with your desired iFrame content. By default HP comes with two html frames that shows a weather forecast in two different formats.

Most tiles now also contain 4 fields hidden by default that display the last four events that occurred and their date in the UTC time zone. One or up to all four of these fields can be revealed using the tile editor or by adding the following to your skin (more on skins later).

div.event_1 {
    display: block;
    font-size: 9pt;
    width: 100%;
    background-color: rgba(90,90,90,1);
    font-style: italic;
}
A very important feature of HousePanel is the Tab layout. All controllable things are presented on one of several Tabs that can be quickly swapped in and out of view. This uses the tabbed display capability of modern web browsers. Under the hood HP uses jQuery to make this efficient. This means that any number of pages can be displayed, and on each page, any number of "things" can be shown and controlled. Later in this document we will explain how to customize the names of pages and the number of pages used. A default page configuration is provided but pages can be easily renamed, deleted, or added when in Edit mode.

For advanced users HousePanel is a highly flexible API that can serve as a web service to access your smart home devices from another web application. This works for SmartThings and Hubitat connected devices. This feature requires that users first authenticate their hubs using the GUI. API calls are possible without using prior GUI authentication if the user knows and provides the fairly complex URL-encoded security codes on the API command line. Instructions for using the API are in the advanced section of this document.

The main page of HousePanel once installed and configured will look something like this:

Requirements - What You Need to Use HousePanel

HousePanel is a web application written in PHP and Javascript that is paired with a SmartThings and/or Hubitat SmartApp written in the Groovy language. There is also an optional small Node.js module used to push status info to the dashboard in real time. If this module is installed, your panel will stay in sync with the status of things in your home in near real time. Otherwise HousePanel uses polling to keep things in sync, so there can be up to a one minute delay before your dashboard is updated to match external changes. Any state change made on the dashboard itself will always be immediately shown correctly.

To use Housepanel you will need a modern browser that supports HTML5 and Javascript. Obviously you will also need a SmartThings and/or Hubitat account with owner access. You will also need to have owner access to a web server of some type capable of hosting PHP applications. Access to a good CSS editor will also be useful but is no longer essential given the robustness of the integrated tile editor. If you do plan on editing CSS directly to make custom changes to your HousePanel configuration, you can do this with any text editor, but you will be much happier if you are using a coding editor that assists you with the crazy syntax of CSS and graphical aids for color selections. I personally use NetBeans which is my favorite coding editor. You can get a copy from the Oracle website at www.netbeans.org. If you do use NetBeans be sure to install the plugin for PHP editing. I also find the color code preview plugin to be useful for picking colors easily. Again, most users won't need to worry about this because the look and feel of HousePanel can be controlled using a proviided in-app tile editor (more on that later).

Installation

Server Options and Instructions

Option 1 - Raspberry Pi (Best Option)

This is by far my favorite and the strongly preferred option. This is the only option that supports a test and confirmed implementation of 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".

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

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 (not recommended) - 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 Application

There are two groovy files that are used to operate HousePanel - one for SmartThings and one for Hubitat. The SmartThings version is called HousePanel.groovy and it should be installed into your SmartThings smartapp IDE repository. The Hubitat version is called HousePanelHubitat.groovy and it should be installed into your Hubitat IDE on your local LAN.

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.

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. 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. Either works with SmartThings.

Hubitat App Installation

If you are a Hubitat user, you will need to install the HousePanelHubitat.groovy file into the app section of the Hubitat webpage API. Open the HousePanelHubitat.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. DO NOT name it HousePanelHubitat.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 OAUTH. 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 Hubitat you will not be given the option of changing what things you permit during the authentication step.

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 have been reported to 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:

    https://github.com/kewashi/HousePanel
    

If you used the new install script to set up your rPI, then this step is already done.
cd ~
wget https://raw.githubusercontent.com/kewashi/HousePanel/master/install.sh
bash ./install.sh
 
Once you have done this you should be all set and ready to run HousePanel. The following is only if you want or need to do a manual install.

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". This file will still be used if created but it is no longer required. If you have a copy of this file from an older installation, it is strongly recommended that you remove it. For now the code will attempt to use it, but this feature may be removed in the future.

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 can be found 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:



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


If all goes well, HousePanel will launch and display an authentication page. If this happens, congratulations - you are ready to proceed.

Running HousePanel

First Time Launch - Authenticating

When you first launch HousePanel, the following authentication page will be displayed for you to provide your credentials and other setup information:
The first input section is where you specify your timezone, your default skin directory, your username, and a password. If you don't want to use passwords to protect your panel, leave it blank. Empty passwords mean anyone with physical access to your home panel can load HousePanel and control your home. Multiple users can be defined, each with their own unique Username. If this is your first time running HP, use admin and proceed with authenticating your hubs. You can return to this page later to add additional usernames. When you add a new username later, you can skip the hub auth step and go to the Done button. For now, proceed with identifying your default main user (I recommend leaving it as admin) and giving a password. Then proceed with selecting your first hub and hub info below.

This authentication page is also where you will provide the API Url, Client ID and Client Secret information from the OAUTH settings noted earlier. Note that if you provided a clientinfo.php file, these values will be pre-populated. The Hub Name field is optional and will be filled in automatically for SmartThings and Hubitat.

Hub ID is a unique identifier for this hub that is user provided. Hubitat hubs will populate this field with the hubid of the hub. The user must provide a unique value for SmartThings hubs. This field will be populated with a good guess.

The Fixed Access Token and Fixed Endpoint values are optional. If provided you do not have to provide the Client ID and Client Secret values. You also will not be redirected to an auth challenge page. This option is provided for those who know their tokens and don't want to bother being challenged every time to enter their credentials when doing a reauth. Otherwise, to proceed you must provide the Client ID and Client Secret values. You also ALWAYS have to provide a valid API Url address Typical values for the API Url are:

SmartThings:https://graph.api.smarthings.com
Hubitat Local:Your local IP address of your Hub, such as http://191.168.1.50
Hubitat Cloud:https://oauth.cloud.hubitat.com
If you want local processing for Hubitat use the local version. If you want to be able to use your panel anywhere use the cloud version. Once these are provided, select "Authorize Hub" and the app will redirect you to the Hub's page. For local Hubitat processing there is no auth challenge. For the cloud versions you will have to provide your login information, and then you select all of the devices that you want HousePanel to control. Your login information should be the same information you use to access the SmartThings or Hubitat account online.

It is this authentication step that prevents anyone from accessing your HousePanel installation. This is why it is important to protect this login information; otherwise, anyone who has it will also be able to access your HousePanel and control your smart home. On the other hand, if you installed HousePanel on a Raspberry Pi on your home local network, then only people with access to your home network will have access to HousePanel. This gives you one extra layer of protection and is why I prefer the Raspberry Pi installation option (see Option 1 in Section 1). This same extra layer of protection exists for Option 2 installations on a PC or Mac with a web server, but such a server must stay on and can be more easily accessed via a keyboard than a rPi that has been tucked inside a cabinet. Anyway, enough preaching about the benefits of the rPi install.

SmartThings hubs will present a list of your hubs. Select which hub you want to associate with HP. Most people only have 1 hub so there isn't any decision to make here, but you will still need to explicitly click on the one hub that you have. I have two hubs so in my case I have to pick the one that I want to control. Anyway, after you click on the hub, or in the case of Hubitat, after you authenticate, all supported things will be shown in a list. For local Hubitat installs the list of things must be selected when you install the app. The authentication step will only ask you to authorize access with Hubitat.

This is where you select which things you want HousePanel to have the option of displaying and controlling. IMPORTANT!! I am saying the "option of" here because HP does not have to display everything you select here. It is just that ONLY the things selected here will be possible to display. The way you select what is displayed where and how they are displayed will be described in the next few sections. What I recommend doing here is to just select everything that is supported in the most intuitive category. For example, dimmer switches will show up on both the switch list and the switchlevel list. I would select it only on the switchlevel list, but you can do both. You might decide to exlude some devices. For instance, I excluded a light that I have in my food pantry that is activated by a door open sensor, since I don't ever anticipate needing to turn the lights on in a closed food pantry. Anyway, just select the things you want and you will be good to go. To finish this step click on the Save button at the bottom of the screen. Again, this applies only to SmartThings because Hubitat requires the things to be selected when you install the app. This same approach can be used with SmartThings where you select the things you want from the smartphone SmartThings app. If you do that, the things you selected on your smartphone will be selected by default when you authenticate the hub.

You will then be redirected back to this same Authentication page where the number of devices read will be shown for the hub you selected. At this point you can authorize another hub following the same procedure. Just select the hub you want from the "Authorize which hub" drop down list and proceed accordingly. If you want to add a hub then select the last item which is always a new blank hub. If you are done authorizing hubs, select the "Done Authorizing" button at the bottom of the screen. This will show you the main HousePanel page and you'll be ready to start enjoying your panel. Sometimes when you return from the auth page a Refresh is needed for your new things to show up. Just reload your browser or click the Refresh button.

When the HousePanel main dashboard loads the first time, it reads all things that you selected and their states. It then assigns unique ID numbers to each thing, it automatically organizes each thing selected into one of several pre-defined rooms. That information is then saved in a file called hmoptions.cfg onto your server. In our example case, it will be stored in: "/var/www/html/housepanel/hmoptions.cfg". As an aside, this is why you had to do the step of making your server directory Read/Write. Without that setting HousePanel will not be able to save this file. If all goes well HousePanel will then render the page and display it to you. It will look something like:

If you are curious how HousePanel decides what thing to put in which room by default, here is how it does it. First, HP creates seven default rooms named Kitchen, Family, Living, Office, Bedrooms, Outside, and Music. Then it places and activates any thing whose name contains one of several keywords into the corresponding room. The keywords are listed below separated by "|" for the rooms noted. This keyword map can be found in the housepanel.php source code in the setDefaults function roughly around line 2770. If you are comfortable with editing source code, feel free to change these keywords to your liking; however, end users will have other ways of moving things around and renaming rooms using the graphical editor. We'll discuss how to use this editor to edit, add or delete things and rooms in a later section.

Kitchen: "kitchen|sink|pantry|dinette|clock|mode"
Family: "family|mud|fireplace|casual|thermostat|weather"
Living: "living|dining|entry|front door|foyer"
Office: "office|computer|desk|work"
Bedrooms: "bedroom|kid|bathroom|closet|master|guest"
Outside: "garage|yard|outside|porch|patio|driveway"
Music: "sonos|music|tv|television|alexa|stereo|bose|samsung"

Using HousePanel

Your default HP page should look something like the image in the prior section. Before getting into how to customize things, lets first explore how to use HP to get the most out of it. Most of it will be obvious and intuitive, but a few hidden gems require explanation. For starters, you can browse different rooms by clicking on any tab at the top of the page. Notice that the room display changes INSTANTLY! This is because HP renders all pages in advance and organizes them into tabs. When you select a different tab you are just telling HP to show that tab that was previously created.

Turning Things On and Off

While on any page, you can click or tap on any thing tile to change its state. For example, clicking on "Kitchen Light" will turn the light off if it is on, and will turn it on if it is off. If you click on a closed garage door, it will open. However, not all things support state changes from HP. Contacts, motion sensors, clocks, and blanks are display only tiles so clicking on them will do nothing. Tiles that invoke actions include switch, bulbs, lights, dimmers, garage doors, mode, routines, shm (SmartThings), hsm (Hubitat), thermostats, and music tiles. If you are using a computer, the cursor will change to a pointer when you hover over things that can be clicked to change state.

Some tiles such as thermostat and music tiles have multiple controls that can be individually controlled by clicking on them. For example, each thermostat has a heater and an AC control and each one has up and down arrows that can be clicked on to adjust the temperature setting. On music tiles, play, pause, skip, and stop can also be clicked on. On dimmer tiles you change the intensity of the light by moving the slider. When you do this the light will always come if it is off.

If you have the browser control panel open (F12 on Chrome), clicking on things will return status information to that screen. This is a great way to see if your panel is working properly.

Edit Mode: Moving Tiles Around

One of the most exciting features of HousePanel is the ability to highly customize its look and feel. The first level of customization involves simply moving existing tiles around on a page. To do this, you need to enter edit mode using the Edit radio button on the bottom right corner of the screen. When you are in this mode, tiles can be moved around freely on the page by clicking and dragging them with your mouse or finger. While edit mode is fully supported on a tablet, I strongly recommend that you do edits on a PC and then deploy your edited configuration to your tablet by simply doing a Reload. When in edit mode you can also rename pages, add pages, delete pages, add tiles using drag and drop from the library, delete tiles, and edit individual tiles in detail. When editing page names, please be advised that page names cannot contain spaces. You should also avoid the use of symbols in page names. Tile names can contain spaces and symbols but I recommend keeping things simple. Edit mode will look something like this:

The green dots on the page tabs are used to edit the page in the Tile Editor. The red dots are clicked on to delete a page. Similar green and red dots are shown on each tile for entering edit mode or to delete that tile. If you select a red dot to delete a tile or page, you will be prompted to confirm. Upon confirmation the tile will be removed from the room being displayed. If you select a green dot on a tile, the Tile Editor will launch. The blue dot will launch the Tile Customizer. Tile Editor and Tile Customizer are documented in later sections.

Reorder Mode: Changing Order of Rooms and Tiles

You can select Reorder mode to enable the reordering of tiles and rooms. The main difference of this mode is things are automatically snapped into place in this mode based on the order. This is also the only mode that allows room tabs to be moved around into a different order. To do this, simply click and hold a tab and move it left or right to reorder your rooms. The new room location will be permanent on this server. IMPORTANT!! You can mix edit and reorder mode, but you should first do reorder and then do edit to make fine tuning adjustments. If you reorder after you edit the relative positions will no longer be applicable so they are reset to zero. If you mistakenly do this, just click Refresh and the page will render properly.

Adding or Removing Things from Rooms

Deeper customization involves adding or removing things to your rooms. One way to do this is to use Edit mode described above. While in Edit mode a catalog will display on the right hand side. You can drag things from this catalog and drop them on the page. A confirmation box will appear - click on Yes to confirm addition of the dropped tile.

An easy way to make multiple changes to multiple rooms at the same time is to use the Options page. This page is launched using the Options button found at the bottom left of the page. Clicking this button will load a page with a two-dimensional matrix of all your things and all your rooms that looks like this:

Everywhere you see a check mark means the thing of that "row" will be shown in the room of that "column". If you have a large number of things you can filter showing things by type by clicking on the check boxes on the top of this page. You can add or remove a check mark in any room for any thing. Duplicates are allowed. For example, at one extreme, if you want all things to show in all rooms, you would just check all of the boxes. This wouldn't make any sense but hopefully this extreme example indicates the tool's extreme flexibility. A more realistic example might be to check a thing with a name that didn't match one of the default keywords, or to uncheck a thing that matched that you don't want shown in the default room. For example, in my installation I added a check to "Back Yard Rock" to the Outside room, and removed the "Garage Entry Door" from the Outside room. I also checked the clock row for every room so I have a clock on all pages. You should also notice that the hub number and type of each thing is shown in this table.

Customizing HousePanel

Styling Tiles Using TileEdit

Some amazing work done by @nitwit in the SmartThings community inspired the development of a robust tile editor in HousePanel that can be used to modify the look of just about every element of every tile. To use the editor, select "Edit" mode in the radio buttons near the bottom of the page. Each tile will then show a green, blue, and red dot.
Red will delete the tile, Blue will open the Tile Customizer described in the next section, and Green will open the following Tile Editor page.
This window can be dragged around on the screen such that you can see the effects of edits made on the main screen immediately. Tile editor use is self-explanatory as it uses standard dialog box features. To style a particular item, first click on it in the tile display or you can select the item from the drop down list below the tile. Some items are hidden and can only be selected from the drop down list. For those items you can select them and then unhide them and style them however you like. The icon background will style the entire tile. So if you want an image background on a tile, select "whole tile" and then pick the image you want. The on or off state of some tiles can be toggled by clicking on the main icon. Some tiles have multi-state icons such as thermostats. Each click rotates to the next state.

There is even a gradient background feature to add some flair to your tiles. The icon can be selected from your local subdirectory or it can be taken from a library of standard Android icons. There is also a directory called "media" where you can load any custom images. By default this directory contains a number of interesting backgrounds you can use. This is how I used my photo in the presence tile.

I think you will enjoy tinkering with this feature. If you are more of a power user and want to fully control your own destiny, keep reading for how one would style the page using custom written CSS. One other thing is worth noting -- if you use the tile editor feature, HousePanel will create a file named "customtiles.css" containing the styling information specified. This file should not be edited directly. You can save this file and create a library of profiles for later use. There are lots of options here. If you want to customize your setup, you should make those custom edits in the housepanel.css file in your skins directory following the instructions below.

Styling Pages Using Tile Editor

Pages can now be edited using the Tile Editor, so strictly speaking the Tile Editor is now both a tile and a page editor. To use this feature click on the green dot next to a page tab when in Edit mode. When the editor launches for a page a simple box is shown with the name of the page and two links for styling the tab itself. The tab color when selected and when not selected can be changed here. You can also put an icon in the tab using this feature and change its outline.

If you select whole tile option then the page background image or color can be selected. You can also change the border, apply gradients, and other effects as you wish. You can also still manually edit page backgrounds in the CSS using the directions below.

Customizing Tile Content

Tile content can also be altered using the built in Tile Customizer in HousePanel. To use the customizer, select "Edit" mode in the radio buttons near the bottom of the page. Clicking on the blue circle will open the Tile Customizer page that looks as follows:
The Custom Type option in the upper left is used to pick what type of customization you are performing. Seven options are available: TEXT, POST, GET, PUT, URL, LINK, and RULE. TEXT links are used to add any user provided text to the tile. When adding anything to the tile, you must name the field in the User Field Name area on the left. You can also select an existing field, in which case your text will show up instead of the default behavior that this tile normally shows. Be careful with this feature because it can remove important functionality. Then again, this flexibility means you can make all sorts of creative effects.

POST, GET, and PUT types are used to add a user-specified web service to the tile being customized using the method selected. In the top of the right column, enter a valid URL to the web service. You must also either pick the field this will override OR give a new user-defined field name using the entry box on the left. Click the "Add" button and this field will be added to the list of "Existing Fields" shown on the left side of this dialog box. You can mix and match this with any other addition.

URL types are similar to POST, GET, and PUT except it opens the given URL in a new window. The text entered must begin with http for this to work. TEXT fields will behave like URL fields when a valid URL is provided.

LINK types enable you to add any other field in any other tile in your smart home to the tile being customized. In the top of the right column, select the tile to link to, and then select which field of this tile to link into the customized tile using the "Available Fields" list above on the right. Once you are happy with your selection, click the "Add" button and this field will be added to the list of "Existing Fields" shown on the left side of this dialog box. You can mix and match this with any other addition. Note that with LINK customizations the field name must be taken from the linked tile. If you link in a switch field from another tile, it will replace the existing switch field. If you attempt to link in another switch field, it will overwrite any existing one unless you alter the field name by adding some custom text after the word switch. For example, you could make this field name switchtwo. This only works if there is already a linked field named switch.

RULE types provide a simple automation capability. The rule is provided as a single line of text representing the tile number you want to control, the field, and the type of action you want to take. These three values are separated by an equal sign. Any number of rules can be entered separated by a comma or semicolon. For example, to turn on tiles 42 and 60 that are both switches you would enter:

42=switch=on, 60=switch=on
More complex rules are allowed such as setting level and mixing on and off. For example, the following will open a garage door, set the level of a dimmer, turn one light on, and turn another light off.

42=switch=on, 16=door=open, 60=switch=off, 51=level=30
To use this rule feature you need to have the tile numbers that you want to control. Tile numbers can be obtained from the Info page.

The Tile Customizer is a powerful tool for making custom panels. The tile shown above for example was made by adding a switch, a slider, a smart home monitor, and a close time field to a blank tile. Once these fields are added they take on the style of their parent, but that can be modified using the Tile Editor described in the prior section.

Macros

Macros are a more powerful alternative to automation than the RULE system provided by the Tile Customizer described in the previous section. With Macros you can string together any number of action calls that HousePanel supports and connect it to any field on any tile. The catch is there is no GUI for defining Macros. Macros must be hand-written and saved in your hmoptions.cfg file, so this is a feature only for power users. Macros are defined in a section of the hmoptions.cfg file called "macros". That section looks something like:
"macros":{
"custom|custom_4|test":
[
  ["-","adcd1-12345-4a33-c111-11223ea123","switch","switch","toggle"],
  ["-","dcba9-54321-4cda-a222-223344abcd","switch","switch","off"],
  ["-","dcba9-26371-5cda-b333-65432abcda","switchlevel","level","on","60"]
]
}
The keys are a string composed of the type, the id, and the field, separated by the "|" symbol. The type|id pair is the "connected tile" that is used to trigger the macro. This should be one of the tiles listed in the "index" section of the hmoptions.cfg file. The field specified is the field that is clicked on to invoke the macro. An array of arrays follow. Each array entry has up to 6 fields. The first array element is the hub id. If "-" is entered, the hubid of the connected tile is used. The second element is the id of the thing to automate. The third element is the type of thing. The fourth element is the field to control. The fifth element is the command or value to pass to HP. For example, it could be "on", "off", "open", or "close". A sixth element is attribute that is sent for some tiles to be controlled. For example, level can be sent this way.

Any number of macros can be defined and they can be tied to anything, including custom fields as is shown in the above example. The only restriction is they cannot be mixed with RULE custom fields.

Styling Things Using CSS

The following several sections are legacy methods for styling HousePanel. These methods should only be used if you can't get the Tile Editor to do what you want.

An important type of customization is performed by either creating your own custom style sheet or editing the provided one in the "skin-housepanel" directory. When you unpack or clone the master source files this directory will exist underneath the master root location where you installed HousePanel. It is best to keep a local copy of all files to edit and then upload them when you are ready to your server. If you are using NetBeans then that IDE can handle uploads for you automatically if you set up the project files with your FTP username and password. Doing this is beyond the scope of this Wiki but you can find instructions in the NetBeans help file. To begin customizing open the housepanel.css file in your favorite text editor. That file will have many well designed defaults for most types of HTML classes and tags that you will find in the displayed webpage. In the following sections we define how you would alter some of these settings. All tabbed pages inherit the property of the "div.panel" style that is defined in the default CSS file. The default should look something like this:

div.panel {
    display: inline-block;
    border: 0px solid #3333cc;
    padding: 2px;    width: 100%;    margin: auto;
    position:relative;    background-repeat: no-repeat;
    background-position: left;
    box-shadow: 0px 0px 41px rgba(0, 0, 0, 0.50);
}


So if you want all pages to by default to be squeezed onto 75% of the page you could change "width:100%" to "width:75%".

Each specific tabbed page is identified by a <div class="panel-name"> style with the name "panel-" pre-pended to the name of the page shown on the tab. Case is not significant when doing this styling. For example, the Kitchen page is tagged with div.panel-kitchen. This is the setting one would alter in the CSS file to provide a unique styling for any page with the tab named "kitchen". The default styling is defined here:

div.panel-family, div.panel-familyroom {
    background-image: url('family.jpg');
}
div.panel-kitchen, div.panel-dinette {
    background-image: url('kitchenroom.jpg');
}
div.panel-formal, div.panel-living, div.panel-livingroom {
    background-image: url('formal.jpg');
}
div.panel-outside, div.panel-garage {
    background-image: url('outside.jpg');
}
div.panel-office, div.panel-library {
    background-image: url('office.jpg');
}
div.panel-bedroom, div.panel-bedrooms {
    background-image: url('bedroom.jpg');
}
div.panel-music, div.panel-theater, div.panel-entertainment {
    background-image: url('music.jpg');
}
div.panel-thermostats, div.panel-thermostat {
  background-image: url('thermostat.jpg');
}


If you want to change the background image just provide your custom image and upload it to your server and refer to it in the above section of the CSS.

Default Thing Styling

All things displayed in HousePanel inherit the styling tied to the <div class="thing"> tag style. The default should look something like this:

div.thing {
    display: inline-block;
    margin: 3px;
    text-align: center;
    vertical-align: top;
    border-top: 2px solid #999999; 
    border-right: 2px solid #333333;
    border-bottom: 2px solid #333333; 
    border-left: 2px solid #999999;
    background-color: rgba(0, 51, 204, 0.6);
    box-shadow: 2px 2px 7px black;
    color: rgba(250, 250, 250, 1);
    cursor: default;
    width: auto; 
    height: auto;
}    


If you want all tiles displayed to be a different size or have a different border color, this is where you would specify your custom information.

Specific Thing Type Styling

Any given thing has a known thing type and each type can be styled distinctly. This is done by providing styling information tied to the <div class="thingtype"> tag, where thingtype is one of the recognized types of things that HousePanel supports. For example, if you wanted to make all things of type "switch" look a certain way, you would style the following block:

div.switch {
    width: 118px;
    height: 112px;
}


This would just style the switch portion of the tile. Each tile also has a title bar and potentially other elements. The entire tile can be styled by referencing "div.thing.switch-thing". This approach will take priority over anything you provided previously to "div.thing" described above, but only for switch things. For example, let's say you wanted to put a photo of your cat into all switch things, you could do that by doing something like:

div.thing.switch-thing {
  background-image: url('mycat.jpg');
}


Styling Things Based on State

Things in HousePanel that can be clicked upon typically also change state. The current state of all such things is available to be used to provide state based styling. The most common example of this is a switch, which changes the styling "div" to include "on" or "off" based on whether the switch is on or off in state. Using this one can provide a unique image or unique color styling based on whether the switch is on or off. The default CSS uses this to style "on" switches to use a bright light bulb, and "off" switches to use a dim light bulb.

Notice that this styling applies to switches, dimmers, bulbs, and lights. Any image styling provided in the div.switch section will be overridden by this. This same concept applies to open and closed doors, momentary buttons that are pushed, and locked and unlocked locks. Other single word states provided by the SmartThings system will be available to use for styling.

Thermostat, Music, Weather, and other Complex Formatting

The principles and concepts described above apply equally well to thermostats and music thing tiles. The difference is that these tile types involve more complex multi-part elements. The important thing to note is that each individual element can be styled individually or all of them can be styled using the master div information that wraps around the entire tile. For thermostats, the master div information is tagged with div.thing.thermostat-thing following a similar pattern as the simpler tiles. This applies to all complex tiles such as Music and Weather tiles. The following styling from the default file presents the temperature reading as a blue-green circle. This can be changed to whatever you prefer.

div.thermostat.temperature {
    display: inline-block;
    width: 118px;
    background-color: #006666;
    color: #ffffee;
    border: 2px solid white;
    box-shadow: 5px 4px 15px black;
    cursor: default;
    text-align: center;
    height: 50px !important;    width: 50px;
    padding: 4px 3px 0 3px;
    margin-top: 10px;    margin-bottom: 10px;
    border-radius: 50%;
    font-size: 20px;
    line-height: 45px;
    -webkit-border-radius: 50%;
    -moz-border-radius: 50%;
}

Customizing Special Things and Tiles

HousePanel includes a number of special things/tiles that are by default styled appropriately; however, in keeping with the flexibility principle of HousePanel, all of them can be customized to your liking. The custom tiles and how to customize them are described below.

Blank Tiles

Blanks are just that - blank. They are used as spacers. Four blanks are provided for SmartThings hubs and a different set of four blanks are provided for Hubitat hubs. Any of them can be added to any page using the Options feature described previously. All blanks are styled as transparent in a standard tile size. The div tag used to style all blanks is div.thing.blank-thing so this div can be styled to make blanks look differently. For example, one might want to use blanks as dividing lines to separate tiles into sections. The four SmartThings blank sizes are provided under the names b1x1, b1x2, b2x1, and b2x2. The Hubitat blanks have the names h1x1, h1x2, h2x1, and h2x2. The names indicate the default sizes of these four blank tiles using the following default styling:

div.b1x1, div.b1x2, div.b2x1, div.b2x2 {
    width: 120px;    height: 160px;
    font-size: 0px;    padding-left: 0px;
}
div.b2x1, div.b2x2 {
    width: 244px;
}
div.b1x2,div.b2x2 {
    height: 320px;
}


The above makes b2x1 a double-wide, b1x2 a double-high, and a b2x2 a double wide and double high tile. Again, these four default sizes can be changed to whatever you like. For example, all four can be made the same size and then the gap size can be driven by how many of them you include on any given page.

Clock Tile

HousePanel has a built-in digital clock and a built-in analog clock tile both of type "clock". The digital clock thing is a digital clock tile that by default shows the day of the week, the date in MMM dd, yyyy format, and the time in hh:mm AM/PM format. The overall clock tile can be styled using the Tile Editor or manually by modifying the div tag div.thing.clock-thing. By default this element is styled to be a 246x160 blue tile but it need not be. All three sub-items can be styled in the editor or by using the tags:

div.clock.weekday
div.clock.date
div.clock.time


The actual format of the sub-item fields cannot be modified using CSS, but it can be changed using the Tile Customizer by editing the fmt_date and fmt_time fields. These fields are not displayed but contain text telling HousePanel how to format the date and time fields that are displayed. Their contents can be adjusted using the TEXT feature of the Tile Customizer. For example, you can specify "g:i:s" as the fmt_time field and time will show seconds and drop the AM/PM. The default fmt_time value is "g:i A"

The font, color, size, and placement are all fair game to change in the Tile Editor. The overall tile size can be styled using div.thing.clock-thing. Finally this tile has a name bar just like all others, but by default it is hidden. It can be displayed and uniquely styled using the tag name of div.thingname.clock.

The analog clock is a round faced analog clock that uses a third party javascript plugin. The clock style cannot be modified using the editor, but the size, color, and background can all be modified as with other things.

Image Tiles

Four place-holder image tiles are provided for end-user unique styling for each hub that is authenticated. These tiles are named "img1" through "img4" for SmartThings hubs and "himg1" through "himg4" for Hubitat hubs. THey are styled using the div tag div.thing.image-thing. By default this styling is a double-wide tile that forces the image to stretch to fill the tile (using background-size: cover). Each individual image tile is where one would provide the online asset containing the graphical image to display. For example, the img1 tile would be styled to display a "jpg" file using the following:

div.image.url.img1 {
    background-image: url("livingroom.jpg");
}


In the above example the jpg file must be on the same server as the HousePanel app and in the same directory as the CSS file, but any valid Web URL can be provided here. The other three img tags can be similarly styled.

Video Tiles

Four video tiles are provided for end-user custom display of video files stored on the server. These files must be named video1.mp4 through video4.mp4 and stored in the media folder. This is the top-level media folder, not the media folder inside of each skin's folder. Any file named video1.mp4 will be played in the video1 tile. Same for video2 through video4. When the tile is clicked, the video will replay. Note that this is not a live camera video feed - these are static videos only. However, you can write a script to grab the latest video feed from your camera and save it to the media folder with the appropriate name. This is how I view the videos from my Arlo cameras. There is a sample script provided called getarlo-sample.py that will save the latest video recorded by an Arlo camera to video1.mp4. A second sample is provided called arlo-sample.py that will save the last four videos to the media folder with names video1.mp4 through video4.mp4. The next section describes frames that can be coaxed into displaying live video feeds for some cameras. Examples are shown on the forum.

Frame Tiles

Four frame tiles are provided for end-user custom display of arbitrary web content. These tiles are named "frame1" through "frame4". THey are styled using the tag div.thing.frame-thing. By default this styling points to a forecast web page in two styles. Modifying frames requires a code edit in the housepanel.php file. You should only do this if you are comfortable with coding. Search for forecast.html or accuweather.html to locate where to make the changes.

There are some amazing examples in the SmartThings community for how to customize the styling of img tags to do things ranging from live video feeds to 5-day forecasts. The sky is the limit. I encourage you to browse the forum to get ideas for taking your HP to new heights.

Mode Tiles

Four mode tiles are provided that each can be used to show the current state of the SmartThings location. This will be one of the modes defined by the user in the SmartThings app, such as Home, Away, or Night. Mode tiles can be styled by modifying the div tag div.thing.mode-thing. There are four mode tiles that parallel the naming convention used for blank tiles: mode1x1, mode1x2, mode2x1, and mode2x2. The default sizes are the same as their equivalent blank defaults. Each mode tile contains three sub-items: mode.themode, mode.name, and mode.zipcode. By default mode.zipcode is hidden. The actual mode within the "mode.themode" sub-item is styled to be larger than the name of the hub, which is in the mode.name sub-item. Again, these sub-items can be uniquely styled or even hidden to your liking.

Routine Tiles

Routines are "Hello Home" actions that are defined in the mobile app. These are presented as boxes without title bars by default. The name of the routine is shown by default as simple text in an 18 point font. The tag div.thing.routine-thing can be used to create a unique look for routine tiles. Alternatively the specific label sub-item under the div.routine.label tag can be styled. The latter is what is in the default CSS.

Weather Tile

Of all the special tiles the weather tile is the most complex. Unlike other tiles this tile is associated with a specific device instead of with a generic capability. For this reason there can only be one weather tile. This one weather tile can be displayed in any or all rooms. If edited with the Tile Editor, the changes will reflect on all weather tiles in every room. You can make it look different in each room because each room by editing the CSS directly because it is wrapped with a room "div" tag that can be used as a qualifier. The overall weather block is styled using the tags div.thing.weather-thing and div.weather

Weather tiles have many sub-items and each one can be uniquely styled. The code block below is from the default CSS file showing just one of many possibilities. Note that several sub-items are hidden by default in this example. The outside temperature is shown using a similar circle as is used with thermostat tiles.

div.thing.weather-thing, div.weather {
    text-align: center;
    height: auto;
}
div.thing.weather-thing {
    background-color: rgba(50,50,50,0.4) !important;
    width: 240px;
}
div.weather.temperature, div.weather.feelsLike {
    display: inline-block;
    width: 118px;
    background-color: #006666;
    color: #ffffee;
    border: 2px solid white;
    box-shadow: 5px 4px 15px black;
    cursor: default;
    text-align: center;
    height: 60px !important;
    width: 60px;
    padding: 4px 3px 0 3px;
    margin-top: 10px;
    margin-bottom: 10px;
    margin-left: 10px;
    margin-right: 10px;
    border-radius: 50%;
    font-size: 20px;
    line-height: 55px;
    -webkit-border-radius: 50%;
    -moz-border-radius: 50%;
}
div.weather.feelsLike::before {
    content: "~";
}
div.weather img {
    margin-left: 15px;
    margin-right: 15px;
}
div.weather.wind::before {
    content: "Wind: ";
}
div.weather.wind::after {
    content: " mph";
}
div.weather.humidity::before {
    content: "Humidity: ";
}
div.weather.percentPrecip::before {
    content: "Rain: ";
}
div.weather.humidity::after, div.weather.percentPrecip::after {
    content: "%";
}
div.weather.sunriseset {
    margin-top: 10px;
}
div.weather.sunriseset, div.weather.humidity,
div.weather.wind, div.weather.percentPrecip, div.weather.alerts{
    background-color: #333333;
    margin-bottom: 4px;
}
div.weather.timeZoneOffset, div.weather.alertKeys,
div.weather.sunriseDate, div.weather.sunsetDate,
div.weather.illuminance {
    display: none;
}
div.weather.weatherIcon, div.weather.forecastIcon {
    display: inline-block;
}


WebCoRE Pistons

WebCoRE is the wildly popular "Community Owned Rule Engine" by @ady624 on the SmartThings forum. If you are a WebCoRE user then you will see all of your WebCoRE pistons in the Options matrix as described in a previous section. You will need to select the pistons you want to display in the room columns where you want them to show up. Once you do that they will appear in a style defined by the tags: div.piston-thing, div.piston, div.piston.webcore, div.piston.pistonName, and div.piston.pistonName.firing. The default shows a graphic that looks like an automotive piston and when it is fired it looks like it is on fire.

Advanced Styling of Specific Tiles

Up to this point we have described how to manipulate and style specific categories of things. In this section the overall format of the rendering of things on the webpage is described. Using this information one can uniquely style any one given thing or device. For example, using the methods in this section it will be possible to style a specific door using a unique icon (such as a barn door), while all other doors use a regular door icon.

To understand how this works it is best to start with defining how all tiles are organized and accounted for. All tiles on the HousePanel webpage follow the following template.

<div id="t-n" bid="swid" class="thing type-thing" p_m >
<div id="s-n" class="thingname type" t_m > tilename </div>
Loop i = 1 to N (
  <div id="a-n-subitem[i]" class="type names[i] {subitem[i]} {status[i]}" >
    content {status[i]}
  </div>
)
</div>


I know this looks intimidating, but it will make sense as we go through each element and the nomenclature. First, everything in bold (except the Loop = 1 to N) is a variable that changes with each thing and sub-item. Second, the type variable is the type of the thing, such as switch, switchlevel, contact, thermostat, weather, or piston. Third, everything inside of curly backets { } is optional and may not be present at all. The rules for what shows up in the file and what doesn't are as follows:

This template now includes a unique integer number prefixed with "p_" where "m" is correlated with the native SmartThings ID number. The latter is a long complex string so it is probably easier to style HP using the shorter p_ number. This "p_" number is used in the customtile.css file to provide the automatic customizations.

The title bar also includes a special class tag starting with "t_" and ending with "m" where "m" is a unique integer correlated with the ST id number. The {names[i]} parameter included in the class name represents the first three whole words taken from the name of the thing. For exmaple if I have a switch named "Kitchen Table Lamp Upstairs" then the class for this item will include the words "kitchen", "table", and "lamp" -- but not the word "upstairs". All words are converted to lower case.

The {subitem[i]} parameter is shown if and only if it is a different word than the thing "type". This is because the thing type is already included in the class name so this avoids listing it twice. The word "value" is also skipped if it is the first sub-type. This is done because subitems named "value" only happen when there is one and only one sub-type.

The {status[i]} value is shown if it is a single state word such as "on", "closed", or "locked". Multiple state values like song titles are not listed in the class. This treatment is used to allow state-specific styling as described earlier. For example, switches that are "on" will have the word "on" included in the class name so that can be used to make on switches look different than off switches.

For example, the full class name of a switch named "Kitchen Table Lamp" that happens to be on will be "div.switch.kitchen.table.lamp.on". If this same light is a dimmer of type switchlevel, the subitem representing the switch itself will have a class name of "div.switchlevel.kitchen.table.lamp.switch.on". Note the addition of the word switch. This is the subitem in the switchlevel thing. The same "switch" word also existed as a sub-item in the switch thing but it didn't get listed twice because the sub-item matched the type so it was skipped.

An important side-note about switchlevel and bulb things. The level sub-item is now rendered as a slider. The previous three part approach is still there but just hidden so you can reveal it if you want. Each hidden level sub-item block looks as follows:

<div class="switchlevel level">
  <div aid="n" subid="level" class="level-dn"></div>
  <div aid="n" subid="level" class="level-val office main" id="a-n-level">75</div>
  <div aid="n" subid="level" class="level-up"></div>
</div>


By default these items are hidden and replaced by a slider that controls the level. The Loop statement is intended to indicate that there are potentially multiple "N" blocks that follow the shown template. For example, in dimmer switchlevel things the value of N is 3 where one sub-item is the switch and a second sub-item is the level. The third sub-item is an indicator light that is hidden by default. More complex tiles like Weather tiles have more sub-items so N will be larger.

Finally, the parameter "n" shown in the template is a unique number assigned to every visible element on screen. This is the number that you must use if you want to style a specific thing to look different than all other things of the same type and capability. You can find this unique number by inspecting the visible thing in your browser or by revealing the source code. Warning - the screen will be very messy if you use the source code method. Once you know this number you can style any specific sub-item using "#a-n-subitem[i]" or you can style the entire tile using "#t-n" or "div.p_m" where "m" is the id number. Note that the first option is an "id" based styling in CSS and the id can change as you add and remove devices. The div.p_m is a better approach because it will be more stable as you add and remove items.

Manually Renaming, Adding and Deleting Pages

NOTE: This is no longer necessary because pages can be edited now using the TileEditor, and multiple user configurations are handled automatically. The following instructions will still work for those wanting more fine grained control.

Power users can also edit room names manually by editing the hmoptions.cfg file and the default users hm_admin.cfg file. You will find these files in the home directory of your HousePanel configuration. If you are using multiple users, there will be a room configuration file for each user that contains a subset of the master hmoptions.cfg file. That user's file should be edited, not the master. The default user name is admin so if you are ignoring multiple users, edit the hm_admin.cfg file. Otherwise edit the hm_xxx.cfg file where xxx is the username's configuration you want to modify.

This file is a direct write of the room and thing options in "json" format so care must be taken to ensure that your edited file follows strict "json" formatting rules. Note that this file will not exist on your local machine unless you download it first, because it is dynamically generated by HousePanel when you run it for the first time and it is updated every time you make an edit to the options. So download the file and load it into your favorite editor. You will see the names of the rooms listed in two places. You will need to make your desired room changes in both places. When done, save the file and re-upload it to your server. Make sure you update the permissions of this file after uploading to enable writing privileges as described earlier.

The file looks like this.

{ "rooms": 
  {
    "Kitchen":0, 
    "FamilyRoom":1, 
    "LivingRoom":2, 
    "Office":3,
    "Bedrooms":4, 
    "Outside":5,
    "Thermostats":6, 
    "Music":7
  },
  "things":
  {
    "Kitchen":[113,107,193,47,16,50,25,79,87,104,103,139,109,102,168],
    "LivingRoom":[0,2,5,11,12,29,32,41,45,52,53,58,59,76,78,82,84,91,92],
    "FamilyRoom":[1,27,30,34,39,42,54,57,83,88,99],
    "Outside":[7,14,20,23,33,35,36,37,38,46,56,61,65,78,91,118,119,169,170],
    "Office":[10,[44,-25,35],80,101,131],
    "Bedrooms":[24,28,33,17,43,48,51,56,85,86,89,90,167],
    "Music":[60,63,64,68,70,99,100,101,166],
    "Thermostats":[102,167,168]
  },
}    


Actually, the "things" section now looks far more complex because it has tile location and custom names in each item. The "rooms" info will be shown on a single line, and the "things" info will be shown on a second single line, so you need to preserve that too. If you don't know how to preserve this then you should just stick with using the visual TileEditor.

Each item in the "things" list can be a single integer or an array of four integers plus a string. The first integer is the thing index in the master list. If there is an array then the next two integers are offsets where the icon is physically displayed, the last integer is the z-index and the string is the custom tile name. This is normally established dynamically when tiles are dragged around screen but the user is free to edit these.

Important!!! Please be sure to confirm that your uploaded hm_xxx.cfg and hmoptions.cfg files retain read/write privileges after you upload it. Many FTP programs do not retain the permissions of files when they are overwritten. Once you have made this change, you will need to force a re-read of your things and the room configuration. The easiest way to do this is to click the "Refresh" button on the bottom left of the main screen. This will force the app to re-load all of your rooms and things, so your new room setup will be active.

Kiosk Mode

To run HousePanel in Kiosk mode, first you will need to download a good kiosk mode browser. I like the Fully Kiosk Browser for Android or Amazon Fire tablets. For iOS iPAD tablets you will have to research other options. You can also use Safari to then put the page on the iOS desktop to create a Kiosk effect. Once you have that then turning on kiosk mode will remove the Options button from the bottom of the options page. On the options page, select the Kiosk option box. Be aware that once you turn kiosk mode on the only way to turn it back off is to force HousePanel to display the options page again by entering:

yoururl/housepanel.php?useajax=showoptions

Using HousePanel as a Web Service or EndPoint

This section is for advanced users who want to use HousePanel as a web service to control their smart homes from other web or desktop applications. The possibilities are quite endless when one enables this, but be warned that such endpoints if exposed to the open Internet would allow anyone to control your smart home, so care must be taken to protect against this. There is a tradeoff between ease of use and security here. The simplest approach is to place your HousePanel app on your home Intranet on the "safe" side of your router and firewall. Then you can feel free to enable the easy access options that will be explained below. But even then nothing is fully secure so an extra precaution one can use is to require the authentication variables to always be provided when using the end point. Then again this means that information is still traveling over your network, so even that isn't fully secure. The bottom line is this feature does create some risk so just be aware of that if you proceed. The reward for this nominal risk is a super rich API that can be called from just about any other application using simple REST endpoint calls. Let me reiterate this point, because it is quite profound! This feature will allow you to write a complex and rich application using modern scripting tools like Python to control your smart home. Keep reading to find out how.

Getting Access and Endpoint Information

To use HousePanel as an EndPoint start by loading HP as usual and then selected "Show Info" from the buttons on the bottom of the page. This will retrieve a page that gives you all the info you need to make the web service call using tools like Python or an EventGhost script. The page returned will look something like this:

HousePanel API Syntax

The syntax for calling the HousePanel API is:

yoururl/housepanel.php?useajax=[doquery|doaction]&st_access=xxxx&st_endpt=zzzz
  [&id=abcd|tile=1234][&hubnum=num][&subid=thesubid]&type=thetype&value=thevalue&attr=theattr


where,
Either id or tile number must be provided, but not both. You also have the option of providing an array of tile numbers or id's separated by commas and each device listed will be acted on in a single API call. The access and endpt values are optional if you have already authenticated HP. Otherwise, you must provide these values on the API command line. To simplify making API calls your computer should be previously authenticated. Note - previous versions of HP stored auth values in cookies. This is no longer done. Instead the auth values are stored on the server in the hmoptions.cfg file so API calls will always work if the hub was authenticated.

Calling the HousePanel API

Once you have the endpoint info above, you are ready to use the API to turn on any switch, query any thing, or do any other action that HousePanel knows how to do. There are two types of API calls: actions and queries. Actions are done using "useajax=doaction" and queries use "useajax=doquery". So one would use the API by submitting REST calls using strings that look like:

yoururl/housepanel.php?useajax=doaction?id=abcd1234...

or

yoururl/housepanel.php?useajax=doquery?id=abcd1234...


Of course you have to use the full id from the list returned by showid. The first call will toggle the switch matching the id. The second call will query any "thing" matching the id. You can use locks, momentary buttons, contacts, thermostats, and anything else supported by HousePanel in the above calls. The examples so far have all used GET but POST works equally well and is more secure as it does not visibly expose your endpoint information.

When you use doaction for something other than a switch you have to also supply the "attr" and "value" variables. You can also provide a "type" variable to speed things up, but if omitted the code will figure out the type automatically. For example, dimmers are set using:

yoururl/housepanel.php?useajax=doaction?id=abcd1234&value=on&attr=40
yoururl/housepanel.php?useajax=doaction?id=abcd1234&amp;attr="level-dn"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&amp;attr="level-up"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&type=switchlevel&value=on&attr=40


Example 1 will set a dimmer to the 40% level. Example 2 will dim the light by 5% and example 3 will raise the light level by 5%. Notice that we didn't have to tell HousePanel the type of thing - it figured that out automatically. Example 4 is identical to example 1 but will run slightly faster since it skips the autotype logic in the code. You will probably not notice the difference. Of course in all of these examples you have to supply the full and correct id number instead of the place-holders shown.

Another option is to provide tile numbers that match the "p_m" values and the code will lookup the complicated "id" nubers noted above. This is now the preferred approach. So rewriting the first example, we would have:

yoururl/housepanel.php?useajax=doaction?tile=12&value=on&attr=40


Thermostat temperatures can be modified similarly as shown below:

yoururl/housepanel.php?useajax=doaction?id=abcd1234&attr="heat-dn"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&attr="heat-up"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&attr="cool-dn"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&attr="cool-up"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&value=heat&attr="72"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&value=cool&attr="76"
yoururl/housepanel.php?useajax=doaction?id=abcd1234&amp;value=heat


If you are using a browser or other tool that can read the REST response, you will receive a json string with the post-action status. The above examples performed on a light dimmer return a string like this: {"switch":"on","level":75}.
More complex things return longer json strings. For example, thermostats will return the following type of result:

{"temperature":75,"heat":68,"cool":72,"thermofan":"fanAuto","thermomode":"cool","thermostate":"cooling"}


All things can be queried using doquery, but only types that can be clicked or tapped on in the HousePanel web app support doaction. One important exception is motion sensors. To support the use case where one might want to "fake" the activation of a motion sensor, the API supports sending "active" or "move" in the value parameter. This will set the motion device type to active. Any other value sent will set it to inactive. For this bit of magic to work, you must use a custom Motion Sensor device type for any motion sensor that you want to trick this way.

The custom device type is called MotionZwaveManual.groovy and is found in the main folder of the HousePanel GitHub. Note that this only works on Zwave motion sensors so please don't try this on the SmartThings ZigBee based motion sensors.


One of the exciting things about this feature is it enables one to control their smart home from apps like EventGhost. With this feature you can now tie HousePanel to any event invoked by your PC via the EventGhost application. For example, I use this to fake my office motion sensor to think I am moving around in my office when I am typing.

If you are the adventurous type you can skip EventGhost and write your own Python application that interacts with your Smart Home. For example, you can use the more flexible features of Python to write your own custom smart applications complete with any logic you like to control your home. For me I much prefer the logic and syntax of Python over Groovy so this will become my scripting tool of choice for implementing sophisticated smart home features.

The possibilities are endless.