Install Domoticz

As the download page at Domoticz says, a one-line script will install the program.

Start a web browser on your desktop and connect to Domoticz' built-in web server on the Raspberry Pi at http://192.168.0.22:8080. You will not see much, because nothing is installed, but at least you are now assured that everything is working.

Its time to define the system settings. Click on the Setup button at the top right and then select Settings. By default the System tab is opened. At a minimum, the Location (longitude and lattitude) should be defined. I used my car's GPS to find the exact values. Perhaps a GPS equipped smart phone or tablet could be used. If none of these possibilities are available, Domoticz can provide reasonably accurate coordinates given a street address. Presumably, the information is used to calculate sunset and sunrise.

It is a good idea to password protect the website. Provide a username and a password in the Website Protection section. It does become cumbersome to fill in that information. Thankfully, it is possible to specify "login free" local networks. Using a browser on a machine located on any one of those specified networks will log in automatically, bypassing the login requirement.

Consult the Domoticz wiki page Application Settings for more information about other settings.

Consult the page dedicated to installation on the Raspberry Pi. In particular you should look at the section entitled Raspberry Pi additional software installations. You will notice that I shamelessly copied the "Setting up a RAM drive on Raspberry Pi" from that page.

My first attempt at adding Mochad was based on a Domoticz wiki page: X10 devices, CM15Pro. It certainly worked but it was not optimal. I have since added a warning in the wiki to explain that native support for the CM15A and CM19A interfaces using Mochad is available. Adding switches is now a snap that does not involve writing scripts. As a bonus, there is also real time updating of the status of devices. Unfortunately, the dimming function of lamp modules is not supported; they must be installed as on/off switches.

Before adding X10 lights, switches and other devices, the "hardware" (the Mochad bridge) needs to be installed. This is done only once. After that X10 hardware modules are added one by one. All this is done using Domoticz web interface, the same one that you can later use to turn a light on or off.

Log on to Domoticz web page at http://192.168.0.22:8080. Click on the Setup tab and then, once the setup menu is showing, click on the Hardware submenu button.

Fill the fields to define the hardware. Change the Type: to Mochad CM15Pro/CM19A bridge with LAN interface, give the hardware a name, Mochad seems like an obvious choice, and specify the Remote Address and Port used by the Mochad daemon. In this case, this is 192.168.0.22:1099 but instead I used the localhost address 127.0.0.1:1099. If a different Ethernet address is assigned to the Raspberry Pi, it will not be necessary to adjust the Remote Address field. Click on the Add button.

The added hardware should then be visible in the table at the top of the page.

Individual X10 devices can now be added. Turn the light or device off. Then click on the Switches tab and then on the Learn Light/Switch button at the top right of the page to automagically install a device. Domoticz will display a prompt saying to Press button on Remote... which, of course, must be a button that turns on the device to be added. Be quick about it, you will be given only a couple of seconds to press that button. Of course you can click on Lean Light/Switch again and retry as often as you want.

If there is no remote handy, then netcat into Mochad and prepare the command to turn on the device but wait to press the Return or Enter key until prompted to press the button on the remote:

Domoticz will display a prompt asking for a unique name for the device and the type of switch it is:

Leave the Switch Type set at On/Off, dimmers do not work in the Mochad bridge eventhough Mochad does handle them.

Whether the remote or a Mochad command was used, make sure the light or device was turned on. If it is, then installation is complete. Not much to it!

Debugging

If something does not work, there are a few things that can be done to pinpoint the error. First, open a new ssh session on the Raspberry Pi and issue the following commands which should connect to Mochad and toggle the dresser light on and off:

This must work. If it does not, go back to the debugging instructions concerning Mochad above.

If Mochad is working correctly, then continue investigating by turning the dresser light on and off using Domoticz. Check the Domoticz log (click on the Setup tab and then on the Log button). When things work normally you should see something like:

2016-11-26 13:23:38.892 User: Admin initiated a switch command (1/Dresser lamp/On)
2016-11-26 13:23:41.745 (Mochad) Lighting 1 (Dresser lamp)
2016-11-26 13:23:47.131 (Mochad) Lighting 1 (Dresser lamp)
2016-11-26 13:24:05.892 User: Admin initiated a switch command (1/Dresser lamp/Off)
2016-11-26 13:24:39.374 (Mochad) Lighting 1 (Dresser lamp)
2016-11-26 13:24:46.101 (Mochad) Lighting 1 (Dresser lamp)

11/26 13:23:41 Tx RF HouseUnit: D1 Func: On
11/26 13:24:39 Tx RF HouseUnit: D1 Func: Off

Reference: Domoticz wiki: X10 with CM11a

There is no native (hardware) support for the Heyu in Domoticz so it will be necessary to add devices "manually" and to handle them with scripts.

The first step is to create a "dummy" hardware representing the gateway. Again click on the Setup tab and then select Hardware. For a name, I chose Heyu. For the Type click on Dummy (Does nothing, use for virtual switches only) in the drop down list.

Don't forget to click on the Add button. This step is done only once. The following two steps are repeated for each device to be added.

Before proceeding with the installation of X10 modules (lamp, appliance, receptacles etc.), it is best to plan ahead. Namely, each device must be given a name in the database. This is the name that will be used in the script. Names should not be too long, especially if you will be using an intelligent telephone to log into Domoticz and interact with the device. Addresses given to virtual devices do not have to correspond to the corresponding X10 address of the physical devices, but its probably less confusing that they match.

Here is an example setup:

Since the Heyu hardware is virtual, those four X10 devices will be controlled with virtual sensors. Click on the Setup tab, then select Hardware and then click on Create Virtual Sensors in Heyu hardware.

