Control X10 devices using xPLHal - XPLProject

Contents

Introduction

The core of many people's home automation systems involves controlling and responding to X10 signals, so we thought we'd put together this document to explain just how flexible an xPL environment can be when it comes to controlling your X10 devices.

We will guide you through installing the CM12 service, the application that talks to your CM11/12 and transmits xPL messages to the other components of your xPL network (such as xPLHal), and show you how to write some basic macros to get things going. xPLHal's macros are written as VBScript sub-routines. If you've never programmed in VBScript, the xPLHal Manager includes a sub-routine builder that will write all the code for you!


What You Need

Hardware:

  • A PC running Windows NT 4.0, Windows 2000, Windows XP or Windows Server 2003
  • A CM11 or CM12 X10 Computer Interface
  • Some X10 devices to control, eg lamp or appliance modules

Software:

  • xPLHal, xPLHal manager and an xPL Hub installed and configured as described in the HowTo guide Get Started on Windows.


Downloading the Software

Download the xPL CM12 service from http://johnb.xplproject.org.uk/downloads/xplcm12/xplcm12.zip (193KB)

Installing the Software

  • Unzip the file xplcm12.zip that you previously downloaded into a temporary directory.
  • In Windows Explorer, double-click the file xplcm12setup.msi to begin the installation.
HalHowTo cm1.jpg
  • Click Next
HalHowTo cm2.jpg
  • Agree to the GPL Licence, and Click Next
HalHowTo cm3.jpg
  • Select "Everyone" and Click Next
HalHowTo cm4.jpg
  • Click Next
  • Installation will take around thirty seconds.
HalHowTo cm5.jpg
  • Click Close, The CM12 Gateway is now installed
  • Go into Control Panel -> Administrative Tools -> Services and ensure that the xPL CM12 service is listed and is started.


Configuring the Software

  • Click Start -> Programs -> xPLHal -> xPLHal Manager
  • In the xPLHal Manager, in the left window, expand the xPL Devices node and click Awaiting Configuration.
HalHowTo conf1.jpg
  • In the right-hand window you should see the device johnb-cm12.computername1 (where computername is the name of the computer running the service, in this case, a Windows 2000 Server called TURING).
  • Double-click on the device to view it's properties.
HalHowTo conf2.jpg
  • Select "newconf" from the list of configurable options and enter the name by which you want the CM12 xPL service to be identified. In this case, we use the computer name "TURING"
  • Select "comport" from the list and enter the port number that the CM12 is connected to. Note: You only need to enter the numeric portion of the port, i.e. 1, 2, 3 etc.
  • Click OK.
  • If the CM12 is connected to a COM port other than COM1 (the default setting), go into Control Panel and restart the CM12 service so that it detects the CM12 on the correct port.
  • In the xPLHal Manager, click on the xPL Devices tree node. Your CM12 device should appear in the list with the name that you assigned to it.
HalHowTo conf3.jpg

Don't worry if the device is still listed under the Awaiting Configuration node - it can take a few minutes for the device to disappear.

Congratulations! You have now configured the xPL CM12 service.


Testing X10 Functionality

To ensure that everything is configured and working correctly, we will now take you thrugh the steps required to add an X10 device to xPLHal's X10 database, and turn that device on and off through the user interface.

  • In the xPLHal Manager, select the X10 tree node. You will then see all the X10 devices that have been entered into the xPLHal database.
  • Right-click on the X10 tree node and select New X10 Device.
  • Enter a name for the device. This should be a brief label that will help you identify the device, e.g. "Office light", "Hall PIR" etc.
  • Enter the X10 address of the device, e.g. C1, F13 etc.
  • If the device is controlling a light, tick the "This device is a light" checkbox.
  • Click OK.
  • The device should now be listed in the right-hand window of the xPLHal Manager.
  • Right-click on the device and select "Switch On".
  • The device should switch on, and you should see the status change to "On".
  • Right-click on the device again and select "Switch off".
  • The device should switch off and you will see the status change to "Off".
  • For devices that support status request, like the TM12, TM13 and AWM2, you can use the "Status request" option to ask the module for it's current on/off state. This will update the state in xPLHal's database.

