| My professional interests |
|
Computing Law Education Science and research |
| My leisure interests |
|
Martial arts Heritage railways Garden railways Motorcycles DIY |
| Downloads |
|
Linux downloads Windows downloads Java downloads Perl downloads Home automation downloads |
| About me |
|
Home & family My CV |
| Site info |
|
Contact the author Download policy Keyword index |
Home > Downloads > Home automation downloads A Java API for X10 home automation controllers Last modified: Thu Jul 8 07:20:01 2004 This package contains the specification of the API for X10-compliant home automation drivers. Supporting drivers are expected to implement the
X10Controller and X10Driver interfaces in
accordance with this specification. The specification supports the
complete range of standard X10 operations, but does not define support
for X10 extended status codes (because there is such little hardware support
for these features).
X10 features
This API supports the following X10 features, but not all drivers or their corresponding hardware will have full support.- on, off
- bright, dim
- status
- all lights on, all lights off, all units off
- event monitoring
getMetaData() on the
X10Controller object.
X10 clients
The client interacts with this API in a manner similar to the code shown below. This example sends an `on' event to the specified housecode and unitcode. Note that not all events require unitcodes, although the housecode is mandatoryX10Controller controller = X10DriverManager.getX10Controller (url, user, password); controller.send(new X10Event (X10Event.X10EVENT_ON, housecode, unitcode); controller.close();Not all controllers support user authentication, and those that do don't always require both user and password. However, the client is required to supply something in these arguments; the underlying driver is free to ignore it if desired.
To make this API work, vendor-specific drivers are required. The driver manager selects
a suitable driver from those available by checking the URL. X10 URLs are expected to begin
with x10; following this should be a product identifier; everthing after this
is vendor specific. For example, the twserial driver will respond when offered
URLs like this:
x10:twserial:[host]:[port]The precise nature of the URL is defined by the driver vendor.
X10DriverManager
X10DriverManager is responsible for selecting drivers on behalf of
clients. The mechanism of operation is exactly the same as for the SQL driver manager:
the client opens a connection like this:
X10Controller c = X10DriverManager.getX10Controller (url, user, pass);The driver tries to match the URL to those understood by the loaded drivers. It tries each driver on the list by calling its
canConnect()
method; it this returns true, it tries to call getX10Controller()
on the driver. If this returns a driver, then the driver manager considers its
job done. If none of the loaded drivers responds, then getX10Controller
throws an X10NoSuitableDriverException.
Exceptions
The API specification defines a number of exceptions, all subclasses ofjavax.automation.x10.X10Exception. One of the subclasses,
X10DriverException is defined to be thrown by most operations
that involved a driver; this includes everything where actual hardware operations
are invoked. A number of sub-classes of X10DriverException are defined,
to identify common errors (access denied, timeout, etc). Implementations are encouraged
to throw these exceptions rather than X10DriverException where practicable,
to give assistance to the client in determining what the problem was.
X10 events
To an X10 controller, an X10 event is any control signal being placed on the power line bus. Not all controllers support event monitoring, but all should support the sending of events. An event may correspond to a keypress on a remote control, or an appliance control signal generated by a timer, or something else. All these events have two things in common. First, they carry the housecode of the controller that generated them and, second, the X10 protocol does not define particular numbers or names for them. They are known by the effect they will have on the appliances. So, therefore, pressing the `off' button for appliance number 1 on housecode 1 can be identified only as that; there are no defined codes for these events. Therefore, the X10 API defines some. These codes are arbitrary, and drivers should attempt to map the events onto these codes for compatibility across applications. The codes are defined as constants in the classX10Event.
Clients receive notification of X10 events by means of an event listener. The interface X10EventListener
has only one method: handleEvent, and this is called whenever an event listener has been installed
in the controller and an event arrives. Note that it is not the job of the X10 driver to filter events. If a client
calls addEventListener on the X10Controller instance, it will get all events whether it
wants them or not. Selecting the events of interest is unlikely to be a problem for the client.
Drivers for hardware that does not support event notification, but relies on polling (like the twseriald server) are responsible for polling for events at a reasonable frequency (perhaps in a separate thread of execution) and calling the event listeners as appropriate. This specification does not indicate how frequently the driver should poll for events, but once every second or two is probably about right. The driver should endeavour not to lose events between polling intervals, but is not required to retain events when no clients are listening.
Status reports
The X10 protocol defines a simple status reporting system. A device is either `on' or `off'. Not all controllers support status reports, and even when they do the controlled hardware (e.g., appliance modules) might not. There is, in general, no way for software to tell whether a particular device can respond to a status request. In general, the driver will time out if asked to get the status for something that does not respond.
| Search |
| Shameless plug |
 By the author of this site. Buy on-line from Amazon USA | UK |
| Editorial |
So you want to be a university lecturer? Read this first! Speak like your boss: new developments in managerese |
| Computing features |
|
File handling in the Linux kernel: an in-depth look at how Linux handles files, filesystems, and file I/O
All sorts of Linux stuff Confused about CLASSPATH? answers are here First steps in EJB using jBoss (recently revised for jBoss 3.2) |