com.jpeterson.x10server
Class X10ServerStub

java.lang.Object
  |
  +--com.jpeterson.x10server.X10ServerStub
Direct Known Subclasses:
X10Server

public abstract class X10ServerStub
extends java.lang.Object
implements AddressListener, FunctionListener

This class implements an X10 service as a network controllable device by utilizing a CM11A device and the X10 Java interface. It implements a TCP service that is controlled through simple text commands. This provides a rudimentary human interface as well as a programmable interface. Because it provides a TCP interface, totally seperate systems running on independent boxes can be enabled with X10 control as long as the controlling system is able to make a TCP connection.

This class also provides a mechanism to receive X10 events. The events are broadcast via UDP multicast broadcasts. This allows the service to efficiently notify multiple clients at once.

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:
Turn on device A3(A03)(AON)
Turn off all lights for house code EEL0
Dim B13 by 11 dims(B13)(BDI11)

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.


Field Summary
static java.lang.String ALL_LIGHTS_OFF_KEY_CODE
          All Lights Off Key Code - "L0"
static java.lang.String ALL_LIGHTS_ON_KEY_CODE
          All Lights On Key Code - "L1"
static java.lang.String ALL_UNITS_OFF_KEY_CODE
          All Units Off Key Code - "A0"
static java.lang.String BRIGHT_KEY_CODE
          Bright Key Code - "BR"
protected  java.net.MulticastSocket broadcastSocket
          Status broadcast socket.
static java.lang.String COMMAND_HELP
          Command to get help on possible commands.
static java.lang.String COMMAND_QUIT
          Command to quit, logging out of the server.
protected  java.lang.String comPort
          Serial port to talk to CM11A to.
static java.lang.String DEFAULT_COM_PORT
          Default serial port: COM2
static int DEFAULT_LISTEN_PORT
          Default listen port: 4377
static java.lang.String DEFAULT_STATUS_ADDRESS
          Default UDP status broadcast address: 239.6.20.71
static int DEFAULT_STATUS_PORT
          Default UDP status broadcast port: 4378
static java.lang.String DIM_KEY_CODE
          Dim Key Code - "DI"
static int EXIT_INVALID_ARGUMENT
          Exit value of '1' indicates and invalid argument.
static int EXIT_INVALID_LISTEN_PORT
          Exit value of '2' indicates and invalid listent port.
static int EXIT_INVALID_STATUS_ADDRESS
          Exit value of '3' indicates and invalid status address.
static int EXIT_INVALID_STATUS_PORT
          Exit value of '4' indicates and invalid status port.
static java.lang.String EXTENDED_DATA_KEY_CODE
          Extended Data Key Code - "EX"
static java.lang.String HAIL_ACKNOWLEDGE_KEY_CODE
          Hail Acknowledge Key Code - "HR"
static java.lang.String HAIL_REQUEST_KEY_CODE
          Hail Request Key Code - "HR"
protected  int listenPort
          TCP port to listen for client connections on.
static java.lang.String OFF_KEY_CODE
          Off Key Code - "OF"
static java.lang.String ON_KEY_CODE
          On Key Code - "ON"
static java.lang.String PRESET_DIM_1_KEY_CODE
          Preset Dim 1 Key Code - "D1"
static java.lang.String PRESET_DIM_2_KEY_CODE
          Preset Dim 2 Key Code - "D2"
static java.lang.String PROMPT
          Default command prompt: '>'
protected  boolean run
          Variable used to indicate that the server is running.
static java.lang.String STATUS_OFF_KEY_CODE
          Status Off Key Code - "S0"
static java.lang.String STATUS_ON_KEY_CODE
          Status On Key Code - "S1"
static java.lang.String STATUS_REQUEST_KEY_CODE
          Status Request Key Code - "SR"
protected  java.net.InetAddress statusAddress
          IP Address for UDP status broadcasts.
protected  int statusPort
          UDP port for status broadcasts.
protected  java.util.Vector threads
          Where worker threads stand idle.
protected  int timeout
          Inactivity timeout.
protected  Transmitter transmitter
          X10 gateway.
protected  int workers
          max # worker threads.
 
Constructor Summary
X10ServerStub(int listenPort, java.net.InetAddress statusAddress, int statusPort, java.lang.String comPort)
          Create a new X10ServerStub
 
Method Summary
 void address(AddressEvent e)
          Listener for AddressEvents.
 void broadcast(java.lang.String msg)
          Send a UDP broadcast message.
