E m b e d d e d G a t e w a y |
J e s s e P e t e r s o n |
By entering simple text commands, it is possible for both human users and software based systems to control X10 devices through the EmbeddedGateway. This is accomplished by establishing a TCP link to the server. A human user can accomplish this by using a standard Telnet client. Computer controlled systems can establish a connection through a TCP socket interface. Many of today's computer languages support this capability; from traditional C on a Unix system or Visual Basic on a Windows based PC all the way to a Palm OS based device.
EmbeddedGateway will also allow a program to receive notification of X10 events that happen on your X10 powerline network. The events are broadcast via UDP multicast message transmissions. This allows multiple client to receive notifications simultaneously as well as make efficient use of the network.
Requirements
EmbeddedGateway is designed to run on a TINI board. EmbeddedGateway has the following requirements.
TINI processor Available from Dallas Semiconductor at the url http://www.ibutton.com/TINI/. Developed and tested with 68 pin TINI (rev G), although newer 72 pin devices should work. TINI socket board Available from Dallas Semiconductor at the above address or Systronix at the url http://www.systronix.com/. Developed and tested with Dallas Semiconductor TINI Socket, 68 pin connector. TINI OS 1.01
Installation
To run EmbeddedGateway, the tini file must be installed on the TINI board. This is accomplished by FTP'ing the file "EmbeddedGateway.tini", located in the "tini" directory, up to your TINI device.
The CM11A device must be hooked up the TINI serial port. If using the TINI socket board from Dallas Semiconductor, this requires a null modem between the CM11A cable and the 9 pin serial connector on the socket board. I also had to use a gender changer. Other TINI daughter boards may or may not require the null modem connector.
Running
The program can be started by loggin into the TINI device through a telnet session. Change directory to the directory where the file "EmbeddedGateway.tini" was FTP'ed to. The gateway is started with the following command:
java EmbeddedGateway.tini [-listenport port] [-statusaddress IPAddress] [-statusport port] [-port comport]
Where:
Note: The EmbeddedGateway communicates with the CM11A through the serial port. By default, TINI starts with a serial server started. This server has control of serial port serial0. Before EmbeddedGateway can be started on port serial0, the serial server must be stopped. This can be done by executing the following command from the TINI slush command line: "stopserver -s".
-listenport port Set the port that the server listens for control to connect to. Dafault: 4377 -statusaddress IPAddress Set the status broadcast address that status messages will be sent on. Must be a valid multicast address from 224.0.0.1 through 239.255.255.255, inclusive. Default: 239.6.20.71 -statusport port Set the port that the status messages will be sent to. Default: 4378 -port comport Set the com port that the CM11A can be contacted on. Default: COM2
Example
Running EmbeddedGateway.
java EmbeddedGateway.tini -listenport 4377 -statusaddress 239.6.20.71 -statusport 4378 -port serial0
Interface
X10 commands are sent to the service via a TCP connection. A client connects to the host running the service on the configured port. The client will be prompted with the prompt ">". This indicates that the service is ready to receive commands. Commands should be entered followed by a "\n". This signifies completion of the command. The service will then attempt to execute the commands. Upon an error, an error message will be displayed, followed by the prompt ">". When an error occurs in a line, none of the line is executed. If the command completes, the prompt ">" will be displayed, waiting for the next commands. Commands take the following form.
commands = helpcmd | quitcmd | +( "(" command ")" )
helpcmd = "help"
quitcmd = "quit"
command = house-code key-code [ *extra-data ]
house-code = "A"
| "B"
| "C"
| "D"
| "E"
| "F"
| "G"
| "H"
| "I"
| "J"
| "K"
| "L"
| "M"
| "N"
| "O"
| "P"
key-code = "01" ; Unit 1
| "02" ; Unit 2
| "03" ; Unit 3
| "04" ; Unit 4
| "05" ; Unit 5
| "06" ; Unit 6
| "07" ; Unit 7
| "08" ; Unit 8
| "09" ; Unit 9
| "10" ; Unit 10
| "11" ; Unit 11
| "12" ; Unit 12
| "13" ; Unit 13
| "14" ; Unit 14
| "15" ; Unit 15
| "16" ; Unit 16
| "A0" ; All Units Off
| "L1" ; All Lights On
| "ON" ; On
| "OF" ; Off
| "DI" ; Dim
| "BR" ; Bright
| "L0" ; All Lights Off
| "HR" ; Hail Request
| "HA" ; Hail Acknowledge
| "D1" ; Preset Dim 1
| "D2" ; Preset Dim 2
| "EX" ; Extended Data
| "S1" ; Status On
| "S0" ; Status Off
| "SR" ; Status Request
extra-data = <Extra data is key code specific. Presently, 'DI'
and 'BR' use extra data. The extra data is a number
from 1 - 22 to indicate the number of dims.>
Example:
These examples could be entered into a telnet window
connected to the gateway's listen port (4377 is the default listen port).
Turn on device A3 | (A03)(AON) |
Turn off all lights for house code E | EL0 |
Dim B13 by 11 dims | (B13)(BDI11) |
Terminate client session | quit |
The UDP status messages will take the following form:
h=E&k=DI&dim=11&max=22
The format is similar to a HTTP URL encoded query string. The
data is represented as key/value pairs, where the key and value
are seperated by the equals ('=') character, and the pairs are
seperated by the ampersand ('&') character. Parsing of this
format should be straight forward as well as providing flexibility to
extend the messages in the future.
The key 'h' will contain the house code. This will be an upper case letter from 'A' through 'P', inclusive. The key 'k' indicates the key code. This will be the number 1 through 16 to indicate an address function for the device number, or one of the two character key codes described above in the command section. For a Dim or Bright function, the key 'dim' will be present and will indicate the number of dims, and the key 'max' will be present and indicates the total number of dims for that command type.
Code
The source code for EmbeddedGateway.java
can be found in the tini/EmbeddedGateway directory. The class
EmbeddedGateway
extends the class X10ServerStub
.
The base class X10ServerStub
actually performs most of
the work, while the class EmbeddedGateway
intializes the
server. The main method is mostly responsible for processing
the command line parameters, initializing the server, and then
starting the server with a call to start. The class
X10Server, including in this distribution, is very similar to
EmbeddedGateway. X10Server uses the standard CM11A interface, while
EmbeddedGateway uses a lighter version of the CM11A interface that has
a much smaller footprint.
See Also
To Do...
Future Directions
The program EmbeddedGateway can be more than just a sample program showcasing the TINI processors ability to communicate with X10 devices. It can integrated into a diverse home automation system. The protocol that EmbeddedGateway implements is designed to be simple enough that most programming languages, including scripting languages can support the command structure. By using a simple TCP interface, remote systems can interact with the gateway. The gateway also supports multiple client connections. It currently supports up to 5 concurrent client connections. (The TINI itself has an upper limit of about 20 threads.) By supporting multiple client connections, the gateway can be utilized by different systems at the same time. For example, a servlet implementing an HTML based home automation system can connect to the gateway and execute X10 commands. At the same time, a cron job on a Linux system can execute a perl program at the predefined time to execute certain X10 commands. Eventually, I would like to use EmbeddedGateway in a Jini environment. One Jini project, Surrogate, endevours to define a protocol for including devices that do not have suffient ability to perform Jini lookup and discovery directly to still participate in a Jini federation. Using the Surrogate protocol, it would be possible to include the EmbeddedGateway in a Jini environment.
Also, it should be noted that EmbeddedGateway can be used as a
sample on how to use the class
com.jpeterson.x10.embedded.CM11AGateway
. This class
could be included directly into a TINI program to enable X10
capabilities in said program.