Difference between revisions of "Event Keywords"

From HSYCO
Jump to navigation Jump to search
(Created page with "== System Events == == Cameras == == DMX == == Infrared Control == == I/O Servers == == Modbus == == Network Services == == PBX == == Squeezebox == == Timers and Schedulers ==...")
 
 
(73 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[Category:Events]]
 +
An event is defined as a keyword that identifies the event type, usually followed by one or more parameters and conditional operators. Every keyword uses a specific syntax that interprets parameters according to its own rules.
 +
 
== System Events ==
 
== System Events ==
 +
=== DAY ===
 +
 +
A stable condition that is true during day time, as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| DAY
 +
| stable
 +
| triggered at sunrise; remains true until sunset
 +
|}
 +
 +
 +
'''Examples:'''
 +
 +
DAY : IO k.33 k.34 k.35 = 0
 +
 +
=== HAACTIVE ===
 +
 +
This event is triggered when HSYCO is a master or slave in a high availability configuration and the server is active.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| HAACTIVE
 +
| transient
 +
| this HSYCO server is active
 +
|}
 +
 +
 +
'''Examples:'''
 +
 +
Send an email when the slave HSYCO server becomes active:
 +
 +
HAACTIVE AND $HAMASTER$ = 0 : MAIL email@hsyco.com = hsyco@hsyco.com "Sent from HSYCO" "The slave server is now active"
 +
 +
=== HSYCOSTART ===
 +
 +
This event is triggered only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field devices interface threads.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| HSYCOSTART
 +
| transient
 +
| occurs only once at start-up
 +
|}
 +
 +
 +
'''Examples:'''
 +
 +
HSYCOSTART : $count = 0
 +
 +
=== INIT ===
 +
 +
This event is triggered when HSYCO reloads any EVENTS file.
 +
 +
Note that, because HSYCO takes a few seconds to reload these files after they are changed, if multiple changes occur very closely in time, a single INIT event may be triggered for a batch of changes.
 +
 +
Reloading occurs when HSYCO starts and every time the file is manually saved, even with no content changes.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| INIT
 +
| transient
 +
| an EVENTS file has been reloaded
 +
|}
 +
 +
 +
'''Examples:'''
 +
 +
INIT : $count = 0
 +
 +
=== NIGHT ===
 +
 +
A stable condition that is true during night time, as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| NIGHT
 +
| stable
 +
| triggered at sunset; remains true until sunrise
 +
|}
 +
 +
 +
'''Examples:'''
 +
 +
NIGHT: IO k.33 k.34 k.35 = 1
 +
 +
=== POWER ===
 +
 +
Triggered by a change of the current power load level, as set using the powerSet() Java method or JavaScript function, or the POWER action.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| POWER
 +
| transient
 +
| triggered by any change to the power level
 +
|-
 +
|
 +
POWER > power<br>
 +
POWER < power<br>
 +
POWER >= power<br>
 +
POWER <= power
 +
| stable
 +
|
 +
occurs when a change in the power level is detected. It is true if the comparison condition is satisfied
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* power - the power in Watt.
 +
 +
 +
'''Examples:'''
 +
 +
POWER > 2000 : IO k.70 = 0
 +
POWER : LOG "NEW POWER: " $POWER$
 +
 +
=== PROGRAMTIMER ===
 +
 +
Triggered by a program timer.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| PROGRAMTIMER name
 +
| transient
 +
| triggered after the program timer’s set time-interval
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - program timer id.
 +
 +
 +
'''Examples:'''
 +
 +
Turns on light k.33 approximately 10 seconds after the click on a user button:
 +
 +
USER timer : PROGRAMTIMER test = SET 10
 +
PROGRAMTIMER test : IO k.33 = 1
 +
 +
=== SUNAZIMUTH ===
 +
 +
This event is triggered every time there is a change in the integer part of Sun’s azimuth angle (the angle between North and the Sun’s projection on the horizon), as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| SUNAZIMUTH
 +
| transient
 +
| triggered when the Sun's azimuth changes
 +
|-
 +
|
 +
SUNAZIMUTH = value<br>
 +
SUNAZIMUTH > value<br>
 +
SUNAZIMUTH < value<br>
 +
SUNAZIMUTH >= value<br>
 +
SUNAZIMUTH <= value
 +
| stable
 +
| true if the condition matches. Angles are compared ignoring decimals
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* value - angle in decimal degrees, as a positive integer number, between 0 and 359.
 +
 +
 +
'''Examples:'''
 +
 +
SUNAZIMUTH > 180 AND SUNAZIMUTH < 220 : IO k.54 = 0
 +
 +
=== SUNELEVATION ===
 +
 +
This event is triggered every time there is a change in the integer part of Sun’s elevation angle (the angle between the horizon and the Sun), as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| SUNELEVATION
 +
| transient
 +
| triggered when the Sun's elevation changes
 +
|-
 +
|
 +
SUNELEVATION = value<br>
 +
