From eBower Wiki
Jump to: navigation, search

Unhappy with the security around the INSTEON Hub, I decided I wanted to front end it with a secure, modern webserver. I made the following assumptions:

  • I don't want to deal with password management, I want to use an OpenID(-like) solution.
  • All webservers should be TLS encrypted, even if there is no secure content.
  • I have a webserver on my home network that's world-accessible.
  • The webserver is a modern Linux system running php5.
  • I can either attach the Hub to a dedicated network on my webserver or rely on my router to filter traffic to it from only acceptable IP addresses.
  • I use an original Hub, however most of the code is abstracted that adding support for other controllers (or even WEMO via the ouimeaux libraries) should be easy enough.
  • The only browser I tested with is Chrome, but much of it is basic Javascript/HTML so other browsers should work.


I'm assuming you've got a webserver up and running with php5:

sudo apt-get install apache2 php5 curl

Run the following and put the files into /var/www/insteon/ or the directory of your choice.

git clone

Go into the insteon directory and run chmod 755 insteon.

Edit insteon.conf to include your Hub information.

Edit insteon.ini, we're mostly interested in the [devices] section as of now. You can delete the sample entries, the format is:

A short form of the device name, keep it small, unique, and one word. This is no longer used except as a key.
The INSTEON ID, usually printed on the device or visible from the app. Use a format that's not mistakable for a number, like xx.xx.xx or xx:xx:xx.
The product code for the device, visible from the app and provides a way to identify the type and version of the device. Today I just use this to determine if the device is a dimmer or one of my fan modules, but in theory device-specific icons and behavior are possible. You may use a device_details value of "pc" for a Wake-on-LAN enabled PC.
What will be displayed in the UI. Avoid commas, but most other characters should be fine.
Either true or false, determines whether clicking the Away link will turn off the device. For example, leave the grow lights on but turn off the closet lights.
A short version name of the room in which the device resides.

You can also edit the [other_services] section to choose whether to display links to other home automation sites.

Move both insteon.conf and insteon.ini to /etc/. You should now be able to run the insteon shell script manually to make sure you can see the status of your devices.

Wake on LAN Dependencies[edit]

If you want to use the Wake on LAN features, you'll need to install the following:

sudo apt-get install nmap etherwake

Now you'll need to make it so anyone can use etherwake, by default root-only. This has some amount of risk, so beware:

sudo su
chmod +s /usr/sbin/etherwake

Google+ Authentication[edit]

I've moved this section to Google Plus Authentication.


Just open it up and you'll see a web page that displays a summary of all of your devices broken down by room. I default to four per row, but you can change this by editing $dev_per_row in insteon.php. The icons are designed to give you a nice, intuitive overview with basic black shapes differentiating between fan controllers and light controllers. There's an off-white circle that appears if a light is on, it will be filled with the level of the light if it's a dimmer. Fans will be animated if they're on, with a fan level indicator in the lower right.

Error creating thumbnail: File missing
Error creating thumbnail: File missing

The page is just a snapshot in time, it doesn't automatically update. However in the upper right is a blue refresh icon that will update that device. Updating all devices at once is easier with a page refresh.

Clicking the green power icon in the lower left of the device will bring up a device-specific remote. Clicking buttons should work in (near) realtime and the device will be refreshed when you close the remote (by clicking off the remote).

I also now support pulling data from your Nest account:

Nest Data Example

Here we see that the current temperature is 77°F, the set temperature is 71°F, the fan is on, and the Nest is set to Away. This assumes at most one Nest per room and there are icons for heating and cooling. The Nest data is like the device data, a snapshot in time rather than a polled refresh mechanism. However, I do refresh the Nest data with every device refresh because it's fairly lightweight and doesn't cause affect the Hub polling at all.

File Descriptions[edit]

This section describes the various files included with the package.

Support Files[edit]

A shell script I wrote to control INSTEON devices. I use this as a standalone module as well.

This is the script that I started out with, primarily because setting a cron job is easier than configuring scenes and schedules.

