Plugin: XPL
Launch Data (ActiveX
Classname): PH_XPL.phxpl
Initialization Data : Enter the full path and filename
of the INI file for this particular instance of the xPL plugin. If
you're using the defaults, then this value will be: c:\program
files\powerhome\plugins\phxpl.ini
The PowerHome Generic xPL Plugin provides send and receive support for xPL
messages to PowerHome. It is the first of a series of steps to
implementing the xPL protocol from within PowerHome. The next step
is to provide an xPL controller within PowerHome so PowerHome can send and
receive controller commands from other xPL gateways. If you would
like to learn more about xPL as well as the programs available, visit
http://wiki.xplproject.org.uk/index.php/Main_Page.
Using the xPL Plugin, users can send xPL messages using the ph_picmd
function. Multiple filters for incoming messages can be set and the
plugin will fire Generic Plugin triggers on incoming messages. You
can also have multiple instances of the xPL Plugin running with a
completely different set of filters and triggers. You MUST have an
xPL Hub running on the PowerHome machine. It is also useful to have
some xPL compliant programs running on either the PowerHome machine or on
other machines on your internal network in order for the plugin to be
useful. Keep in mind that you MUST have an xPL Hub running on every
machine that is hosting an xPL program. You will also most likely
need to configure personal firewalls such as Comodo or ZoneAlarm in order
to allow the xPL traffic to be transmitted and received.
Configuring the phxpl.ini file:
- Open the phxpl.ini file in Notepad. You'll need
to configure the xPL plugin by modifying this file.
- Under the [Setup] section, set the "Instance"
parameter to a unique instance name for this iteration of the plugin.
The instance name MUST be lower case letters a thru z and numbers 0-9
only. No spaces, no dashes, or any others characters are
acceptable. The total length of the instance name MUST be 16 characters
or less. If you will be running multiple instances of the xPL plugin,
you MUST make a copy of the phxpl.ini file with a different filename (such as
phxpl1.ini). Make sure that each xPL plugin instance has a separate,
unique "Instance" parameter.
- Set the "Target" parameter to a valid xPL target
application ID for direct communications. Use "*" without the quotes to
broadcast your xPL messages to all xPL clients. The "Target" parameter
only affects the sending of xPL messages.
- Set the "Interval" parameter to a value between 5 and
9 inclusive. This is how often an xPL heartbeat message will be sent by
the plugin. The default value of 5 should be fine.
- Set the "PassHBeat" parameter to "yes" if you want
the plugin to pass xPL heartbeat messages to the filter processor (a filter
may still block the message depending upon the filters). If you set the
parameter to "no" then heartbeat messages are outright discarded.
- Set the "PassConfig" parameter to "yes" if you want
the plugin to pass xPL config messages to the filter processor (a filter may
still block the message depending upon the filters). If you set the
parameter to "no" then config messages are outright discarded.
- Under the [Filters] section, you can define up to 16
different filters for incoming messages. Keep in mind that filters ONLY
affect incoming messages. Messages sent from the plugin are
automatically discarded. When an xPL message is received, it's first
checked to see if it originates from the current plugin instance. If it
does, it's discarded. It's then checked for accuracy in following proper
xPL format and if it fails, it's discarded. The message is then
determined whether it's a heartbeat or config message and depending upon the
settings in the [Setup] section, may be discarded. If a message makes it
this far, it is then checked against the filters in order from 1 to 16 (or
less if you have less). If a message does not MATCH a filter, it is
discarded. In order for the plugin to fire a trigger on a message, it
MUST match at least one plugin. This means that you MUST declare at
least ONE filter. More information on Filters can be found on the xPL
website under the Core Protocol documentation. Below is a very brief
overview of filters to get started with.
- The filter to match ALL incoming xPL messages is:
*.*.*.*.*.*
- An xPL message consists of 6 separate sections
separated by a single period. You can use the asterisk (*) character to
wildcard a section. The sections are: xPL command, source vendor, source
device, source instance, schema, and type. A typical message might look
like: xpl-cmnd.pha.phpi.xpl.x10.basic. This would be a fully qualified
message and would be matched by the ALL filter above or the following filters:
- *.pha.*.*.x10.*
- *.pha.phpi.*.*.*
- *.*.*.*.x10.*
- xpl-cmnd.*.*.*.*.*
- xpl-cmnd.pha.phpi.xpl.x10.basic
- In order for a trigger to be fired, the incoming
message MUST match at least one filter. The particular filter that is
matched, WILL ALSO determine the particular trigger that is fired. As
such, the order in which you define filters is important. It would do no
good to define the following filters in this particular order:
- *.pha.*.*.*.*
- *.pha.phpi.*.*.*
- Since the first filter will always be matched before
the second filter has a chance to be checked. As such, filters should
typically be defined in order of most restrictive to least restrictive.
Leave unused filter lines blank.
- Once you've finished defining your filters, close and save the INI
file.
At this point, you should already have an xPL Hub up
and running. Launch PowerHome and open the PowerHome Explorer.
Navigate to Setup|Controllers and create a new blank plugin line.
Give the plugin an appropriate ID and use the following information for
the "Launch Data (ActiveX Classname)": PH_XPL.phxpl
For the "Initialization Data" field, enter the full path and filename of
the INI file for this particular instance of the xPL plugin. If
you're using just a single instance or this is the first instance, the
default value would be: c:\program files\powerhome\plugins\phxpl.ini
Close the PowerHome Explorer and restart or reinitialize PowerHome in
order for the plugin to be loaded. Once PowerHome restarts, go to
Help|About|Plugins and verify that the plugin successfully started.
Using the PowerHome xPL Generic Plugin:
- To send xPL messages, use the ph_picmd
function. The simplest way to send an xPL message is shown in the
example below:
- ph_picmd(5,"XPL",1,0,0,"x10.basic","command=ON~ndevice=B5")
- In the example above, the first parameter is 5
which is the number of seconds to wait for the plugin to process the command
before timing out.
- The second parameter is "XPL" which is our sample
programs ID for the xPL plugin (defined in the Plugins screen of the
PowerHome Explorer).
- The third parameter is the command type for the
plugin to perform. In this case, the value is 1 which tells the plugin
to send a simple xPL message using the INI file supplied target and the INI
file supplied Instance as part of the source ID. The hops will be set
to 1.
- The fourth parameter (0 in the example) is the type
of xPL message to send. A value of 0 is for an xpl-cmnd message.
- The fifth parameter is not used so is left as 0.
- The sixth parameter is "x10.basic" which is the xPL
schema and type.
- The seventh parameter("command=ON~ndevice=B5" in the example) is
the body of the xPL message. This particular message has two
name/value pairs consisting of command and device. It's
important to note that a "~n" is used to separate the name/value
pairs. The "~n" is the PowerHome equivalent to the line feed
character and is required to separate name/value pairs when
constructing your xPL messages. You MUST not embed any spaces,
commas, or other characters in the body unless it's actually a part
of the value section of a name/value pair.
- The available command types for use in the ph_picmd
function are:
- Send Simple xPL message.
lData1 = xPL command type (0 = xpl-cmnd, 1 = xpl-stat, 2 = xpl-trig)
lData2 = Unused
sData3 = xPL schema and type
sData4 = xPL message body. Separate name/value pairs
with a line feed character (~n in PowerHome)
- Send Raw xPL message.
lData1 = xPL command type (0 = xpl-cmnd, 1 = xpl-stat, 2 = xpl-trig
lData2 = Unused
sData3 = Source ID (in the format of xxx-yyy.zzz), Target ID (in the
format of xxx-yyy.zzz or *), and schema/type. Separate the 3
individual components with a line feed character.
sData4 = xPL message body. Separate name/value pairs
with a line feed character (~n in PowerHome)
- Set the default target for messages sent with command 1.
lData1 = Unused
lData2 = Unused
sData3 = New target in the form of xxx-yyy.zzz or * for broadcast.
sData4 = Unused
- Retrieve the current default target for sending xPL messages.
lData1 = Unused
lData2 = Unused
sData3 =
Unused
sData4 = Unused
- Set the values for whether or not to pass Heartbeat and Config
messages.
lData1 = 0 to NOT pass Heartbeat messages. > 0 to pass Heartbeat
messages. < 0 for no change.
lData2 = 0 to NOT pass Config messages. > 0 to pass Config
messages. < 0 for no change.
sData3 = Unused
sData4 = Unused
- Return whether the plugin is configured to pass Heartbeat messages
or not.
lData1 = Unused
lData2 = Unused
sData3 =
Unused
sData4 = Unused
- Return whether the plugin is configured to pass Config messages or
not.
lData1 = Unused
lData2 = Unused
sData3 =
Unused
sData4 = Unused
- The return value from the ph_picmd function will be as follows:
0 = success
1 = error
99 = bad command
100 = plugin not enabled
- On command 2, a "2" can be returned if the sData3
parameter was not properly constructed.
- On command 4, the return value will be the current
Target ID.
- On commands 6 and 7, "1" will be returned if the
value is true, "0" will be returned on false.
- If a match is made on one of the 16 filters, then the
plugin will fire a "Generic Plugin" trigger. The particular values for
the "Trigger ID Number" and "Trigger Value" will depend upon the type of xPL
message received and the particular filter that was matched. To fire a
single trigger on ANY matching xPL message, use a "Trigger ID Number" of
"(Any)" and a "Trigger Value" of "(Any)".
- The Trigger ID Number fired is dependant upon the
filter matched (in the case of broadcast messages) or if it's a direct message
matching the source ID of the xPL plugin. The Source ID of the xPL
plugin will be: pha-phpi.INSTANCE where INSTANCE is the instance defined in
the INI file. If the message is a direct message that exactly matches
the source ID of the plugin, the Trigger ID Number will "Command 1". If
it's a broadcast message that matches Filter1, then "Command 2" will be
fired. A Filter2 match will fire "Command 3". Following this
sequence, this means that valid Trigger ID Numbers will be from Command 1 to
Command 17. You can use (Any) to fire on any match.
- The Trigger Value fired is dependant upon the type of
xPL message. Option 1 will be fired for xpl-cmnd messages. Option
2 will be fired for xpl-stat messages. Option 3 will be fired for
xpl-trig messages. You can use (Any) to fire on any type of message.
- When the trigger is fired, both the [TEMP] and [LOCAL] variables
will populated with trigger related data. The data populated
will be as follows:
[TEMP1] = The ID of the trigger
[TEMP2] = 0
[TEMP3] = The number of name/value pairs in the body of the xPL
message
[TEMP4] = The number of hops in the xPL message
[TEMP5] = The Schema and type of xPL message
[TEMP6] = 27
[TEMP7] = The ID of xPL plugin
[TEMP8] = The Trigger ID Number (1 for Direct message, 2 - 17 for
Filter 1 thru 16
[TEMP9] =
The Trigger Value (1 for xpl-cmnd, 2 for xpl-stat, 3 for
xpl-trig
[TEMP10] = The Source ID of the xPL message
[LOCAL1] = The value of the 1st Name/Value pair
[LOCAL2] = The value of the 2nd Name/Value pair
[LOCAL3] = The value of the 3rd Name/Value pair
[LOCAL4] = The value of the 4th Name/Value pair
[LOCAL5] = The value of the 5th Name/Value pair
[LOCAL6] = The value of the 6th Name/Value pair
[LOCAL7] = The value of the 7th Name/Value pair
[LOCAL8] = The raw body section of the xPL message (The name/value
pairs)
[LOCAL9] = The target of the xPL message
[LOCAL10] = The complete raw xPL message
- Since xPL messages have their name/value pairs in a predictable
order (based upon the message), you should be able to quickly
reference up to the first seven values in the [LOCAL1] thru [LOCAL7]
variables. If the message has more than 7 name/value pairs OR if
you wish to access the NAME as well as the VALUE, you'll need to parse
[LOCAL8] since it will contain ALL of the name/value pairs in raw
format.