Difference between revisions of "Dummy"
| (20 intermediate revisions by 2 users not shown) | |||
| Line 30: | Line 30: | ||
|false | |false | ||
|auto-detect for devices is disabled | |auto-detect for devices is disabled | ||
| + | |||
| + | |- | ||
| + | |||
| + | |rowspan="2"|commandstate | ||
| + | |rowspan="2"|false | ||
| + | |true | ||
| + | |enables command/state mode, see below | ||
| + | |- | ||
| + | |false | ||
| + | |normal mode | ||
| + | |||
| + | |- | ||
| + | |||
| + | |rowspan="2"|persistent | ||
| + | |rowspan="2"|false | ||
| + | |true | ||
| + | |enables persistent state, see below | ||
| + | |- | ||
| + | |false | ||
| + | |normal mode | ||
|- | |- | ||
|lights | |lights | ||
| − | | | + | |0 |
|0 ... 10000 | |0 ... 10000 | ||
|number of on/off light devices to generate | |number of on/off light devices to generate | ||
| Line 41: | Line 61: | ||
|dimmers | |dimmers | ||
| − | | | + | |0 |
|0 ... 10000 | |0 ... 10000 | ||
|number of dimmer devices to generate | |number of dimmer devices to generate | ||
| Line 48: | Line 68: | ||
|automations | |automations | ||
| − | | | + | |0 |
|0 ... 10000 | |0 ... 10000 | ||
|number of automation devices to generate | |number of automation devices to generate | ||
| Line 57: | Line 77: | ||
| | | | ||
|string of 8 or more uppercase or lowercase letters and digits | |string of 8 or more uppercase or lowercase letters and digits | ||
| − | |enables the HTTP API | + | |enables the HTTP API |
| − | + | ||
| + | |- | ||
| + | |||
| + | |httpcalltimeoutseconds | ||
| + | |0 | ||
| + | |>= 0 | ||
| + | |if > 0, the connection datapoint is set to "offline" if no httpcall request is received for more than the set value, and reset to "online" after a valid httpcall request.<br>Otherwise the connection datapoint is set to "online" when the I/O Server is started | ||
|} | |} | ||
| Line 94: | Line 120: | ||
dummy.autom.1 : AUTOM ; VSHUT ; Dummy automation 1 | dummy.autom.1 : AUTOM ; VSHUT ; Dummy automation 1 | ||
dummy.autom.2 : AUTOM ; VSHUT ; Dummy automation 2 | dummy.autom.2 : AUTOM ; VSHUT ; Dummy automation 2 | ||
| + | </pre> | ||
| + | |||
| + | == 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. | ||
| + | |||
| + | == 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. | ||
| + | |||
| + | <pre> | ||
| + | # 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 | ||
</pre> | </pre> | ||
| Line 106: | Line 169: | ||
|- | |- | ||
| − | |connection | + | |rowspan="2" |connection |
|online | |online | ||
|R | |R | ||
| − | |I/O Server ready | + | |I/O Server ready, or httpcall received within the httpcalltimeoutseconds timeout |
| + | |- | ||
| + | |offline | ||
| + | |R | ||
| + | |httpcall not received within the httpcalltimeoutseconds timeout | ||
|- | |- | ||
| Line 220: | Line 287: | ||
== HTTP API == | == 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 == | == Release Notes == | ||
| + | |||
| + | === 3.8.0 === | ||
| + | |||
| + | *new "persistent" option | ||
=== 3.7.0 === | === 3.7.0 === | ||
| + | *new "commandstate" option | ||
*new HTTP API: data points can now be set and read remotely with the /x/httpcall HTTP API | *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 === | === 3.6.0 === | ||
Latest revision as of 09:57, 27 April 2022
The DUMMY I/O Server is a virtual server that doesn’t actually connect to any external system, but simulates basic lighting 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.
Contents
HSYCO Configuration
Add a DUMMY I/O Server in the I/O Servers section of the Settings and set its parameters.
High Availability
- Shutdown when inactive: defaults to false.
Options
| ID | Default | Values | Description |
|---|---|---|---|
| discovery | true | true | automatically lists all virtual devices in the systemtopo.txt 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 | ||
| 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 |
| httpcallpassword | string of 8 or more uppercase or lowercase letters and digits | enables the HTTP API | |
| httpcalltimeoutseconds | 0 | >= 0 | if > 0, the connection datapoint is set to "offline" if no httpcall request is received for more than the set value, and reset to "online" after a valid httpcall request. Otherwise the connection datapoint is set to "online" when the I/O Server is started |
The Device Configuration Database
The systemtopo.txt file contains the list of all virtual devices that should be directly associated to graphic objects 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 systemtopo.txt file, use the discovery option in Settings.
This is an example of an automatically generated systemtopo.txt file:
(devices) dummy.autom.1 : AUTOM ; VSHUT ; DUMMY dummy.autom.2 : AUTOM ; VSHUT ; DUMMY dummy.autom.3 : AUTOM ; VSHUT ; DUMMY dummy.autom.4 : AUTOM ; VSHUT ; DUMMY dummy.autom.5 : AUTOM ; VSHUT ; DUMMY dummy.dimmer.1 : LIGHT ; DIMMER ; DUMMY dummy.dimmer.2 : LIGHT ; DIMMER ; DUMMY dummy.dimmer.3 : LIGHT ; DIMMER ; DUMMY dummy.dimmer.4 : LIGHT ; DIMMER ; DUMMY dummy.dimmer.5 : LIGHT ; DIMMER ; DUMMY dummy.light.1 : LIGHT ; LIGHT ; DUMMY dummy.light.2 : LIGHT ; LIGHT ; DUMMY dummy.light.3 : LIGHT ; LIGHT ; DUMMY dummy.light.4 : LIGHT ; LIGHT ; DUMMY dummy.light.5 : LIGHT ; LIGHT ; DUMMY
You should then manually add comments and other optional parameters:
(devices) dummy.autom.1 : AUTOM ; VSHUT ; Dummy automation 1 dummy.autom.2 : AUTOM ; VSHUT ; Dummy automation 2
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.
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
(set to this value 30 seconds after a 'up' command) |
| offdown | R | autom <n> is stopped in lower position
(set to this value 30 seconds after a 'down' command) | |
| 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 | ||
| <name> | <value> | R | generic data point <name> has value <value> |
| W | set value of generic data point <name> to <value> |
Virtual automation devices automatically go to the offup or offdown state 30 seconds after the up or down command.
Note that generic data point names must not start with "light", "autom" or "dimmer".
User Interface
All the devices that have been added in systemtopo.txt (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.
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.
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
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
