Dummy

The DUMMY I/O Server is a virtual server that doesn’t actually connect to any external system, but simulates basic lighting, color and automation devices, and general purpose virtual data points.

Data points can also be remotely set or read using a simple HTTP API, based on the /x/httpcall interface.

HSYCO Configuration

Add a DUMMY I/O Server in the I/O Servers section of the Settings and set its parameters.

note

Note that the DUMMY I/O Server doesn't count in the I/O servers license total, so you don't need an extra I/O Server license to use DUMMY with HSYCO.

High Availability

• Shutdown when inactive: defaults to false.

Options

ID	Default	Values	Description
startupevents	true	true	generate IO events, on persistent state data points, during the driver’s start-up phase
		false	start generating events only after persistent state data points are initialized
discovery	true	true	automatically lists all virtual devices in the catalog.json file
		false	auto-detect for devices is disabled
commandstate	false	true	enables command/state mode, see below
		false	normal mode
persistent	false	true	enables persistent state, see below
		false	normal mode
automationsontime	30	>= 0	If the value is greater than 0, virtual automation devices automatically switch to the offup or offdown state n seconds after receiving an up or down command. If the value is 0, the device remains on indefinitely.
lights	0	0 ... 10000	number of on/off light devices to generate
dimmers	0	0 ... 10000	number of dimmer devices to generate
automations	0	0 ... 10000	number of automation devices to generate
rgbs	0	0 ... 10000	number of RGB color devices to generate
rgbws	0	0 ... 10000	number of RGBW color devices to generate, with a white channel in addition to the three color channels
httpcallpassword		string of 8 or more uppercase or lowercase letters and digits	enables the HTTP API
httpcalltimeoutseconds		n > 0	when set, the connection data point is set to offline when no httpcall request is received for n seconds. When not set, the check is disabled and the connection data point is never set to offline

The Device Configuration Database

The catalog.json file contains the list of all devices and their individual input, output and virtual data points that could be directly associated to graphic object in the Web-based user interface. This file can be filled manually or automatically by HSYCO at start-up.

To enable automatic discovery and automatic generation of devices’ information in the catalog.json file, use the discovery option in Settings.

This is an example of the catalog.json entries:

{
  "devices": [
    { "ioServer": "dummy", "id": "autom.1",  "function": "AUTOM", "type": "VSHUT",  "description": { } },
    { "ioServer": "dummy", "id": "dimmer.1", "function": "LIGHT", "type": "DIMMER", "description": { } },
    { "ioServer": "dummy", "id": "light.1",  "function": "LIGHT", "type": "LIGHT",  "description": { } },
    { "ioServer": "dummy", "id": "rgb.1",    "function": "DIMMER", "type": "DIMMER", "description": { } },
    { "ioServer": "dummy", "id": "rgb.1.brightness", "function": "DIMMER", "type": "DIMMER", "description": { } }
  ]
}

You should then edit the description of the devices. See catalog.json for the full structure and editing instructions.

The Persistent State Mode

Normally, when HSYCO is restarted, the data points of the Dummy I/O Server are deleted and re-initialised at start-up.

In persistent mode, all existing data points are retained and reset to their last value at start-up. Note that, just like persistent variables or data loggers, HSYCO typically saves data permanently to the local database storage (in the data directory) every 60 seconds, not immediately.

If a Dummy I/O Server that was previously running in persistent mode is restarted with persistent mode disabled, all retained datapoints are discarded and the server starts fresh, as in normal mode.

The Command/State Mode

In normal mode, when a writable data point is set to a value, its state immediately reflects the set command.

In command/state mode, enabled setting the "commandstate" option to "true", the data points feedback state is decoupled from the corresponding command. For each writable data point, an additional data point, having the ".cmd" suffix, is used to intercept commands (writes) to the primary data point and another data point, with the ".state" suffix, is used to actually set the data point state value.

For example, let's assume that we have declared a DUMMY I/O Server with ID "engine", and we want to use the data point "run" to represent the running state of the engine and also let the engine be turned on or off by writing to the "run" data point.

The engine run status is acquired polling a Modbus discrete input, and can be turned on/off via a Modbus coil address. The following simple events script explains how to use the "cmd" and "state" data points.

Remember that, basically, the "cmd" data point is read-only, it can only be used as an event trigger. Writing to it has no effect.

Conversely, the "state" data point is write-only. It is only used to write the primary data point's state. "state" data points are not visible in the Status Browser, as it is not the "state" data point that is set to the value, but the primary data point.

# engine run state polling via Modbus
init : programtimer 1sec = repeat 1
programtimer 1sec : io "modbus.1.101" = "readdiscreteinputs:1"

