com.jpeterson.x10.module
Class CM11A

java.lang.Object
  |
  +--com.jpeterson.x10.GatewayImpl
        |
        +--com.jpeterson.x10.SerialGateway
              |
              +--com.jpeterson.x10.module.CM11A

public class CM11A
extends SerialGateway
implements Transmitter, java.lang.Runnable, javax.comm.SerialPortEventListener, java.io.Serializable

Gateway to X10 CM11A serial interface unit. The CM11A is both a producer and consumer of X10Events. It receives X10Events from other software components and transmits the event through the X10 protocol. It sends X10Events that it receives on the power line.

See Also:
Serialized Form

Field Summary
static byte CM11_MACRO_INITIATED
           
static byte CM11_POWER_FAILURE
           
static byte CM11_RECEIVE_EVENT
           
 
Fields inherited from class com.jpeterson.x10.SerialGateway
baudRate, dataBits, parity, portName, stopBits
 
Fields inherited from class com.jpeterson.x10.GatewayImpl
gatewayListeners, gatewayQueue
 
Fields inherited from interface com.jpeterson.x10.Transmitter
QUEUE_EMPTY, QUEUE_NOT_EMPTY
 
Constructor Summary
CM11A()
          Construct a new CM11A object.
 
Method Summary
 void addAddressListener(AddressListener l)
          Add an X10 Address listener.
 void addCM11AListener(CM11AListener l)
          Add a CM11A event listener.
 void addCM11AStatusListener(CM11AStatusListener l)
          Add a CM11A status listener.
 void addFunctionListener(FunctionListener l)
          Add an X10 Function listener.
 void addMacroInitiator(MacroInitiator macroInitiator)
          Add a macro initiator.
 void addTimerInitiator(TimerInitiator timerInitiator)
          Add a timer initiator.
 void allocate()
          Start the serial link between the computer and the actual CM11A module.
 void clearMacroInitiators()
          Clear all macro initiators.
 void clearTimerInitiators()
          Clear all timer initiators.
protected  FunctionEvent createEvent(FunctionEvent function, java.lang.Object newSource)
          Create a copy of a FunctionEvent but with the specified source.
protected static int dayOfYear(int month, int day)
          Convert a date in the format of month and day to day of year format.
 void deallocate()
          Stop the serial link between the computer and the actual CM11A module.
 CM11AStatusEvent decodeStatus(byte[] bytes, int off, int len)
          Decode a status buffer.
 void dispatchControlEvent(ControlEvent event)
          Calls TransmitterListener methods.
 void downloadInitiators()
          Transmit the CM11A macro initiators to the X10 CM11A device.
protected  int encodeEEPROM()
          Encode the EEPROM array.
protected  int encodeMacro(Macro macro, int macroOffset)
          Encode a macro into the EEPROM array.
static int extractDay(int julianDay)
          Utility method to convert the Julian day returned in getJulianDay to a the day of the month represented.
static int extractMonth(int julianDay)
          Utility method to convert the Julian day returned in getJulianDay to the month the day represents.
protected  void fireCM11AEvent(CM11AEvent evt)
          Fire a CM11A event.
protected  void fireCM11AStatusEvent(CM11AStatusEvent evt)
          Fire a CM11A status event.
protected  void fireX10Event(X10Event evt)
          Fire an X10 Transmission.
 int getBatteryUsage()
          Retrieve the CM11A's idea of what the current battery usage is.
 int getCurrentDay()
          Retrieve the CM11A's idea of what the current day is.
 java.util.BitSet getDimStatus()
          Indication of the dim status as the CM11A sees it for the monitored house code.
 int getHours()
          Retrieve the CM11A's idea of what the current hour is.
 int getJulianDay()
          Retrieve the CM11A's idea of the current day of the year.
 java.util.BitSet getLastAddressedDevice()
          Indication of the last addressed device as the CM11A sees it for the monitored house code.
 int getMinutes()
          Retrieve the CM11A's idea of what the current minute is.
 char getMonitoredHouseCode()
          Get the house code that the CM11A is configured to monitor.
 java.util.BitSet getOnOffStatus()
          Indication of the On/Off status as the CM11A sees it for the monitored house code.
 boolean getPowerFailureAutoRecover()
          Determine if this CM11A object has been configured to auto recover upon sensing a power failure at the CM11A device.
 int getSeconds()
          Retrieve the CM11A's idea of what the current second is.
 boolean isRunning()
          Indicates if the the interface to the CM11A is up.
 java.util.Enumeration macroInitiators()
          Retrieve an Enumeration of all timer initiators.
