Skip to content

xAP and xPL Getting started

Jump to bottom Edit New page
Lieven Hollevoet edited this page Sep 22, 2014 · 1 revision

This topic addresses aspects that are common to the xAP and xPL home automation protocols. Details specific to each are covered by other topics. Topics covered here are:

#introduction

Table of Contents

Introduction

xAP and xPL are home automation protocols designed to permit a network-distributed set of devices, appliances and software programs to interoperate. Each protocol is conceptually similar--relying on broadcast UDP (vice TCP) messages. xAP and xPL "peers" (whether a device, gateway, etc.) broadcast messages that may be "targetted" to another peers or set of peers. Because they are broadcast, it is possible (and often desirable) to be able to "listen" to all messages and then decide if action should be taken. Targetted peers are expected to take appropriate action. Often, the action results in a change of state that is communicated as a new message broadcast to all peers (and, not exclusively back to the originating peer).

xPL or xAP?

A discussion on the misterhouse mailing list in May 2010 yielded that unless you have existing devices that require xAP, xPL seems to be where all the cool kids go nowadays :) It has support for:

  • owfs gateway, including hubs
  • loads of hardware interfaces, as per this list (this includes X10RF, W800, and rfxcom, which you can read about in more details on this page).
#addressing

Understanding xAP and xPL Addresses

A core-theme in both xAP and xPL is the concept of an address. The address is (usually) human-interpretable and includes portions of the "vendor's code", the application name and "instance" name. For xAP, an example is: code acmeapps.myfavapp.home code In xPL, the format slightly differs: code acmeapps-myfavapp.home code Note that usually, the author of the device/application controls the first two parts of the address, whereas the user (that is you) can alter the last piece--which will usually have a reasonable default name. It is important that you recognize and discover the pertinent addresses as they are key to declaring the xAP and xPL items. Sometimes, authors of the device/application will specify the address format; however, it is usually suggested that you obtain a message "viewer" to confirm that actual address names.

Another subtle point is the concept of "wildcarding". Wildcarding in xPL is very simple--a single asterisk ("*") is used to indicate that any match is acceptable. In xAP, wildcarding is more sophisticated and allows for sub-parts of the address to be matched (much like a regular expression). In addition, xAP implements the concept of "sub-addresses". A "sub-address" is very useful for "gateways" that control more than one device. An example of a gateway is application that controls/monitors one-wire devices. In xAP, subaddresses follow the main address and are delimitted by a colon. For example: code acmeapps.myfavapp.home:device1 code xPL approaches the problem differently and instead identifies the "sub-address" or device as a property in the message block. Often the attribute is called "device". However, this is not always the case and you should first consult any documentation specific to the device/application and/or it's pertinent schemas.

#hubs

About Hubs and Do I need One?

xAP and xPL messages are broadcast to a specific port (3865 for xPL and 3639 for xAP). If more than one program is running on a single platform, then only one of them may bind to any given port. This is where a hub is used. A hub is used exclusively to listen to the broadcast port and will then rebroadcast the message to each xPL or xAP listener on the local system. Unless the xAP or xPL peer is a dedicated device/appliance (and therefore is a software application), a hub is always necessary. Misterhouse has built-in xAP and xPL hubs that are enabled by default. For beginning users or users with low to moderate xAP and/or xPL traffic, the built-in hub is sufficient. Users with more advanced xAP and/or xPL networks may prefer the performance improvements by using a dedicated hub.

If you plan on doing over the wire XPL configuration with DCM (given below), for instance setting up Iranger's rfx-xpl gateway, you will need a real standalone hub (pick one below), the misterhouse one will not work for that.

    • Note**: The order of startup of the hub and misterhouse is critical! The hub must be running before misterhouse starts. Even if the built-in hub has been disabled, misterhouse will bind the listen port if a hub is not found. This will prevent the hub from starting later. Also, with the current code, if the hub is restarted, misterhouse does not re-bind to the new hub.
#configuration

Configuration Essentials

The following sections describe parameters that may be set in your local (private) mh.ini file.

Enabling/Disabling xAP and/or xPL

Basic protocol support for xAP and xPL is enabled within misterhouse. Unless you have xAP or xPL messages generated within your environment, there is no additional overhead--and, so, you may well want to consider leaving them enabled. In some cases, however, you may want to totally disable this support (an example is a proxy--which usually doesn't need this support and can be disruptive if you do have traffic). To disable all support for xAP and xPL: code xap_disable = 1 xpl_disable = 1 code

Enabling/Disabling Hubs

To disable (hubs are enabled by default) the built-in hubs: code xap_nohub = 1 xpl_nohub = 1 code Note: you may choose to operate xAP with an external hub and xPL with the built-in hub or vice versa. Any combination is acceptable. These settings are overridden by the above xap_disable and xpl_disable parameters.

    • Note**: When using an external hub, be sure that the hub is running before misterhouse starts.

Network Parameters

Setting network specific parameters is especially important if you have more than one subnet that your misterhouse platform supports. In addition, there are some occasions in which compatibility with other external hub(s) or interoperating applications require these settings. In general, it is a good idea to set them to your network's appropriate values even if you do not have multiple subnets. The following parameters are example if the misterhouse platform's primary (internal) IP address is 10.20.1.5 and the subnet mask is 255.255.255.0: code ipaddress_xap_broadcast = 10.20.1.255 ipaddress_xap = 10.20.1.5 ipaddress_xpl_broadcast = 10.20.1.255 ipaddress_xpl = 10.20.1.5 code

#essentialtools

Essential Tools - Viewers and Hubs

Viewers and hub are considered essential tools because without them, deployment of applications may not work or you will not be able to monitor the interactions between applications and devices. As described above, hubs are essential for any generic computer platform. Unless a hub is built-in and enabled, you will need to install a stand-alone hub. Likewise, viewers are essential for monitoring the message traffic that occurs between devices/applications. A separate viewer will allow you to confirm that messages are being sent as well as their content.

A list of known and tested hubs and viewers follows.

xAP - Windows only

xAP - Unix only xPL - Windows only xPL - Unix only xPL - Multi-platform Note, Viewers aren't just "nice to have" for xPL. For instance, iranger's rfx-xpl (support for rfxcom & w800 to receive oregon weather sensors, X10RF and X10security), requires the use of DCM to configure it (the other half is configured through the web interface, which you also setup via DCM). #working

Working with xAP and xPL Applications and Devices

There are two types of interactions that misterhouse provides built-in support that treats common across xAP and xPL. They are:

Virtually all other types of interactions require dedicated modules and are addressed in other topics (soon to be added). Current topics include:

Main page

Add a custom sidebar
Clone this wiki locally