Home
House Panel Open Source Web App for SmartThings
Ken Washington (@kewashi) (c) 2017
This wiki is out of date. Current up to date documentation is being maintained on the integrated github webpage located here:
https://kewashi.github.io/HousePanel/
HousePanel (HP) is the 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. HousePanel is the primary app of the Open-Dash open source community.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 involve editing a CSS file. HP runs on a customer-provided web server and does not expose your personal data nor any details about your SmartThings environment to the developer or any other party. You are in total control. The default settings are designed by a professional web designer to create a highly acceptable user interface for non-technical people. This was the motive for writing HP in the first place. It is designed to not look and feel "geeky". By default the tiles are large and colorful, placed on beautiful full color backgrounds. Finally, a more advanced application 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.
HousePanel can display and/or control most types of things in the SmartThings ecosystem, including:- switches
- dimmers
- bulbs
- lights
- momentary buttons
- contact
- doors
- locks
- thermostats
- temperature sensors
- motion sensors
- water sensors
- valves (sprinklers)
A number of special tiles are also supported, including:
- Smart Home Monitor
- blanks
- clock
- images
- mode
- routines
- weather
- iFrame web pages
- WebCoRE pistons,
- video
- custom
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.
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 we use jQuery to make this efficient. This means that any
number of user 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. The default is 6 pages and each page has a fixed name. Pages can be
easily renamed from within the web app. We will show how to do this later.
Finally, for advanced users HousePanel is a highly flexible API that can serve as a web service to access your smart home devices from anywhere. This only works for SmartThings items and is ignored for Hubitat connected devices. This feature requires users to make intelligent decisions about the tradeoff between ease of use and security. By default, using this capability requires each API call to include multiple fairly complex URL-encoded security codes. HP can be set up to override this by hard coding these codes into the configuration file. Instructions for doing this are in the advanced section of this Wiki.
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. To use Housepanel you will need a modern browser with Javascript support. 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. You should also have access to a good CSS editor that you will use 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. This option is perhaps the simplest and provides the most flexibility, but less security and speed than the other two options below. To use this option you need to simply 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.This option has great flexibility and speed as well as more security over a public facing web server. It is more 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.
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". Enter the next several lines to install the Apache and PHP applications onto the rPi.
sudo apt-get update sudo apt-get -y upgrade sudo apt-get -y install apache2 php5 php5-gd wiringpi raspi-gpio rpi-update --fix-missing sudo apt-get -y install curl sudo rpi-update
Next, you need to configure PHP to use cUrl. This should be on by default,
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:
Before proceeding I highly recommend that you test your web server and confirm that it works with PHP and cUrl. To do that create a simple file with just the following in it:sudo service apache2 restart
<?php
phpinfo();
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.
There are two groovy files that are used to operate HousePanel - one for SmartThings and one for Hubitat. The SmartThings version is call 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 Hubitate IDE on your local LAN.- SmartThings - 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.
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.
- Hubitat HousePanelHubitat.groovy
Note that you can install either the SmartThings or Hubitat apps 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.
The Hubitat app has an option for using only Hubitat that you can select when
you add the instance of the app to the Hubitat system. This means the ST auth flow
will be skipped. When a HousePanel app instance is created the credentials for Hubitat
will also be automatically pushed to the web app. This only works if your web app
is up and running already, so you should do the next step first.
A typical place would be in its own directory called /housepanel. Be sure to preserve the directory structure when you download and then upload the files to your web server.https://github.com/open-dash/HousePanel
As with the groovy file, 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, so you can skip this section. If you proceed and create this file, it will supercede any parameters you provide in the app. The clientinfo.php file is where you can provide your CLIENT_ID and CLIENT_SECRET constants from the installation of housepanel.groovy. You will find that information in the SmartThings IDE as described in the previous sections. The clientinfo.php file will look like this:
<?php
define('TIMEZONE', 'America/Detroit');
define('CLIENT_ID', 'a1b23aa1-a123-123a-b12c-12345abc1234');
define('CLIENT_SECRET', 'a123456a-bc12-1212-123a-a12312312312');
define('ST_WEB','https://graph.api.smartthings.com');
// define these to use a locally hosted Hubitat hub
// the first is the Host IP number or name
// the ID should replace ## and can be obtained from your hubitat login page
// if you don't have a hubitat hub leave these set to false
//define('HUBITAT_HOST',"http://192.168.1.50");
//define('HUBITAT_ID',"##");
//define('HUBITAT_ACCESS_TOKEN',"1234blahblahblah");
// provide the access_token and endpt values below if your browser does not support cookies
// this can also be used to skip the authentication step if you are operating in a secure internal environment
// *** WARNING *** do not do this if your website is exposed to the world and discoverable via search
// doing so will enable anyone in the world to control your home
// the access_token and endpt information can be obtained by going through authentication once
// and then loading your webpage using mypanel.com/housepanel.php?useajax=showid
// this will return a page with the access_point and endpt data plus other info about your devices
define('USER_ACCESS_TOKEN',FALSE);
define('USER_ENDPT',FALSE);
define('USER_SITENAME',FALSE);
The first parameter to set is TIMEZONE to reflect where your house
is located. The times displayed will always be shown in this time zone.
If you are using SmartThings, you must put your own
CLIENT_ID, CLIENT_SECRET, and ST_WEB information into
this file and then re-upload it to your web server.
This information is obtained from the ST IDE where you uploaded
the HousePanel.groovy app and enabled OAUTH2.
The ST_WEB variable can also be changed here if your IDE is at a different location
which will be the case if you are in Europe. If you are running a Hubitat-only installation these parameters
can be set to false in this file. If that is the case the Hubitat
parameters described below must be defined.
The information in the above sample is fake data and will not work
without being changed to include your real OAUTH2 information. Again,
you find this information in Step 2 above in your SmartThings IDE.
If you are not using SmartThings just put false here and ignore the rest.
If you want HousePanel to read your Hubitat devices, you must provide
valid values for the following parameters:
HUBITAT_HOST, HUBITAT_ID, and HUBITAT_ACCESS_TOKEN. These are obtained
from the Hubitat webpage on your mobile. The only tricky one is the last one
which is displayed once you activate Hubitat..
For now you can ignore the last three variables. These will be discussed later when we explain how to customize HousePanel or how to use it as a GhostScript endpoint or as a generic SmartThings web service. The comments provided in the sample file above should give you a pretty good hint as to what these options are for and how they are used, but don't worry, we will explain this in detail later.
This step ensures that your web server can create and update as needed an options file that is generated dynamically when you run the web App. 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 1 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 666 /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 3 - Raspberry Pi - then your best option is to SSH over to the Raspberry Pi and then use the Linux command "chmod 777 /var/www/htdocs/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. If you have made it this far, you are ready to do an initial test. Before you do, let's review things to confirm that you have the following set up. A lot of people have forgotten the cURL step, so don't forget that. If you are missing anything, you should go back to the relevant section and complete that step:- Web server set up with PHP configured
- Confirmed that cUrl is activated in your PHP
- either... HousePanel.groovy installed in your SmartThings IDE with OAUTH2 activated
- and/or... HousePanelHubitat.groovy installed in your Hubitat IDE with OAUTH2 optionally activated
- either... clientinfo.php file includes your CLIENT_ID, CLIENT_SECRET, and ST_WEB for SmartThings
- and/or... clientinfo.php file includes HUBITAT_HOST, HUBITAT_ID, and HUBITAT_ACCESS_TOKEN for Hubitat
- open-dash/HousePanel files uploaded to its own directory on your web server
- the directory above configured to read/write using "chmod 777 yourdirectory"
- Web browser with javascrpt and cookies enabled
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 table),
Microsoft Edge (on a Windows 10 PC),
IE 11 (on a Windows 7 and Windows 10 PC),
Safari (on a Mac and iPhone), and Fully Kiosk Browser (on PC and an
Android tablet). All have been confirmed to work but others options are
likely to work as well. Fire tablets work as well but videos don't reload.
Chrome and Edge appear to work best and are fastest. 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 challenge. If this happens, congratulations - you are ready to proceed. If you are using a Hubitat only installation there is nothing else to do. All supported devices will just simply show up as options to include. If you selected Hubitat only then you will not get a prompt to authenticate ST; instead HP will just show your things on the Hubitat side. The authentication page is where you will provide the CLIENT_ID and CLIENT_SECRET information from the SmartThings OAUTH settings. Once these are provided, the app will redirect you to SmartThings to authenticate. Note that if you provided a clientinfo.php file, these values will be pre-populated.
If you have used other Web-based SmartThings apps HousePanel should look familiar
to you. This is where you provide your credentials. This should be the
same username and password that you use to access the SmartThings Web IDE
and your 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 3 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.
Once you have authenticated using your credentials, HousePanel 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, all of the supported things will be shown in a list.
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, which will be everything shown. In my
installation the only thing I didn't include is 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 everything and you will be good to go. To finish this step click
on the Save button at the bottom of the screen. This will be the moment you
waited for...
What happens next is control is returned to HousePanel and the app starts by
reading all things and their states that you selected. 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 that is saved on your
server. In our example case, it
will be stored in: "http://192.168.1.50/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. As it turns
out it will actually run just fine even if it can't create this file, but each
time you run you will see the same default configuration. 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 getOptions subroutine roughly around line 700. 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. We'll also discuss how to add or delete rooms in a later section by editing the hmoptions.cfg file directly.
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"
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 door, it will open. However, not all things support state changes from HP. Door and motion sensors for example are display only tiles so clicking on them will do nothing. Same for the clock and blank tiles. Tiles that support mode changes include switch, dimmers, doors, mode, routines, thermostats, and music tiles. If you are using a computer, the cursor will change to a pointer when you hover over thing tiles that can be clicked on to change state. Other thing tiles will remain an arrow icon.
Dimmer, 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 clicke on. On dimmer tiles you change the intensity of the light by clicking on the up or down arrows. When you do this the light will always come if it is off.
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, click and hold down any tile and then move it. It will move with you. Release it and it will permanently be relocated to that spot. Note: this will only be permanent if your hmoptions.cfg file is read/write. You can apply this same maneuver to page tabs. Simple 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. Deeper customization involves adding or removing things to your rooms. To do this scroll to the bottom of the page and click on the Options button in the lower left corner of the page. This will load a page with a two-dimensional matrix of all your things and all you rooms that looks like this:
Everywhere you see a check mark, that means the thing of that "row" will be shown in the room of that "column". 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. Finally, I also made a new room just for my thermostats. The following section explains how to do that.
Thanks to some amazing work done by @nitwit in the SmartThings community HousePanel can now be edited from the Options page by clicking on the Edit button for some tiles. For these tiles this action will bring up a self-explanatory dialog box that will allow users to select the on or off icon for that tile as well as the background color and text formatting. 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 the standard Smartthings library. We 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 this feature HP will create a file named "customtiles.css" containing the styling information selected in the dialog box. This file should not be edited directly. 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. The most 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 into your 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 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);
-moz-box-shadow: 0px 0px 41px rgba(0, 0, 0, 0.50);
-webkit-box-shadow: 0px 0px 41px rgba(0, 0, 0, 0.50);
}
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');
}
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;
}
div.switch {
width: 118px;
height: 112px;
}
div.thing.switch-thing {
background-image: url('mycat.jpg');
}
div.switch.on, div.switch.light.on, div.switchlevel.on, div.bulb.on, div.light.on {
background-image: url('bulbon.png');
}
div.switch.off, div.switch.light.off, div.switchlevel.off, div.bulb.off, div.light.off {
background-image: url('bulboff.png');
}
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.
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%;
}
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.
The clock special 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 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 using the tags: div.clock.weekday, div.clock.date, and div.clock.time respectively. Unfortunately the actual format of the sub-item fields cannot be modified, but their font, color, size, and placement are all fair game. 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. Four place-holder image tiles are provided for end-user unique styling. These tiles are named "img1" through "img4" and 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");
}
There are some amazing example 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.
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. 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. 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. It can look different in each room because each room 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.weatherWeather 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;
}
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 rendered as multi-part content. Each 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>
The styling of the div.switchlevel.level block by default includes a graphical
icons indicating up and down.
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.
Pages can be easily renamed from the main GUI page in Edit mode.
If you select Edit, each page tab will have a green and a red dot.
Clicking the green dot will enable renaming the page. Clicking the
red dot will delete the page upon confirmation.
Power users can also edit room names manually by editing the hmoption.cfg file.
You will find this file in the home directory of your HousePanel configuration. This
file is a direct write of the room 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
},
"index":
{
"routine|01234717-1234-1244-1234-abcd12341234":197,
"routine|12341234-abcd-1234-abcd-123412341234":193,
"switch|abcdabcd-1234-1234-abcd-123412341234":0,
"switch|1234abcd-1234-abcd-1234-abcd12341234":1,
...
"image|img3":116,
"image|img4":117
},
"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]
},
"skin":"skin-housepanel"
"kiosk":"false"
}
Actually, the "things" section now looks far more intimidating becuase it has tile location and custom names in each item. If you don't know how to preserve this then you should just stick with using the visual editor. The part not shown and represented by "..." is a long list of things with their corresponding unique SmartThings ID's. These should not be edited manually. Finally, each item in the "things" list can be a single integer or an array of four integers plus a string. If the latter, 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 in the hmoptions.cfg file if wanted.
Important!!! Please be sure to confirm that your uploaded hmoptions.cfg file retains 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 load the page with the following:
yoururl/housepanel.php?useajax=showoptions
This will force open the options page which in turn forces the app to re-load all of your rooms and things, so your new room setup will be active.
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 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, type in "true" for the kiosk option text. Only this word "true" will be recognized to turn on kiosk mode. Any other word will leave the Options button active. 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 using the same method described above. Again, this is:yoururl/housepanel.php?useajax=showoptions
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.
yoururl/housepanel.php?useajax=showid
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:
yoururl/housepanel.php?useajax=[doquery|doaction]&hmtoken=xxxx&hmendpoint=zzzz& id=abcd&type=thetype&value=thevalue&attr=theattr
where,
- either doquery or doaction must be provided
- xxxx is the full access_token returned by the useajax=showid call above
- zzzz is the full endpt returned by the useajax=showid call above
- thetype is the type of thing, such as switch, motion, contact, thermostat, etc
- thevalue is a command such as on or off typically
- theattr is a settings value such as a number when dimming lights
If you are fine with providing the access token and endpoint information as command line parameters, or if you authenticated HousePanel on the same computer that you plan to make API calls from (in which case you can skip providing these parameters as they will be read from a Cookie), then you are all set and can skip the next section. Otherwise, keep reading.
To simplify the API calls your computer can either be previously authenticated and have the ability to save cookies. If this is not possible you can save your authentication information in the clientinfo.php configuration file described earlier in the Wiki. The last section of that file looks as follows:// provide the access_token and endpt values below if your browser does not support cookies
// this can also be used to skip the authentication step if you are operating in a secure internal environment
// *** WARNING *** do not do this if your website is exposed to the world and discoverable via search
// doing so will enable anyone in the world to control your home
// the access_token and endpt information can be obtained by going through authentication once
// and then loading your webpage using mypanel.com/housepanel.php?useajax=showid
// this will return a page with the access_point and endpt data plus other info about your devices
define('USER_ACCESS_TOKEN',FALSE);
define('USER_ENDPT',FALSE);
define('USER_SITENAME',FALSE);
The information you need to include here is at the top of the page returned
in the prior call using "?useajax=showid". Just copy and paste that information
into the file above and re-upload it to your server. This will make the API
calls work from any computer that can access your HousePanel website. As an
added bonus this will mean you will never have to re-authenticate, unless
you ask it to from the Options page. If you change the groovy code in the
SmartThings IDE you will need to update this information by call ?useajax=showid
again.
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&attr="level-dn" yoururl/housepanel.php?useajax=doaction?id=abcd1234&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&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, a lock thing when queried using doquery will return something that looks like:
{"battery":83,"lock":"locked"}
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 supportsf
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.