The Create Virtual Sensor window, as shown below, will be displayed. Fill in the Name field and press the OK button.

Create other virtual switches for the other X10 devices. Once that is done, click on the Switches tab. The newly created On/Off virtual switches will be visible, Click on the Edit button in the Floor lamp box to change its switch type to Dimmer.

A device editing page will be shown. As you can see there are a number of changes that can be made including changing the name of the device and its switch type.

Set Switch Type: to Dimmer and press the Save button. Return to the Switches tab sheet by pressing on the Back and change the switch type of any other virtual switch corresponding to a dimmable X10 device.

The result is something like this:

This is very nice looking, but clicking on an icon to toggle a lamp or sconce off or on or moving the slider to change the light intensity of either lamp will do nothing. These are virtual switches, scripts that invoke Heyu have to be written to do something. First I will describe the scripts for the sconces, dimmers are somewhat more complicated.

Scripting on/off switches

Rules about Lua scripts are quite strict. A Lua script for a virtual sensor

• must be saved in the directory /home/pi/domoticz/scripts/lua,
• its name must begin with the prefix script_device_,
• its name must end with the .lua extension.

There are numerous lines that merely add information in the Domoticz log to help in debugging. They may hide how simple the script actually is. Here it is stripped of that information:

Of course, the status of the lights is updated when a light is turned off or on with the web interface. However, I have a couple of old Radio Shack (RS) programmable controllers and some wireless controllers that I use to toggle the lights at set times or to manually turn then on or off. If I do that, the corresponding status will not be updated in Domoticz, which is a problem.

• Lamp switch B2 is turned on or off using the RS controller
• The CM11A which monitors the power line reports the activity to Heyu
• Heyu executes a script which sends an http request to the Domoticz web server informing it of the change in status of the device.
• Domoticz updates the status of B3 in its database and updates the web interface.

In practice care must be exercised to avoid creating a loop because in that last step Domoticz does not just update its database, it also performs the associated action. In other words it executes the script script_device_heyu_b2.lua which can restart the sequence. This problem is discussed at length in the forums and solutions have been suggested. The solution I have adopted is specific to Heyu using its own script trigger conditions.

The index number (idx) of the virtual switches must be used in the Heyu scripts. Those can be found on the Devices list found in the Setup sheet.

The next step is to edit the Heyu configuration file to

• automatically load the heyu engine which executes the scripts on receiving triggers through the power line,
• to specify where to write a log file (optional but useful when debugging), and
• to specify the scripts to be executed.

Open a terminal and launch an ssh session with the Raspberry Pi. Then edit the x10config and restart Heyu.

Test everything, turn the sconce on and off with Domoticz and with a manual controller. It may take a while, but when doing the latter, the bulb icon should reflect the state of the sconce.

If you open the Heyu monitor on the Raspeberry Pi, you will see what happens.

The Heyu log file, if enabled, will confirm that in the second case the script was launched in between the two power line commands issued to the CM11A. And that explains the second power line command as Heyu responded to Domestics action. Note how Heyu distinguishes between power line transmissions received by the CM11A rcvi and commands it sends on to the CM11A for transmission over the power lines sndc. Including rcvi in the script trigger ("B2 on rcvi" ::) a loop is avoided.

Scripting dimmer switches

Scripts for dimmer switches are a little bit more complex. For one thing, it is necessary to keep track of the bulb intensity in a user variable. This is because the slider control manipulated by the user in the web interface sets the brightness level wanted, but the CM11A and Heyu dim and bright commands are decrements or increments in the level. So the first step is to create two user variables. Click on the Setup tab, chose More Options and then User variables.

The variable Bright_Level_B1 is already defined. Another variable for the other dimmer switch is about to be added. Its name Bright_Level_B4, is entered in the Variable name: field, Integer is selected for the Variable type, there remains to click on the Add button.

If you want to use different variable names, you will have to adjust the Lua scripts. It would be wise to end the name with the X10 address of the switches as this simplifies the script.

The Lua script for the floor lamp, script_device_heyu_b1.lua dimmer switches is

Again, all the debugging code obfuscates the simple logic. Here is a version without that extra baggage:

The string parameter otherdevices_svalues[NAME] is the light level chosen with the slider control. The string is converted to an integer, in the range 0 to 100, with the function tonumber. I am not too sure about the details but reading the Heyu documentation there seems to be 22 steps between full off and full on for X10 lamp modules. So the percentage level is converted to an integer between 0 and 22 and stored in wanted_level. The same interpolation is done to convert the saved percentage saved in Bright_Level_xx to a 0 to 22 level. That value is assigned to variable current_level. The current value of the user variable is no longer needed so it is updated immediately to the value of the slider control. That's the meaning of the arcane looking line commandArray['Variable:'..name_level_var] = otherdevices_svalues[NAME]. The difference between the wanted and current levels is stored in delta. If it is 0 nothing will happen. If delta is positive, a bright command will be sent to Heyu. If delta is negative, a dim command will be sent with the absolute value of delta.

As before, copy the file script_device_heyu_b1.lua to script_device_heyu_b4.lua and adjust the NAME and ADDR assigns for the table lamp.

We now need to write two bash scripts that Heyu will call to handle the dim and bright events.

This is a three line script:

• retrieve the current brightness level of the device
• update the user variable in Domoticz
• update the switch in Domoticz.

Copy this script to create another named dim_B4.sh and edit it, setting the correct values for NAME and ADDR. Make sure that the two scripts are executable:

The last step is to add scripts for the two modules in the Heyu configuration file:

The Bash and Lua scripts as well as the Heyu configuration file are available for download.