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.

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
	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

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.

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 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.

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`

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

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 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