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:
- GitHub: Chad Wackerman's OpenLinc Project
- SmartHome Forum: SmartHome Custom Scenes
- 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