Domotcl

Download

Terminology

Operation

Actions

Nodes

Drivers

Development

CM11 driver

Driver for devices that utilize the X-10 protocol. The driver requires a CM11 power line interface to transmit and receive X-10 signals.

X-10 is a power line protocol for controlling different types of devices, referred to as modules. An X-10 module is identified by its unit address. Such an address is a combination of one of 16 house codes (A through P) and a unit number (1 to 16). This means that an X-10 network can contain a maximum of 256 individually addressable units.

X-10 sequences

An X-10 sequence consists of a number of signals received on the power line in the specified order within a limited amount of time. Possible signals are:
  • A house and unit code (such as A-1)
  • A house and function code (such as A-On)
  • A preset dim level (e.g. Preset Dim 13)
An X-10 sequence is created by building a hierarchy of house/unit, house/func, and presetdim devices. Each of those devices has a timeout parameter that specifies the time limit for the sequence that matches the path through the hierarchy. A timeout of 0 means that the sequence is not yet complete (no event will fire at that point).
Regular X-10 modules that are included in an X-10 sequence behave the same as a house/unit device where the signal matches the house- and unit code of the device, with a timeout value of 0.
For example, assume the following hierarchy exists:
  • x10 - interface device
    • Fan - appliance device: House code=B, Unit code=12.
      • B12 - house/unit device: House code=B, Unit code=12, Timeout=0
        • Boff - house/func device: House code=B, Function code=Off, Timeout=8
      • Boff - house/func device: House code=B, Function code=Off, Timeout=3
        • Boff - house/func device: House code=B, Function code=Off, Timeout=5
Now also assume the following X-10 signals appear on the power line: B-12 (t=0), B-12 (t=2), B-off (t=6), B-off (t=9). Then this is what happens at different points in time:
  • t=0: The B-12 signal matches the /x10/Fan device, but no event fires because an appliance module has an implied timeout of 0 for X-10 sequences.
  • t=2: The /x10/Fan/B12 event does not fire because the timeout is set to 0.
  • t=6: The /x10/Fan/B12/Boff event fires because the B-12:B-12:B-Off sequence occurred in 6 seconds, which is within the limit of 8 seconds.
    The /X10/Fan/Boff event does not fire because the B-12:B-Off sequence that started at t=2 took 4 seconds, which exceeds the specified limit of 3 seconds.
  • t=9: The /x10/Fan/Boff/Boff event fires because the B-12:B-Off:B-Off sequence completed in 7 seconds.
The example demonstrates two features of X-10 sequences:
  1. X-10 sequences can overlap.
  2. A missed time out at some point of a sequence does not terminate the sequence.

Arguments

A CM11 is a serial device that can either be connected directly to the system that runs domotcl, or remotely via a terminal server. For that reason the driver offers the possibility to connect via either a serial interface (comport), or via TCP/IP (socket).
connection
The type of connection to use toward the CM11 interface.
Default: comport.

The next arguments depend on the value of the connection argument:
  • socket
    host
    The FQDN or IP-address of the terminal server.
    Default: 127.0.0.1.
    port
    The TCP port on the terminal server.
  • comport
    device
    The serial device name, e.g. /dev/cm11
    baudrate
    The baud rate of the serial connection
    Possible values: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 230400.
    Default: 4800.

Appliance type

An X-10 appliance module is a simple device that doesn't have any levels other than on and off.

Arguments

address
The device addres, e.g: A1
options
Options define which X10 signals are honored by the device.
Available options: alllightson, alllightsoff, allunitsoff.

Properties

state
The current state of the device.
Possible values: off, on, neutral.

Events

on
Fires when an X-10 On signal is received for the device.
off
Fires when an X-10 Off signal is received for the device.
state
Fires whenever the state of the device changes.

Commands

on
Switch the module to the on state.
off
Switch the module to the off state.
toggle
Switch the module to the on state if it is currently off, or to the off state if it is currently on or neutral.
refresh
Send the necessary X-10 signals to set the device to the current state, as tracked by domotcl.
neutral
Set the tracking state of the module to unknown. No X-10 signal is sent onto the power line.
unitcode
Transmit the house/unit code of the device onto the power line.

Lamp type

An X-10 lamp module is a device that can be set to a desired brightness level.

Arguments

address
The device addres, e.g: A1
options
Options define which X10 signals are honored by the device.
Available options: alllightson, alllightsoff, allunitsoff.

Properties

state
The current state of the device.
Possible values: off, on, neutral.
level
Brightness level in %.
An integer value between 0 and 100.

Events

on
Fires when an X-10 On signal is received for the device.
off
Fires when an X-10 Off signal is received for the device.
state
Fires whenever the state of the device changes.
level
Fires whenever the value of the level property changes.

Commands

on
Switch the module to the on state.
off
Switch the module to the off state.
toggle
Switch the module to the on state if it is currently off, or to the off state if it is currently on or neutral.
refresh
Send the necessary X-10 signals to set the device to the current state, as tracked by domotcl.
neutral
Set the tracking state of the module to unknown. No X-10 signal is sent onto the power line.
unitcode
Transmit the house/unit code of the device onto the power line.
dim amount speed
Reduce the brightness level by the specified amount.
bright amount speed
Increase the brightness level by the specified amount.
level pct speed
Set the brightness level to the specified value.

LW11 type

