md
ActiveHome Pro SDK (ahsdk) with Delphi
July 15, 2013
-- Importing the SDK's Type Library->

Impatient? You can go to the last page, it has links to all the downloads.

What is it?

Here is a quote from X10’s knowledge base wiki:

The ActiveHome Pro Software Developer's Kit (SDK) is a set of tools and code designed for programmers outside of X10 to make use of ActiveHome Pro in their own applications.

The aim is to let user programs talk to a CM15A interface to control home automation devices. And that’s precisely what will be done : we will write a simple application in Delphi that uses the CM15A to control some X10 modules.

A Windows service called x10nets is part of the software installed by ActiveHome Pro (or by the AHSDK). A service is a type of program that is automatically started when the computer is booted and that runs in the background. You can verify that a service is running by pressing the Alt-Ctrl-Del chord of keys and selecting the Task Manager. Usually services and processes are listed alphabetically so look for x10nets to the bottom of the list.

This service takes care of all the details of communicating with the CM15A transceiver which is a USB device. Since this is, by no means, a simple task, we can be grateful that it handles the details about which we need know nothing. However, the service cannot be directly accessed to send commands to the CM15A. As the SDK's help puts it "Communication with the ActiveHome Scripting Interface is done through the scripting object, an ActiveX object that communicates with the general X10 device service." Presumably, the "Scripting Interface" is provided by the service and the "scripting object" or "ActiveX object" is contained in the dynamic-link library (dll for short) called ahscript.dll which is also part of the AHSDK (or the ActiveHome Pro software).

AHSDK schema

The figure above displays a simplified version of the communication stack which does not show any drivers. But it is obvious that the important interface for our purpose is the one between the application and ahscript.dll.

Update 2013-08-09 Two drivers are installed by default :

x10ufx2.sys
which shows up as X10 USB ActiveHome (ACPI-compliant) in the list of peripherals shown by Device Manager. It is installed in the C:\Windows\System32\Drivers folder on my Windows 7 (64 bit) system.
x10hid.sys
which shows up as X10 HID Device in the list of peripherals shown by Device Manager. It is installed in the same folder as the other driver. This driver can be disabled without consequence for the programs shown here. In other words, the x10nets service appears to interact with the CM15A using the USB driver, not the USB-HID driver.
If the x10nets service is suspended and then reactivated using Windows's task manager, it will be necessary to restart the sample programs provided later on.

Why these pages?

The ActiveHome Pro SDK, AHSDK or SDK from now on, contains sample applications written in C++, C#, Basic, Perl and so on, but no example in Delphi. There is information for Delphi programmers in X10's SDK forum. I thought it might be useful to bring some of it together.

What will you need?

Obviously, you’ll need the hardware: a CM15A interface and a couple of modules to test everything.

Some software is needed. The X10nets service must be running. It handles communications with the CM15A taking care of all the complicated USB stuff. We actually use a required dll (ahscript.dll) to talk to the service.

I suggest that you install the ActiveHome Pro software as it will install these required bits and register them so that they are always available. You can get these components by installing the AHSDK without installing ActiveHome Pro. There is of course a benefit to installing the software, you can test the hardware before trying to control it in your own applications. That’s a good idea given some of the problems associated with the hardware. I have a lamp module that will not respond to commands sent to a CM11A (a serial precursor of the CM15A) even when the module was plugged into the CM11A but it will respond when plugged into a wall socket in another room!

The version of the dll installed on my system is 3.0.0.3113 dated 2011-05-16. It's located in the following folder: C:\Program Files (x86)\Common Files\X10\Common\ahscript.dll or, presumably, C:\Program Files\Common Files\X10\Common\ahscript.dll; if you have a 32 bit version of Windows. You should make sure you have that version or a more recent version.

And you need Delphi of course. I will be using Delphi2010 and Delphi 7 but I assume that the application will function with other versions of Delphi.

-- Importing the SDK's Type Library->