Web Code[edit]

A very basic landing page that displays the login button.
A transitional page that parses the data the Google+ login gives, authorizes the user, and sets the session. It also displays the login failed message.
The main page to render the screen.
The primary JavaScript for the page.
Edit this to change the formatting of things.

This is the basic application.

API Calls[edit]

If you've got a PHP session active, it will pull the light level of device_id. Note that "on" will return 100 and "off" will return 0.
If you've got a PHP session active, it will pull the fan status of device_id. Output should be off, low, medium, or high.
Sets device_id to value - you can call this directly (once you're logged in and have a session active).
Like set_light.php but sets the fan status.
Shows the current state of each nest.
Will attempt to see if the PC has an IP address and responds to pings.
Well send a wakeup message to the PC.

I could have done this a bit better, more PHP-contained rather than simply a callout to a shell script (sort of like now nest.php is structured). But I already had the script and I'm lazy. It does check if a session is active, so using curl directly isn't easy (and something I'd just do via the shell script), but it should be easy enough to modify if you want other security.

Note that the status API calls will return text beginning with ERROR if there is a failure of some sort. Check the JavaScript console for details if an error icon appears.

Config Files[edit]

The configuration for the insteon shell script. It can also be placed in ~/.insteon.conf but for www-data that's a little tougher.
The configuration for the web-based controller including the user and device database.

Two files since insteon is also a standalone app. You may need to update insteon.ini every time you add or replace a device, but I'm assuming that's not often. As a side effect, it also stores the device ID someplace, useful if your Hub goes wonky. Note that I don't bother storing devices that I can't control or that are directly controllable. This includes the 6-button keypads that control the fans.

Both config files should be moved to /etc/, if they're left in-place they could be downloaded. While they don't contain hugely sensitive data, better safe than sorry.

Image Files[edit]

The standard light (meaning !fan) backdrop, defaults to a black vector art light bulb.
The standard fan backdrop, a four-blade ceiling fan.
An off-white circle positioned over the center of the light or fan backdrops.
An animated fan used when a fan module has a status not equal to off.
fan-low.png, fan-medium.png, fan-high.png 
Used to show an increasing number of bars for the fan speed. Note that fan-off.png is not part of this sequence since a fan that's off doesn't get a speed icon.
The image displayed at the lower right when the device information is being loaded.
The icon in the upper right to refresh the device information.
The icon in the lower left to bring up the remote.
An icon displayed in the lower right if there is an error getting the status.
nest.png, dropbox.png 
Sample logos that can be used to generate links to related services. Check out insteon.ini for examples on how to use them.
Away icon to batch turn off devices and as a Nest indicator.
hvac-heat.png, hvac-cool.png, hvac-fan.png 
Nest-related icons to show current state.
An image of a PC with a blank screen.
An image of a window and mouse cursor.

Each of these files is automatically resized, in theory you can just swap them out for other files and things should just work. All files should be roughly square in aspect ratio or you may get scaling issues.

Bugs and To-Do List[edit]

Things I want to add/fix:

  • I display dimmer information but I don't allow setting anything other than on/off.
  • Away mode seems to enable things simultaneously, this should be changed to sequentially.
  • CLEANUP: I've got a lot of silly prints which would be more readable as a heredoc.
  • Away mode doesn't set the Nest to away. But if I set the Nest to away I need some way to setting it back.
  • I support these outdated Fahrenheit units, I don't know why... At least if you have the Nest set to C it will report appropriately.
  • When the Nest is away I still show the non-away temperature setting. I don't know if this is confusing or not...
  • I refresh the Nest temperature with every device refresh, I should show an icon when this happens.
  • When there's both a fan and light status error I only show the fan error.
  • The device database is now a lot more complex than when I started, I should move it to some sort of multi-dimensional array.

Things I'm not sure I care about:

  • On Android devices some light icons appear off-center.
  • There is no support for scenes or adding devices. This is not something I use so it may be a community-driven feature.