xPL Project
What is the xPL Project?
The xPL Project was started in January 2003 by Ian Lowe and Tony Tofts. It's goal: To create a unified protocol to allow the control and monitoring of all devices within the home, whilst maintaining an unparalleled level of simplicity and ease of use. During the first half of 2003, the protocol was refined to include powerful auto-discovery and configuration capabilities. With the core protocol now in place, much of the work involves integrating xPL support into software and hardware devices.
What is xPL?
xPL is an open protocol intended to permit the control and monitoring of home automation devices. The primary design goal of xPL is to provide a rich set of features and functionality, whilst maintaining an elegant, uncomplicated message structure. The protocol includes complete discovery and auto-configuration capabilities which support a fully "plug-n-play" architecture - essential to ensure a good end-user experience.
xPL benefits from a strongly-specified message structure, required to ensure that xPL-enabled devices from different vendors are able to communicate without the risk of incompatibilities.
What does xPL stand for?
It's an abbreviation for "eXtremely simPle protocoL".
I would like to have some hands on experience with xPL. Can you direct me to where I can get xPL devices to test?
There are a lot of different types of device that have been xPL-enabled, so it really depends on exactly what area of automation you are interested in. The best place to ask is the xPL Forums.
I have an X-10 controllable thermostat that I would like to control via xPL. Is there a schema defined for that? If not, how does one go about getting one created and approved?
You should be able to use the existing x10.basic schema, as this covers every aspect of the published X10 protocol. If you would like to consider enhancing the schema to make it more appropriate for your temperature sensor, the best place to discuss this is in the xPL Forums.
The Basics
What do I need to get xPL working?
The first step is to install an xPL Hub. On Windows, you will want to Install_the_xPL_Monkey_Windows_xPL_Hub
An xPL hub is also available for Linux, and Perl and Java versions are available which should operate on any platform that has Perl or Java support.
With the Hub in place, xPL applications can be installed.
For more details see xPL hubs specification.
Do I need a network card to be able to use xPL?
Many xPL applications use TCP/IP over Ethernet to communicate with each other. It is therefore recommended that you have a network card installed in your computer, with a fully functioning TCP/IP stack.
If you do not have a network card installed, and you are running Microsoft Windows NT 4.0, Windows 2000 or Windows XP, you can install the Microsoft Loopback Adaptor.
Why should I consider using xPL?
Many home automation packages on the market today rely on a highly proprietary plug-in architecture to provide extensibility. This means that once committed to a particular package, you are entirely dependent on support for a particular device being added to your chosen home automation package.
Because xPL is a fully open protocol, supported on a wide variety of platforms, only a single “gateway†application needs to be written to allow the features of a particular device to be exposed to every other xPL-enabled device.
I want to learn more about xPL. Who can I speak to?
Check out the xPL Forums for regular chat and questions. There is also a more technical developers section
I would like to control an HVAC thermostat that I own. Is there a schema for controlling thermostats? If not, how does one go about getting a schema created and approved/listed?
The sensor.basic schema is usually used for reporting the state of sensing devices such as thermostats. You could use this schema to report the current temperature, and you could enhance the schema by adding extra items to the message if you wanted. Discussion of enhancements and additions to the official published schemas takes place in the xPL Forums developers forum, so if you are interested in contributing to the official schema, posting to the group is probably the best place to start.
How do I get a vendor Id for the hardware/software devices I develop?
Post your request to the xPL Forums developer forum, and one of the xPL project team will confirm whether your chosen vendor ID is available, and allocate it to you accordingly.
xPL HAL
What is xPLHal?
xPLHal is the engine at the heart of a Windows xPL-based home automation system. It is responsible for processing incoming xPL messages, and executing scripts to perform a wide variety of tasks.
In addition to processing xPL messages, xPLHal includes a powerful Timed Events Engine, which allows actions to take place at specific times of the day. The events system includes many powerful features such as both single and recurring events, and automatic randomisation of event timing.
It also includes an xPL Configuration Manager, which provides automatic configuration of all your xPL-based devices.
Management of your xPLHal home automation system can be achieved either through a Windows-based Manager, or via the xPLHal Web Access product, which allows browser-based access to your xPLHal installation from anywhere.
The xPLHal Project, like many of the xPL projects, is completely open-source and released under the GNU General Public License. If you would like to contribute to the continued development of the xPLHal Project, please contact the Development Team by visiting the forums, or you can download xPLHal in the download section
What is the difference between xPLHal and xPLHalManager?
xPLHal is a gui-less service in windows - it runs all the time, even when no one is logged in. xPLHal does the scripting, runs determinators, configures devices when they power up etc.
xPLHalManager is a console app which uses XHCP (not xPL) to configure the low lying service. (xplhal manager can for instance run on any PC on the network, it doesn't have to be on the xplhal server PC).
Similarly, xplhal can run without the manager, and you could (if you wanted to) configure the service by editing the various configuration files.
xPLHalManager is the first XHCP client, but could easily be implemented on Linux, Mac OS, whatever, and talk to an xPLHal server somewhere on the network.
I get an error when I try and start the xPLHal service. What am I doing wrong?
Make sure you have an up-to-date install of the xplHub and xplHAL, since old versions of the xPLHal included a hub that will conflict with the stand-alone hub. To avoid this problem, no applications embed a hub anymore.
I have created/modified some scripts, but the changes don't seem to have taken effect.
Before any changes you have made to xPLHal scripts will take effect, you need to tell xPLHal to reload your scripts.
You can do this by right-clicking on the Scripts node in the xPLHal Manager and selecting Reload Scripts.
I want to write my own front-end to xPLHal. How can I do this?
All front-end applications communicate with the xPLHal server using the xPLHal Control Protocol (XHCP). This is a fully open, TCP-based protocol that allows anyone to develop their own management tools, on just about any platform that supports TCP sockets.
The latest XHCP protocol specification is available at http://xplproject.org.uk/wiki/index.php?title=XHCP_Protocol
I am receiving the error "COM object with CLSID {0E59F1D5-1FBE-11D0-8FF2-00A0D10038BC} is either not valid or not registered." in my xPLHal error log. What is wrong?
This error usually occurs if you do not have the Microsoft Script Control installed. If you are running Windows NT 4.0, it is likely that this control will not be installed, and you will need to download it from the Microsoft web site.
What is the xPLHal Error Log, and how can I access it?
The xPLHal Error Log is the place where xPLHal will log details of any problems that are encountered during it's operation. If you are having problems with any part of xPLHal, the error log is a good place to look for any clues as to what could be going wrong.
You can access the error log by right-clicking on your server name at the top of the xPLHal Manager tree and selecting View Error Log.
What are Determinators?
Determinators were added to xPLHal version 1.4, released in early 2004.
Prior to the introduction of Determinators, users of xPLHal used a scripting language - VBScript - to program the logic that they wanted to be performed by the xPLHal engine.
Determinators provide a totally graphical, wizard-driven way for users to control their xPLHal installation.
A Determinator consists of a list of conditions, and a list of actions.
The conditions specify the set of criteria which must be true for the Determinator to run. For example, the time of day, the temperature, the light level.
The actions specify what should happen if all the conditions are satisfied, for example switching on or off a light.
Do Determinators remove the need for scripting?
Determinators provide an easy-to-use, powerful way for you to control your xPL devices - you don't need any knowledge of the underlying xPL protocol, and you don't need to write any code.
However, for more advanced situations, it may be easier to achieve the desired effect using scripting, or a mixture of scripting and Determinators.
What is a Plugin (or Vendor Plugin)?
Plugins are files that describe a xPL enabled device. Using them, tools like xPLHAL and DCM can provide tailored information and menu options to xPL users. They allows creating user interfaces easier, creating determinators, etc, etc. In short, they allow a program that previously did not know anything about a new device to present meaningful options and controls for that device.
Plugins are created and maintained by the devices vendor/author. If you try to use a device that doesn't seem to have any applicable options to it in xPLHAL or DCM, you should contact the device vendor and ask they create or update their plugin.
Transmission-Media Specific Questions
What media will xPL run over?
Ethernet and RS232. Is this the full list?
How do I run xPL over RS232?
xPL Messages can be sent over RS232 and RS485 based networks - in these environments, it is considered good practice to encapsulate the xPL message, thus:
<STX> xPL Message <ETX> (note: no CR characters after either the STX, or the xPL Message)
A software tool exists as a "bridge" between serial and ethernet networks - the xPLDevCOM Tool.
xPL Hubs
What does an xPL hub do?
An xPL hub is the glue that connects multiple xPL applications together, by passing xPL messages it receives to all clients that are connected to it. See xPL hubs specification for full details.
Do hubs send all messages to all their clients - even the client that originated the message?
Yes.
Should a Hub be embedded in an xPL application or applications distribution?
No.
Every computer running xPL applications needs to have an xPL hub running. The hub is an absolutely critical resource and if it is not present or fails, all xPL apps on the computer will suffer/fail. As such, it's important that hubs are installed explicitly by the end user and not by an application.
The reasoning is simple -- with multiple xPL frameworks and technologies, there is no foolproof way to insure that there is or is not an existing hub on a computer. Without that, your app can not know if it should install the hub or if installing a hub would "step-on" an existing hub. To get rid of this untenable situation, installation of a hub has been made a seperate item, explicitly done by the computers user when setting up xPL for the first time.
Further, no application should come with a built in hub for very similar reasons -- it's difficult to impossible to be sure if your apps hub should be *the* hub for the computer or not (remember that some xPL applications are designed to run on many different computers, so anything specific to a single computer that might solve this could not be depended on).
Finally, as xPL evolves, hubs may need to change. If the hub is embeded in an application, it would be locked to that applications release cycle. While xPL has always been extremely concerned about backwards compatibility and such a hub should continue to work, it may deny new features to other xPL applications on the same computer.
Supported Platforms
What platforms are supported?
There are implementations of the xPL framework in Windows .Net, Windows C++, Linux C, Perl and Java. The perl and Java versions run on any platform with Perl or Java installed.