Insteon Hub HTTP API for Insteon | LeftoverCode.info

Insteon Hub HTTP API for Insteon | LeftoverCode.info

The Insteon Hub and SmartLinc 2414N HTTP API for Insteon Devices

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.

Objectives

After reading this document, you should be able to control an InsteonLampLinc 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.

Introduction

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.

Credits

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.

Assumptions

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 0E.A7.22.

First Steps

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!

Turning On

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 0EA722:

curl http://172.30.1.101/3?02620EA7220F11FF=I=3

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:

• HTTP Resource: We're using the /3 resource on the web server. (If this confuses you, you can think of it like a page called "3")
• Direct Command Flag: Indicates we are sending a direct command. (As opposed to scene commands that control groups of devices.)
• Device: The hardware address of the device we want to control.
• SD Flag: Indicates we are sending a standard command, not an extended command. (Don't worry about extended commands, we won't be using them)
• Command: The command we are sending to the device. (11 is the command for "ON") I've only found five supported commands, which we'll see in a minute.
• Level: The Brightness level we want the device to be at. (FF is 100%) We'll see how these are constructed in a minute.
• Unknown? I haven't been able to find out what =I=3 represents, 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.

Information Needed
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:

curl http://172.30.1.101/3?02620EA7220F11FF=I=3

Turning Off

Now let's turn the lamp off by sending the command 13:

curl http://172.30.1.101/3?02620EA7220F13FF=I=3

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.

Commands

I mentioned earlier that there are five direct commands we'll be working with. They are:

Code	Command	Description
11	On	Turn device on, ramping up
12	Fast On	Turn device on immediately (no ramp)
13	Off	Turn device off, ramping down
14	Fast Off	Turn device off immediately (no ramp)
19	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.

Information Needed
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.

Levels

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:

Level Chars	Percentage
00	0 %
40	25 %
7F	50 %
BF	75 %
FF	100 %

You can specify any value from 0-100% by inserting the appropriate hexadecimal value.

Why Hexadecimal?
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.

Combining Levels and Commands

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 Device Status

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 19 (status):

curl http://172.30.1.101/3?02620EA7220F19FF=I=3

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?)

curl http://172.30.1.101/buffstatus.xml

The buffer request will return an XML response like this:

<response><BS>02620EA7220F117F0602500EA72216A9442B117F</BS></response>

Gotcha Warning!
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.

Decoding the 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:

• Last Command: The last command sent to the target device
• Response Flag: Indicates success (value 06) or failure (value 15)
• Return Flag: Indicates that this is a return message
• Target Device: The device you are querying
• SmartLinc: The device that sent the response (should be the SmartLinc address)
• Ack: Some kind of acknowledgment (should be a value 2)
• Hop Count: Not sure, but the value should be B, F, 7, or 3
• DB Delta: When a device's value changes, this value increments. (Not sure how this is useful)
• Level: The current level of the device.

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.

Conclusion

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.

Useful Links

I found these links extremely useful while putting this document together:

• SmartHome Wiki: Using Custom Commands in SmartLinc
• SmartHome Forum: SmartLinc Direct Command for Light Status?
• SmartHome Forum: Custom Screens on the SmartLinc
• SmartHome Wiki: Insteon Command Table
• Smarthome Forum: SmartLinc web automation solved
• SmartHome Forum: 2412N Insteon Central Controller - Software
• Ramp Rate
• Insteon Commands