A few months ago, I showcased an imperfect approach to adding X10 lamp modules which are light dimmers. Back then, I knew that I would not be keeping the X10 devices so I did not go further. But now that I am passing the hardware on to a sibling, I feel I should do better and I think I have come up with an acceptable solution given the limitations of the hardware. This was tested with an older (pre 2007) LM465 lamp module. It may not work properly with newer LM465
Table of Contents
- Adding A Virtual Dimmer Switch in Domoticz
- Click on the Setup tab
- Select Hardware in the drop down menu.
- Add a virtual dimmer switch by clicking on the
- Fill in the
Namefield in the Create Virtual Sensor window.
- Press the OK button
- Click on the Switches tab.
- Click on the button of the newly created switch:
- The switch type will show as On/Off, select
- Click on the button
- Click on the button.
- Understanding the Domoticz Virtual Dimmer
- The bulb icon of a virtual dimmer works just like the bulb icon of an on/off switch.
- Clicking on the bulb icon to turn the light on or off never changes the position of the slider.
- The lamp can be turned off completely by moving the slider to the left edge of its track. However, after performing an 'Off' action, the slider will spring back to its initial position before the slider motion was started. In other words, turning the lamp off of by sliding the intensity control to the left edge is exactly the same as clicking on the bulb icon.
- Moving the slider always turns the bulb icon on if it was off unless the slider is released at the left edge of the track.
- Behaviour of the LM465 Lamp Module
- A Lua Script to Control a Lamp Module
- A Bash Script to Update Domoticz
The first step in using a lamp module is to create a virtual dimmer switch that will represent the physical X10 lamp module with address B3. The process is initially the same as in the previous post.
To change the virtual On/Off switch to a virtual dimmer,
You will see that the bulb icon will be different and that the virtual dimmer now has a movable slider to set the bulb intensity.
Some add a virtual switch by clicking on Switches tab. If they define it to be an
X10 switch of type
then that gives a virtual a dimmer with a slider that
cannot be moved under any circumstances. They may then go on to define the
dimmer to be of type
will result in a virtual dimmer with moveable slider. I think that may be
a mistake. For one thing, the number of discrete light intensity levels
supported by these devices does not correspond to the number of levels of
X10 lamp modules. For another, these virtual devices correspond to supported
physical devices, so I assume that when a user modifies their state, Domoticz will try to perform some action until it realizes
that there is no hardware. And because these dimmers will have to be
scripted to control the lamp module, those scripts will still have to
be executed, and of course, written before hand.
As recently as January 16th of this year, gizmocuz confirmed in the forum that the software does "not support dimming for X10" and he goes on to suggest creating a dimmer in the fashion described here.
There is no way that I can change how the virtual dimmer works, unless I were to fork Domoticz and modify the program. Since that's not about to happen; it is best to understand how the virtual dimmer works and try make the X10 lamp module behave in the same way using scripts.
Here, in bullet form, is the gist of the behaviour.
It seems to me that the developers decided that a virtual dimmer should mimic a physical dimmer comprised of a rheostat in series with an on/off switch. It is therefore possible to set the level with the slider/rheostat and then switch the lamp off. When the lamp is lit again, its intensity will be at the set level.
The following lua script making use of the logging capabilities of Domoticz allowed me to see what information will be available for scripting the dimmer:
Here is a sample of the log where the intensity of the lamp was set to
60% with the slider, then the lamp was turned off and lastly, turned on by
clicking on the bulb icon.
2017-05-28 13:36:59.577 User: Admin initiated a switch command (2/Test Dimmer/Set Level)
2017-05-28 13:36:59.614 LUA: devicechanged[Test Dimmer]: Set Level: 60 %
2017-05-28 13:36:59.614 LUA: otherdevices_svalues[Test Dimmer]: 60
2017-05-28 13:36:59.579 (Heyu) Light/Switch (Test Dimmer)
2017-05-28 13:37:26.636 User: Admin initiated a switch command (2/Test Dimmer/Off)
2017-05-28 13:37:26.671 LUA: devicechanged[Test Dimmer]: Off
2017-05-28 13:37:26.671 LUA: otherdevices_svalues[Test Dimmer]: 0
2017-05-28 13:37:26.638 (Heyu) Light/Switch (Test Dimmer)
2017-05-28 13:37:38.529 User: Admin initiated a switch command (2/Test Dimmer/On)
2017-05-28 13:37:38.563 LUA: devicechanged[Test Dimmer]: On
2017-05-28 13:37:38.563 LUA: otherdevices_svalues[Test Dimmer]: 0
2017-05-28 13:37:38.531 (Heyu) Light/Switch (Test Dimmer)
This log confirms that when Domoticz turns the lamp on, and expects it to resume the level of intensity it had when it was last turned off, it will not tell the script what that intensity was.
Using direct Heyu commands it becomes possible to investigate the behaviour of the X10 module. The following describes the behaviour of an older, pre 2007, LM465 lamp module.
The 'on' command only works if the previous command was an 'off' command. As can be seen, if the lamp was totally turned of with 'dim' commands, the 'on' command will not work. When the previous command was 'off', a 'bright' command (and, strangely, a 'dim' command) is the same as an 'on' command. In other words a 'bright' command cannot be used to set the light intensity to an intermediate level if an 'off' was issued before. On the other hand, a 'bright' command when the lamp was completely off with dims works as expected.
Just to complicate things a little bit, the post 2007 redesigned WS467 wall switch cannot be turned on from the off state by a dim or bright alone, according to the Heyu man page. There are other commands that change the light intensity. According to the man page installed along with the program
|Direct Command listing (H = Housecode, HU = Housecode|Units):|
|dimb HU <level>||Dim to <level> (1-22) after full bright|
|obdim HU <level>||Dim to <level> after on and full bright|
|brightb HU <level>||Brighten by <level> (1-22) after full bright|
These commands are actually macros: sequences of 'dim',
'bright', and 'on' commands. Here is what
(using a second SSH session into the Raspberry Pi) reveals:
Looking at these macros, it appears that the man page definitions are a
bit confusing as both
obdim actually dim
by <level> after turning the lamp on to full intensity. The
obdim macro is for use with the redesigned WS467 wall switch
which does nothing in response to the 'bright' command if the previous
command had been 'off'. Finally, to quote the man page, the "... 'brightb'
command (brighten after brightening to 100%) is essentially useless" because
it will turn the lamp on at full brightness no matter what value is given to
<level> or, in the case of the redesigned wall switch WS467, it will
do nothing if the previous command had been 'off'.
It is now clear that there is no Heyu command to set the absolute level of intensity of an X10 lamp module. Furthermore, not only must our script keep track of the light intensity level, it appears that it must keep track of the state of the module. This will require the use of two user defined variables.
These are the steps required to create a user variables. Click on the
Setup tab, chose
More Options and then
Add the user variable named
Bright_Level_B3, make sure it is of
Integer, set its initial value to 0 and the click on the
Repeat these steps to create another user variable of type integer named
Last_Cmnd_B3. It will be used to store the previously sent
command to the lamp module. These will be encoded as follows: 0 means 'off',
1 means 'on' and 2 means 'bright' or 'dim'.
This is the lua script that will be executed by Domoticzto update the lamp module with commands sent to Heyu.
The script begins by assigning only the first 9 letters of the changed
device state, converting them to lower case, to a variable named
cmd. Three other local variables are assigned values:
wanted_percent set to the changed device
current_percent set to the value of the user defined variable
last_cmd set to the value of
the user defined variable
The action performed by the script depends on the content of
cmd. The 'off' command is the simplest to handle. The built-in
os.execute will be invoked to pass on the command
'sudo -u pi /usr/local/bin/heyu on B3' to the operating system.
This is obviously a Linux command:
heyu is being executed with
root privileges as user
pi. Then the user variable
Last_Cmd_B3 is set to 0.
If the command is 'on', then something slightly more complex needs to
be done. Recall that Domoticz will send this command
only if the bulb was off. The first step is to invoke Heyu to turn the module on and the user variable
Last_Cmd_B3 is set to 1. The on command will brighten the bulb to
full intensity, not to the intensity saved in
wanted_percent is set to
current_percent is updated to 100 reflecting the fact that
the bulb is fully on. Finally
cmd is changed to 'set level'.
Execution of the script goes on and the test (cmd == 'set level') will be true
so that that part of the script will then adjust the lamp level.
If the command is 'set level' then the intensity of the bulb must be
adjusted. Remember that the X10 lamp module has 22 discrete on levels, 23 if
completely off is counted. So the wanted and current intensity measured in
percentage are converted to levels (0-22) and stored in the local variables
current_level. The difference is
saved in the local variable
delta. If delta is not 0 then
either a 'bright' or a 'dim' command is passed on to
Heyu as appropriate. Before
calculated, there is a slight bit of legerdemain. Recall that if the module
is in an 'off' state, a 'bright' or 'dim' command will turn the light bulb
full on and the level will be ignored. So we pass an 'on' command to
Heyu immediately, and set
to 22 indicating that the lamp is fully on. That way the calculation of
delta in the following line will be correct.
I will conclude this discussion of this script with three observations.
At first it may be amusing, but it will probably be tiresome after a while,
to see the light bulb go full on before dimming to the desired level.
Nevertheless, it most often gets there. Which brings me to my second
observation: sometimes it does not get there.
stores the last command sent to the module and this may not be the current
state of the module. To see what I mean, dim the bulb to a low level using
Domoticz. Unplug the module and then plug it back in
and slightly increase the brightness of lamp slightly with Domoticz again. The bulb will go to full intensity and will not
dim down to the desired level. The last observation is that this problem
cannot be solved even by querying Heyu about the
state of the module. It gets confused by this unplugging and plugging
The final step is to create bash scripts that will update Domoticz when the lamp module is dimmed or brightened with an X10 controller.
#!/bin/bash # Script to update X10 dimmer module status in Domoticz when the level has been changed manually # # Adjust the value assigned to IDX to reflect the module idx number in Domoticz # Adjust the value assigned to ADDR to reflect the module house and device code # IDX=2 ADDR=B3 # get the module's current dim level LEVEL=`sudo -u pi heyu dimlevel $ADDR` # debugging messages #echo 'LEVEL = ' $LEVEL >> debug_dim.log & #curl "http://192.168.0.22:8080/json.htm?type=command¶m=addlogmessage&message=Updating%20B1%20to%20level%20$LEVEL" # Update the Domoticz user variable holding the dim level. This MUST be done before updating the device to avoid action curl "http://192.168.0.22:8080/json.htm?type=command¶m=updateuservariable&vname=Bright_Level_$ADDR&vtype=0&vvalue=$LEVEL" # This will update the slider (svalue) of the Domoticz device, but when the lua script is called, there will be # no action, the calculated change in dim level, delta, will be 0. curl "http://192.168.0.22:8080/json.htm?type=command¶m=switchlight&idx=$IDX&switchcmd=Set%20Level&level=$LEVEL"
This is a three line script:
- retrieve the current brightness level of the device
- update the
Bright_Level_B3user variable in Domoticz
- update the switch in Domoticz.
Last_Cmd_B3variable, Domoticz, or more to the point, the above lua script will do that.
Make sure that the script is executable:
The last step is to modify the Heyu configuration file to call on the bash script when pertinent the power line command from the X10 controller is detected:
... # B3 is a dimmer switch: do not set the device's svalue # (which is the dim level) when updating on/off status # SCRIPT B3 on rcvi :: curl "http://192.168.0.22:8080/json.htm?type=command¶m=udevice&idx=2&nvalue=1" SCRIPT B3 off rcvi :: curl "http://192.168.0.22:8080/json.htm?type=command¶m=udevice&idx=2&nvalue=0" SCRIPT B3 dim rcvi :: /home/pi/.heyu/dim_b3.sh SCRIPT B3 bright rcvi :: /home/pi/.heyu/dim_b3.sh
The bash script will not work if the Domoticz web site is password protected and if local networks have not been defined. In that case, you can pass on the user name and password in the URL request. Look at Authorization_with_parameters on the Domoticz API/JSON URL's Wiki page for details.
What about newer (post 2007) LM465 Lamp Modules? And couldn't preset dim values be used?
Good questions. Since only post 2007 LM465 lamp modules respond to extended codes, these really boil down to one question. Unfortunately, the one newer LM465 module I had broke down very quickly after I got it, so that I am not able to test any ideas I might have about the newer lamp modules. <diatribe>Typical X10 quality control from what I can see, the RF portion of a second generation CM15A USB computer interface packed it in also. This is one the reasons I decided to rebuild my home automation system around a different technology.</diatribe>
The following paragraph from the document entitled New LM465.txt certainly hints at the the possibility of avoiding the 'full on before dimming' behaviour.
The new design has a "resume" feature similar to the LM14A, i.e., the ability of returning from Off to the previously set brightness level. However this feature is not called into play when the module receives an On signal but when it receives a Dim signal. The dimming continues from that point, so to repeatedly turn Off and then resume the exact same level, it is necessary to follow the Dim signal with a Bright signal of the same magnitude. If the new design receives an On signal when Off, it ramps up gradually over about two seconds, but to full brightness regardless of the previous level.
I take that to mean the following:
I leave it as an exercise to the reader with a newer LM465 to rewrite the scripts to take advantage of this functionality. If someone wants to "donate" a working newer LM465 module, then I would not refuse it. Send me an e-mail by clicking on my name at the bottom of this page. Hurry, because I will no longer have a working CM11A interface by early next August and it will not be feasible to borrow it from my sister as she lives a thousand kilometres away.
The Bash and Lua scripts as well as the Heyu configuration file are available for downloads on the Downloads page or below:
- Lua script to investigate
Domoticz virtual dimmer switch. Copy to the
/home/pi/domoticz/scripts/lua) directory on the Domoticz server. Remove from that directory when installing the following Lua script.
- Lua script to update X10
dimmer switch using Heyu. Copy to the
/home/pi/domoticz/scripts/lua) directory on the Domoticz server.
- Bash script to update the state of a virtual dimmer switch in the Domoticz database and web site when the light level of an lamp module has been changed manually with an X10 controller.
configuration file with scripts to update the
state of a virtual dimmer switch in the Domoticz
database and web site when the status of a lamp module has been
changed manually with an X10 controller (uses above bash script).
/home/pi/.heyu) directory on the Domoticz server and rename