xPL Protocol

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.

Communications between xPL applications on a Local Area Network (LAN) use UDP on port 3865.

xPL development has primarily occurred in the DIY community, where users have written connecting software to existing protocols and devices. Some examples include bridges to other home automation protocols like Z-Wave and UPB. Commercially, the Logitech SqueezeCenter software for the Squeezebox supports xPL.

Architecture

Different devices communicate using xPL within a local network. They all broadcast their messages on the IANA registered UDP port 3865 for the other devices to handle.

As on modern operating systems only one program can listen to a given port, there is a need for a hub forwarding the messages to all devices on the same machine. The devices register to the hub on a private UDP port and the hub then forwards all incoming message to these private ports.

HUB

A hub is the first xPL component required on a machine running xPL devices.

All devices send a heartbeat message to the hub on a regular basis (typically 5 minutes). When disconnecting, they also can send a special heartbeat end message for the hub to radiate them out of his list.

The hub forwards all messages to every device in its list. There is no filtering of messages: a blind redistribution of all messages is carried out.

XPL device

Applications add functionality to a home automation solution such as light control, sun rise/set, weather information and so on.

A device chooses a free UDP port and sends heartbeat messages from that port to the hub on the IANA registered UDP port 3865.

From that time, the devices listens for messages on its private port but sends messages as broadcast on the xPL port 3865. The message types are one of the following:

• command, targeted to control other devices
• status, generally as an answer to a command
• trigger, used to notify a change in a device's state

An extensive list of applications can be downloaded from the net. Tooklits are also provided for users wishing to develop their own devices.

Bridge

It is assumed that your network protocol is UDP/IP but this is by no means a requirement. If you wish for your XPL message to cross from one transport medium to another (UDP/IP to RS232 for example) then you will need a Bridge.

Rules

On Windows, xPL HAL processes incoming xPL messages and executes scripts to perform a wide variety of tasks. Configuration is done either through a Windows-based Manager or via a browser. xPL HAL also includes an xPL Configuration Manager.

On Linux or Mac OS, xpl-central monitors all xPL messages and can trigger other messages based on a set of rules stored in an XML file.

Transmission media

The xPL protocol can operate over a variety of transmission media, including Ethernet, RS232 and RS485.

Ethernet

All xPL devices broadcast their messages over UDP, on IANA registered port 3865.

But, as only one application can listen at a time to a given port, the xPL protocol uses a hub to retransmit all broadcast messages to the different applications on the same machine. The applications subscribe to the hub on a free port by sending heartbeat messages which specifies the port they are listening to. In turn, the hub forwards all xPL broadcast messages it receives to every application in his list.

Protocol

Lite on the wire, by design

Example

xPL Messages are line based, with each line ending with a linefeed (ASCII: 10 decimal) character. The following is an example of a typical xPL Message:

xpl-cmnd
{
hop=1
source=xpl-xplhal.myhouse
target=acme-cm12.server
}
x10.basic
{
command=dim
device=a1
level=75
}

Message Structure

All messages are made out of:

• The message type (xpl-cmnd, xpl-stat or xpl-trig)
• The header block, inside curly braces, containing:
  • hop=n, the hop count which is incremented each time the xPL message is transferred from one physical network to another
  • source=vendor_id-device_id.instance_id, which serves to identify the sender of the message
  • target=vendor_id-device_id.instance_id, which serves to identify the destination of the message
• The message schema, in the format class.type
• The message body, inside curly braces, containing name=value pairs

In the header block, the target name is replaced by the wildcard symbol "*" for broadcast messages. This is the case for tigger and status messages.

Message Schema

xPL uses well defined message schemas to ensure that applications from different vendors can interact sensibly. Message Schemas are extensible, and define not only the elements which should be present in a message, but also the order in which they appear.

This allows simple devices and applications to parse messages more easily.

All of the existing message schemas can be found on the xPL project home page. Developers looking to create a new schema are invited to do so.

See also

• xAP Home Automation protocol - A substantially similar home automation protocol

External links

Official

• xPL Home Automation Project homepage
• xPL Home Automation Project WIki
• xPL Forum
• xPL Project URL links

Development

• xPL on BeagleBone or Raspberry Pi, using Perl scripts
• xPL Mal's C++ SDK
• Java SDK
• Perl toolkit
• Perl SDK
• Medusa
• glh33

Other

• Misterhouse supports xPL
• Logitech Media Server supports xPL, Logitech Media Server message schema