protected static int normalizeDay(int month, int day)
          Make sure that the day is valid.
protected static int normalizeMonth(int month)
          Make sure that the month is valid.
 void processPendingRequests()
          Process the input stream, handling unsolicited events.
 void processTransmissionQueue()
          Process the queue of events to be processed by the CM11A.
 void removeAddressListener(AddressListener l)
          Remove an Address listener.
 void removeCM11AListener(CM11AListener l)
          Remove a CM11A event listener.
 void removeCM11AStatusListener(CM11AStatusListener l)
          Remove a CM11A status listener.
 void removeFunctionListener(FunctionListener l)
          Remove a Function listener.
 boolean removeMacroInitiator(MacroInitiator macroInitiator)
          Remove a macro initiator.
 boolean removeTimerInitiator(TimerInitiator timerInitiator)
          Remove a timer initiator.
 void ringDisable()
          Disable the serial Ring Indicator signal.
 void ringEnable()
          Enable the serial Ring Indicator signal.
 void run()
          Process CM11A events.
 void serialEvent(javax.comm.SerialPortEvent event)
          Receive serial events from the CM11A module.
 void setClock(int hour, int minute, int second, int month, int day, int dayOfWeek, char houseCode, boolean clearBatteryTimer, boolean clearMonitoredStatus, boolean purgeTimer)
          Update the CM11A interface's internal clock, set the monitored house code, reset battery timer, clear monitored statuses, and purge timer.
 void setPowerFailureAutoRecover(boolean autoRecover)
          Indicate if you want the CM11A object to autorecover upon detecting a power failure.
 void stateTransition(long state)
          Encapsulates state transition rules.
 java.util.Enumeration timerInitiators()
          Retrieve an Enumeration of all timer initiators.
protected static byte[] toBytes(int value, int len, boolean bigEndian)
          Convert an integer value to a byte array.
 void transmit(X10Event evt)
          Implementation of Transmitter.
 void updateStatus()
          Request the status from the CM11A interface.
 void updateStatus(CM11AStatusListener statusListener)
          Request the status from the CM11A interface.
 
Methods inherited from class com.jpeterson.x10.SerialGateway
getBaudRate, getDataBits, getParity, getPortName, getStopBits, setBaudRate, setDataBits, setParity, setPortName, setStopBits
 
Methods inherited from class com.jpeterson.x10.GatewayImpl
addGatewayListener, fireControlEvent, getGatewayQueue, getGatewayState, pause, removeGatewayListener, resume, setGatewayQueue, setGatewayState, testGatewayState, waitGatewayState
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CM11_RECEIVE_EVENT

public static final byte CM11_RECEIVE_EVENT

CM11_POWER_FAILURE

public static final byte CM11_POWER_FAILURE

CM11_MACRO_INITIATED

public static final byte CM11_MACRO_INITIATED
Constructor Detail

CM11A

public CM11A()
Construct a new CM11A object.
Method Detail

setPowerFailureAutoRecover

public void setPowerFailureAutoRecover(boolean autoRecover)
Indicate if you want the CM11A object to autorecover upon detecting a power failure. If set to true, when the CM11A object detects a power failure signal from the CM11A device, the command to set the clock will be sent. If set to false, it is up to another device to set the clock via a call to setClock before the CM11A can be used.

By default, auto recover is turned on.

Parameters:
autoRecover - True if the object should automatically recover upon detecting a power failure of the CM11A device.
See Also:
getPowerFailureAutoRecover, setClock

getPowerFailureAutoRecover

