"My Home Automation Projects"

xPLMyHouse - Device Xml File

Please also read the Disclaimer

Device XML File

A device xml file is needed for each type of device that you wish to add to xPLMyHouse
The standard device files are stored in .\Devices\ in the xPLMyHouse Program Files folder
User files can be stored in .\Devices\User\ and if they have the same name as a device file in .\Devices\ then the file is loaded instead of the standard file

A device is made up of information about the device, at least one state and a help text. It can also optionally include upto 6 parameters the user will input at the time the device is added to the floorplan, a method of requesting a single state, actions, attributes and statuses

The basic layout of the xml file is as follows [] = optional

<device basetype="" subtype="" devicetype="" [vendordevice=""] [ignorestate=""] [aliases=""] [security=""] [dependson=""] [offlinestate=""] [widget=""] [Other Options] >
    [parameters]
    [state request]
    state(s)
    [actions]
    [attributes]
    [statuses]
    [display]
    <help add="" />
</device>

basetype
This defines the basic type of the device and has the following possible values: Telephony, Utility, Media Device, Control, Light, Switch, Security, Sensors, PIR, Power, Medianet

subtype
This is a sub section of Basetype (e.g. a subtype of Telephony might be Caller ID) and can be any existing value or any new value

devicetype
The devicetype is the unique name of this particular xPL device. Using the example above this might be "Meteor Caller ID"

Other than providing at least one state (see later) the 3 items above are the only compulsory items in a device xml file

