X 1 0 S e r v e r
J e s s e  P e t e r s o n



X10Server implements a LAN accessible interface to your powerline X10 network through a CM11A serial interface device. By entering simple text commands, it is possible for both human users and software based systems to control X10 devices. 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.

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

The server program X10Server can be started by entering the following command line:

java X10Server [-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

Example

Running X10Server.

java X10Server -listenport 4377 -statusaddress 239.6.20.71 -statusport 4378 -port COM2

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 X10Server.java can be found in the src/com/jpeterson/x10server directory. The X10Server extends the class X10ServerStub. The base class X10ServerStub actually performs most of the work, while the class X10Server 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 method start first allocates the CM11A device with a call to the method createTransmitter implemented in the object X10Server. It then creates the MulticastSocket that is used to transmit X10 event messages. Next, a pool of worker threads is created. This thread pool was derived from the article A Simple, Multithreaded Web Server by David Brown available on the Java Developer Connection site. Then, a ServerSocket is created. The program goes into a continual while loop, waiting for TCP connections on the ServerSocket. When a connection is established, the connection is handed off to a worker thread where the connection is acutally processed.

When a worker thread is awakened, the method handleClient will be called. This method provides the basic text based user interface. The prompt character '>' is displayed indicating that the server is ready to accept input. The program waits for a line to be entered. The line must be terminated with a carriage return. The method processCommand is called to process the command entered.

The method processCommand will parse the command line into individual X10Event objects. If the command line contains multiple commands, indicated by using parenthesis to enclose each command, the commands are parsed apart. Then, actual X10Event objects are create for each command. Finally, the CM11A object is used to transmit each individual X10Event commands.

Commands are converted to X10Event objects via a call to createX10Event.

When the CM11A object is created, the X10Server object registers itself as an AddressListener and a FunctionListener. The object X10Server must therefore implement all of the methods defined in the AddressListener and FunctionListener interfaces. When one of these event listener methods is called, the method broadcast is invoked to send a UDP multicast message out with the event information encoded as the body of the message.



Copyright © 2000 Jesse Peterson