public boolean getPowerFailureAutoRecover()
Determine if this CM11A object has been configured to auto recover upon sensing a power failure at the CM11A device.

By default, auto recover is turned on.

Returns:
True if auto recover is turned on, false otherwise.
See Also:
setPowerFailureAutoRecover

stateTransition

public void stateTransition(long state)
Encapsulates state transition rules. Only implements Transmitter specific states. Lets parent's stateTransition handle the generic gateway states.
Overrides:
stateTransition in class GatewayImpl

transmit

public void transmit(X10Event evt)
              throws GatewayStateError
Implementation of Transmitter. Other software components can send X10 events to the CM11A to have sent through the X10 protocol to X10 devices on the power line network.
Specified by:
transmit in interface Transmitter
Parameters:
evt - X10 event to transmit
Throws:
GatewayStateError - if called for a transmitter in the DEALLOCATED or DEALLOCATING_RESOURCES states

updateStatus

public void updateStatus()
Request the status from the CM11A interface.

updateStatus

public void updateStatus(CM11AStatusListener statusListener)
Request the status from the CM11A interface.
Parameters:
statusListener - Notification is sent to the listener

getMonitoredHouseCode

public char getMonitoredHouseCode()
Get the house code that the CM11A is configured to monitor. The CM11A device will record changes to devices on the monitored house code. It record the on/off status and if a device is dimmed or not. The data can be retrieved from the methods getOnOffStatus, getDimStatus, get last addressed device. Use setClock to change the monitored house code.
Returns:
The character from 'A' through 'P' that indicates the house code that is being monitored.
See Also:
setClock

getOnOffStatus

public java.util.BitSet getOnOffStatus()
Indication of the On/Off status as the CM11A sees it for the monitored house code. The value is set after a call to updateStatus.
Returns:
The bit is set (true) if the device is on, not set (false) if the device is off. The bit index indicates the device: bit index 0 = device 1, bit index 1 = device 2, ..., bit index 15 = device 16.
See Also:
updateStatus

getDimStatus

public java.util.BitSet getDimStatus()
Indication of the dim status as the CM11A sees it for the monitored house code. The value is set after a call to updateStatus.
Returns:
The bit is set (true) if the device is dimmed, not set (false) if the device is not dimmed. The bit index indicates the device: bit index 0 = device 1, bit index 1 = device 2, ..., bit index 15 = device 16.
See Also:
updateStatus

getLastAddressedDevice

public java.util.BitSet getLastAddressedDevice()
Indication of the last addressed device as the CM11A sees it for the monitored house code. The value is set after a call to updateStatus.
Returns:
The bit is set (true) if the device was addressed, not set (false) if the device was not addressed. The bit index indicates the device: bit index 0 = device 1, bit index 1 = device 2, ..., bit index 15 = device 16.
See Also:
updateStatus, setClock

getCurrentDay

public int getCurrentDay()
Retrieve the CM11A's idea of what the current day is. The value is initialized after a call to updateStatus().
Returns:
The CM11A's idea of what the current day is. Will be one of Calendar.SUNDAY, Calendar.MONDAY, Calendar.TUESDAY, Calendar.WEDNESDAY, Calendar.THURSDAY, Calendar.FRIDAY, Calendar.SATURDAY.
See Also:
updateStatus, setClock

getJulianDay

public int getJulianDay()
Retrieve the CM11A's idea of the current day of the year. The value is zero based; 0 for January 1, 31 for February 1, ... The value is initialized after a call to updateStatus().

The utility methods CM11A.extractMonth() and CM11A.extractDay() have been provided to convert this value into month and day representations.

As far as I can tell, the CM11A has no way of determining leap years. It therefore always uses 366 days in a year. The caller is responsible for determining if the current day has been corrected for a non-leap year.

Returns:
Day of year.
See Also:
extractMonth, extractDay

getHours

public int getHours()
Retrieve the CM11A's idea of what the current hour is. The value is initialized after a call to updateStatus().
Returns:
The CM11A's idea of what the current hour is. Expressed as 24 hour value.
See Also:
updateStatus, setClock

