Tuesday 25 May 2010

How to get xAP up and running

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 following UDP port:

UDP: 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

Hope this article helps others?