# engine.run data point state updated based on Modbus polling
io modbus.1.101.1 : io engine.run.state = io modbus.1.101.1

# intercept writes to the engine.run data point to send Modbus write coil commands
io engine.run.cmd = 1 : io modbus.1.1 = bit:1
io engine.run.cmd = 0 : io modbus.1.1 = bit:0

# the engine is started at 08:00 and stopped at 09:00
time 0800 : io engine.run = 1
time 0900 : io engine.run = 0

Datapoints

ID	Value	R/W	Description
connection	online	R	I/O Server ready, or httpcall received within the httpcalltimeoutseconds timeout
	offline	R	httpcall not received within the httpcalltimeoutseconds timeout
light.<n>	0	R	light <n> is off
		W	switch off light <n>
		off	W
	1	R	light <n> is on
		W	switch on light <n>
		on	W
dimmer.<n>	0	R	dimmer <n> is off
		W	switch off dimmer <n>
		off	W
	1	W	switch on dimmer <n>
		on	W
	1% ... 100%	R	the light level of dimmer <n> corresponds to the reported value
		W	set the light level of dimmer <n> to the specified value
autom.<n>	offup	R	autom <n> is stopped in upper position
	offdown	R	autom <n> is stopped in lower position
	stop	W	stop autom <n>
			off
			0
	up	R	autom <n> is moving upwards (opening)
		W	move autom <n> upwards
	down	R	autom <n> is moving downwards (closing)
		W	move autom <n> downwards
rgb.<n>	<r>,<g>,<b>	R	the color of RGB device <n>, whether it is on or off
		W	set the color. The state is not changed. See Color
	<r>,<g>,<b>,on	W	set the color and the state in one write, with on or off as the last field
	0,0,0	W	ignored: all zeros is not a color. Use off to turn the device off
	on	W	turn on RGB device <n>
		1	W
	off	W	turn off RGB device <n>
		0	W
	flip	W	invert the state of RGB device <n>
rgb.<n>.on	1	R	RGB device <n> is on
		W	turn on RGB device <n>
		on	W
	0	R	RGB device <n> is off
		W	turn off RGB device <n>
		off	W
	flip	W	invert the state of RGB device <n>
rgb.<n>.brightness	1% ... 100%	R	the overall brightness of RGB device <n>
	off	R	RGB device <n> is off
	1 ... 100	W	set the brightness, with or without the trailing %, keeping the proportion between the channels, and turn the device on
	on	W	turn on RGB device <n>. The brightness is not changed
	off	W	turn off RGB device <n>. The brightness is not changed
		0	W
	flip	W	invert the state of RGB device <n>
rgb.<n>.fault	1	R/W	RGB device <n> is simulating a fault. See Faults
	0	R/W	RGB device <n> is not simulating a fault
			on and off are accepted as well
	flip	W	invert the simulated fault of RGB device <n>
rgbw.<n>	<r>,<g>,<b>,<w>	R	the color of RGBW device <n>, the last field being its white channel
		W	set all four channels. The state is not changed
	<r>,<g>,<b>	W	set the three color channels, leaving the white channel as it is. The state is not changed
	<r>,<g>,<b>,<w>,on	W	set the channels and the state in one write, with on or off as the last field. The three channel form takes it too
	0,0,0,0	W	ignored: all zeros is not a color. Use off to turn the device off
	on	W	turn on RGBW device <n>
		1	W
	off	W	turn off RGBW device <n>
		0	W
	flip	W	invert the state of RGBW device <n>
rgbw.<n>.white	1 ... 255	R	the white channel of RGBW device <n>
	off	R	RGBW device <n> is off, or its white channel is at zero
	1 ... 255	W	set the white channel and turn the device on
	on	W	turn on RGBW device <n>. The white channel is not changed
	off	W	turn off RGBW device <n>. The white channel is not changed
		0	W
	flip	W	invert the state of RGBW device <n>
rgbw.<n>.on	1	R	RGBW device <n> is on
		W	turn on RGBW device <n>
		on	W
	0	R	RGBW device <n> is off
		W	turn off RGBW device <n>
		off	W
	flip	W	invert the state of RGBW device <n>
rgbw.<n>.brightness	1% ... 100%	R	the overall brightness of RGBW device <n>
	off	R	RGBW device <n> is off
	1 ... 100	W	set the brightness, with or without the trailing %, keeping the proportion between the four channels, the white one included, and turn the device on
	on	W	turn on RGBW device <n>. The brightness is not changed
	off	W	turn off RGBW device <n>. The brightness is not changed
		0	W
	flip	W	invert the state of RGBW device <n>