getMinutes

public int getMinutes()
Retrieve the CM11A's idea of what the current minute is. The value is initialized after a call to updateStatus().
Returns:
The CM11A's idea of what the current minute is.
See Also:
updateStatus, setClock

getSeconds

public int getSeconds()
Retrieve the CM11A's idea of what the current second is. The value is initialized after a call to updateStatus().
Returns:
The CM11A's idea of what the current second is.
See Also:
updateStatus, setClock

getBatteryUsage

public int getBatteryUsage()
Retrieve the CM11A's idea of what the current battery usage is. The value is initialized after a call to updateStatus().
Returns:
The CM11A's idea of what the current battery usage is. Expressed in minutes.
See Also:
updateStatus, setClock

setClock

public void setClock(int hour,
                     int minute,
                     int second,
                     int month,
                     int day,
                     int dayOfWeek,
                     char houseCode,
                     boolean clearBatteryTimer,
                     boolean clearMonitoredStatus,
                     boolean purgeTimer)
Update the CM11A interface's internal clock, set the monitored house code, reset battery timer, clear monitored statuses, and purge timer.
Parameters:
hour - Current time, hours. 0 - 23.
minute - Current time, minutes. 0 - 59.
second - Current time, seconds. 0 - 59.
month - Current month, zero based. e.g., 0 for January (Calendar.JANUARY), 1 for February (Calendar.FEBRUARY).
dayOfWeek - A day of the week constant from the class java.util.Calendar. Should be one of the following: Calendar.SUNDAY, Calendar.MONDAY, Calendar.TUESDAY, Calendar.WEDNESDAY, Calendar.THURSDAY, Calendar.FRIDAY, or Calendar.SATURDAY.
houseCode - the house code of the event. Valid codes are 'A' through 'P', uppercase.
clearBatteryTimer - If true, the interface's battery timer will be cleared.
clearMonitoredStatus - If true, the interface's monitored statuses will be cleared.
purgeTimer - If true, this will purge the interfaces timer, but I don't know what that means???

ringEnable

public void ringEnable()
Enable the serial Ring Indicator signal.

ringDisable

public void ringDisable()
Disable the serial Ring Indicator signal.

addCM11AListener

public void addCM11AListener(CM11AListener l)
Add a CM11A event listener.
Parameters:
l - CM11AListener to add.
See Also:
removeCM11AListener

removeCM11AListener

public void removeCM11AListener(CM11AListener l)
Remove a CM11A event listener.
Parameters:
l - CM11AListener to remove.
See Also:
addCM11AListener

fireCM11AEvent

protected void fireCM11AEvent(CM11AEvent evt)
Fire a CM11A event.
Parameters:
evt - The event to send to listeners.

addCM11AStatusListener

public void addCM11AStatusListener(CM11AStatusListener l)
Add a CM11A status listener.
Parameters:
l - CM11AStatusListener to add.
See Also:
removeCM11AStatusListener

removeCM11AStatusListener

public void removeCM11AStatusListener(CM11AStatusListener l)
Remove a CM11A status listener.
Parameters:
l - CM11AStatusListener to remove.
See Also:
addCM11AStatusListener

fireCM11AStatusEvent

protected void fireCM11AStatusEvent(CM11AStatusEvent evt)
Fire a CM11A status event.
Parameters:
evt - The event to send to listeners.

addAddressListener

public void addAddressListener(AddressListener l)
Add an X10 Address listener. The CM11A will send any X10 address events that it intercepts on the power line to all registered address listeners.
Parameters:
l - X10 AddressListener to add.
See Also:
removeAddressListener

removeAddressListener

public void removeAddressListener(AddressListener l)
Remove an Address listener.
Parameters:
l - AddressListener to remove.
See Also:
addAddressListener

addFunctionListener

public void addFunctionListener(FunctionListener l)
Add an X10 Function listener. The CM11A will send any X10 function events that it intercepts on the power line to all registered function listeners.
Parameters:
l - X10 FunctionListener to add.
See Also:
removeFunctionListener