protected abstract  Transmitter createTransmitter()
          Subclasses must implement this method, creating an instance of the Transmitter interface.
 void functionAllLightsOff(FunctionEvent e)
          Listener for All Lights Off function.
 void functionAllLightsOn(FunctionEvent e)
          Listener for All Lights On function.
 void functionAllUnitsOff(FunctionEvent e)
          Listener for All Units Off function.
 void functionBright(FunctionEvent e)
          Listener for Bright function.
 void functionDim(FunctionEvent e)
          Listener for Dim function.
 void functionHailAcknowledge(FunctionEvent e)
          Listener for Hail Acknowledge function.
 void functionHailRequest(FunctionEvent e)
          Listener for Hail Request function.
 void functionOff(FunctionEvent e)
          Listener for Off function.
 void functionOn(FunctionEvent e)
          Listener for On function.
 void functionPresetDim1(FunctionEvent e)
          Listener for Preset Dim 1 function.
 void functionPresetDim2(FunctionEvent e)
          Listener for Preset Dim 2 function.
 void functionStatusOff(FunctionEvent e)
          Listener for Status Off function.
 void functionStatusOn(FunctionEvent e)
          Listener for Status On function.
 void functionStatusRequest(FunctionEvent e)
          Listener for Status Request function.
 void start()
          Start listening for client connections.
 void stop()
          Stop the running server.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EXIT_INVALID_ARGUMENT

public static final int EXIT_INVALID_ARGUMENT
Exit value of '1' indicates and invalid argument.

EXIT_INVALID_LISTEN_PORT

public static final int EXIT_INVALID_LISTEN_PORT
Exit value of '2' indicates and invalid listent port.

EXIT_INVALID_STATUS_ADDRESS

public static final int EXIT_INVALID_STATUS_ADDRESS
Exit value of '3' indicates and invalid status address.

EXIT_INVALID_STATUS_PORT

public static final int EXIT_INVALID_STATUS_PORT
Exit value of '4' indicates and invalid status port.

DEFAULT_LISTEN_PORT

public static final int DEFAULT_LISTEN_PORT
Default listen port: 4377

DEFAULT_STATUS_ADDRESS

public static final java.lang.String DEFAULT_STATUS_ADDRESS
Default UDP status broadcast address: 239.6.20.71

DEFAULT_STATUS_PORT

public static final int DEFAULT_STATUS_PORT
Default UDP status broadcast port: 4378

DEFAULT_COM_PORT

public static final java.lang.String DEFAULT_COM_PORT
Default serial port: COM2

PROMPT

public static final java.lang.String PROMPT
Default command prompt: '>'

COMMAND_HELP

public static final java.lang.String COMMAND_HELP
Command to get help on possible commands. "help"

COMMAND_QUIT

public static final java.lang.String COMMAND_QUIT
Command to quit, logging out of the server. "quit"

ALL_UNITS_OFF_KEY_CODE

public static final java.lang.String ALL_UNITS_OFF_KEY_CODE
All Units Off Key Code - "A0"

ALL_LIGHTS_ON_KEY_CODE

public static final java.lang.String ALL_LIGHTS_ON_KEY_CODE
All Lights On Key Code - "L1"

ON_KEY_CODE

public static final java.lang.String ON_KEY_CODE
On Key Code - "ON"

OFF_KEY_CODE

public static final java.lang.String OFF_KEY_CODE
Off Key Code - "OF"

DIM_KEY_CODE

public static final java.lang.String DIM_KEY_CODE
Dim Key Code - "DI"

BRIGHT_KEY_CODE

public static final java.lang.String BRIGHT_KEY_CODE
Bright Key Code - "BR"

ALL_LIGHTS_OFF_KEY_CODE

public static final java.lang.String ALL_LIGHTS_OFF_KEY_CODE
All Lights Off Key Code - "L0"

HAIL_REQUEST_KEY_CODE

public static final java.lang.String HAIL_REQUEST_KEY_CODE
Hail Request Key Code - "HR"

HAIL_ACKNOWLEDGE_KEY_CODE

public static final java.lang.String HAIL_ACKNOWLEDGE_KEY_CODE
Hail Acknowledge Key Code - "HR"

PRESET_DIM_1_KEY_CODE

public static final java.lang.String PRESET_DIM_1_KEY_CODE
Preset Dim 1 Key Code - "D1"

PRESET_DIM_2_KEY_CODE

public static final java.lang.String PRESET_DIM_2_KEY_CODE
Preset Dim 2 Key Code - "D2"

EXTENDED_DATA_KEY_CODE

