Domotcl

Download

Terminology

Operation

Actions

Nodes

Drivers

Development

Operation

These instructions show how to set up a typical domotcl configuration, where the core runs on a linux machine and the system is controlled from a desktop computer. For clarity the machines will be addressed by their host name, rather than IP addresses. To be able to do this also in practice, the host names should be configured in the local DNS (if present), or in the hosts files of each of the relevant machines. These are the host names that will be used:
haserver
The linux system that runs 24x7 and will host the domotcl core.
desktop
A regular PC that is used for day-to-day computer work and will also be used to configure and monitor domotcl. This machine may be switched off when it is not being used.

Installation

The domotcl application has to be installed on all machines that will be used to either run the domotcl core, a domotcl satellite, or the domotcl explorer. The machines must have a functional development environment, including a C compiler, tools such as autoconf and make, and header files for system facilities such as dbus and openssl.

In principle, the installation consists of only two steps:

  • Downloading the domotcl application. Choices are to download and unpack a tarball or to clone the domotcl repository into a directory of your choice.
  • In the domotcl directory, run make. This takes care of downloading, building, and installing Tcl and the libraries that may be needed by domotcl itself or its drivers.
The application can be downloaded from the fossil download page.

Details for different operating systems are described on the OS specifics page.

Core

The core is the main domotcl component, designed to run 24x7 on the haserver machine.

The various domotcl components communicate via dbus. If all components will always run on a single machine, the standard session dbus can be used. But for the described setup, a dbus accessible via TCP will be needed. First check whether apparmor is installed on the machine: 

    aa-enabled
If this returns "Yes", then use the session-apparmor.conf config file in the step below. When it returns "No", or you get an error message, use the session.conf config file. 
    cd ~/domotcl
nohup dbus-daemon --config-file=session.conf &
      or
    nohup dbus-daemon --config-file=session-apparmor.conf &
Now the core can be started, making sure it connects to the dbus that was started in the previous step. 
    nohup tclkit core/domotcl --address=tcp:port=4253 &

Explorer

The Explorer provides a graphical user interface to the Domotcl core. It allows the user to configure drivers, edit actions, and monitor the system. It is possible to run multiple explorers from different machines at the same time. Contrary to the other components, the explorer can run on windows as well as on linux.

To start the explorer:

Linux

cd ~/domotcl
tclkit explorer/editor --address tcp:host=haserver,port=4253

Windows

Double-click the explorer shortcut.
There is a seperate page that provides information on using the explorer.

Logger

To investigate unexpected behavior of your domotcl schedule, it can be very useful to have logs. These can be created by a separate tool. As logs will normally need to be collected continuously, the best place to do that is on the machine that runs the domotcl core. 
    cd ~/domotcl
nohup tclkit core/logger -s0 -t logs/domotcl/log-%Y%m%d.txt --address=tcp:port=4253 &
Make sure the user running this command has the appropriate permissions to create files at the specified path.

The -s option controls how much data is buffered before it is written to disk. The default is 4kBytes. A value of 0 means all reports are immediately flushed to disk. This is convenient when tailing the log file. But it causes many write actions on the disk, which may be undesirable on a Raspberry Pi, where the disk is an SD card with a limited number of write cycles.

Log files are rotated daily. The -t option specifies a template for the name of the log files. %Y is the 4-digit year, %m a 2-digit month, %d a 2-digit day of the month.

Web server

To access domotcl from a tablet or smart phone, a web browser can be used. This requires the domotcl web server to run. 
    cd ~/domotcl
nohup tclkit web/webserver --address=tcp:port=4253 &
A user can add customized web pages that can show the state of devices in domotcl and perform commands of the devices.

MQTT

The MQTT server provides access to Domotcl via the MQTT protocol. 
    nohup tclkit core/mqtt --address=tcp:port=4253 &
Available command line options are:
    --system
    connect to the system bus
    --address=ADDRESS
    connect to the given bus
    --server=HOST[:PORT]
    the address of the MQTT server
    --name=NAME
    the ClientID to use when connecting to the MQTT server
    --user=USER
    username for authentication to the MQTT server
    --password=PASSWORD
    password for authentication to the MQTT server
    --help
    display help and exit

Satellite

A satellite can host drivers on other systems than the machine that runs the domotcl core. This can be useful for drivers that access resources local to those systems that are not approachable via the network, like serial ports, or running programs. The sattelite process provides the communication between the domotcl core and the remote drivers.

A satellite can run in active (client) and passive (server) mode. An active satellite will set up the connection to the domotcl core itself. A passive satellite waits for the domotcl core to set up the connection. Systems that are not running 24x7 should use the active mode.

In domotcl you would create a server node to accept connections from an active satellite, or a remote node to connect to a passive satellite.

Active mode: 

    tclkit remote/satellite haserver 1723
Passive mode: 
    tclkit remote/satellite 2341