Let Domoticz Tell You when Your Bedroom has been Ventilated

The Domoticz home automation system is nifty and has nicely evolved since its early days. Since having set it up in 2014, I’ve had my fair share of not-yet-compatible sensors, having to manually upgrade Domoticz because the auto-updater crashed, and whatnot. But at the time of writing this article, the system has matured into a stable and reliable piece of software. It even features a bunch of scripting languages to react to sensor events. Nice.

Still, all my attempts to find a ready-made solution for the follwing use case failed miserably: I wanted to receive a push notification when my bedroom window has been open for a given time interval (to let me know that the room has been properly ventilated). Searching several Internet forums was no big help, though, and neither was the Domoticz documentation. I managed to get it working nonetheless, and have documented my approach here, so you don’t have to go through the same hassle when you need a solution to the above use case.

Setting up a virtual sensor

As far as I can tell, the Domoticz scripting engine does not currently feature a global event queue, in which individual scripts can insert events to be executed some time in the future. As such, a proxy object whose state can be modified by the scheduler is needed. For the sake of simplicity, I’m using a “virtual sensor” here, because this also provides a nice visualization on the Domoticz dashboard whether a push notification has been sent.

Click the Setup button, then Hardware. In the bottom part of the newly displayed screen, enter a name for your fake sensor device (such as DummyDevice) and select type Dummy, then click Add. The dummy device should now show up in the list of devices on top of the screen.

Next, let’s create the actual virtual sensor. Click the Create Virtual Sensors button showing up in the table row of your dummy device. In the popup window, give the virtual sensor a name, but (and this is important) leave its type as Switch. Do not change the type to Alert. If all went well, the virtual sensor will now show up in the Domoticz Switches tab.

At last, click the dummy device’s Edit button and change its icon from Switch to Alarm for some fancy visuals. I also recommend to check its Protected box to avoid accidentally changing its state from the dashboard.

Adding the event handler

We’re already halfway there. Next up, navigate to Setup - More Options > - Events in order to define how and when this alarm is supposed to become active.

A list will be displayed, showing the available event sources as well as their most recently updated values. From this list, identify the name of the window sensor you want to use as a trigger for the ventilation duration alarm (in my case, it’s a simple BedroomWindow).

Click the small + in the tab above the list to open the choice of scripting languages, and selected dzVents > - Device. An editor window will open, into which you can paste the below code. For improved clarity, I also suggest changing the default name of Script #1 to something more meaningful (like BedroomTimeout). Once you have inserted the code, don’t forget to click the Save button to ensure your event handler is properly stored.

Event handler code

In a nutshell, the following code works as follows:

1. It subscribes to events by both the actual window sensor and the virtual sensor.
2. When the window has been opened, it triggers a delayed change of the virtual sensor to its On state.
3. When the window has been closed, it cancels the delayed change of the virtual sensor and resets it to the Off state if needed.
4. When the virtual sensor has turned On (because the window has not been closed within the timeout interval), a notification is sent.

To adapt my code to your Domoticz setup, the following three modifications are needed:

1. Change the two occurrences of BedroomWindow (lines 4 and 10) to the name of the correct window sensor (see Adding the event handler).
2. Change the two occurrences of BedroomOpenAlarm (lines 5 and 11) to the name of your newly created virtual alarm sensor (see “Setting up a virtual sensor”).
3. Change the number of minutes (line 9) as desired

return {
	on = {
		devices = {
			'BedroomWindow',
			'BedroomOpenAlarm'
		}
	},
	execute = function(domoticz, device)
	    local minutes = 15 -- set the desired timeout value
	    local window = domoticz.devices('BedroomWindow')
	    local notify = domoticz.devices('BedroomOpenAlarm')
	
	    if device == window then -- script was called because window status has changed
    	    -- Trigger the alarm N minutes after the window has been first opened
            if window.state == 'Open' then
                notify.switchOn().checkFirst().afterMin(minutes)
                domoticz.log('The user will be notified in ' .. minutes .. ' minutes', domoticz.LOG_INFO)
                
            -- Cancel and deactivate the alarm when window is closed
            elseif window.state == 'Closed' then
                notify.cancelQueuedCommands()
                notify.switchOff().checkFirst()
            end
        end
    
        if device == notify then -- script was called because alarm has triggered (or was deactivated)
            if notify.state == 'On' then
	            domoticz.notify("Bedroom info",
                                "The bedroom window has been open for " .. minutes .. " minutes",
                                domoticz.PRIORITY_NORMAL,
                                domoticz.SOUND_TUGBOAT)
    		    domoticz.log('Notification sent for ' .. device.name, domoticz.LOG_INFO)
    		end
        end
	end
}

Help, I don’t receive any notifications!

Of course, you must have configured at least one notification service (under Setup - Settings - Notifications tab) for the push messages to work.

If there’s still nothing going on, take a look at the event log (via Setup - Log) to debug what is happening. Hint: Use the log window’s Status tab to filter out unrelated sensor events.