public static final java.lang.String EXTENDED_DATA_KEY_CODE
Extended Data Key Code - "EX"

STATUS_ON_KEY_CODE

public static final java.lang.String STATUS_ON_KEY_CODE
Status On Key Code - "S1"

STATUS_OFF_KEY_CODE

public static final java.lang.String STATUS_OFF_KEY_CODE
Status Off Key Code - "S0"

STATUS_REQUEST_KEY_CODE

public static final java.lang.String STATUS_REQUEST_KEY_CODE
Status Request Key Code - "SR"

listenPort

protected int listenPort
TCP port to listen for client connections on.

statusAddress

protected java.net.InetAddress statusAddress
IP Address for UDP status broadcasts.

statusPort

protected int statusPort
UDP port for status broadcasts.

comPort

protected java.lang.String comPort
Serial port to talk to CM11A to.

threads

protected java.util.Vector threads
Where worker threads stand idle.

workers

protected int workers
max # worker threads.

timeout

protected int timeout
Inactivity timeout.

broadcastSocket

protected java.net.MulticastSocket broadcastSocket
Status broadcast socket.

transmitter

protected Transmitter transmitter
X10 gateway.

run

protected boolean run
Variable used to indicate that the server is running.
Constructor Detail

X10ServerStub

public X10ServerStub(int listenPort,
                     java.net.InetAddress statusAddress,
                     int statusPort,
                     java.lang.String comPort)
Create a new X10ServerStub
Parameters:
listenPort - TCP port to listen for client connections on.
statusAddress - UDP multicast address to send status messages to.
statusPort - UDP port to send status messages to.
comPort - Serial port to talk to Transmitter to.
Method Detail

createTransmitter

protected abstract Transmitter createTransmitter()
Subclasses must implement this method, creating an instance of the Transmitter interface. The transmitter should be initialized to for X10Event generation if appropriate. i.e., call addAddressListener(this) and addFunctionListener(this).

start

public void start()
           throws java.io.IOException
Start listening for client connections.

stop

public void stop()
Stop the running server.

broadcast

public void broadcast(java.lang.String msg)
               throws java.io.IOException
Send a UDP broadcast message.
Parameters:
msg - Message to send

address

public void address(AddressEvent e)
Listener for AddressEvents.
Specified by:
address in interface AddressListener
Parameters:
e - AddressEvent.

functionAllUnitsOff

public void functionAllUnitsOff(FunctionEvent e)
Listener for All Units Off function.
Specified by:
functionAllUnitsOff in interface FunctionListener

functionAllLightsOn

public void functionAllLightsOn(FunctionEvent e)
Listener for All Lights On function.
Specified by:
functionAllLightsOn in interface FunctionListener

functionOn

public void functionOn(FunctionEvent e)
Listener for On function.
Specified by:
functionOn in interface FunctionListener

functionOff

public void functionOff(FunctionEvent e)
Listener for Off function.
Specified by:
functionOff in interface FunctionListener

functionDim

public void functionDim(FunctionEvent e)
Listener for Dim function.
Specified by:
functionDim in interface FunctionListener

functionBright

public void functionBright(FunctionEvent e)
Listener for Bright function.
Specified by:
functionBright in interface FunctionListener

functionAllLightsOff

public void functionAllLightsOff(FunctionEvent e)
Listener for All Lights Off function.
Specified by:
functionAllLightsOff in interface FunctionListener

functionHailRequest

public void functionHailRequest(FunctionEvent e)
Listener for Hail Request function.
Specified by:
functionHailRequest in interface FunctionListener

functionHailAcknowledge

public void functionHailAcknowledge(FunctionEvent e)
Listener for Hail Acknowledge function.
Specified by:
functionHailAcknowledge in interface FunctionListener

functionPresetDim1

public void functionPresetDim1(FunctionEvent e)
Listener for Preset Dim 1 function.
Specified by:
functionPresetDim1 in interface FunctionListener

functionPresetDim2

public void functionPresetDim2(FunctionEvent e)
Listener for Preset Dim 2 function.
Specified by:
functionPresetDim2 in interface FunctionListener

functionStatusOn

public void functionStatusOn(FunctionEvent e)
Listener for Status On function.
Specified by:
functionStatusOn in interface FunctionListener

functionStatusOff

public void functionStatusOff(FunctionEvent e)
Listener for Status Off function.
Specified by:
functionStatusOff in interface FunctionListener

functionStatusRequest

public void functionStatusRequest(FunctionEvent e)
Listener for Status Request function.
Specified by:
functionStatusRequest in interface FunctionListener