removeFunctionListener

public void removeFunctionListener(FunctionListener l)
Remove a Function listener.
Parameters:
l - FunctionListener to remove.
See Also:
addFunctionListener

fireX10Event

protected void fireX10Event(X10Event evt)
Fire an X10 Transmission. When an X10 event is received from the power line, this method is called with the X10 event to send to all registered X10 transmission listeners.
Parameters:
evt - The event to send to X10Transmission listeners.

isRunning

public boolean isRunning()
Indicates if the the interface to the CM11A is up.
Returns:
Returns true if the interface is up, false if the interface connection is down.

allocate

public void allocate()
              throws GatewayException,
                     GatewayStateError
Start the serial link between the computer and the actual CM11A module.
Overrides:
allocate in class GatewayImpl
Tags copied from interface: Gateway
Throws:
GatewayException - if an allocation error occurred or the gateway is not operational.
GatewayStateError - is called for an engine in the DEALLOCATING_RESOURCES state
See Also:
getGatewayState, deallocate, ALLOCATED, GATEWAY_ALLOCATED

deallocate

public void deallocate()
Stop the serial link between the computer and the actual CM11A module.
Overrides:
deallocate in class GatewayImpl
Tags copied from interface: Gateway
Throws:
GatewayException - if a deallocation error occurs.
GatewayStateError - if called for a gateway in the ALLOCATING_RESOURCES state
See Also:
allocate, GATEWAY_DEALLOCATED, QUEUE_EMPTY

dispatchControlEvent

public void dispatchControlEvent(ControlEvent event)
Calls TransmitterListener methods. Lets parent's dispatchControlEvent call the GatewayListener methods.
Overrides:
dispatchControlEvent in class GatewayImpl
Tags copied from class: GatewayImpl
Parameters:
event - the ControlEvent to be propagated to the listeners
See Also:
fireControlEvent

run

public void run()
Process CM11A events.
Specified by:
run in interface java.lang.Runnable

processTransmissionQueue

public void processTransmissionQueue()
Process the queue of events to be processed by the CM11A.

processPendingRequests

public void processPendingRequests()
Process the input stream, handling unsolicited events. This method will drain the input stream of all available bytes.

createEvent

protected FunctionEvent createEvent(FunctionEvent function,
                                    java.lang.Object newSource)
Create a copy of a FunctionEvent but with the specified source.
Parameters:
functionEvent - FunctionEvent to copy with the new source.
newSource - The new source to use in the copied FunctionEvent.
Returns:
A new FunctionEvent subclass based on the function in the provided function event. The event source will be set to the provided source.
Throws:
java.lang.IllegalArgumentException - Thrown if the functionEvent parameters function is unknown.

serialEvent

public void serialEvent(javax.comm.SerialPortEvent event)
Receive serial events from the CM11A module.
Specified by:
serialEvent in interface javax.comm.SerialPortEventListener

decodeStatus

public CM11AStatusEvent decodeStatus(byte[] bytes,
                                     int off,
                                     int len)
Decode a status buffer. Also notifies CM11AStatusListeners.
Returns:
Returns the CM11AStatusEvent decoded from the bytes.

downloadInitiators

public void downloadInitiators()
                        throws OutOfMacroMemoryException
Transmit the CM11A macro initiators to the X10 CM11A device. This method stores the macro in memory on the CM11A device. The macros can be executed from the device with the controlling computer turned off or event disconnected.
Throws:
OutOfMacroMemoryException - There are too many timer timer initiators, macro initiators, and their associated macros to be downloaded. Some of the initiators and/or macros must be removed in order to successfully download to the CM11A device.

toBytes

protected static byte[] toBytes(int value,
                                int len,
                                boolean bigEndian)
Convert an integer value to a byte array.
Parameters:
value - Integer value to convert.
len - Number of bytes to use.
bigEndian - If true, most significant byte is byte 0. If false, least significant byte is byte 0.
Returns:
Byte array set to integer value.

encodeEEPROM

protected int encodeEEPROM()
                    throws OutOfMacroMemoryException
