Domotcl

Download

Terminology

Operation

Actions

Nodes

Drivers

Development

Terminology

A number of terms are used throughout domotcl that may need some explanation.

Nodes

A node represents some piece of equipment that plays host to one or more modules. The most important one is the local node, which is the node that hosts the modules and devices local to the computer that runs the domotcl core. This node is already installed when domotcl is first started. Other nodes may be added for remote computers where devices are connected, or for integrating self-contained home automation controllers.

Modules

A module is the top level of grouping devices. Every module usually represents a complete system. For example a TV, receiver, or an X-10 or Z-Wave interface.

Drivers

A driver is a file containing the code to handle a module. There are several drivers included with domotcl. Drivers for modules that are not supported out of the box can be developped by the user.

The same driver may actually be installed multiple times with different module names (usually with different module parameters). This might be used when controlling more than one system of a particular type, like a TV in the living room and another one in the master bedroom. It can also be useful for logic separation. For example to separate time events and time points. Another reason could be to allow different log levels. If there is a variable that changes very frequently, you may not want to report that every time. But lowering the log level for the module would also mean that changes to other variables will not be reported any more. Putting these variables under two different modules would solve that.

Devices

A device is a single item that can be controlled by domotcl. For example, Within a module representing a receiver, the tuner and the different zones could be defined as separate devices. Also each X-10 or Z-Wave module would be a separate device under an X-10 or Z-Wave interface module. A device doesn't have to be related to a physical device. There are also devices that are related to time or for storing information.

Devices can be given names containing forward slashes. This can be used to logically group devices together in the Domotcl Explorer.

Properties

Most devices will have some state information. For example whether a light is on or off, the volume setting of an amplifier, etc. Within Domotcl these are called properties. A property has three attributes:
  • The current value
  • The previous value
  • The time of the last change
A property doesn't come into existence until the driver assigns a value to it. If no previous value is available, the current value and previous value will be equal. This is the only situation where that can happen.

Events

Whenever something happens on a device, the driver may fire an event. Most of the time this will coincide with a property change, but there is not a hard one-to-one relationship. Some property changes may not fire an event. Conversely there can also be events that are not related to a property. For example, when a periodic event expires or an infrared signal is received. Events can be used to trigger actions.

Actions

To be able to do something with all the devices configured in a domotcl instance, they must be glued together via some user defined rules. These rules are defined in actions. Each action may be triggered by zero or more events. The action code can check device properties and functions and run commands on devices.

Actions can be given names containing forward slashes. This can be used to logically group actions together in the Domotcl Explorer.

Actions can run as a result of an event, invoked from other actions, or executed manually on demand.

Symbols

Symbols can be used to assign a more meaningfull name to fixed values. For example, if you have a tuner that you can set directly to a frequency, it may be clearer to define some symbols for radio stations than to use the actual frequency. Suppose you define a symbol called /tuner/stations/KBBL of type float with a value of 102.5. Then in your action you can use: 
    /amp/tuner frequency $symbol(/tuner/stations/KBBL)
Another use of symbols is for values referenced in several places which may require some tuning. For example the light level below which lights should come on when motion is detected in a certain area. You have different actions that trigger on motion in different areas. Those actions control different lights, but they all check the outdoor light level to determine if it makes sense to switch on the light. With fixed values in those actions, you would have to update all actions when you find out that the lights come on too early or too late. If instead you use a symbol, you only have to change it in one place. A change to the value of a symbol is effective immediately.

Of course you could also choose to use variables in these circumstances. But variables are more volatile. They could be changed accidentally in an action or after an ungraceful shutdown of the application. Symbols are stored as part of the schedule, so they don't run that risk.

Groups

Groups can help the user to get a quick overview of related devices using different technologies. For example: X-10 and Z-Wave lights or temperatures obtained from a thermostat as well as hard-wired and RF sensors.