An LW11 lamp module is a lamp device that supports additional methods to control the light level.

Arguments

address
The device addres, e.g: A1
options
Options define which X10 signals are honored by the device.
Available options: alllightson, alllightsoff, allunitsoff.

Properties

state
The current state of the device.
Possible values: off, on, neutral.
level
Brightness level in %.
An integer value between 0 and 100.

Events

on
Fires when an X-10 On signal is received for the device.
off
Fires when an X-10 Off signal is received for the device.
state
Fires whenever the state of the device changes.
level
Fires whenever the value of the level property changes.

Commands

on
Switch the module to the on state.
off
Switch the module to the off state.
toggle
Switch the module to the on state if it is currently off, or to the off state if it is currently on or neutral.
refresh
Send the necessary X-10 signals to set the device to the current state, as tracked by domotcl.
neutral
Set the tracking state of the module to unknown. No X-10 signal is sent onto the power line.
unitcode
Transmit the house/unit code of the device onto the power line.
dim amount speed
Reduce the brightness level by the specified amount.
bright amount speed
Increase the brightness level by the specified amount.
level pct rate
Set the brightness level to the specified value.

Shutter type

An X-10 shutter module is used to control sunblinds. Depending on how the module is connected, "off" can either mean fully closed, or fully open. The official method is to consider "off" fully closed, which doesn't seem right to me.

Arguments

address
The device addres, e.g: A1

Properties

state
The current state of the device.
Possible values: off, on, neutral.
level
The current level of the blinds, in %.
An integer value between 0 and 100.

Events

on
Fires when an X-10 On signal is received for the device.
off
Fires when an X-10 Off signal is received for the device.
state
Fires whenever the state of the device changes.
level
Fires whenever the value of the level property changes.

Commands

on
Switch the module to the on state.
off
Switch the module to the off state.
toggle
Switch the module to the on state if it is currently off, or to the off state if it is currently on or neutral.
refresh
Send the necessary X-10 signals to set the device to the current state, as tracked by domotcl.
neutral
Set the tracking state of the module to unknown. No X-10 signal is sent onto the power line.
unitcode
Transmit the house/unit code of the device onto the power line.
dim amount speed
Reduce the shutter level by the specified amount.
bright amount speed
Increase the shutter level by the specified amount.
level pct
Set the shutter level to the specified value.

Housecode type

An X-10 house code can contain a maximum of 16 modules.

Arguments

address
The house code.
Possible values: A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P.

Commands

on
Send an X-10 On house/function code onto the power line.
off
Send an X-10 Off house/function code onto the power line.
alllightson
Send an X-10 AllLightsOn house/function code onto the power line.
allunitsoff
Send an X-10 AllUnitsOn house/function code onto the power line.
alllightsoff
Send an X-10 AllLightsOff house/function code onto the power line.
allshutterson
Send an X-10 AllShuttersOn extended code for the house code (CMD=4, DATA=0) onto the power line.
allshuttersoff
Send an X-10 AllShuttersOff extended code for the house code (CMD=11, DATA=0) onto the power line.
statusreq
Send an X-10 StatusRequest house/function code onto the power line.
statuson
Send an X-10 StatusOn house/function code onto the power line.
statusoff
Send an X-10 StatusOff house/function code onto the power line.
hailreq
Send an X-10 HailRequest house/function code onto the power line.
hailack
Send an X-10 HailAck house/function code onto the power line.
bright
Send an X-10 Bright house/function code onto the power line.
dim
Send an X-10 Dim house/function code onto the power line.
scene scene
Execute the specified X-10 scene.
refresh
Refresh all units in the house code.

House/Unit type

The House/Unit device type defines a signal of an X-10 sequence.

Arguments

hc
House code.
Possible values: A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P.
unit
An integer value between 1 and 16.
timeout
Maximum allowed time for the sequence (seconds). Set to 0 if the sequence is not yet complete.
Default: 0.

Events

sequence
Fires when the sequence is detected on the power line.

House/Func type

The House/Func device type defines a signal of an X-10 sequence.

Arguments

hc
House code.
Possible values: A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P.
func
Possible values:
  • On
  • Off
  • Bright
  • Dim
  • All Lights On
  • All Lights Off
  • All Units Off
  • Hail Request
  • Hail Acknowledge
  • Status Request
  • Status Is On
  • Status Is Off
  • Extended Code
  • Extended Data
timeout
Maximum allowed time for the sequence (seconds). Set to 0 if the sequence is not yet complete.
Default: 0.

Events

sequence
Fires when the sequence is detected on the power line.

PresetDim type

The PresetDim device type defines a signal of an X-10 sequence.

Arguments

level
An integer value between 0 and 31.
timeout
Maximum allowed time for the sequence (seconds). Set to 0 if the sequence is not yet complete.
Default: 0.

Events

sequence
Fires when the sequence is detected on the power line.

Interface type

The interface device type represents the complete X-10 network.

Commands

dimlevel level
Send a Preset Dim X-10 signal onto the power line.
allshutterson
Send an X-10 AllShuttersOn extended code for the network (CMD=5, DATA=0) onto the power line.
allshuttersoff
Send an X-10 AllShuttersOff extended code for the network (CMD=12, DATA=0) onto the power line.

Functions

index num
Find an X-10 module by its index (0=A-1, 1=A-2, etc.)