xPLHal will automatically keep track of the state of all X10 devices, so if you turn on A1 by using a mini-controller, xPLHal will see the A1 On signal and will update the internal database accordingly.

You have now confirmed that your X10 interface is fully operational!


Creating a simple macro

Suppose you have a motion sensor that sends out an X10 signal "A1 On" whenever movement is triggered. You have a lamp module set to B1 that you want to be activated whenever an A1 On is sent.

First, a bit of background: As previously mentioned, xPLHal's macros are sub-routines written in the VBScript programming language. From this point, we will refer to macros as sub-routines. Scripts are text files containing a collection of sub-routines.

In the xPLHal Manager, expand the Scripts node. In the right-hand window you will see a list of all scrips in the root directory. xPLHal automatically creates scripts for each device it detects on your xPL network. You will see two nodes below the Scripts node in the tree: Headers and User. The Headers folder contains scripts that xPLHal creates automatically, as well as some special scripts containing code to be executed when the mode or period changes - more on those later. The User folder is intended to contain your own scripts, and it is here where we will write our macro.

It's worth noting that the scripting hierarchy is purely for organising your scripts - it makes no difference to xPLHal whether you put your scripts in the root directory, the headers directory or the user directory.

Creating the macro

  • Right-click on the User folder and select New Script.
  • The Script Editor appears.
  • On the Tools menu, click Sub-Routine Builder.
  • The Sub-Routine Builder Wizard will appear.
  • Click Next.
  • Enter the following as the name of the sub-routine, then click Next.
   X10_A1_On_Trigger(XplMsg)


We will talk more about the name of the sub-routine later.

  • On the next screen, click the Add button to add a new operation into your sub-routine.
  • In the list of Functions, select X10 Command.
  • Select "On" from the list of actions.
  • Enter B1 for the device, then click OK.
  • You will then be taken back to the sub-routine builder, with your newly created X10 command shown in the list.
  • Click Next.
  • The sub-routine builder will now create your sub-routine and show you the code it has created.
  • Click Finish.

The wizard will close and you will return to the Script Editor. The following sub-routine will now have been created for you:

 Sub X10_A1_On_Trigger(XplMsg)
   call X10.Send("B1","On",0)
 End Sub

The name of the sub-routine is very important - xPLHal will execute sub-routines based on their name.

For X10 events, the sub-routine names must be in the following format:

 X10_<Device>_<Command>_Trigger(XplMsg)

The XplMsg parameter contains the raw xPL message that the CM12 service generated when the X10 signal was received. Although we are not interested in it's contents for this example, it can be useful to query portions of the xPL message in more advanced situations.

The sub-routine contains a single command:

 call X10.Send("B1","ON",0)

In xPLHal, you have access to a number of special sets of routines. One such set of routines relates to X10 functionality. The Send routine allows an X10 command to be sent. The first parameter is the device to which the command is destined. The second parameter is the command, and the third parameter is the brightness level for dim and bright commands. For all other commands, the brightness parameter should be 0, and will be ignored.

  • On the File menu, click Save.
  • xPLHal will suggest a default name for the script, such as:
     User\NewScript.xpl

You should consider changing this to something like:

     user\x10.xpl

to better reflect the purpose of the script.

  • Click File -> Exit to close the Script Editor.
  • Right-click on the User folder and select Reload Scripts. You will receive a message saying scripts were reloaded successfully.

Now go ahead and press A1 on your X10 remote control, (or trigger a motion sensor that is set to A1) and you should see any device that is set to B1 switch on.

Using Timed Events