Encode the EEPROM array.
Returns:
Total number of bytes to be transmitted to the device.
Throws:
OutOfMacroMemoryException - Throw if there are too many macros to fit into the devices EEPROM memory.

encodeMacro

protected int encodeMacro(Macro macro,
                          int macroOffset)
Encode a macro into the EEPROM array.
Parameters:
macro - Macro to encode.
macroOffset - Index in EEPROM to copy macro to.
Throws:
ArrayIndexOutOfBoundsException - if copying would cause access of data outside array bounds.
ArrayStoreException - if an element in the src array could not be stored into the dest array because of a type mismatch.

addTimerInitiator

public void addTimerInitiator(TimerInitiator timerInitiator)
Add a timer initiator. The initiator will not be triggered until it is downloaded to the CM11A device with a call to downloadInitiators()
Parameters:
timerInitiator - A timer initiator to add to the CM11A.

removeTimerInitiator

public boolean removeTimerInitiator(TimerInitiator timerInitiator)
Remove a timer initiator. The initiator will still be active until a call to downloadInitiators()
Parameters:
timerInitiator - The timer initiator to remove.
Returns:
true if the timer initiator was found, false otherwise.

clearTimerInitiators

public void clearTimerInitiators()
Clear all timer initiators.

timerInitiators

public java.util.Enumeration timerInitiators()
Retrieve an Enumeration of all timer initiators.

addMacroInitiator

public void addMacroInitiator(MacroInitiator macroInitiator)
Add a macro initiator. The initiator will not be triggered until it is downloaded to the CM11A device with a call to downloadInitiators()
Parameters:
macroInitiator - A macro initiator to add to the CM11A.

removeMacroInitiator

public boolean removeMacroInitiator(MacroInitiator macroInitiator)
Remove a macro initiator. The initiator will still be active until a call to downloadInitiators()
Parameters:
macroInitiator - The macro initiator to remove.
Returns:
true if the macro initiator was found, false otherwise.

clearMacroInitiators

public void clearMacroInitiators()
Clear all macro initiators.

macroInitiators

public java.util.Enumeration macroInitiators()
Retrieve an Enumeration of all timer initiators.

normalizeMonth

protected static int normalizeMonth(int month)
Make sure that the month is valid. If it is greater than December(11), set the month to December. If the month is less than January(0), set the month to January.
Parameters:
month - Month, zero based. e.g., 0 for January, 1 for February.
Returns:
Normalized month.

normalizeDay

protected static int normalizeDay(int month,
                                  int day)
Make sure that the day is valid. If it greater than the maximum day for the specified month, set the day to the maximum day. If it is less than the minimum day for the specified month, set the day to the minimum day.
Parameters:
day - Day to normalize.
month - Month, zero based. e.g., 0 for January, 1 for February.

dayOfYear

protected static int dayOfYear(int month,
                               int day)
Convert a date in the format of month and day to day of year format. The algorythm uses 366 days in a year, where 0 is January 1 and 365 is December 31.
Parameters:
month - Month, zero based. e.g., 0 for January, 1 for February.
day - Day of month
Returns:
Day of year.

extractMonth

public static int extractMonth(int julianDay)
Utility method to convert the Julian day returned in getJulianDay to the month the day represents. The month is zero based, i.e. 0 for January, 1 for February, ..., 11 for December.

As far as I can tell, the CM11A has no way of determining leap years. It therefore always uses 366 days in a year. The caller is responsible for determininging if the current day has been corrected for a non-leap year.

Returns:
Month represented by the julian day value. The month is zero based, i.e. 0 for January, 1 for February, ..., 11 for December.

extractDay

public static int extractDay(int julianDay)
Utility method to convert the Julian day returned in getJulianDay to a the day of the month represented.

As far as I can tell, the CM11A has no way of determining leap years. It therefore always uses 366 days in a year. The caller is responsible for determininging if the current day has been corrected for a non-leap year.

Returns:
Day of the month represented by the Julian day
See Also:
extractMonth, getJulianDay