“Complexity must be grown from simple systems that already work”
From Out of Control by Kevin Kelly
Introduction
In our previous Home Toys paper we described how the IO Anywhere network appliance could be used as a Home Automation Portal Appliance in general terms.
In this paper we are going to illustrate the IOA internal API using a detailed (albeit trivial) example of a remote lamp and a temperature sensor.
The IO Anywhere network appliance, X.10 modules, the lamp and the temperature sensor will be located remotely in the IO Anywhere office in Kitchener, Ontario, Canada.
This paper will describe the deployment and operation of a graphical script which can be run on your local computer. This script will interact with and control this lamp from anywhere over the Internet.
Not only will our script be capable of simply issuing on/off commands to the lamp but it will exhibit some facits of complete closed loop control. The IO Anywhere appliance will be configured to push an event message at a particular temperature threshold. This event message will be received and handled by our script.
We’ll be doing all this in less than 100 lines of code.
Description of our online test system gateway
This is a digital picture of the online setup, located at the IO Anywhere office. This setup can be exercised from a web browser (Try Me tab) or from a remote Tcl/Tk script.
The black box in the photo is a Linux server which acts as a gateway into the world of the IOA appliance.
While the gateway is not an essential element of the system, it does allow many scripts/applications to access many IOA appliances. The simpler point to point access library is available but it would restrict you to a single Tcl/Tk script accessing a single IOA appliance. A specialized IOA module can act as a more modest gateway to allow up to 4 scripts to access up to four IOA appliances.
The small white box in the center of the two white boxes is the actual microIOA appliance. Our Tcl/Tk scripts will be exchanging messages with this box. The Try Me tab on the IO Anywhere website has all its pages served directly from this little box.
The two outer white boxes are the X.10 modules.
The lamp (standard 7W night light) and temperature sensor are attached to the X.10 module on the right.
This experimental setup is diagrammed in more detail below.
We are going to show how it is possible to write a Tcl/Tk (open source scripting language) script, run it locally and have it interact over the Internet with the remote IOA appliance setup shown above.
Our script is going to open a TCP/IP socket connection (over the Internet) to the gateway appliance and then logically onto the IOA appliance itself. The script is going to issue some commands to configure the microIOA appliance (set temperature limits, event message and communication protocol). The user is going to be able to initiate the X.10 sequence to turn on the lamp with the click of a mouse. The script is going to react to the event message issued after the temperature trip point and issue the lamp turn off X.10 command.
Downloading the Tcl/Tk toolset
Tcl/Tk is an open source, multiplatform, compact and easy to use scripting language. Tcl/Tk has a relatively simple syntax and core function set but is powerful enough to allow us access to TCP/IP sockets and messaging at a sufficiently low level to meet our needs.
Tcl/Tk is also available for free for a download.
To download the Tcl/Tk toolset simply go to the Active State website if you are running a Windows computer system. Many Linux distributions come with the Tcl/Tk toolset preinstalled.
The installation is pretty well described on that website but if you wish more tutorial material on this aspect as well as aspects of the Tcl/Tk language itself you might consult the somewhat dated online iCanProgram course material.
Once you have the Tcl/Tk tools installed and you are reasonably comfortable with the environment and some trivial scripts, you’ll need to download the zip’d Tcl/Tk IOA appliance package. Once again this material is licenced as open source and made available for free.
You’ll need to do a little folder creation work here. You’ll need to create a folder right off your C hard drive called ioanywhere . It is inside this folder that you expand the zip archive that you downloaded above.
If all goes well you should end up with several subfolders:
* p2p – the point to point libraries
* gw – the gateway libraries
* demos
* images
inside your C:\ioanywhere folder.
Running the demo code
There are several demos available in the demos folder above.
We’ll focus our attention on the one called
demo5.tcl
Try running this code.
If all goes well, and the microIOA appliance is online, you should see a screen similar to that below come up.
At this point the demo5 script will have already interacted across the Internet with the test setup in the in the previous section. It will have established a TCP/IP socket channel for communications between your box and the remote gateway appliance and then on to the microIOA itself.
Click anywhere in the image and a signal will be sent out to the remote IOA appliance telling it to issue the local X.10 command required to illuminate the lamp.
In addition, at the click event, the same communications channel will be used to issue some configuration commands to the remote IOA. These configuration commands will:
* read the current temperature
* set the temperature trip point 3 C above the current temperature
* configure the remote IOA appliance to respond by issuing an event message if the temperature exceeds this trip point
* set the text associated with the event string which will be issued by the remote IOA appliance
* tell the IOA appliance to use SIMPL messaging and how to reach our local Tcl/Tk application
It may take a few seconds for this to happen. X.10 is not the fastest protocol around. Once the lamp is illuminated the remote IOA appliance will respond to your signal and the window should change to:
You can watch the temperature slowly rise in the display in the upper left corner of this window. Be patient it is only a 7 W night light. The temperature widget is on a 10 sec poll loop.
Eventually the temperature will exceed the threshold as noted in the center text at the bottom of the Window. Our script setup this limit and configured the IOA appliance to respond to this trip point by issuing an event message.
As the temperature climbs past that trip point the IOA appliance will issue a SIMPL message back over the Internet channel to our script. When this SIMPL message is received the Tcl/Tk script will display the event message text contained therein on the screen. The first line in that event message is the string we configured from our script. This string is represented by the myeventstr variable near the top of the demo5.tcl script. Feel free to change this string to something different.
Once the event message has been displayed the script will issue a signal to the remote IOA appliance telling it to issue the local X.10 command responsible for turning off the lamp.
The final state of your application window should look something like the figure below:
We did all this in less than 100 lines of Tcl/Tk script.
Understanding the demo code
For those readers who are curious about the details of the demo5 script there is a mailing list associated with the IOA Library open source project (see references below). There are people on that mailing list who would be more than willing to explain the details of the demo5 script and the accompanying libraries.
Having said this there are two open source projects at work here.
The SIMPL open source project (see references below) provides the lower level communication protocol libraries and the gateway server which runs on the Linux gateway appliance. If you consult your folders created on the harddrive during the installation step above you’ll see that these libraries are themselves Tcl/Tk scripts:
* fcsocket.tcl – lowest level socket and protocol API
* fcgateway.tcl – higher level mapping of the socket API to the SIMPL Send/Receive/Reply API
The SIMPL libraries are no more that a couple hundred lines of active (non comment or whitespace) Tcl/Tk code.
The IOA Library open source project contributes the libraries which contain the IO Anywhere API functions:
* ioasocketlib.tcl – point to point version ioagatewaylib.tcl – gateway version
Our demo5 script makes use of the following IOA API calls from the ioagatewaylib.tcl package. They are easy to recognize because they all end in _IOA:
* init_IOA – used to establish a communication channel to the IOA appliance (by name)
* configure_IOA – used to set parameters and modes in the remote IOA appliance
* read_tc_IOA – used to read the temperature probe (A-D)
* X10_IOA – used to issue X.10 commands to the locally connected X.10 network
The rest of the demo5 script is associated with the GUI, widget creation and manipulation and the plumbing to connect the whole thing together. Conclusion The Home Automation Portal Appliance will soon become an essential addition to most home automation projects of any complexity.
In this paper we’ve discussed how the small, lightweight and low power box produced by IO Anywhere can act as a Home Automation Portal Appliance.
We discussed how a simple script written using a free open source language (Tcl/Tk) can be used to interact and control this Home Automation Portal Appliance across the Internet. We illustrated how this script could be used to provide closed loop control.
This opens up a powerful new dimension for automation and control.
For futher info
* There is lots more info on the IO Anywhere website
* the SIMPL project website
* the IOA library project website
* nofee online course which demonstates programming for the IO Anywhere device