SUNELEVATION > value<br>
 +
SUNELEVATION < value<br>
 +
SUNELEVATION >= value<br>
 +
SUNELEVATION <= value
 +
| stable
 +
| true if the condition matches. Angles are compared ignoring decimals
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* value - angle in decimal degrees, as an integer number, between -90 and 90.
 +
 +
 +
'''Examples:'''
 +
 +
SUNELEVATION > 45 : IO k.55 = 0
 +
 +
=== TIME ===
 +
 +
The current time event.
 +
 +
In its simple form, it is just a transient event that is triggered every minute.
 +
 +
It can also be used as a stable condition, comparing the current time with a constant time in the HHMM format.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| TIME
 +
| transient
 +
| triggered at the beginning of each minute
 +
|-
 +
|
 +
TIME = hhmm<br>
 +
TIME > hhmm<br>
 +
TIME < hhmm<br>
 +
TIME >= hhmm<br>
 +
TIME <= hhmm
 +
| stable
 +
| compares the current time with the specified time in the HHMM format
 +
|}
 +
 +
 +
'''Examples:'''
 +
 +
TIME : CAMERAREC entrance = 60
 +
TIME = 0930 : IO k.33 = 0
 +
 
== Cameras ==
 
== Cameras ==
 +
=== CAMERA ===
 +
 +
This event is true while HSYCO is recording video from a specific camera.
 +
 +
Recording could start automatically when a camera notifies a recording request with the recording HTTP API call:
 +
 +
<nowiki>http://192.168.0.50/x/camerarec?camera=name</nowiki>
 +
<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>
 +
 +
 +
Recording can also be triggered by the CameraRecTrigger() Java call or the CAMERAREC or CAMERARECFULL actions in EVENTS.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| CAMERA name
 +
| stable
 +
| the camera is recording
 +
|-
 +
| CAMERA name = zone
 +
| transient
 +
| transient event triggered by a camera recording request with zone information
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - the camera id
 +
* zone - the zone id.
 +
 +
 +
'''Examples:'''
 +
 +
CAMERA entrance
 +
 +
=== CAMERACOMMAND ===
 +
 +