As well as responding to incoming xPL messages, xPLHal can also initiate macros in response to timed events. In this example, we will create a recurring event which occurs randomly between 21:00 and 22:00 each weekday evening to turn on a lamp.

  • Right-click on the Events node and select New Event.
  • On the Welcome screen of the New Event Wizard, click Next.
  • Select Recurring Event, then click Next.
  • You can now select the sub-routine to be executed. You can either pick one of the routines that is already defined, or you can create one using the Sub-Routine Builder. As we want to create a new routine, click the Sub Builder button.
  • Click Next on the Welcome screen of the Sub-Routine Builder.
  • Enter the name of the sub-routine, e.g. BedroomLightOn and click Next.
  • When the list of actions appears, click Add.
  • Select X10 Command from the list of functions.
  • If you have an X10 dimmer such as an LD11 that supports extended X10 codes, select Leviton Dim from the list of X10 actions. Otherwise, select On.
  • Enter an X10 device code that corresponds to the lamp you want to turn on, e.g. B1.
  • If you selected Leviton Dim, you can now specify the level to which the device should be set. This can be a value between 0 and 63. Values 0 through 62 will cause the light to be gradually adjusted to the specified level, whilst level 63 will cause the lamp to go straight to 100% brightness.
  • Click OK.
  • Back at the list of actions to be performed by your sub-routine, click Next.
  • The Sub Builder will create the routine and show you the code.
  • Click Finish to close the Sub-Routine Builder.
  • You will now return the the New Event Wizard, with your newly created sub-routine selected.
  • Click Next.
  • Now you must specify the time at which you want the event to be executed. For our example, select 21:00 and click Next.
  • On the next screen you can specify whether the event should occur once at the specified time, or whether it should occur at regular intervals between two specified times. For example, you may want to gradually send dim command to a lamp at 5 minute intervals over an hour-long period. For our example, we only want this event to occur once, so leave the values on this page unchanged and click Next.
  • Next you specify the amount of randomisation that will occur. This is a value that specifies by how many minutes the time that the event occurs will be randomised. Specifying a value of 0 will result in no randomisation, whilst specifying a value of 30 will result in the time of the event being randomised by a period of up to 30 minutes after the specified time. For our example, we want our light to come on between 21:00 and 22:00, so we enter 60 in the randomisation box to specify that the event should occur within 60 minutes after 21:00.
  • On the next screen, you can pick the days of the week on which you want the event to be executed. You can either tick the boxes for the individual days, or you can use the Select All button to select all 7 days, or the Select Weekday button to select Monday to Friday.
  • Finally you are asked to give the event a name. This will default to the same name as the sub-routine that will be executed, but you can change the name if you wish. Note that unlike sub-routine names, event names may contain spaces.
  • On the next page, the Event Wizard will summarise the event it is about to create. If you are happy with the options, click Finish and the event will be created.
  • If you look in the Scripts\User folder, you will see a script called events.xpl that contains the code for the event you just created.
  • Don't forget to reload the scripts to make your new sub-routine active.

When you edit or create scripts, they are not actually loaded into memory until you click the Reload Scripts menu option.

This allows you to make a series of changes and make them all active at a single time, without worrying about potential conflicts caused by incomplete code being loaded into memory.


Conclusion

In this HowTo we have shown you the basics of xPLHal and how you can use it to control your X10 devices without the need to do any programming. Although the Sub-Routine Builder is useful when creating simple macros, we highly recommend that you familiarise yourself with VBScript, as well as the xPLHal extensions to VBScript which are described in the online documentation.

There are already many xPL-enabled devices, including caller ID units, infra-red transmitters, text-to-speech applications, network MP3 players and many more.

Remember that xPL is an open protocol, and many of the xPL applications, including all the ones described in this HowTo, are available free of charge and released under the terms of the GNU General Public License.

xPLHal and it's associated applications are being actively developed, so if there's something you'd like xPLHal to be able to do, just let the development team know by posting a message to the mailing list enabled xPL forums.

This page was last modified on 15 February 2008, at 14:25. This page has been accessed 15,224 times.