vendordevice
Where a device file relates to a specific xPL device you can specify the vendor-device (e.g. tonyt-meteor)
Otherwise you should specify * (or don't include vendordevice=)

ignorestate="true"
This allows you to specify that xPLMyHouse always acts on a message that effects the device, regardless of whether the state actually changes. i.e. if a device has a simple on/off pair of states xPLMyHouse would normally only action events etc which change the state from on to off (or off to on). By specifying ignorestate="true" means it will always action events even if the state doesn't actually change.

aliases="true"
This specifies if a user can create an alias of this device

security="true"
This specifies if this device is a security zone device. e.g. a PIR would be a security zone device. Security devices can be made part of a security area.

dependson
Use this to specify that the device can only be added if another device is already added to xPLMyHouse floorplan. e.g. a mediatnet rio device would have a dependon="medianet server"

offlinestate
With this you can specify a particular state (e.g. on or off) that the device will change to if it is offline (e.g. offlinestate="on")

widget
Specifies that this device should use a built-in widget of the xPLMyHouse GUI. Current widgets are medianet, sonos and webcam

add
The add parameter of the "help" section is used to provide a short description of the device and any special instructions

NOTE: after creating a device xml file it is advisable to open it in Internet Explorer to check the validity of the xml file

Other Options

These additional options are used to link a device to a particular function of xPLMyHouse

isdawndusk="true"
Device provides dawndusk information using dawndusk.basic

isgateway="true"
Device is a gateway device. A gateway would typically be an X10 or RF interface. Basically the 2nd device parameter provides a schema mask and any messages being sent that match that schema mask would be directed to the gateway instead of *

isoccupancy="true"
Device provides occupancy information using ocupancy.basic

issmtp="true"
Device provides an SMTP gateway using sendmsg.smtp

istwitter="true"
Device provides a Twitter gateway using sendmsg.twitter

istimer="true"
Device is a timer device

issecurity="true"
Device provides security system information using security.basic

issecurityarea="true"
Device is a security area

Parameters Section

Up to 6 parameters can be specified and these are filled in by the user when the device is added to the floorplan

name
The text for the parameter e.g. "xPL Instance Name"

usedevicename="true"
The parameter value gets populated by the name given to the device when it is added to the floorplan (useful for Homeeasy devices etc)

Parameters can be referenced in the other sections of the device xml file as {1} to {6}

In addition to referencing the items as {1} to {6}, if the first parameter is the xPL Instance name then it can be referenced as {instance}

State Request Section

This section allows a method of requesting the current device state. It is optional but if it exists then xPLMyHouse Pivot will action the method on start to update it's device state cache. It can also be used by the GUI to request all or a single state

xpl - msgtype
Any valid xpl message type i.e. xpl-cmnd, xpl-stat or xpl-trig

xpl - target
Either * or vendor-device.instance or vendor-device.{instance}
e.g. "tonyt-mypivot.{instance}"

xpl -schema
The xPL schema to be used e.g. dawndusk.request

xpl - message parts
Semi-colon seperated items that make up the xPL message
e.g. "command=status;query=daynight" or "command=status"

State(s) Section

This section defines the varying states that the device can have, how to determine that state and how to set that state. It also has a few other items as explained below.

This is the only section that MUST appear at least once. i.e. a device must have at least 1 state

Each state can have 1 "set" item (doesn't need to have one) and multiple "get" items

A device can have as many states as required BUT must have a minimum of one

state
This specifies the name of the state. Typically On/Off, Alert/Normal etc

image
The name of the image to use for this state on the floorplan and elsewhere. e.g. dawndusk_day.gif

menu
Specifies text to display on menu gui's when a device has a "set". Leave blank if no "get" specified

menuimage
Specify an alternative image for showing with a "set" menu item. Leave blank to use "state" image

door
This is either door="open" or door="closed"
If this device is dropped on a door you can relate the state of the device to the state of the door. e.g. for a door sensor device which has states alert/normal then the specify door="open" on the alert state and door="closed" on the normal state

antibounce
Use this to specify the number of seconds for which any change of state or repeat state will be ignored after a change of state

hidden="true"
Specifies this device is always hidden in GUI's (not in design/event modes)

timeout and timeoutstate
Allows an automatic timeout of a device to a different state where the state of a device cannot be guaranteed. Most likely use though would be where perhaps you use the xpl heartbeat to determine a device is online. e.g. for the "online" state specify that timeout="600" and timeoutstate="offline" which means if heartbeats were to stop, and no heartbeat end was handled/detected then the lack of hearbeat would be actioned

Set Item

The set is optional, but only 1 should exist if it does. It enables GUI's to set the device to this particular state

xpl - msgtype
Any valid xpl message type i.e. xpl-cmnd, xpl-stat or xpl-trig

xpl - target
Either * or vendor-device.instance or vendor-device.{instance}
e.g. "tonyt-mypivot.{instance}"

xpl -schema
The xPL schema to be used e.g. dawndusk.request

xpl - message parts
Semi-colon separated items that make up the xPL message
e.g. "command=status;query=daynight" or "command=status"

sanity
sanity is semi-colon separated list of states that the device must be in to make it valid to display this item. If no sanity is specified then the item is always available
e.g. for a media device then the "stopped" state would probably have sanity of sanity="playing;paused"

Get Item(s)

xpl - msgtype
Any valid xpl message type i.e. xpl-cmnd, xpl-stat or xpl-trig

xpl - source
Either * or vendor-device.instance or vendor-device.{instance}
e.g. "tonyt-mypivot.{instance}"

xpl -schema
The xPL schema to be used e.g. dawndusk.request

xpl - message parts
Semi-colon separated items that make up the xPL message
e.g. "command=status;query=daynight" or "command=status"

Single State

Every device must have at least one state, so for devices where a state is not applicable and online/offline via heartbeat is not possible then use a state similar to the following

image
This is the only item that should have a value when no state exists e.g. "webcam.gif"

Special States

It is also possible to specify special states that represent 2 or more of the above states in a group
These special states are not selectable BUT can be used for event handling

state
This is the description of the special state e.g. state="Any Occupied"

any
A hash separated and enclosed list of the states in the group
e.g. any="#occupied#single#active#sleep#"

This above examples allow for an event to be run on any occupancy occupied state based on the standard occupied states and also for any occupied state as "Any Occupied"

Actions Section

Actions allow for a device action to be made via the GUI or in eventing

name
A descriptive name of the action for a GUI menu

image
Image to use on the GUI menu

xpl - msgtype
Any valid xpl message type i.e. xpl-cmnd, xpl-stat or xpl-trig

xpl - target
Either * or vendor-device.instance or vendor-device.{instance}
e.g. "tonyt-mypivot.{instance}"

xpl -schema
The xPL schema to be used e.g. dawndusk.request

xpl - message parts OR {schema}
Semi-colon separated items that make up the xPL message
e.g. "command=status;query=daynight" or "command=status"

One of the message parts can optionally contain either {text} or {slider} e.g. speech={text} or volume={slider}

if {schema} is specified, rather than message parts, then the GUI would launch a dialog box and the message is constructed from the contents of the specified schema file (.\Schemas\)

sanity
An optional list of semi-colon separated states that the device must be in for this action to be offered. e.g. if an action is "power on", then sanity would probably be "power off"

prompt
Text prompt to display if message parts contains a text input

min, max and default (numeric)
The minimum and maximum values and default start values when a slider input is included in the message parts

Attributes Section

Attributes represent values associated with the device (e.g. volume level, mute on/off) that are not a state

A device can have as many attributes as required, or none

Each attribute has one, or none, setattr and can have multiple getattr

name
The name of the attribute (e.g. Volume Level)

min, max and realtime
Where the attribute is a numeric value and the setattr includes a {slider} then these are the minimum and maximum values of the slider. Realtime="true" or "false" specifies if the setattr is actioned on every change of the slider value or only on completion

sanity
A semi-colon list of states that setting the attribute is valid for

setattr - image
Image to use on GUI menus for this attribute

setattr - xpl
The message parts is semi-colon separated xpl message parts and can include either {slider} or {text}

getattr - xpl
The message parts is semi-colon separated xpl message parts and can include either {slider} or {text}
It must indicate which item gives the attribute value. e.g. level={attribute} means the attribute value will be set to match the value of level=

Statuses Section

Statuses are similar to Attributes, but they represent values only and cannot be sent

There can be as many statuses as required, or none

There are 2 types of Status

name
Description of the status (e.g. last phone number)

hide="true"
Specifying this option hides the status from GUI's but can be used in Eventing

getstat - xpl
The message parts is semi-colon seperated xpl message parts
It must indictate which item gives the status value. e.g. level={status} means the status value will be set to match the value of level=

name
Description of the status (e.g. last phone number)

onstate
When the device enters the state specified in onstate then the value of the status is set to the current date/time

Display Section
This section allows you to overlay information onto the image of the device. Might be useful for displaying a temperature on an image of a thermostat

status
The status value(s) to overlay on the image
Statuses are indexed from 0 so {0} = 1st status value
e.g. for my thermostat "{0}°{3}" displays {0} then current temperature then the degrees character then the unit of measure {3}

left and top
Numeric pixel position relative to the top left corner of the device image