Triggered by a camera control input from the Web interface.
 +
 +
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view.
 +
 +
{| class="wikitable"
 +
| width=240 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| CAMERACOMMAND name = function
 +
| transient
 +
| if this event has a positive match in EVENTS, the standard PTZ command associated to the camera’s PTZ driver is not executed
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - the camera id
 +
* function - see the table below.
 +
 +
<div data-skipeditordoc>
 +
{{ui_camerapanel_ptz_table}}
 +
</div>
 +
 +
'''Examples:'''
 +
 +
CAMERACOMMAND entrance = focusfar
 +
 +
=== CAMERAVIEW ===
 +
 +
This event is used to check if HSYCO is currently displaying the real-time video from a camera.
 +
 +
The event will reset to off when no Web client has been loading images from the camera for several consecutive seconds.
 +
 +
{| class="wikitable"
 +
| width=180 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| CAMERAVIEW name = status
 +
| stable
 +
| the camera real-time view status
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - the camera id
 +
* status - set to “on” or “1” to match the event when HSYCO is displaying the live view, and to “off” or “0” to match the event when HSYCO is not displaying a live view of the camera on any client.
 +
 +
 +
'''Examples:'''
 +
 +
CAMERAVIEW entrance = on
 +
 
== DMX ==
 
== DMX ==
 +
=== DMX ===
 +
 +
Events on the DMX bus channels.
 +
 +
{| class="wikitable"
 +
| width=150 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| DMX address
 +
| transient
 +
| any change to the channel value
 +
|-
 +
| DMX address = ON
 +
| stable
 +
| channel value > 0
 +
|-
 +
| DMX address = OFF
 +
| stable
 +
| channel value = 0
 +
|-
 +
|
 +
DMX address = value<br>
 +
DMX address > value<br>
 +
DMX address < value<br>
 +
DMX address >= value<br>
 +
DMX address <= value
 +
| stable
 +
| the channel value is equal, greater, greater or equal, less, less or equal to the given value.
 +
Valid values are numbers between 0 and 255
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* address - when using one DMX gateway, address will be a standard DMX-512 address between 1 and 512. If there is more than one gateway, 1000 must be added to the DMX address for the second gateway, 2000 for the third one and so on. For example, 2100 stands for the address 100 on the DMX bus controlled by the third gateway.
 +
 +
 +
'''Examples:'''
 +
 +
DMX 100 = ON
 +
DMX 1200 = OFF
 +
DMX 135 = OFF OR DMX 100 > 50
 +
DMX 41 <= $LEVEL
 +
 +
=== DMXSTART ===
 +
 +
This event is triggered when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread.
 +
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| DMXSTART busid
 +
| transient
 +
| occurs when HSYCO connects to the DMX gateway.
 +
HSYCO establishes the connection at start-up.
 +
 +
If the gateway is turned off and then on, or if communication errors occur, HSYCO automatically re-establishes the connection as soon as possible, calling this event in case of success
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* busid - the id of the DMX gateway. The first gateway has address 0. The second  has address 1, etc. busid can be omitted if 0.
 +
 +
'''Examples:'''
 +
DMXSTART: DMX 100-200 = OFF
 +
DMXSTART 1: DMX 1100-1200 = OFF
 +
 
== Infrared Control ==
 
== Infrared Control ==
 +
=== IR ===
 +
 +
This event is triggered when an IRTrans receives and successfully decodes an infrared command.
 +
 +
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}
 +
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| IR name = command
 +
| transient
 +
| command received by an IRTrans device
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - the IRTrans, as defined in the IRTrans parameter in hsyco.ini
 +
* command - the command format is “remote.command”, that is the remote control database name followed by a dot and the command name.
 +
 +
 +
'''Examples:'''
 +
 +
IR theater = dvd.play
 +
 
== I/O Servers ==
 
== I/O Servers ==
−
== Modbus ==
+
=== IO ===
 +
 
 +
Triggered by a status change of any data port of an I/O server.
 +
 
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| IO name
 +
| transient
 +
| any change of an I/O variable
 +
|-
 +
|
 +
IO name = value<br>
 +
IO name > value<br>
 +
IO name < value<br>
 +
IO name >= value<br>
 +
IO name <= value
 +
| stable
 +
| the value is equal, greater, greater or equal, less, less or equal to the given value.<br>
 +
{{tip|The names and values of the I/O variables are specifically related to the type of I/O server. Values can be numeric or strings}}
 +
|}
 +
 
 +
 
 +
'''Parameters:'''
 +
 
 +
* name - the data point name of the input or output port. According to the type of server, the format changes but it generally appears as server name, as declared with the ioServers parameter in hsyco.ini, followed by a dot and the input/output port name. See the Application Notes for more information.
 +
 
 +
 
 +
'''Examples:'''
 +
 
 +
IO tempmeter.indoor > 25.5
 +
IO contacts.c1 = 1
 +
 
 +
=== IOSTART ===
 +
 
 +
This event indicates that the connection with an I/O server has been correctly established.
 +
 
 +
It should be safe to associate this event with actions that set the I/O server writable variables.
 +
 
 +
 
 +
{| class="wikitable"
 +
| width=120 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| IOSTART id
 +
| transient
 +
| Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors
 +
|}
 +
 
 +
 
 +
'''Parameters:'''
 +
 
 +
* id - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini; If only one I/O server is available, it can be omitted.
 +
 
 +
 
 +
'''Examples:'''
 +
 
 +
IOSTART: IO contacts.c1 = 1
 +
IOSTART 2: IO relays.door = 1
 +
 
 +
== Leak Detector ==
 +
=== LEAK ===
 +
 
 +
This stable event is triggered by a LEAK action when the Intelligent Leak Detector detects a leak condition, or the leak condition is reset.
 +
 
 +
See the LEAK action for additional information.
 +
 
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| LEAK name
 +
| transient
 +
| any status change of the leak detector
 +
|-
 +
| LEAK name = ON
 +
| stable
 +
| leak condition detected
 +
|-
 +
| LEAK name = OFF
 +
| stable
 +
| leak condition reset
 +
|}
 +
 
 +
 
 +
'''Parameters:'''
 +
 
 +
* name - the name of a leak detector. Using different names you can implement several independent leak detectors.
 +
 
 +
 
 +
'''Examples:'''
 +
 
 +
HSYCOSTART : PROGRAMTIMER modbusread = repeat 4
 +
PROGRAMTIMER modbusread : IO modbus.2.768 = readholdingregisters:uint, LEAK water = IO modbus.2.768
 +
LEAK water = ON : MAIL john@example.com = hsyco@example.com “Urgent Message from HSYCO” “Leak Detected”
 +
LEAK water = OFF : MAIL john@example.com = hsyco@example.com “Message from HSYCO” “Leak Reset”
 +
 
 
== Network Services ==
 
== Network Services ==
 +
 +
=== HTTP ===
 +
 +
This transient event is triggered when the HSYCO HTTP server receives a GET request with the following path:
 +
/x/httpcall?query
 +
 +
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}
 +
 +
If a matching event is found, and the httpCallEvent JavaScript or Java callbacks are not defined, the HTTP server will respond with an "ack" text/plain answer to the HTTP client (with HTTP response code 200).
 +
 +
HSYCO will return a 404 Not Found response code if all of the following conditions are true:
 +
* no HTTP event matches the query in EVENTS
 +
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value
 +
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.
 +
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| HTTP query
 +
| transient
 +
| the HSYCO HTTP/HTTPS server received an HTTP GET request: /x/httpcall?query
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* query - the string following the ? in the URL path.
 +
 +
 +
'''Examples:'''
 +
 +
HTTP "test" : log = "test http call"
 +
 +
=== LOCATION ===
 +
 +
