Event Keywords

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.

In the IO, POWER, SUNAZIMUTH and SUNELEVATION events, and in variable conditions, the value after the comparison operator can be a constant, a variable, a data point (IO name) or an arithmetic computation, like IO tempmeter.indoor > $setpoint + 0.5. See Arithmetic in Events for the rules. All other events accept only constant values.

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.

Event	State	Description
HAACTIVE	transient	this HSYCO server is active
HAACTIVE = ON	stable	this HSYCO server is active
HAACTIVE = OFF	stable	this HSYCO server is not 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"

Send an email when the HSYCO server, master or slave becomes active:

HAACTIVE = ON : MAIL email@hsyco.com = hsyco@hsyco.com "Sent from HSYCO" "The HSYCO server is active"

Send an email when the HSYCO server, master or slave becomes not active:

HAACTIVE = OFF : MAIL email@hsyco.com = hsyco@hsyco.com "Sent from HSYCO" "The HSYCO server is not 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. It can be a constant, a variable, a data point or a computation.

Examples:

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

Turn off the oven when the power load exceeds 90% of the maximum set in the $maxpower variable:

INIT : $maxpower = 3000
POWER > $maxpower * 0.9 : IO k.70 = 0

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. It can also be a variable, a data point or a computation; constant values and constant computations are checked when the EVENTS file is loaded, the others when the event is evaluated.

Examples:

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

Close the awning while the Sun is within 45 degrees from the direction the façade faces, set in the $facade variable:

INIT : $facade = 200
SUNAZIMUTH > $facade - 45 AND SUNAZIMUTH < $facade + 45 : 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. It can also be a variable, a data point or a computation; constant values and constant computations are checked when the EVENTS file is loaded, the others when the event is evaluated.

Examples:

SUNELEVATION > 45 : IO k.55 = 0

Use a threshold that can be changed from the user interface, stored in the $shade variable, with a 5 degrees margin:

SUNELEVATION > $shade + 5 : IO k.55 = 0
SUNELEVATION < $shade - 5 : IO k.55 = 1

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

note

The TIME comparison accepts only constant times in the HHMM format; arithmetic is not supported, as HHMM values can't be added like numbers. To compare the current time with a computed time, use the TIME event as a trigger and the $TIME$ predefined variable, that holds the time in seconds:

TIME AND $TIME$ > $SUNSET$ - 3600 AND NOT $lights = on : IO k.33 k.34 = 1, $lights = on

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
	focus	far
	focus	near
	zoom	tele
	zoom	wide
	move	left
	move	right
	move	up
	move	down
	move	stop

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

I/O Servers

IO

Triggered by a status change of any data point 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 Integrations for more information.
• value - a constant, a quoted string, a variable, another data point (IO name) or an arithmetic computation of numbers, variables and data points. The computation is repeated every time the event is evaluated; if an operand is not a number, the comparison is false.

caution

Only the data point on the left of the comparison triggers the event: data points and variables in the value don't. See Arithmetic in Events.

Examples:

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

Keep the indoor temperature within half a degree from the setpoint stored in the $setpoint variable:

IO tempmeter.indoor > $setpoint + 0.5 : IO heating.relay = 0
IO tempmeter.indoor < $setpoint - 0.5 : IO heating.relay = 1

Compare two data points, evaluating the rule when either of them changes:

(IO tempmeter.indoor OR IO tempmeter.outdoor) AND IO tempmeter.indoor > IO tempmeter.outdoor + 5 : LOG = "Indoor much warmer than outdoor"

Use round brackets to group a computation:

IO meter.power > (IO meter.limit - $reserve) * 1000 : IO k.70 = 0

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"

Location Services

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 :
• zone - id associated to the iBeacon, as declared in the LocationBases configuration in hsyco.ini.

LOCATIONBEACON

caution

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.

LOCATIONGEO

This event is triggered when a geographic location notification is sent by an HSYCO iOS or Android app, for a specific user, if the location is defined in hsyco.ini.

It is a transient event, true if the reported location is inside the distance from the zone's coordinates set in hsyco.ini, or false if outside.

note

Note that the horizontal accuracy radius is taken into account. So, considering a circumference cantered on the zone's coordinates and having a radius equal to the distance parameter set in hsyco.ini, and another circumference centered on the reported position coordinates and with a radius equal to the horizontal accuracy, the event is true if the two circumferences overlap.

Event	State	Description
LOCATIONGEO userid = zone	transient	a geographic location notification is sent by an HSYCO iOS or Android app from userid

Parameters:

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

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"

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" = 200 : 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

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

Called when a Web client initially loads a project and when navigating between pages. Popup and overlay pages do not trigger this event.

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 when the project's pages or overlays have an orientation. A page without an orientation is reported with the #landscape suffix.

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

warning

Adding the first portrait or landscape page to a project can change the value reported for its existing pages too. For example, a rule such as PAGE "myproject" = "home" may need to become PAGE "myproject" = "home#landscape".

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 Button object in command action mode, by a USER action in EVENTS, or by the user() Java method or JavaScript function. Also triggered by by the screensaver.

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 Button object in submit action mode
• param - the parameter of the Button object in submit action mode

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