{{ leftover_code }}


The Insteon Hub and SmartLinc 2414N HTTP API for X10 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 X10 devices on your network.

Objectives

After reading this document, you should be able to control an X10 device via HTTP commands, turning it on, off, changing its level, and getting its status.

Note: It is possible to control Insteon 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 with the great documentation in his OpenLinc project.

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 an X10 Appliance Module for the examples with a device code of A1.

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 the X10 Appliance Module 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. These two calls turn on my device at A1:

curl http://172.30.1.101/3?02636600=I=3
curl http://172.30.1.101/3?02636280=I=3

Why two calls? It turns out that you first have to tell the SmartLinc which house code and unit code to use, then a second call to send a command to that that device. (I'm calling a combination of house and unit code a device code).

Let's break this into pieces that are easier to read:

http://172.30.1.101/3?    0263               6            600         =I=3
HTTP Resource           + X10 Command Flag + House Code + Unit Code + Unknown?

http://172.30.1.101/3?    0263               6            280       =I=3
HTTP Resource           + X10 Command Flag + House Code + Command + 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")
  • X10 Command Flag: Indicates we are sending an X10 command.
  • House Code: The house code of the device we want to control. (see mappings below)
  • Unit Code: The unit code of the device we want to control. (see mappings below)
  • Command: The command we wish to send. (see mappings below)
  • 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 House Code, Unit Code, and Command.

Turning Off

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

curl http://172.30.1.101/3?02636600=I=3
curl http://172.30.1.101/3?02636380=I=3

Mappings for House Code, Unit Code, and Commands

Each house code, unit code, and command has an associated value.

House Codes

House Code Value
A 6
B E
C 2
D A
E 1
F 9
G 5
H D
I 7
J F
K 3
L B
M 0
N 8
O 4
P C

The column on the left shows which house code corresponds to the value on the right. For example, if you want to use a house code of A, you would use the code 6.

Unit Codes

Like the house code mappings above, we have a table of values to associate unit codes with the values you need to use in your commands:

Unit Code Value
1 600
2 E00
3 200
4 A00
5 100
6 900
7 500
8 D00
9 700
10 F00
11 300
12 B00
13 000
14 800
15 400
16 C00

One character or three?
Astute observers will notice that the unit codes 1-16 all end with "00". It's probably more correct to say that the unit codes are a single character value with "00" padded on the end, but I think it's easier to think of them this way because the commands (which we're about to see) are three characters.

Command Codes

Finally, we have mappings for the commands we want to send to X10 devices:

Command Value
On 280
Off 380
Bright 580
Dim 480
All On 180
All Off 680

Combining levels and Commands

We now have enough knowledge to send the six commands to our devices:

curl http://172.30.1.101/3?02636600=I=3 # Set House Code A (6) and Unit Code 1 (600)
curl http://172.30.1.101/3?02636280=I=3 # Send the On (280) command to devices set above

curl http://172.30.1.101/3?02636600=I=3 # Set House Code A (6) and Unit Code 1 (600)
curl http://172.30.1.101/3?02636380=I=3 # Send the Off (380) command to devices set above

In the example above, you don't have to issue the command to set the house code the second time, as long as no other commands have come through that change the house and unit code. In practice, I'd send it anyway just to be explicit.

Multiple Commands

It's possible to set multiple devices and then send a single command to them. (I don't find this very useful, and I've never tested it) It appears that the house code must be the same for each device.

Note: I have not gotten this to work properly on my network! If someone can tell me what I'm doing wrong, please let me know and I'll update this.

curl http://172.30.1.101/3?02636600=I=3 # Set House Code A (6) and Unit Code 1 (600)
curl http://172.30.1.101/3?02636E00=I=3 # Set House Code A (6) and Unit Code 2 (E00)
curl http://172.30.1.101/3?02636200=I=3 # Set House Code A (6) and Unit Code 3 (200)
curl http://172.30.1.101/3?02636280=I=3 # Send the On (280) command to devices set above    

Information Needed
If anyone has more information on the multiple command syntax, please let me know and I'll update this section.

Device Status?

Certain newer X10 devices support status requests, but I've never used these devices and I'm not sure if the SmartLinc supports them. If someone knows, please let me know!

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 an X10 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:


Comments

blog comments powered by Disqus


Warning: include(footer.inc.php) [function.include]: failed to open stream: No such file or directory in /home/snewman/webapps/leftovercode/smartlinc_x10.php on line 428

Warning: include(footer.inc.php) [function.include]: failed to open stream: No such file or directory in /home/snewman/webapps/leftovercode/smartlinc_x10.php on line 428

Warning: include() [function.include]: Failed opening 'footer.inc.php' for inclusion (include_path='.:/usr/local/share/pear52') in /home/snewman/webapps/leftovercode/smartlinc_x10.php on line 428