This event is triggered when a change in the association status of a client to the Wi-Fi access points is detected.
 +
 +
It is a stable condition that represents the current connection state and location of WiFi clients logged into the HSYCO Web interface.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| LOCATION address = zone
 +
| stable
 +
| a device connects to the access point identified by the zone name, as declared in the LocationBases parameter in hsyco.ini
 +
|-
 +
| LOCATION address = ON
 +
| stable
 +
| a device connects to the WiFi network
 +
|-
 +
| LOCATION address = OFF
 +
| stable
 +
| a device disconnects from the WiFi network
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* address - the WiFi device’s MAC address. It is made of 6 byte pairs, written in hexadecimal format and separated by “:”.
 +
 +
=== LOCATIONBEACON ===
 +
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''
 +
</div>
 +
 +
This event is triggered when a change in the proximity of an HSYCO App based client to an iBeacon is detected. See [[Beacons on HSYCO App for iOS]] for additional information.
 +
 +
It is a stable condition that represents the current connection state and location of WiFi clients logged into the HSYCO Web interface.
 +
 +
{| class="wikitable"
 +
| width=260 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| LOCATIONBEACON userid = zone
 +
| stable
 +
| a user is in proximity to an iBeacon
 +
|-
 +
| LOCATIONBEACON zone
 +
| stable
 +
| one or more users are in the proximity range of an iBeacon
 +
|-
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* userid - the user id
 +
* zone - id associated to the iBeacon, as declared in the LocationBases configuration in hsyco.ini
 +
 +
=== PING ===
 +
 +
This transient event is generated by a [[Action_Keywords#PING|PING action]], that tests the reachability of one or more IP hosts, identified by their hostnames or IP addresses, within the optional timeout defined in milliseconds (or using a default timeout of 200 ms).
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| PING hostname = ON
 +
| transient
 +
| the device has been reached after a PING action
 +
|-
 +
| PING hostname = OFF
 +
| transient
 +
| the device is not reachable after a PING action
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* hostname - the IP device name or IP address, as called by the corresponding PING action.
 +
 +
 +
'''Examples:'''
 +
 +
TIME: PING 192.168.1.1
 +
PING 192.168.1.1 = OFF : LOG = "router is off-line"
 +
 +
=== URL ===
 +
 +
This transient event is generated by a URL action, that sends an HTTP or HTTPS request to a given url.
 +
 +
The response can be checked for a specific numeric status code or looking at a string in the response body.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| URL “url” = status_code
 +
| transient
 +
| the response status code to the HTTP url request is equal to status_code
 +
|-
 +
| URL “url” *= “string”
 +
| transient
 +
| the response data to the HTTP url request contains the string
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* url - a full url, including the mandatory http:// or https:// query scheme and optional query string
 +
* status_code - the numeric status code returned by the server’s response; 200 is usually the code returned by a successful request
 +
* string - the event matches any response containing the given string in the response body.
 +
 +
 +
'''Examples:'''
 +
 +
<syntaxhighlight lang="text">
 +
TIME 0800: URL GET "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1"
 +
URL "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1" : LOG = "relay opened"
 +
</syntaxhighlight>
 +
 
== PBX ==
 
== PBX ==
 +
=== PBX ===
 +
 +
Called when a call notification is sent to HSYCO by the PBX system.
 +
 +
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:
 +
 +
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki>
 +
 +
or:
 +
 +
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki>
 +
 +
For example, the HTTP request:
 +
 +
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki>
 +
 +
is interpreted as a call notification from internal number 21 to number 25.
 +
 +
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}
 +
 +
 +
{| class="wikitable"
 +
| width=140 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| PBX from = to
 +
| transient
 +
| phone call event, with originator and destination data
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* from - the caller number
 +
* to - the called number.
 +
 +
 +
'''Examples:'''
 +
 +
A call from number 22 to number 44 turns on light k.33:
 +
 +
PBX 22 = 44 : IO k.33 = 1
 +
 
== Squeezebox ==
 
== Squeezebox ==
 +
=== MUSIC ===
 +
 +
Triggered by a status change in a Squeezebox player. It is a stable condition that represents the current ON/OFF/PLAY/PAUSE status of the player.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| MUSIC address = ON
 +
| stable
 +
| player on
 +
|-
 +
| MUSIC address = OFF
 +
| stable
 +
| player off
 +
|-
 +
| MUSIC address = PLAY
 +
| stable
 +
| player on - play
 +
|-
 +
| MUSIC address = PAUSE
 +
| stable
 +
| player on - pause
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* address - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini.
 +
 +
 +
'''Examples:'''
 +
 +
MUSIC 0 = ON
 +
MUSIC 1 = PLAY
 +
 
== Timers and Schedulers ==
 
== Timers and Schedulers ==
 +
=== TIMER ===
 +
 +
This is a stable event that matches the current status of a user timer or scheduler.
 +
 +
It is triggered by the timer’s activation and deactivation.
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| TIMER name = ON
 +
| stable
 +
| true when the timer or scheduler rule is active (ON status)
 +
|-
 +
| TIMER name = OFF
 +
| stable
 +
| true when the timer or scheduler rule is not active (OFF status)
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - the timer’s id, as declared with the Timers parameter in hsyco.ini, or the scheduler’s rule name.
 +
 +
 +
'''Examples:'''
 +
 +
TIMER irrigation = ON : IO k.33 k.34 = 1
 +
TIMER irrigation = OFF : IO k.33 k.34 = 0
 +
 
== User Interface ==
 
== User Interface ==
 +
=== PAGE ===
 +
 +
Triggered when the specified page of a project is viewed by a client.
 +
 +
There is no guarantee that the event would be fired the exact moment the page is loaded.
 +
 +
Network delays or errors could cause delayed triggering of this event.
 +
 +
{{tip|You can use the UISESSIONSET action with this event}}
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| PAGE project = page
 +
| transient
 +
| a Web client is viewing a specific page of a project
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* project - the name of the project
 +
* page - the page id, with the #landscape or #portrait suffix if the page has distinct orientation versions in the project.
 +
 +
 +
'''Examples:'''
 +
 +
Count how many times the portrait and landscape versions of a project’s menu page are viewed:
 +
 +
PAGE "myproject" = "menu#landscape" : $landscape_counter + 1
 +
PAGE "myproject" = "menu#portrait" : $portrait_counter + 1
 +
 +
=== LOGIN ===
 +
 +
Triggered when a user authenticates with a valid PIN or PIN/PUK.
 +
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| LOGIN userid
 +
| transient
 +
| a user authenticates with a valid PIN or PIN/PUK
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* userid - the user id.
 +
 +
 +
'''Examples:'''
 +
 +
Count how many times the staff user has logged in successfully:
 +
 +
LOGIN "staff" : $login_counter_staff + 1
 +
 +
=== LOGOUT ===
 +
 +
Triggered when a user logs out or locks the user interface.
 +
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| LOGOUT userid
 +
| transient
 +
| a user logs out or locks the user interface
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* userid - the user id.
 +
 +
 +
'''Examples:'''
 +
 +
Count how many times the staff user has logged out:
 +
 +
LOGOUT "staff" : $logout_counter_staff + 1
 +
 +
=== USER ===
 +
 +
Triggered by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method or JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).
 +
 +
{| class="wikitable"
 +
| width=160 | '''Event'''
 +
| width=80 | '''State'''
 +
| '''Description'''
 +
|-
 +
| USER name = param
 +
| transient
 +
| this format requires a match with both name and parameter
 +
|-
 +
| USER name
 +
| transient
 +
| this format requires a match with name only
 +
|}
 +
 +
 +
'''Parameters:'''
 +
 +
* name - the name field of the (user) object
 +
* param - the id of the (user) object.
 +
 +
 +
'''Examples:'''
 +
 +
Turns on light k.33 approximately 10 seconds after the click on a user button:
 +
 +
USER timer : PROGRAMTIMER test = SET 10
 +
PROGRAMTIMER test : IO k.33 = 1

Latest revision as of 18:41, 5 October 2020

An event is defined as a keyword that identifies the event type, usually followed by one or more parameters and conditional operators. Every keyword uses a specific syntax that interprets parameters according to its own rules.

System Events

DAY

A stable condition that is true during day time, as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.

Event State Description
DAY stable triggered at sunrise; remains true until sunset


Examples: 

DAY : IO k.33 k.34 k.35 = 0

HAACTIVE

This event is triggered when HSYCO is a master or slave in a high availability configuration and the server is active.

Event State Description
HAACTIVE transient this HSYCO server is active


Examples:

Send an email when the slave HSYCO server becomes active: 

HAACTIVE AND $HAMASTER$ = 0 : MAIL email@hsyco.com = hsyco@hsyco.com "Sent from HSYCO" "The slave server is now active"

HSYCOSTART

This event is triggered only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field devices interface threads.

Event State Description
HSYCOSTART transient occurs only once at start-up


Examples: 

HSYCOSTART : $count = 0

INIT

This event is triggered when HSYCO reloads any EVENTS file.

Note that, because HSYCO takes a few seconds to reload these files after they are changed, if multiple changes occur very closely in time, a single INIT event may be triggered for a batch of changes.

Reloading occurs when HSYCO starts and every time the file is manually saved, even with no content changes.

Event State Description
INIT transient an EVENTS file has been reloaded


Examples: 

INIT : $count = 0

NIGHT

A stable condition that is true during night time, as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.

Event State Description
NIGHT stable triggered at sunset; remains true until sunrise


Examples: 

NIGHT: IO k.33 k.34 k.35 = 1

POWER

Triggered by a change of the current power load level, as set using the powerSet() Java method or JavaScript function, or the POWER action.

Event State Description
POWER transient triggered by any change to the power level

POWER > power
POWER < power
POWER >= power
POWER <= power

stable

occurs when a change in the power level is detected. It is true if the comparison condition is satisfied


Parameters:

  • power - the power in Watt.


Examples: 

POWER > 2000 : IO k.70 = 0
POWER : LOG "NEW POWER: " $POWER$

PROGRAMTIMER

Triggered by a program timer.

Event State Description
PROGRAMTIMER name transient triggered after the program timer’s set time-interval


Parameters:

  • name - program timer id.


Examples:

Turns on light k.33 approximately 10 seconds after the click on a user button: 

USER timer : PROGRAMTIMER test = SET 10
PROGRAMTIMER test : IO k.33 = 1

SUNAZIMUTH

This event is triggered every time there is a change in the integer part of Sun’s azimuth angle (the angle between North and the Sun’s projection on the horizon), as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.

Event State Description
SUNAZIMUTH transient triggered when the Sun's azimuth changes

SUNAZIMUTH = value
SUNAZIMUTH > value
SUNAZIMUTH < value
SUNAZIMUTH >= value
SUNAZIMUTH <= value

stable true if the condition matches. Angles are compared ignoring decimals


Parameters:

  • value - angle in decimal degrees, as a positive integer number, between 0 and 359.


Examples: 

SUNAZIMUTH > 180 AND SUNAZIMUTH < 220 : IO k.54 = 0

SUNELEVATION

This event is triggered every time there is a change in the integer part of Sun’s elevation angle (the angle between the horizon and the Sun), as computed based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.

Event State Description
SUNELEVATION transient triggered when the Sun's elevation changes

SUNELEVATION = value
SUNELEVATION > value
SUNELEVATION < value
SUNELEVATION >= value
SUNELEVATION <= value

stable true if the condition matches. Angles are compared ignoring decimals


Parameters:

  • value - angle in decimal degrees, as an integer number, between -90 and 90.


Examples: 

SUNELEVATION > 45 : IO k.55 = 0

TIME

The current time event.

In its simple form, it is just a transient event that is triggered every minute.

It can also be used as a stable condition, comparing the current time with a constant time in the HHMM format.

Event State Description
TIME transient triggered at the beginning of each minute

TIME = hhmm
TIME > hhmm
TIME < hhmm
TIME >= hhmm
TIME <= hhmm

stable compares the current time with the specified time in the HHMM format


Examples: 

TIME : CAMERAREC entrance = 60
TIME = 0930 : IO k.33 = 0

Cameras

CAMERA

This event is true while HSYCO is recording video from a specific camera.

Recording could start automatically when a camera notifies a recording request with the recording HTTP API call: 

http://192.168.0.50/x/camerarec?camera=name
http://192.168.0.50/x/camerarec?camera=name&zone=id


Recording can also be triggered by the CameraRecTrigger() Java call or the CAMERAREC or CAMERARECFULL actions in EVENTS.

Event State Description
CAMERA name stable the camera is recording
CAMERA name = zone transient transient event triggered by a camera recording request with zone information


Parameters:

  • name - the camera id
  • zone - the zone id.


Examples: 

CAMERA entrance

CAMERACOMMAND

Triggered by a camera control input from the Web interface.

It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view.

Event State Description
CAMERACOMMAND name = function transient if this event has a positive match in EVENTS, the standard PTZ command associated to the camera’s PTZ driver is not executed


Parameters:

  • name - the camera id
  • function - see the table below.
icon function action
Camover-ff.png focus far
Camover-fn.png focus near
Camover-zin.png zoom tele
Camover-zout.png zoom wide
Camover-l.png move left
Camover-r.png move right
Camover-u.png move up
Camover-d.png move down
move stop
Camerapanel ptz.png

Examples: 

CAMERACOMMAND entrance = focusfar

CAMERAVIEW

This event is used to check if HSYCO is currently displaying the real-time video from a camera.

The event will reset to off when no Web client has been loading images from the camera for several consecutive seconds.

Event State Description
CAMERAVIEW name = status stable the camera real-time view status


Parameters:

  • name - the camera id
  • status - set to “on” or “1” to match the event when HSYCO is displaying the live view, and to “off” or “0” to match the event when HSYCO is not displaying a live view of the camera on any client.


Examples: 

CAMERAVIEW entrance = on

DMX

DMX

Events on the DMX bus channels.

Event State Description
DMX address transient any change to the channel value
DMX address = ON stable channel value > 0
DMX address = OFF stable channel value = 0

DMX address = value
DMX address > value
DMX address < value
DMX address >= value
DMX address <= value

stable the channel value is equal, greater, greater or equal, less, less or equal to the given value.

Valid values are numbers between 0 and 255


Parameters:

  • address - when using one DMX gateway, address will be a standard DMX-512 address between 1 and 512. If there is more than one gateway, 1000 must be added to the DMX address for the second gateway, 2000 for the third one and so on. For example, 2100 stands for the address 100 on the DMX bus controlled by the third gateway.


Examples: 

DMX 100 = ON
DMX 1200 = OFF
DMX 135 = OFF OR DMX 100 > 50
DMX 41 <= $LEVEL

DMXSTART

This event is triggered when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread.

Event State Description
DMXSTART busid transient occurs when HSYCO connects to the DMX gateway.

HSYCO establishes the connection at start-up.

If the gateway is turned off and then on, or if communication errors occur, HSYCO automatically re-establishes the connection as soon as possible, calling this event in case of success


Parameters:

  • busid - the id of the DMX gateway. The first gateway has address 0. The second has address 1, etc. busid can be omitted if 0.

Examples: 

DMXSTART: DMX 100-200 = OFF
DMXSTART 1: DMX 1100-1200 = OFF

Infrared Control

IR

This event is triggered when an IRTrans receives and successfully decodes an infrared command.

Note IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.


Event State Description
IR name = command transient command received by an IRTrans device


Parameters:

  • name - the IRTrans, as defined in the IRTrans parameter in hsyco.ini
  • command - the command format is “remote.command”, that is the remote control database name followed by a dot and the command name.


Examples: 

IR theater = dvd.play

I/O Servers

IO

Triggered by a status change of any data port of an I/O server.

Event State Description
IO name transient any change of an I/O variable

IO name = value
IO name > value
IO name < value
IO name >= value
IO name <= value

stable the value is equal, greater, greater or equal, less, less or equal to the given value.

Note The names and values of the I/O variables are specifically related to the type of I/O server. Values can be numeric or strings


Parameters:

  • name - the data point name of the input or output port. According to the type of server, the format changes but it generally appears as server name, as declared with the ioServers parameter in hsyco.ini, followed by a dot and the input/output port name. See the Application Notes for more information.


Examples: 

IO tempmeter.indoor > 25.5
IO contacts.c1 = 1

IOSTART

This event indicates that the connection with an I/O server has been correctly established.

It should be safe to associate this event with actions that set the I/O server writable variables.


Event State Description
IOSTART id transient Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors


Parameters:

  • id - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini; If only one I/O server is available, it can be omitted.


Examples: 

IOSTART: IO contacts.c1 = 1
IOSTART 2: IO relays.door = 1

Leak Detector

LEAK

This stable event is triggered by a LEAK action when the Intelligent Leak Detector detects a leak condition, or the leak condition is reset.

See the LEAK action for additional information.

Event State Description
LEAK name transient any status change of the leak detector
LEAK name = ON stable leak condition detected
LEAK name = OFF stable leak condition reset


Parameters:

  • name - the name of a leak detector. Using different names you can implement several independent leak detectors.


Examples: 

HSYCOSTART : PROGRAMTIMER modbusread = repeat 4
PROGRAMTIMER modbusread : IO modbus.2.768 = readholdingregisters:uint, LEAK water = IO modbus.2.768
LEAK water = ON : MAIL john@example.com = hsyco@example.com “Urgent Message from HSYCO” “Leak Detected”
LEAK water = OFF : MAIL john@example.com = hsyco@example.com “Message from HSYCO” “Leak Reset”

Network Services

HTTP

This transient event is triggered when the HSYCO HTTP server receives a GET request with the following path: 

/x/httpcall?query

Note The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS

If a matching event is found, and the httpCallEvent JavaScript or Java callbacks are not defined, the HTTP server will respond with an "ack" text/plain answer to the HTTP client (with HTTP response code 200).

HSYCO will return a 404 Not Found response code if all of the following conditions are true:

  • no HTTP event matches the query in EVENTS
  • the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value
  • the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.


Event State Description
HTTP query transient the HSYCO HTTP/HTTPS server received an HTTP GET request: /x/httpcall?query


Parameters:

  • query - the string following the ? in the URL path.


Examples: 

HTTP "test" : log = "test http call"

LOCATION

This event is triggered when a change in the association status of a client to the Wi-Fi access points is detected.

It is a stable condition that represents the current connection state and location of WiFi clients logged into the HSYCO Web interface.

Event State Description
LOCATION address = zone stable a device connects to the access point identified by the zone name, as declared in the LocationBases parameter in hsyco.ini
LOCATION address = ON stable a device connects to the WiFi network
LOCATION address = OFF stable a device disconnects from the WiFi network


Parameters:

  • address - the WiFi device’s MAC address. It is made of 6 byte pairs, written in hexadecimal format and separated by “:”.

LOCATIONBEACON

WARNING! The Beacons functionality for iOS is experimental and subject to changes.

This event is triggered when a change in the proximity of an HSYCO App based client to an iBeacon is detected. See Beacons on HSYCO App for iOS for additional information.

It is a stable condition that represents the current connection state and location of WiFi clients logged into the HSYCO Web interface.

Event State Description
LOCATIONBEACON userid = zone stable a user is in proximity to an iBeacon
LOCATIONBEACON zone stable one or more users are in the proximity range of an iBeacon


Parameters:

  • userid - the user id
  • zone - id associated to the iBeacon, as declared in the LocationBases configuration in hsyco.ini

PING

This transient event is generated by a PING action, that tests the reachability of one or more IP hosts, identified by their hostnames or IP addresses, within the optional timeout defined in milliseconds (or using a default timeout of 200 ms).

Event State Description
PING hostname = ON transient the device has been reached after a PING action
PING hostname = OFF transient the device is not reachable after a PING action


Parameters:

  • hostname - the IP device name or IP address, as called by the corresponding PING action.


Examples: 

TIME: PING 192.168.1.1
PING 192.168.1.1 = OFF : LOG = "router is off-line"

URL

This transient event is generated by a URL action, that sends an HTTP or HTTPS request to a given url.

The response can be checked for a specific numeric status code or looking at a string in the response body.

Event State Description
URL “url” = status_code transient the response status code to the HTTP url request is equal to status_code
URL “url” *= “string” transient the response data to the HTTP url request contains the string


Parameters:

  • url - a full url, including the mandatory http:// or https:// query scheme and optional query string
  • status_code - the numeric status code returned by the server’s response; 200 is usually the code returned by a successful request
  • string - the event matches any response containing the given string in the response body.


Examples: 

TIME 0800: URL GET "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1"
URL "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1" : LOG = "relay opened"

PBX

PBX

Called when a call notification is sent to HSYCO by the PBX system.

The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats: 

http://192.168.0.50/x/vcall/<from>/<to>

or: 

http://192.168.0.50/x/vcall?from=<from>&to=<to>

For example, the HTTP request: 

http://192.168.0.50/x/vcall?from=21&to=25

is interpreted as a call notification from internal number 21 to number 25.

Note The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.


Event State Description
PBX from = to transient phone call event, with originator and destination data


Parameters:

  • from - the caller number
  • to - the called number.


Examples:

A call from number 22 to number 44 turns on light k.33: 

PBX 22 = 44 : IO k.33 = 1

Squeezebox

MUSIC

Triggered by a status change in a Squeezebox player. It is a stable condition that represents the current ON/OFF/PLAY/PAUSE status of the player.

Event State Description
MUSIC address = ON stable player on
MUSIC address = OFF stable player off
MUSIC address = PLAY stable player on - play
MUSIC address = PAUSE stable player on - pause


Parameters:

  • address - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini.


Examples: 

MUSIC 0 = ON
MUSIC 1 = PLAY

Timers and Schedulers

TIMER

This is a stable event that matches the current status of a user timer or scheduler.

It is triggered by the timer’s activation and deactivation.

Event State Description
TIMER name = ON stable true when the timer or scheduler rule is active (ON status)
TIMER name = OFF stable true when the timer or scheduler rule is not active (OFF status)


Parameters:

  • name - the timer’s id, as declared with the Timers parameter in hsyco.ini, or the scheduler’s rule name.


Examples: 

TIMER irrigation = ON : IO k.33 k.34 = 1
TIMER irrigation = OFF : IO k.33 k.34 = 0

User Interface

PAGE

Triggered when the specified page of a project is viewed by a client.

There is no guarantee that the event would be fired the exact moment the page is loaded.

Network delays or errors could cause delayed triggering of this event.

Note You can use the UISESSIONSET action with this event

Event State Description
PAGE project = page transient a Web client is viewing a specific page of a project


Parameters:

  • project - the name of the project
  • page - the page id, with the #landscape or #portrait suffix if the page has distinct orientation versions in the project.


Examples:

Count how many times the portrait and landscape versions of a project’s menu page are viewed: 

PAGE "myproject" = "menu#landscape" : $landscape_counter + 1
PAGE "myproject" = "menu#portrait" : $portrait_counter + 1

LOGIN

Triggered when a user authenticates with a valid PIN or PIN/PUK.


Event State Description
LOGIN userid transient a user authenticates with a valid PIN or PIN/PUK


Parameters:

  • userid - the user id.


Examples:

Count how many times the staff user has logged in successfully: 

LOGIN "staff" : $login_counter_staff + 1

LOGOUT

Triggered when a user logs out or locks the user interface.


Event State Description
LOGOUT userid transient a user logs out or locks the user interface


Parameters:

  • userid - the user id.


Examples:

Count how many times the staff user has logged out: 

LOGOUT "staff" : $logout_counter_staff + 1

USER

Triggered by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method or JavaScript function. Also triggered by by the screensaver (see the Screensaver page for more details).

Event State Description
USER name = param transient this format requires a match with both name and parameter
USER name transient this format requires a match with name only


Parameters:

  • name - the name field of the (user) object
  • param - the id of the (user) object.


Examples:

Turns on light k.33 approximately 10 seconds after the click on a user button: 

USER timer : PROGRAMTIMER test = SET 10
PROGRAMTIMER test : IO k.33 = 1
Retrieved from "https://wiki.hsyco.com/3.7/index.php?title=Event_Keywords&oldid=9162"