Difference between revisions of "Event Keywords"

From HSYCO
Jump to navigation Jump to search
 
(4 intermediate revisions by 2 users not shown)
Line 64: Line 64:
 
=== INIT ===
 
=== INIT ===
  
−
This event is triggered when HSYCO reloads the events.txt file.
+
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.
 
Reloading occurs when HSYCO starts and every time the file is manually saved, even with no content changes.
Line 75: Line 77:
 
| INIT
 
| INIT
 
| transient
 
| transient
−
| events.txt has been reloaded
+
| an EVENTS file has been reloaded
 
|}
 
|}
  
Line 567: Line 569:
 
  /x/httpcall?query
 
  /x/httpcall?query
  
−
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}
+
{{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).
 
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:
 
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.txt
+
* no HTTP event matches the query in EVENTS
−
* the httpCallEvent JavaScript callback is not defined in events.txt, or doesn't return a value
+
* 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.
 
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.
  
Line 635: Line 637:
 
=== PING ===
 
=== 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).  
+
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"
 
{| class="wikitable"
Line 692: Line 694:
 
'''Examples:'''
 
'''Examples:'''
  
−
TIME 0800: URL GET "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1"
+
<syntaxhighlight lang="text">
−
URL "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1" : LOG = "relay opened"
+
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 ==

Latest revision as of 14:26, 8 July 2015

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 an 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 “:”.


Examples: 

LOCATION aa:01:33:e4:41:00 = entrance
LOCATION aa:01:33:e4:41:00 = ON
LOCATION aa:01:33:e4:41:00 = OFF

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

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.

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 "http://wiki.hsyco.com/3.5.0/index.php?title=Event_Keywords&oldid=5836"