Note: This document was originally written for the SmartLinc 2414N controler. I have been told the same API works for the Insteon Hub, but I have not confirmed this myself. If someone wants to send me one, I'll be happy to verify!
The SmartLinc 2414N Insteon Central Controller has a built-in HTTP server and can accept direct commands via HTTP to manage Insteon and X10 devices. Unfortunately, the API is barely documented and cryptic. With some knowledge of the basic commands, you can use your favorite HTTP library to control Insteon devices on your network.
After reading this document, you should be able to control an Insteon LampLinc device via HTTP commands, turning it on, off, changing its level, and getting its status.
Note: It is possible to control X10 devices, but that is covered in a separate document.
If you've purchased the SmartLinc, you've probably seen that the mobile-optimized HTML pages sport some of the ugliest design you'll ever see. Not only are they painful to the eye, the navigation is frustratingly unintuitive. Even after multiple uses, I still find myself hunting and fumbling around through the esoteric icons trying to find the control I'm looking for.
Luckily, this isn't why I purchased the SmartLinc. I love HTTP and I was very excited about the possibility of turning the controller into an HTTP interface to my Insteon network. I've been mildly successful so far, considering the documentation for this is nonexistent. Through a lot of reading and posting on the SmartHome forums, I've been able to pull together the commands needed.
Most of the HTTP commands I've figured out was by piecing together the hard work of others, especially the active contributers on the SmartHome forums and Chris Karr from the fantastic Insteon software Shion. I'm just trying to document everything I've read in a single place. Chad Wackerman was extremely helpful in getting me started.
Also worth noting, I am not a registered Insteon developer and I have not gained any of this information from proprietary materials.
If you are reading this, I assume you have a basic understanding of the HTTP protocol. (If you understand the difference between a GET and POST, you're probably all set) I'm going to use cURL for all my examples so it will be easy to try on many platforms. It should be very easy to take the examples and port them to the programming language of your choice.
If you don't have (or don't like) curl, you can just type the commands into a browser. I find this to be slower when you get to checking the device status, since you'll have to view the source to see the response it sent back.
All the examples will use an IP address of
172.30.1.101, so substitute your device's IP address as needed. I'll be using a LampLinc for the examples with a hardware address of
Let's start off with some instant gratification by sending some commands to the SmartLinc with curl and seeing a light go on and off. I have a LampLinc plugged in at my desk with a night light plugged into it. If your module is in a different room, I can tell you from experience that it's extremely frustrating to type a command then have to get up and walk into the other room to see if it worked!
Let's start with a simple command to turn on the lamp. We do this by calling the
/3 URL on the device followed with a bunch of characters representing the device you are controlling and the command you are sending. This one turns on my device
Let's break this into pieces that are easier to read:
http://172.30.1.101/3? 0262 0EA722 0F 11 FF =I=3 HTTP Resource + Direct Command Flag + Device + SD Flag + Command + Level + Unknown?
Broken down, we have these pieces:
=I=3represents, but I the commands don't seem to work without it. I don't worry about it, since it goes on the end of all the URLs we will use.
If someone knows what the
=I=3 part of the URL represents, please let me know so I can update this document.
Of all these pieces, the only ones we will change are Device, Command, and Level. The bolded parts of the command below should give you a better idea of where we'll be working:
Now let's turn the lamp off by sending the command
You might be wondering why we send the command
13 (representing "off") and a level of
FF (representing 100%). Why would we send 100% for off? To the best of what I can tell, the level has to be something valid, even though it's ignored. We could have sent
00 and seen the same result.
I mentioned earlier that there are five direct commands we'll be working with. They are:
||On||Turn device on, ramping up|
||Fast On||Turn device on immediately (no ramp)|
||Off||Turn device off, ramping down|
||Fast Off||Turn device off immediately (no ramp)|
||Status||Get the current status of the device (returns level)|
The commands that ramp will nicely fade from off to on (or vice-versa). Using the fast commands will immediately turn on or off.
Status is a funny command because you can't just call it and read the response. We'll see why in a section below.
If anyone knows of more commands that the SmartLinc supports, please let me know so I can document them! These are all I have been able to make work so far, mostly from the SmartHome Wiki page INSTEON Translation Table.
Similar to the commands above, we have a few levels we can send with our commands to change the brightness level. Unfortunately, we cannot send the level as a simple numeric integer, they are represented as hexadecimal values from 0 to 255. Here are some common levels I use:
You can specify any value from 0-100% by inserting the appropriate hexadecimal value.
I can't speculate why it was designed this way, but by using hexadecimal codes for level, they all nicely fit into two characters. I'm not going to explain binary math here, but you can read all about it by Googling binary to hexadecimal.
With this knowledge, we can use these four commands and five levels to set our device:
curl http://172.30.1.101/3?02620EA7220F11FF=I=3 # Turn Device 0EA722 On (w/ramp) curl http://172.30.1.101/3?02620EA7220F13FF=I=3 # Turn Device 0EA722 Off (w/ramp) curl http://172.30.1.101/3?02620EA7220F12FF=I=3 # Turn Device 0EA722 On (no ramp) curl http://172.30.1.101/3?02620EA7220F14FF=I=3 # Turn Device 0EA722 Off (no ramp) curl http://172.30.1.101/3?02620EA7220F117F=I=3 # Turn Device 0EA722 To 50% (w/ramp) curl http://172.30.1.101/3?02620EA7220F117F=I=3 # Turn Device 0EA722 To 50% (no ramp)
Getting status is pretty tricky because we have to make a couple URL calls to get it. (Yeah, it sucks!) We start by sending the command
Notice that we sent a the level
FF with the command. You can send any valid level, it's required but ignored.
You'd expect that this would return the status, right? Unfortunately, no. We send the command and we'll see nothing happen. We need to check the device's buffer for the value. (Ugh. Really SmartLabs? You couldn't have made this easier?)
The buffer request will return an XML response like this:
If you are making these calls with a program or script, you must wait about 500 milliseconds between the status request call and the buffer request. If you don't, you'll get some weird gibberish response.
Since all the responses will be wrapped with <response><BS> and </BS></response>, we'll omit it below. Here's how the response is composed of these parts:
02620EA7220F117F 06 0250 0EA722 16A944 2 B 11 7F Last Command + Response Flag + Return Flag + Target Device + SmartLinc + Ack + Hop Count + DB Delta + Level
Broken down, we have these parts:
06) or failure (value
That's a lot of work just to get the level! In practice, I really just check the length of this message (to make sure it's not a garbage response) and then look at the last two characters to get the level.
My Plea to SmartLabs
This two-step process to retrieve device status is a real bummer. Not only is it a pain, but with the required delay, it's extremely slow to retrieve the status of all the devices. This could be SO much better if we could make a single call and get back a response.
I hope you found this documentation useful. The SmartLinc is a cool, though very limited, device. There's no way (that I know of) to be able to respond to device events on your network, such as a motion or contact sensor. (If you need this kind of functionality, here's a shameless plug to my friend Chris' fantastic software Shion that does this and more beautifully)
If anything here is unclear or incorrect, please contact me (snewman18 at gmail dot com) and I'll fix it ASAP.
I found these links extremely useful while putting this document together: