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



EmbeddedGateway implements a LAN accessible interface to your powerline X10 network through a CM11A serial interface device. EmbeddedGateway is designed to execute on a TINI processor. The TINI processor is an embedded system capable of executing Java programs. The processor is small and inexpensive. It includes serial and Ethernet ports, making it an ideal platform for creating an X10 gateway.

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 processorAvailable 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 boardAvailable 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:

 
-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
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".

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 EEL0
Dim B13 by 11 dims(B13)(BDI11)
Terminate client sessionquit

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

X10Server
A server that implements the same interface as EmbeddedGateway, but uses the standard CM11A interface instead of the embeddable lighter version. X10Server is more appropriate for running on substantial systems like PCs.
X10ServerClient
X10ServerClient is a sample program supplied in the samples directory that demonstrates a basic programmatic interface that implements the protocol supported by EmbeddedGateway.
MulticastListener
MulticastListener is a sample program supplied in the samples directory that demonstrates a basic X10 event listener that receives X10 event broadcast as UDP messages by the EmbeddedGateway program.


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.



Copyright © 2000 Jesse Peterson