-
Notifications
You must be signed in to change notification settings - Fork 26
Home
House Panel web service PHP application for SmartThings
author: Ken Washington (c) 2017
- switches
- dimmers
- momentary buttons
- contact sensors
- doors
- thermostats
- lights
- locks
- bulbs
- water sensors
- valves
A number of special tiles are also supported, including:
- time
- weather
- mode
- routines
- WebCoRE pistons,
- blanks
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 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 page - we will show how to do this later.
House Panel is a web application written in PHP that is paired with a SmartThings SmartApp written in the groovy language. Obviously you will need a SmartThings 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 666 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 "666" 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 of course is you can't access your home unless you are at home on the same network. This can be a big restriction but many people don't control their 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.
ssh in as username = pi and password = your-password
modify /etc/defaults/keyboard to be a "us" keyboard and not the default "gb".
Next several lines will install the Apache and PHP applications you will need on 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 rpi-update
Next 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 you have that
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();
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 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 your web server was not installed correctly and it will need to be addressed before you can proceed.
Start with installing the HousePanel.groovy file in your SmartThings smartapp IDE repository. Unfortunately I was not able to get the IDE install option to work with my account so you will have to install this manually. First, go to my GitHub "kewashi" account and copy the "raw" code. Do this by browsing to:Navigate down to housepanel.src/HousePanel.groovy Open this file and then click on the "raw" icon in the upper right corner. This will open a window showing just the lines of code. Copy the entire file 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".http://github.com/kewashi/HousePanel
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 tweaks 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, I would appreciate seeing them via a pull request.
Before you leave the ST IDE, you will need to enable OAUTH2 in the IDE app settings. To do this, select App Settings then turn on OAUTH2 in the options that show on the lower left of the screen. 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. In this step you will install the PHP application by copying the files from the following GitHub into a directory of your choice: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.http://github.com/kewashi/hpanel-server
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 tweaks 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 want edits have been made
using visual cues.
The final install step is to edit the file named "clientinfo.php" This file has placeholder data in it for your CLIENT_ID and CLIENT_SECRET constants that must be obtained from your installation of housepanel.groovy. You will find that information in the SmartThings IDE as described in the previous section. The clientinfo.php file will look like this:
<?php
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('TIMEZONE', 'America/Detroit');
// 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);
You must put your own CLIENT_ID and CLIENT_SECRET information into
this file and then re-upload it to your web server. Note that 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.
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. The TIMEZONE can also be updated in
this file to reflect where your house is located. The times displayed will
always be shown in this time zone.
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.
This step ensures that your web server can create and update as needed an options file that is generated dynamically when you run the 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 666 /var/www/htdocs/housepanel". Replace the directory name here with where your Apache stores html files and the name of your install directory. If you have made it this far, you are ready to do an initial test. Before you do, let's review to confirm that you have the following set up. If you don't go back to the section noted and complete that step:- Web server set up with PHP configured
- Confirmed that cUrl is activated in your PHP
- HousePanel.groovy installed in your SmartThings IDE with OAUTH2 activated
- clientinfo.php file updated to include your CLIENT_ID and CLIENT_SECRET real information
- hpanel-server files uploaded to its own directory on your web server
- the directory above configured to read/write using "chmod 666 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, Microsoft Edge, IE 11, Safari on mac, and Fully Kiosk Browser on PC. All have been confirmed to work but others are likely to as well. 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 can proceed to the next section on how
to operate HousePanel. If not, please post in the community form what error
you are seeing and either I or other users will assist you.
When you first run HP it should look something like:
TODO: include image
If you have used other Web-based SmartThings apps this 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 that
looks something like this:
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 all save 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 it you will get 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 mapped 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.
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"
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.
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 "Rock Waterfall" to the Outside room, and removed the "Garage Entry Door" from the Outside room. I also added the appropriate motion and door sensors to the right rooms. Finally, I also made a new room just for my thermostats. The following section explains how to do that.
The most important type of customization is performed by either creating your own custom style sheet or editing the provided on 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 hpanel-server. 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');
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.
All things displayed in HousePanel inherit the syling 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: 0px solid #cccccc;
border-right: 0px solid #cccccc;
border-bottom: 0px solid #ffffff;
border-left: 0px solid #ffffff;
background-color: rgba(0, 51, 204, 0.6);
box-shadow: 2px 2px 7px black;
color: #eeeeee;
cursor: default;
width: 120px;
height: 160px;
}
div.switch {
width: 118px;
height: 112px;
}
This would just style the switch portion of the tile. Each tile also has a title 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');
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 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. Same applies to all complex tiles. The following styling from the default file presents the temperature reading inside of 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%;
}