rgbw.<n>.fault	1	R/W	RGBW device <n> is simulating a fault. See Faults
	0	R/W	RGBW device <n> is not simulating a fault
			on and off are accepted as well
	flip	W	invert the simulated fault of RGBW device <n>
<name>	<value>	R	generic data point <name> has value <value>
		W	set value of generic data point <name> to <value>

note

Note that generic data point names must not start with "light", "autom" or "dimmer", and are stripped of space characters.

The data point names of color devices, "rgb.<n>" and "rgbw.<n>" with their ".on", ".brightness", ".fault" and ".white" suffixes, where <n> is a number, are reserved as well. Any other name beginning with rgb, such as "rgbstrip", is a generic data point.

Color

A color device holds a color, a brightness and an on/off state, and the three are independent. Turning a device off does not change its color: rgb.<n> always reports the color the device is showing, or the color it will show when it is turned back on, so a user interface can display it either way.

rgb.1              255,67,31
rgb.1.brightness   100%
rgb.1.on           0

An RGBW device has a fourth channel driving a white LED, reported as the last field of rgbw.<n> and also on its own as rgbw.<n>.white:

rgbw.1             255,67,31,128
rgbw.1.white       128

Writing accepts a comma, a semicolon, an asterisk or spaces as the separator, so all of these set the same color:

IO dummy.rgb.1 = 255,67,31
IO dummy.rgb.1 = 255;67;31
IO dummy.rgb.1 = 255*67*31
IO dummy.rgb.1 = 255 67 31

Each channel is a number from 0 to 255, or a percentage of full output such as 50%. Values above 255 are set to 255, and a value that is negative, not a number, or a list with the wrong number of fields is rejected with an error in the log and changes nothing.

Color, state and brightness

Setting a color never turns a device on. The state changes only when it is written: with on, off or flip, on the .on data point or on the device's own, or by adding on or off as a last field to a color, which sets both in one write.

IO dummy.rgb.1 = 255,67,31        # set the color, on or off as it was
IO dummy.rgb.1 = 255,67,31,on     # set the color and turn it on
IO dummy.rgb.1.on = 1             # turn it on, at the color it was given

A color of all zeros is not a color, and is ignored. A light or a dimmer has to read a zero as off, having no state data point of its own, but a color device is turned off through off, 0 or its own .on data point. So the stored color is never lost, and a color that shows nothing while the device is on cannot be constructed. An on or off written as the last field still applies, and on an RGBW device a white channel written to zero is ignored in the same way when the three color channels are already at zero.

rgb.<n>.brightness is the overall brightness, from 1% to 100%, and setting it scales the channels while keeping their proportion, so the color does not change. It reads back with the percent sign, like a dimmer, and can be written with or without it. On an RGBW device the white channel scales with the other three.

The brightness and white data points behave as dimmers, so that a slider or a knob bound to either of them works with no extra logic. They report off while the device is off, a level written to them turns the device on, and 0 turns it off, leaving the level where it was. They also take on, off and flip. Note that this makes them different from the device's own data point, which never changes the state and always reports every channel, whether the device is on or off: that is where the color and the brightness a device comes back to remain visible, and where they can be set on a device that is off.

IO dummy.rgb.1 = 255,67,31        # rgb.1.brightness reads 100%
IO dummy.rgb.1.brightness = 10    # rgb.1 reads 26,7,3
IO dummy.rgb.1.brightness = 100%  # rgb.1 reads 255,67,31 again

Brightness and color are two views of the same numbers: while the device is on, the brightness is that of the brightest channel, max(r,g,b) / 255. A color written as 128,34,16 therefore reads back a brightness of 50%, and taking the brightness to 100% gives that color at full scale, 255,68,32. The driver keeps the color internally at full scale, so moving the brightness up and down always recomputes from the same color and never wears it away.

note

Brightness here is a straight percentage of the channel values, not of perceived light: at 50% a lamp still looks brighter than half. Note also that at a low brightness the channels quantise, and a channel that was already low reaches zero: 255,67,31 at 1% is 3,1,0. The color itself is not affected, and returns unchanged as the brightness goes back up.

Faults

A real device can be unreachable, and a user interface shows that with its own visual flag. rgb.<n>.fault and rgbw.<n>.fault simulate that condition, so a project can be designed and tested without unplugging anything.

IO dummy.rgb.1.fault = 1

Setting the fault adds a fault field to the values the device and its brightness and white companions are published with, <r>*<g>*<b>*<on|off>*fault, <n>%*fault and <w>/255*fault, which is what makes the user interface raise its fault flag over them. Nothing else changes: the state is left in place, so an interface still shows the device as it is, and its color, brightness and on/off state keep being set and reported on their own data points. Clearing the fault shows the device exactly as it was left.

