xPLHal is based on the .NET framework, so to install it you require the Framework installed.
Please note that this version of xPLHal is a Service and therefore will only run on NT4,
W2K and WinXP. An exe version is also available, for Win98/ME.
Download the current version of xPLHal from
http://www.xplproject.org.uk/modules.php?op=modload&name=Sections&file=index&req=printpage&artid=25&POSTNUKESID=a850ca4b4d08fd20362276bd7bc63adaNote that the current version of the service is always available seperately for download.
To install this stop your current versions service, copy the new service exe into
c:Program FilesxPLxPLHal & restart the service. This means your existing settings and
scripts will not be lost.
If you wish to do a completely fresh install, then you should un-install the current version
and delete the xPLHal program directory.
Having downloaded the zip file and extracted it to a temporary directory, just double-click
the ./release/xPLHalSetup.msi file to install. It is recommended that the default
installation folder is used where possible.
This will install all of the necessary files along with sample scripts.
The folder structure is (files in [] are not part of the installation, but will appear after
xPLHal has been running):
File/Folder Structure
---------------------
./xPLHal.exe - the main service exe for xPLHal
./Interop.MSScriptControll.dll - a dll to enable vb scripting in .net
./xpllib.dll - John's excellent xPL library
./xplhal.InstallState - a file created by the installation
./data/xplhal.xml - main xPLHal configuration file
[./data/xplhal_events.bin] - file containing saved events
[./data/xplhal_globals.bin] - file containing saved global values
[./data/xplhal_x10cache.bin] - file containing a cache of x10 devices and states
[./data/error_log.txt] - a text file for error logging
./data/Configs - this folder contains cached device configurations
./data/Vendor - this folder contains vendor supplied (or xplhal
auto-created) device configuration descriptions
./data/scripts - this folder contains the scripts
./data/scripts/xPLHal_Load.xpl - script file run when xPLHal Loads
./data/scripts/xPLHal_Unload.xpl - script file run when xPLHal quits
./data/scripts/*.xpl - the best place to put device/schema based scripts
includes some sample scripts
./data/scripts/headers - contains various header files
./data/scripts/headers/modes.xpl - a script file for MODE related scripts
./data/scripts/headers/periods.xpl - a script file for PERIOD related scripts
./data/scripts/headers/xPLHal_Settings.xpl - a script file created at load
DO NOT EDIT!
./data/scripts/headers/xPLHal_SYS.xpl - a script file for defining SYS parameters for
vb scripting. Avoid editing.
./data/scripts/headers/xPLHal_X10.xpl - a script file for defining X10 parameters for
vb scripting. Avoid editing.
./data/scripts/headers/xPLHal_XPL.xpl - a script file for defining XPL parameters for
vb scripting. Avoid editing.
./data/scripts/user/*.xpl - an area for users to put other scripts
includes sample scripts
Please note that script files put in folders other than those above will NOT be loaded.
The ./scripts/headers folder is really reserved for xPLHal. However the defines they
include are there to aid the user. In particular you will need to refer to the X10 script
for the defines to use in conjunction with x10 vb script extensions.
Configuration
-------------
The only immediate file to be concerned about is ./data/xplhal.xml
This file can be edited with notepad
After editing the file it is necessary to restart the xPLHal service
THE INFORMATION BELOW (other than deciding whether or not to use the hub) is included only
for completeness, and CAN be ignored at this time from the point of view of making changes.
However it is recommended to read the information to understand how sub routine names
are constructed and executed.
There are 3 main sections in this file,
Settings
This section currently contains a single entry,
<control loadhub="N" />
If you wish to make use of xPLHal's built-in hub, change the value to "Y"
If you already have an xPL Hub running on the same machine this MUST be "N"
You can run xPLHal without a hub, but it MUST be the ONLY xPL application
Constructs
This section contains the definitions for the components that can used to construct
the layout of vb script sub names for scripting xPL messages and also contains
the definition of available settings.
The first 6 entries relate to xPL message components and MUST NOT be changed
<construct subid="F" key="%msgtype%" desc="Message Type" />
<construct subid="V" key="%vendor%" desc="Source Vendor" />
<construct subid="S" key="%device%" desc="Source Device" />
<construct subid="I" key="%instance%" desc="Source Instance" />
<construct subid="C" key="%class%" desc="Schema Class" />
<construct subid="T" key="%type%" desc="Schema Type" />
The next 3 entries relate to X10 specific message components and MUST NOT be changed
<construct subid="H" key="%house%" desc="X10 House Code" />
<construct subid="D" key="%device%" desc="X10 Device Code" />
<construct subid="X" key="%command%" desc="X10 Command" />
The remaining entries can edited/deleted as required, and additional entries created
They consist of a descriptive line as per the standard entries above
Each entry is then followed by a list of valid values
Internally in xPLHal the first value is 0, next is 1 etc in the order they appear
There are 2 of these types of entry in the file by default, MODE and PERIOD
<construct subid="M" key="mode" desc="Mode" />
<values key="empty" desc="Security" />
<values key="single" desc="Single Occupant" />
<values key="multiple" desc="Multiple Occupants" />
<values key="bedroom" desc="Bedroom Security" />
<values key="sleep" desc="Sleep Security" />
<construct subid="P" key="period" desc="Period" />
<values key="day" desc="Daytime" />
<values key="night" desc="Nightime" />
To explain the structure of the above (the construct key),
subid= this is a single letter to uniquely identify
the sub in the schema's section (see later)
key= this is a short name for the entry/setting (% denotes a system value)
desc= this is a description for the entry
The values are constructed as follows,
key= this is the short name of the value (used in the sub/function names)
desc= this is a description of the value
As stated previously each value entry is internally recognised in xPLHal
starting at 0
To aid the use of these values in vb scripting xPLHal generates the file
./scripts/headers/xplhal_settings.xpl with defines of the above values, e.g.
' constants for mode
const sys_mode_empty=0
const sys_mode_single=1
const sys_mode_multiple=2
const sys_mode_bedroom=3
const sys_mode_sleep=4
' constants for period
const sys_period_day=0
const sys_period_night=1
Therefore rather than remembering to put 3 for 'bedroom' mode you can always
refer to it in scripts as sys_mode_bedroom, and not have to worry about the
value changing if you insert other values later. It is also easier to remember.
Although variations on the MODE and PERIOD constructs above are probably the only
options you will need, by making these (and additions) totally user-definable you
can easily control the internal settings of xPLHal. e.g. you may find it useful
to create a weather construct (with values of say hot, cold, wet etc) that you
could then make use of in scripting.
There are functions within xplhal that you can use within your vb scripts to
set/get the current value. e.g. x = sys.setting("MODE") returns the current MODE.
To restore a setting to it's previous state on loading xplhal you MUST include
a statement equivalent to sys.setting("Period")=sys.value("Period") for each of
your additional settings. Otherwise the setting will always inialise to ZERO.
NEVER set the value by sys.value("Period")= ALWAYS use sys.setting("Period")=
Schemas
This final section maps how you wish to construct particular sub routine names
against different messages. It is based on the principle of xPL filters.
All but the last entry (subs) make up the filter for the particular xPLmessages
with * used to wildcard any particular element
msgtype= this is the xPL message type (e.g. xpl-cmnd, xpl-stat and xpl-trig)
source_vendor= this is the vendor component (e.g. tonyt)
source_device= this is the name of the app/device (e.g. cm12u or TTS)
source_instance=this is the individual instance assigned (e.g. line1)
schema_class= this is the schema class (e.g. CID or OSD)
schema_type= this is the type within the schema (e.g. BASIC or EXTENDED)
The subs= item defines how the sub-routine name will be constructed
e.g. "VSIF" is Vendor/Source/Instance/message type which might result in a sub being
called (if a message matches the filter) of tonyt_tts_voice1_Command(xplmessage)
This ability to totally define how sub routine names are constructed gives
total control over the scripting in xPLHal
Messages are matched against the filters in turn until a match is made,
if the subroutine exists in a script file somewhere then it is run, otherwise
xPLHal continues to attempt to match against the next filter.
<!-- format for heartbeat and config messages -->
<schema msgtype="*" source_vendor="*" source_device="*" source_instance="*" schema_class="HBEAT" schema_type="*" subs="VSIF" />
<schema msgtype="*" source_vendor="*" source_device="*" source_instance="*" schema_class="CONFIG" schema_type="*" subs="VSIF" />
These first 2 default entries are designed for heartbeat messages and config messages
<!-- format for x10 messages -->
<schema msgtype="*" source_vendor="*" source_device="*" source_instance="*" schema_class="X10" schema_type="*" subs="DMPXF" />
This above is a sample x10 definition, any entries containing H,D or X are considered
to be x10 type messages and are treated slightly differently.
A message containg multiple devices would cause multiple subs to be run
e.g. DEVICE=A1 ON,B2 OFF for this example could generate
X10_A1_SINGLE_DAY_ON_Trigger AND X10_B2_SINGLE_DAY_OFF_TRIGGER
X10 Sub routines are always preceeded with X10_ for identification
With X10 scripting, Where no sub routine is found in the scripts, an attempt
is made to run a default construct of "DXF" so the above examples would (if
they didnt exist) then be tried as X10_A1_ON_Trigger() etc
<!-- catch all for all other message types -->
<schema msgtype="*" source_vendor="*" source_device="*" source_instance="*" schema_class="*" schema_type="*" subs="VSIF" />
The final example above is a catchall
You may delete/amend and add as many entries as required to taylor the way
xPLHal and the Ultra Hal Assistant constructs it's sub routine names. But you MUST have at least one entry!
It is recommended to start with the above samples, which may be all you'll require,
and to look at the sample scripts to get a better understanding of how this works.
All non-alphanumeric characters in a generated script name are replaced with underscores
xPLHal always passes the full xPLMessage to the sub routine as a parameter
Please refer to the scripting manual for more details
IMPORTANT NOTES
---------------
The X10 scripting and X10 Cache is an ongoing development, and now can be used in our Ultra Hal Assistant.
