Difference between revisions of "Event Keywords"
(→PBX) |
(→PBX) |
||
Line 713: | Line 713: | ||
is interpreted as a call notification from internal number 21 to number 25. | 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.}} | ||
Revision as of 17:04, 11 March 2014
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.
Contents
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 the events.txt file.
Reloading occurs when HSYCO starts and every time the file is manually saved, even with no content changes.
Event | State | Description |
INIT | transient | events.txt 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 |
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 |
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 |
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 |
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.
|
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 |
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.
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 |
stable | the value is equal, greater, greater or equal, less, less or equal to the given value. 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
The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.
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.txt
- the httpCallEvent JavaScript callback is not defined in events.txt, 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.
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.
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