[% pagetitle = 'Squeezebox Server xPL Support' %] [% techinfo = '1' %] [% lefttoright = '1' %] [% PROCESS helpheader.html %]

#### Introduction

The Squeezebox Server software includes native support for the xPL home automation protocol. xPL is an open standard, intended to permit the control and monitoring of devices throughout the home. The purpose of xPL is to provide an efficient, unified mechanism for devices to communicate with each other, and with an intelligent house manager. This approach leads to a truly integrated home, and makes it very easy to accomplish tasks which in the past would have required custom programming skills. There is xPL support for a growing list of hardware, including the popular X10 home automation modules.

#### xPL Messages

xPL messages are text-based, and are sent on UDP port 3865. Messages are broadcast to all nodes on the network using the Ethernet broadcast address, allowing xPL-enabled applications, such as an intelligent house manager, to listen to all xPL messages and take appropriate action.

The complete xPL Protocol Specification can be found on the Official xPL Project Site, and is recommended reading for anyone who is interested in using the xPL protocol to greatest advantage.

#### Enabling xPL Support in Squeezebox Server

To enable xPL support, go to Server Settings -> Additional Server Settings -> Network.
Scroll to the xPL section, and set xPL support to Enabled.
Click Change, then restart your Squeezebox Server software.

Once enabled, each player that is connected to Squeezebox Server (including software players) will generate an xPL heartbeat message, alerting other nodes on the network of it's presence.

#### Starting an xPL Hub

To allow multiple xPL applications to run simultaniously on the same host, it is necessary to run an xPL Hub. The Hub handles all incoming xPL messages and distributes them to all xPL-enabled applications that are running on the local machine. There are many different hub implementations available for a variety of platforms including Windows and Linux. See the xPL Project Site for a complete list.

#### Controlling Squeezebox Server via xPL

You can control Squeezebox Server by sending xPL messages, either to all devices, or targetted at a particular player. There are a number of ways of sending an xPL message - see the xPL Project Site for a list of applications that support xPL, and for a variety of command-line tools.

Squeezebox Server can be controlled using four different types of xPL message.

audio.basic messages can be used to provide basic control of Squeezebox Server. This includes functions common to all audio players, such as play, stop, volume etc.

audio.slimserv messages are used to harness the more advanced features of Squeezebox Server, performing any of the commands that can be performed via the command-line interface.

remote.basic messages are used to control Squeezebox Server by simulating button presses on a remote control, in a similar way to the "button" command in the command-line interface.

osd.basic messages are used to display text on a players screen.

#### Squeezebox Server Status Messages

Each player that is connected to Squeezebox Server will send out a heartbeat message as soon as it connects, and at intervals of between 5 and 30 minutes thereafter. The heartbeat message includes information about the player, such as the player's mode (playing, paused or stopped), the name of the song that is currently playing, and the text that is currently displayed on the player's screen.
You can request this information at any time by sending an audio.request message to the player you wish to query. Each player will also send out a status message each time a track changes, when the end of a playlist is reached and when the unit it switched on/off.

#### Infra-red Remote Control Messages

When buttons are pressed on a player's remote control, it is possible to have xPL messages generated to inform other nodes on your network, e.g. to fire macros in your home automation software.
Operation of this feature can be controlled either via the Web interface (Server Settings -> Additional Server Settings -> Network), or remotely by an xPL configuration manager.
The following values are supported:
None : No xPL message will be sent when a button is pressed.
Buttons : An xPL message will be sent when a recognised button code is received, and the name of the button will be included.
Raw : All infra-red codes that the player can receive will cause an xPL message to be sent. The message will contain the raw hex value of the infra-red code. This allows the player to be used as a general purpose infra-red receiver.
Both : This is a combination of Buttons and Raw. The player will send an xPL message for every remote control signal it receives, including the raw hex codes. It will also send messages when recognised buttons are pressed, including the name of the button. Users should be aware that this configuration will result in two messages being transmitted for recognised button codes - one containing the hex value, and one containing the recognised button name.

[% PROCESS helpfooter.html %]