xPL Integrating Common Devices and Applications

Note: if you are new to xPL, please first read xAP and xPL - Getting Started.

Generic Sensors

Schema(s): sensor.basic

mht Syntax:

XPL_SENSOR, <xpl_address>:<device_id>, <mh_item_name>, <mh_grouplist>, <sensor_type>, <state_key>

notes:

• <mh_group_list>, <sensor_type> and <state_key> fields are optional
• unless <sensor_type> is specified, the item will look for updates of "type=input"
• The sensor state will track to the "current" message attribute unless the <state_key> is provided

Example Usage - Receiving status from a device:

This example is for some generic sensor device which will report the value of a key called "pin1".

mht Definition:

XPL_SENSOR, my-device.monitor:1, mysensor_1, Sensors, input, pin1

xPL message from the device:

The key parts of the message:

• source= maps to the xpl_address in the sensor definition: (my-device.monitor)
• device= in the schema maps to the device_id (right of the colon) in the definition (1)
• type= must match the sensor_type defined in the mht (input)
• pin1= matches the state_key in the definition

xpl-stat
{
hop=1
source=my-device.monitor
target=*
}
sensor.basic
{
type=input
device=1
pin1=on
}

Code to detect state changes:

When an xPL message is received that completely matches the sensor definition source:device,type & key, then the state_now will be passed the value of the state_key in the message

if (my $state = $mysensor_1->state_now) {
print_log "Sensor mysensor_1 state changed: $state";
}

When the above message is received by misterhouse, the message "Sensor mysensor_1 state changed: on" would be logged.

Example Usage - Sending output to the device:

in items.mht:

XPL_SENSOR, mandoon-switchcontrol.loungefan:1, LoungeFan_1, Fans, output

in user code:

# the following statement causes a control.basic message to be
# sent anytime: $LoungeFan_1->set(ON);
# it is needed since otherwise, $LoungeFan_1 is receive only
#
# NOTE: The following is no longer needed as it is automatically created.
# However, if you need a different message class (than 'control.basic') or
# attribute (than 'current'), then you will need to use the on_set_message method

$LoungeFan_1->on_set_message('control.basic' => { 'current' => '$state' }); #noloop

# do something in case the state is changed from another device
if ($LoungeFan_1->state_now) {
         print_log "LFan1 state=$state";
}

Example Usage 2 - Sending status from MisterHouse variable

In your user code, add:

$rain_sensor = new xPL_Item(&xPL::get_xpl_mh_source_info); #noloop

if ($state = state_now $is_raining) {
  $rain_sensor->send_trig('sensor.basic' => {
    'x##device'  => 'rain_sense',
    'y##type'    => 'intput',
    'z##current' => $state eq 'true' ? 'HIGH' : 'LOW'
 });
}

Power Supply Management

Schema(s): ups.basic

XPL_UPS, <xpl_address>:<device_id>, <mh_item_name>, <mh_grouplist>

Irrigation

Schema(s): sprinklr

XPL_IRRIGATEWAY, <xpl_address>, <mh_item_name>, <mh_group_list>
XPL_IRRIVALVE, <valve_id>, <mh_item_name>, <gateway_item_name>, <mh_group_list>
XPL_IRRIQUEUE, <queue_id>, <mh_item_name>, <gateway_item_name>, <mh_group_list>

Example Usage:

in items.mht:

XPL_IRRIGATEWAY, cdp1802-sprinklr.irrigation, irrigateway, outside
XPL_IRRIQUEUE, 0, default_queue, irrigateway
XPL_IRRIQUEUE, 1, prewater_queue, irrigateway
XPL_IRRIVALVE, 1, front_lawn_valve, irrigateway
XPL_IRRIVALVE, 2, side_lawn_valve, irrigateway

in user code:

# we always want for mh to be aware of the status of the gateway and it's valves
# so, on reload, interrogate the gateway:
if ($Reload) {
   $irrigateway->request_stat();
}

# assume that other logic has declared and set $front_lawn_is_dry
if ($front_lawn_is_dry) {
    # schedule front_lawn_valve for 30 minutes of water
    # on the default queue:
    $front_lawn_valve->set(30);
    # if the prewater queue would have been preferred, then:
    $side_lawn_valve->set("30:1");
    # queue id is optional second arg; note requirement to use quotes
 }
# setting front_lawn_valve doesn't result in a state change until the
# irrigation controller actually opens/operates the valve;
# so, to notify opening a valve:
if ($front_lawn_valve->state_now eq ON) {
    speak "Now watering the front lawn";
}

Additional hints:

• set debug=irrigation

Lighting

Schema(s): lighting

mht Syntax:

XPL_LIGHTGATEWAY, <xpl_address>, <mh_item_name>, <mh_group_list>
XPL_LIGHT, <device_id>, <mh_item_name>, <gateway_item_name>, <mh_group_list>

Example usage:

in items.mht:

XPL_LIGHTGATEWAY, mal-xplzwave.gateway, light_gateway, Gateways
XPL_LIGHT, light1, mh_light1, light_gateway, All_Lights

in user code:

# always interrogate the gateway at startup; in turn, all other devices are interrogated
if ($Reload) {
   $light_gateway->request_stat(1);
}

# turn a light on:
$mh_light1->set(ON);
# turn a light off:
$mh_light1->set(OFF);
# turn a light on to some dim level:
$mh_light1->set('60%');

# note that relative dims are not intrinsically supported by the gateway and would
# have to be interpretted by the mh code

Additional hints:

• set debug=xpl_light

Basic control

Schema: control.basic

mht syntax:

XPL_SENSOR, <xpl_address>, <mh_item_name>, <mh_group_list>, output

Example usage:

in items.mht:

XPL_SENSOR, hollie-utilmon.ventimon:pwmout, venti_speed, , output

in user code:

# Set the pwm output to 60 (pwmout is of type 'variable', so valid values are 0-255)
$venti_speed->set(60);

Useful info

If you are interfacing to device that depend on the order of the key/value pairs in the xPL message, it is possible to order them. Just prepend the key name with a sort key in this format:

##.

E.g. if the key 'current' needs to be sent last, call it zz##current.