xAP Tutorial – Setting Up the Open Home Automation Protocol

xAP Home Automation   Tutorial

xAP is an open Home Automation Protocol, created by Automated Home readers almost a decade ago.  It allows many disparate systems to talk to each other – for example your Caller ID interface could send packets to your Joggler to display details when someone rings.  Or perhaps you need your Comfort Alarm system to be able to control to your C-Bus lighting?  All do-able with xAP.

Recent discussions on our forums have lead to a new beginners guide / tutorial on setting up and running xAP in your own home and with the kind permission of the author,  we’ve re-created it here.

xAP is a home-automation protocol that is open and extensible, to understand more have a look at xAP Home Automation where you can get an overview of the protocol and applications that have been written already. The purpose of this article is to get you up and running with the core xAP components as their is no simple download and install option (at least not one I could find).

Install a xAP Hub – First off you’ll need a hub; a hub allows the hosting of multiple xAP applications on a single machine (without a hub the first xAP application to start will hog the necessary ports itself). Although a few hubs exist I’d recommend the following:- xfx -Express hub by Ed Pearson. It runs as a service by default (good because this mean any subsequent Apps start after the hub is running). It can also be run in console and verbose modes which is very handy for diagnosing problems.  Just download and run the MSI file which will install and configure the xfx-Express Hub – http://www.erspearson.com/xAP/xFx/hubs_main.htm

Configure Firewall Settings - After the hub is installed we need to allow the xAP protocol port through our OS firewall. I don’t believe in turning off an OS firewall if it is available we just need to identify the ports that should be allowed and let them through

xAP uses the UDP port 3639.  You can use the Firewall GUI from Settings: Control Panel to make firewall exceptions or you can type the following at the command-prompt.  For Windows XP, Windows 2003 and Windows Home Server you issue the following command:

>netsh firewall add portopening UDP 3639 xAP enable custom 127.0.0.1,localsubnet

For a more detailed explanation have a look at Windows Networking – CLI Firewall

The reason I’ve created a custom scope is because I originally just added subnet but discovered running the xAP Viewer locally on the server didn’t pickup any communication. Therefore, I have created a custom scope of loopback adapter (127.0.0.1) and the local subnet of my network.  From a GUI perspective go to Control Panel: Windows Firewall, then exceptions tab and you should see an entry corresponding to the above rule I added from the command-line:

Firewall in Control Panel

clip_image001

From the Windows Firewall dialogue box:

image

xAP Viewer – To enable diagnosis and general health checking it is highly recommend you install a xAP viewer, you can do this locally on the server or another PC.  I went for the latest viewer at Ed Pearson’s Website and installed this on the server that runs my Home Automation software and where I also installed the xAP Hub: xfx xAP Viewer

Installation is through a simple MSI setup program. Once installed you can navigate to the new installed shortcut in your Start Menu: Programs: xFx. Once running you should see something like:

image

That is it for the pre-requisites of xAP.

xAP Monitor – Whilst browsing Mi4.biz the xAP monitor caught my eye and here is how to install it (unfortunately it doesn’t come in a nice easy install package). You can install local or remote to the main xAP server.  The core program can be downloaded from here: xMonitor.  Unfortunately, as stated above, it doesn’t have a setup routine so it is a case of unzipping the downloaded file. I did this into the folder “C:\Program Files\xAP Framework” which was previously created when I installed the xAP viewer above. You will also need to take a few extra steps, at least I did on Windows 7 (as a client) and Windows Home Server (as Node0 / xAP Server).

First you need to register the ActiveX control, to do so type cmd from the “Start: Run” in Windows XP/2003 or “Windows Orb: All Programs: Accessories – right click ‘Command Prompt’ – Run as Administrator” in Vista / Windows 7.  In the Command Prompt Window type the following:

cd /d “c:\program files\xap framework\” [double quotes are needed because of the spaces in the path]

Then type: Regsvr32 xAPIntranet.ocx

Click on the notification window.  N.B – If for any reason the above doesn’t work you can download the specific xAP Intranet OCX 1.4 file extract to “C:\program files\xap framework\” and run Regsvr32 xAPIntranet.ocx

When I tried this and then tried to run xMonitor.exe from C:\program files\xap framework\ I got a couple of errors so here is the resolution – Download missing NTSVC.ocx from the zip NT_Service.zip from vb_Downloads

Extract the zip file to a new folder under “c:\program files\xap framework\”; I created a sub-folder called VBNTService

Navigate to this new sub-folder in my case “c:\program files\xap framework\vbntservice” and double-click “Install.bat”

The above steps download and register the activex control, NTSVC.ocx but I found this wasn’t the only missing ActiveX control I also needed to download another control, mswinsck.ocx:

Download the missing OCX from:

MSWinsck.ocx

Save the file to “C:\program files\xap framework”

Again you need to manually register the ocx file:

In a Command Prompt Window type the following:

cd /d “C:\program files\xap framework\” [again double quotes are needed because of the spaces in the path]

Then type:

Regsvr32 MSWinsck.ocx

That should be it you can now return to “c:\program files\xap framework\xMonitor” and double-click xMonitor.exe which should now start and an icon will appear in the System Tray. Right click the System tray icon and select “Show”. xMonitor will now appear in your default web browser and give you a nice self-updating view of the xAP messages on your network:

clip_image003

 

xapautomation.org   :   smarthome-uk.blogspot.com [Thanks Paul]

Want More? - Follow us on Twitter, Like us on Facebook, or subscribe to our RSS feed. You can even get these news stories delivered via email, straight to your inbox every day

4 Responses to “xAP Tutorial – Setting Up the Open Home Automation Protocol”

  1. I really love the idea of xAP, but the absolute killer everytime I try to extend my (limited) use of it is the quality of the documentation. Its either missing, scattered acrosss multiple websites, out of date, or inpenetrable. Often its two or three of these.

    So a good tutorial hit all the right buttons for me. Then I read “The reason I’ve created a custom scope is because I originally just added subnet but discovered running the xAP Viewer locally on the server didn’t pickup any communication. Therefore, I have created a custom scope of loopback adapter (127.0.0.1) and the local subnet of my network. ”

    OK, I’m fairly techy, and this will seem naive to many, but … what is a ‘scope’, what is a ‘subnet’, what is a ‘loopback adapter’, and is there a ‘local subnet of my network’ that I’d want to adapt anyway. How much googling will I have to do to understand this stuff!

    It really does seem that xAP is written by serious techies to simplify things they didn’t need to simplify.

    So people with limited time just can’t get into the subject because they are hit by layers of complexity that will absorb every spare minute to understand and overcome. So we buy products that don’t need xAP.

    Really, I do love what the xAP guys are trying to achieve, but they really need to explain the stuff more effectively, or it will remain forever in the land of geekdom. If thats what people want to achieve, then I’ll just shut up, but if they want to reach out a little, and create a protocol that integrates a wide range of hardware and software for busy people, then I’ll help wherever I can.

  2. > xAP is an open Home Automation Protocol, created > by Automated Home readers almost a decade ago.

    OK, now I feel old.

    Mark
    Co-founder, xAP

  3. Mark,

    Hate to break it to you – you are old :P

  4. Ditto, exactly what Michael said…?

    I guess no one knows what it means then :-(