Reading values

Data point	Reads
rgb.<n>, rgbw.<n>	the channels, comma separated, scaled to the current brightness
rgb.<n>.on	1 or 0
rgb.<n>.brightness	1% ... 100%, or off while the device is off
rgbw.<n>.white	1 ... 255, or off while the device is off or the channel is at zero
rgb.<n>.fault	1 or 0

All of a device's data points are published together whenever any of them changes, the state last, so a rule triggering on rgb.<n>.on already sees the new color and brightness.

note

In the catalog, and therefore in the User Interface, a color device is published as <r>*<g>*<b>*<on|off>. This is the format the colorpicker object reads: it shows the color of a device that is off, rather than showing it black. The brightness is published as <n>%, and the white channel in the <w>/255 fractional format, or as off when the channel is emitting nothing, so that sliders and knobs show the correct position without any conversion. A device in fault carries fault as a further field on all three.

In persistent mode the color, the brightness and the on/off state of every color device are all retained across a restart.

User Interface

All the devices that have been added in catalog.json automatically or manually are listed in the Project Editor and can be directly associated to button and dimmer objects.

For example, adding a slider for a dimmer requires just a few clicks and no additional EVENTS logic.

To control a color device, add a colorpicker object to your project page, set its action to datapoint and its datapoint to the corresponding rgb.<n> or rgbw.<n> data point. Its on/off button writes on and off to the same data point.

For the brightness, and for the white channel of an RGBW device, add a slider or a knob, set its action to datapoint, its datapoint to rgb.<n>.brightness or rgbw.<n>.white, and its range to 0,100 or 0,255 respectively. Both data points behave as dimmers, so the slider sits at the bottom while the device is off, brings it back on when it is raised, and turns it off when it is taken to zero.

<colorpicker action="datapoint" datapoint="dummy.rgbw.1" hsv="true" onoffbutton="true" />
<slider action="datapoint" datapoint="dummy.rgbw.1.brightness" range="0,100" />
<slider action="datapoint" datapoint="dummy.rgbw.1.white" range="0,255" />

HTTP API

The HTTP API, when enabled, allows remote applications to read or set data points of the Dummy I/O Server using a simple HTTP/HTTPS API. This API is enabled setting the "httpcallpassword" option.

note

The password must be at least 8 characters long. Use a very long and randomly generated string to reduce the risk of unauthorized access.

The HSYCO HTTP server will process GET requests with the following path:

/x/httpcall/<dummy server id>/<httpcallpassword>?<query>

where <query> is one or more data point names separated by the "&" character. A data point name followed by the "=" character and a string sets the data point value, while a data point name not followed by the "=" character will return that data point value, if present, in the HTTP text response.

For example, the following HTTP GET request:

/x/httpcall/dummy/dlskd9sd9dk9s?datapoint1=value1&datapoint2=value2&datapoint3&datapoint4

will set data point "dummy.datapoint1" to "value1", "dummy.datapoint2" to "value2" and, assuming that "dummy.datapoint3" and "dummy.datapoint4" exist, return:

datapoint3=value3
datapoint4=value4

Data point names and values must be URL encoded in the query string, and will be returned URL encoded in the response text.

Release Notes

4.2.0

• added RGB and RGBW color devices, with the rgb.<n> and rgbw.<n> data points, their .on, .brightness, .fault and .white companions, and the new "rgbs" and "rgbws" options. A color device keeps its color when it is off, so the user interface can show the color it will come back to, and its color, brightness and state can all be set independently on its own data point, while its .brightness and .white data points behave as dimmers, for sliders and knobs. The .fault data point simulates an unreachable device, so a user interface can be tested against its fault flag. See Color
• the DUMMY I/O Server is now a standard driver. Configuration, data points and options are unchanged, and existing installations, including their persistent state, are not affected. The only difference is in the EVENTS start-up trigger: a DUMMY I/O Server now fires IOSTART <id> only, using the I/O Server's name, and no longer the IOSTART <index> form based on its position in the ioServers list
• the lights, dimmers, automations, rgbs and rgbws options now accept 10000, as documented. It used to be ignored, creating no devices

3.10.0

• new "automationsontime" option

3.9.0

• new "startupevents" option
• data point names are now stripped of space characters

3.8.0

• new "persistent" option

3.7.0

• new "commandstate" option
• new HTTP API: data points can now be set and read remotely with the /x/httpcall HTTP API
• default number of lights, dimmers, automation is 0 (zero)

3.6.0

• added support for generic read/write data points

3.0.0

• initial release