Difference between revisions of "JavaScript Callback Functions API"

From HSYCO
Jump to navigation Jump to search
 
(67 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
= Callback Functions =
+
[[Category:JavaScript]]
−
 
 
 
== System Functions ==
 
== System Functions ==
  
 
=== DaylightEvent ===
 
=== DaylightEvent ===
  
−
DaylightEvent(day)
+
<source lang="java">DaylightEvent(day)</source>
  
 
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
 
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
Line 12: Line 11:
 
'''Parameters:'''
 
'''Parameters:'''
 
* day:  boolean - true at sunrise, false at sunset.
 
* day:  boolean - true at sunrise, false at sunset.
−
 
  
 
=== haActiveEvent ===
 
=== haActiveEvent ===
  
−
haActiveEvent(active)
+
<source lang="java">haActiveEvent(active)</source>
  
 
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.
 
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.
Line 23: Line 21:
 
'''Parameters:'''
 
'''Parameters:'''
 
* active:  boolean - true if the server is active, false if not active.
 
* active:  boolean - true if the server is active, false if not active.
−
 
  
 
=== PowerEvent ===
 
=== PowerEvent ===
  
−
PowerEvent(power)
+
<source lang="java">PowerEvent(power)</source>
  
 
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.
 
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.
  
−
Thanks to this method it is possible to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.
+
Thanks to this function, you can alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.
  
  
Line 42: Line 39:
  
 
{{tip|The JavaScript PowerEvent function is always called, but its return value is used only when the Java PowerEvent callback is not defined or returned -1.}}
 
{{tip|The JavaScript PowerEvent function is always called, but its return value is used only when the Java PowerEvent callback is not defined or returned -1.}}
−
 
  
 
=== programTimerEvent ===
 
=== programTimerEvent ===
  
−
programTimerEvent(name)
+
<source lang="java">programTimerEvent(name)</source>
  
 
Called when a program timer is activated.
 
Called when a program timer is activated.
  
−
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in the EVENTS.
+
Program timers are set using [[Java_Command_and_Utility_Methods_API#programTimerSet|programTimerSet()]], [[Java_Command_and_Utility_Methods_API#programTimerReset|programTimerReset()]], [[Java_Command_and_Utility_Methods_API#programTimerRepeat|programTimerRepeat()]], or using the corresponding actions in EVENTS.
  
  
 
'''Parameters:'''
 
'''Parameters:'''
 
* name: string - program timer name.
 
* name: string - program timer name.
−
 
  
 
=== SchedulerEvent ===
 
=== SchedulerEvent ===
  
−
SchedulerEvent(groupname, schedulename)
+
<source lang="java">SchedulerEvent(groupname, schedulename)</source>
  
 
This callback blocking function allows to call user methods at configurable intervals.
 
This callback blocking function allows to call user methods at configurable intervals.
  
−
You define schedules using a group name and a schedule name.
+
Schedules are defined using a group name and a schedule name.
  
 
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.
 
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.
Line 71: Line 66:
 
* groupname: string - the scheduler’s group name
 
* groupname: string - the scheduler’s group name
 
* schedulename: string - the scheduler’s name.
 
* schedulename: string - the scheduler’s name.
−
 
  
 
=== StartupEvent ===
 
=== StartupEvent ===
  
−
StartupEvent()
+
<source lang="java">StartupEvent()</source>
  
 
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.
 
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.
−
 
  
 
=== SunPositionEvent ===
 
=== SunPositionEvent ===
  
−
SunPositionEvent(azimuth, elevation)
+
<source lang="java">SunPositionEvent(azimuth, elevation)</source>
  
 
Called when the Sun changes its height with respect to the horizon or its angle from true north.
 
Called when the Sun changes its height with respect to the horizon or its angle from true north.
Line 94: Line 87:
 
=== TimeEvent ===
 
=== TimeEvent ===
  
−
TimeEvent(time)
+
<source lang="java">TimeEvent(time)</source>
  
 
Called every 60 seconds.
 
Called every 60 seconds.
Line 109: Line 102:
 
=== varEvent ===
 
=== varEvent ===
  
−
varEvent(name, value)
+
<source lang="java">varEvent(name, value)</source>
  
 
Triggered by the change of value of a program variable.
 
Triggered by the change of value of a program variable.
Line 122: Line 115:
 
=== CameraCommandEvent ===
 
=== CameraCommandEvent ===
  
−
CameraCommandEvent(function, action, camera)
+
<source lang="java">CameraCommandEvent(camerafunction, action, camera)</source>
  
 
Triggered by a camera control input from the Web interface.
 
Triggered by a camera control input from the Web interface.
Line 131: Line 124:
 
'''Parameters:'''
 
'''Parameters:'''
  
−
* function: string - see the table below
+
* camerafunction: string - see the table below
 
* action: string - see the table below
 
* action: string - see the table below
 
* camera: string - the camera name.
 
* camera: string - the camera name.
Line 139: Line 132:
 
* numeric - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.
 
* numeric - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.
  
−
{{tip|The JavaScript CameraCommandEvent function is always called, but its return value is used only when the Java CameraCommandEvent callback is not defined or returned -1.}}
+
{{tip|The JavaScript CameraCommandEvent camerafunction is always called, but its return value is used only when the Java CameraCommandEvent callback is not defined or returned -1.}}
  
 +
<div data-skipeditordoc>
 
{{ui_camerapanel_ptz_table}}
 
{{ui_camerapanel_ptz_table}}
−
 
+
</div>
  
 
=== CameraMotionEvent ===
 
=== CameraMotionEvent ===
  
−
CameraMotionEvent(event, time)
+
<source lang="java">CameraMotionEvent(event, time)</source>
  
 
Called when HSYCO starts recording video from a camera.
 
Called when HSYCO starts recording video from a camera.
Line 154: Line 148:
 
  '''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</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.
+
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.
  
  
Line 161: Line 155:
 
* event: string - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter
 
* event: string - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter
 
* time: numeric - the current time in milliseconds.
 
* time: numeric - the current time in milliseconds.
−
 
  
 
=== CameraViewEvent ===
 
=== CameraViewEvent ===
  
−
CameraViewEvent(camera, active)
+
<source lang="java">CameraViewEvent(camera, active)</source>
  
 
CameraViewEvent() is called on changes of the live view status of cameras.
 
CameraViewEvent() is called on changes of the live view status of cameras.
Line 183: Line 176:
 
=== DmxEvent ===
 
=== DmxEvent ===
  
−
DmxEvent(channel, state)
+
<source lang="java">DmxEvent(channel, state)</source>
  
 
Called after changes to DMX-512 channels.
 
Called after changes to DMX-512 channels.
Line 196: Line 189:
 
=== DmxFilter ===
 
=== DmxFilter ===
  
−
DmxFilter(channel, state, reverse)
+
<source lang="java">DmxFilter(channel, state, reverse)</source>
  
 
This function allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.
 
This function allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.
Line 223: Line 216:
 
=== DmxStartupEvent ===
 
=== DmxStartupEvent ===
  
−
DmxStartupEvent(index)
+
<source lang="java">DmxStartupEvent(index)</source>
  
 
Called 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, for example after communication errors.
 
Called 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, for example after communication errors.
  
−
It is safe, inside this method, to execute command methods for the same DMX gateway.
+
It is safe, inside this function, to execute commands for the same DMX gateway.
  
−
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}
+
{{tip|This is a blocking function. The DMX driver will start after this function returns.}}
  
  
Line 240: Line 233:
 
=== IREvent ===
 
=== IREvent ===
  
−
IREvent(received, irtransid, event)
+
<source lang="java">IREvent(received, irtransid, event)</source>
 +
 
 +
This function is called when an IRTrans receives or sends an IR command from its local IR database.
  
−
This method is called when an IRTrans receives or sends an IR command from its local IR database.
+
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}
  
  
 
'''Parameters:'''
 
'''Parameters:'''
  
−
* received: boolean - true if the command has been received21 by the IRTrans, false if sent
+
* received: boolean - true if the command has been received by the IRTrans, false if sent
 
* irtransid: numeric - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini
 
* irtransid: numeric - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini
−
* event: string - the string of the command received or issued, formatted as: "remote_name,command"
+
* event: string - the string of the command received or issued, formatted as: "remote_name,command".
−
 
 
  
 
== I/O Servers ==
 
== I/O Servers ==
Line 256: Line 250:
 
=== IOEvent ===
 
=== IOEvent ===
  
−
IOEvent(name, value)
+
<source lang="java">IOEvent(name, value)</source>
  
 
Triggered by the value change of any data point of an I/O server.
 
Triggered by the value change of any data point of an I/O server.
Line 269: Line 263:
 
=== IOStartupEvent ===
 
=== IOStartupEvent ===
  
−
IOStartupEvent(index)
+
<source lang="java">IOStartupEvent(index)</source>
  
 
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.
 
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.
Line 282: Line 276:
  
 
== Modbus ==
 
== Modbus ==
 +
 +
For detailed information about the Modbus protocol, and the response PDU formats, you should refer to the MODBUS Application Protocol Specification V1.1b documentation at: [http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf]
 +
  
 
=== ModbusEvent ===
 
=== ModbusEvent ===
  
−
ModbusEvent(name, addr, unitid, pdu)
+
<source lang="java">ModbusEvent(name, addr, unitid, pdu)</source>
  
 
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.
 
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.
Line 306: Line 303:
  
 
== Network Services ==
 
== Network Services ==
 +
 +
=== httpCallEvent ===
 +
 +
<source lang="java">httpCallEvent(address, secure, query)</source>
 +
 +
Called 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}}
 +
 +
This function shoud return a string, that will be sent as the 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.
 +
 +
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.
 +
 +
 +
'''Parameters:'''
 +
 +
* address: string - the IP address of the HTTP client
 +
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server
 +
* query: string - the string following the ? in the URL path.
 +
 +
 +
'''Returns:'''
 +
 +
* string - the string to send as the text/plain answer to the HTTP client.
 +
 +
=== httpRawEvent ===
 +
 +
<source lang="java"> httpRawEvent(host, secure, version, httpmethod, gzip, contenttype, query, session, userid, indata)</source>
 +
 +
Called when the HSYCO HTTP server receives a GET or POST request with the following path:
 +
/x/raw
 +
 +
{{tip|httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}
 +
 +
The application code inside the httpRawEvent() function should return a complete HTTP response (both headers and body).
 +
 +
If multiple httpRawEvent() callbacks or functions are defined, only one should write the HTTP response.
 +
 +
 +
'''Parameters:'''
 +
 +
* host: string - the IP address of the HTTP client
 +
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server
 +
* version: string - the HTTP version, as passed in the HTTP request header
 +
* httpmethod: string - the HTTP request's method, "GET", "POST" or "HEAD"
 +
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")
 +
* contenttype: string - the HTTP request's content type (value of Content-Type header)
 +
* query: string - the string following the ? in the URL path, or null if not present
 +
* session: string - the authenticated session id, or null
 +
* userid: string - the user id for requests having a valid authentication cookie, null otherwise
 +
* indata: string - the POST data, or an empty string for GET or HEAD requests.
 +
 +
 +
'''Returns:'''
 +
 +
* string - the application code should return the full HTTP response, including all headers.
 +
 +
 +
'''Example:'''
 +
 +
function httpRawEvent(host, secure, version, httpmethod, gzip, contenttype, query, session, userid, indata) : {
 +
messageLog("host: " + host);
 +
messageLog("secure: " + secure);
 +
messageLog("version: " + version);
 +
messageLog("httpmethod: " + httpmethod);
 +
messageLog("gzip: " + gzip);
 +
messageLog("contenttype: " + contenttype);
 +
messageLog("query: " + query);
 +
messageLog("session: " + session);
 +
messageLog("userid: " + userid);
 +
messageLog("in: " + indata);
 +
 +
var outdata = httpmethod + " data echoed from host [" + host + "] : " + indata + "\r\n";
 +
var httpreply = version + " 200 OK\r\n";
 +
httpreply += "Server: HSYCO\r\n";
 +
httpreply += "Content-length: " + outdata.length + "\r\n";
 +
httpreply += "Content-type: text/plain\r\n";
 +
httpreply += "Cache-Control: no-store, no-cache\r\n\r\n";
 +
httpreply += outdata;
 +
return httpreply;
 +
}
  
 
=== LocationEvent ===
 
=== LocationEvent ===
  
−
LocationEvent(mac, ip, zoneId)
+
<source lang="java">LocationEvent(mac, ip, zoneId)</source>
  
−
Called, if the location service is active, when a variation in the   association of a client to the Wi-Fi Access Points is detected.
+
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.
  
  
Line 320: Line 404:
 
* zoneId: numeric - in case of association, it is the Access Point sequence number,  according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.
 
* zoneId: numeric - in case of association, it is the Access Point sequence number,  according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.
  
 +
=== LocationBeaconEvent ===
 +
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''
 +
</div>
 +
<source lang="java">LocationBeaconEvent(session, address, userid, zone, distance, background)</source>
 +
 +
Called when the HSYCO App detects a change in the proximity of one of the configured beacons. See [[Beacons on HSYCO App for iOS]] for additional information.
 +
 +
There is no guarantee that the event would be fired.
 +
 +
Network delays or errors could cause delayed triggering of this event.
 +
 +
 +
'''Parameters:'''
 +
 +
* session: string - session id string that uniquely identifies the client session
 +
* address: string - the beacon's address
 +
* userid: string - the user id
 +
* zone: string - the beacon's zone
 +
* distance: string - far, near, immediate or off
 +
* background: boolean - true if the app called the server while in background mode (app closed)
 +
 +
=== SysLogEvent ===
 +
 +
<source lang="java"> SysLogEvent(address, log)</source>
 +
 +
Called when the HSYCO SYSLOG server receives a log message from a network client.
 +
 +
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.
 +
 +
 +
'''Parameters:'''
 +
 +
* address: string - the IP address of the SYSLOG client
 +
* log: string - SYSLOG log message.
  
 
== PBX ==
 
== PBX ==
Line 325: Line 443:
 
=== PBXCallEvent ===
 
=== PBXCallEvent ===
  
−
PBXCallEvent(host, caller, called)
+
<source lang="java">PBXCallEvent(host, caller, called)</source>
  
 
Called when a call notification is sent to HSYCO by the PBX system.
 
Called when a call notification is sent to HSYCO by the PBX system.
  
 
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.
 
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.
 +
 +
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.}}
  
  
Line 338: Line 472:
 
* called: string - the called number.
 
* called: string - the called number.
  
 +
 +
'''Returns:'''
 +
 +
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.
  
 
== Squeezebox ==
 
== Squeezebox ==
Line 343: Line 481:
 
=== SlimPowerEvent ===
 
=== SlimPowerEvent ===
  
−
SlimPowerEvent(index, power)
+
<source lang="java">SlimPowerEvent(index, power)</source>
  
 
Called when a Squeezebox player is turned on or off.
 
Called when a Squeezebox player is turned on or off.
Line 351: Line 489:
  
 
* index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
 
* index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
−
* power - 0: OFF, 1: ON.
+
* power: numeric - 0: OFF, 1: ON.
−
 
 
  
 
=== SlimStatusEvent ===
 
=== SlimStatusEvent ===
  
−
SlimStatusEvent()
+
<source lang="java">SlimStatusEvent()</source>
  
 
Called when a Squeezebox player changes its playback mode.
 
Called when a Squeezebox player changes its playback mode.
Line 369: Line 506:
 
=== SlimVolumeEvent ===
 
=== SlimVolumeEvent ===
  
−
SlimVolumeEvent(index, volume)
+
<source lang="java">SlimVolumeEvent(index, volume)</source>
  
 
Called when a Squeezebox player changes its volume level.
 
Called when a Squeezebox player changes its volume level.
Line 384: Line 521:
 
=== UserTimerEvent ===
 
=== UserTimerEvent ===
  
−
UserTimerEvent(name, active)
+
<source lang="java">UserTimerEvent(name, active)</source>
  
 
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.
 
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.
Line 417: Line 554:
 
=== pageEvent ===
 
=== pageEvent ===
  
−
pageEvent(address, session, userid, project, page)
+
<source lang="java">pageEvent(address, session, userid, project, page)</source>
  
 
Called when a Web client initially loads a project and when navigating between pages.
 
Called when a Web client initially loads a project and when navigating between pages.
Line 432: Line 569:
 
* userid: string - the user id
 
* userid: string - the user id
 
* project: string - project’s id
 
* project: string - project’s id
−
* page: string - the page id of the current page.
+
* page: string - the page id, with the #landscape or #portrait suffix if the page has distinct orientation versions in the project.
 +
 
 +
=== loginEvent ===
 +
 
 +
<source lang="java">loginEvent(address, session, userid)</source>
 +
 
 +
Called when a user authenticates with a valid PIN or PIN/PUK.
 +
 
 +
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.
 +
 
  
 +
'''Parameters:'''
 +
 +
* address: string - the client’s IP address string in textual presentation
 +
* session: string - session id string that uniquely identifies the client session
 +
* userid: string - the user id.
 +
 +
=== logoutEvent ===
 +
 +
<source lang="java">logoutEvent(address, session, userid, lock)</source>
 +
 +
Called when a user logs out or locks the user interface.
 +
 +
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.
 +
 +
 +
'''Parameters:'''
 +
 +
* address: string - the client’s IP address string in textual presentation
 +
* session: string - session id string that uniquely identifies the client session
 +
* userid: string - the user id
 +
* lock: boolean - false when logging out; true when the user locks the user interface.
  
 
=== uiClearEvent ===
 
=== uiClearEvent ===
  
−
uiClearEvent(session)
+
<source lang="java">uiClearEvent(session)</source>
  
 
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).
 
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).
Line 444: Line 611:
 
'''Parameters:'''
 
'''Parameters:'''
  
−
* session: string - session id string that uniquely identifies the client session
+
* session: string - session id string that uniquely identifies the client session.
−
 
 
  
 
=== userCommand ===
 
=== userCommand ===
  
−
userCommand(session, userid, name, param)
+
<source lang="java">userCommand(session, userid, name, param)</source>
  
−
Called 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 userCommand() Java method.
+
Called by user clicks on buttons created in the Web interface with the [[user|user objects]], by a USER action in EVENTS, or by the user() Java method and JavaScript function.
 +
Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).
  
 
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.
 
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.
  
−
If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a (link) object), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called again when that popup or page is closed, with "/close" appended to param.
+
{{userCommand return values}}
 +
 
 +
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}
  
  
Line 462: Line 631:
 
* session: string - a session id string that uniquely identifies the client session
 
* session: string - a session id string that uniquely identifies the client session
 
* userid: string - the user id
 
* userid: string - the user id
−
* name: string - the name field of the (user) object
+
* name: string - the name field of the [[user|user object]]
−
* param: string - the param of the (user) object.
+
* param: string - the param of the [[user|user object]]
  
  
Line 471: Line 640:
  
 
{{tip|The JavaScript userCommand function is alway called, but its return value is used only when the Java userCommand callback is not defined or returned null or an empty string.}}
 
{{tip|The JavaScript userCommand function is alway called, but its return value is used only when the Java userCommand callback is not defined or returned null or an empty string.}}
−
 
  
 
=== userSubmit ===
 
=== userSubmit ===
  
−
userSubmit(session, userid, name, fields)
+
<source lang="java">userSubmit(session, userid, name, fields)</source>
  
 
This function is similar to userCommand(session, userid, name, param).
 
This function is similar to userCommand(session, userid, name, param).
  
−
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.
+
When userSubmit() is defined, it will be called when a [[submit|submit button]] is pressed, while userCommand() will continue to be called on [[user|user buttons]].
  
 
userSubmit() provides a more convenient access to the values of multiple input fields in a form.
 
userSubmit() provides a more convenient access to the values of multiple input fields in a form.
Line 485: Line 653:
 
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.
 
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.
  
−
If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a (link) object), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called when that popup or page is closed, with "/close" appended to param.
+
If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a [[link|link object]]), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called when that popup or page is closed, with "/close" appended to param.
 +
 
 +
You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.
 +
 
 +
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}
  
  
Line 508: Line 680:
  
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
−
function userSubmit(session, user, name, values) : {
+
function userSubmit(session, user, name, values) : {
−
if (session.length > 0) {
+
if (session.length > 0) {
−
messageLog(user + ', ' + name + '=' + values);
+
messageLog(user + ', ' + name + '=' + values);
−
var keys = values.keySet().toArray();
+
var keys = values.keySet().toArray();
−
for (var i = 0; i < keys.length; i++) {
+
for (var i = 0; i < keys.length; i++) {
−
messageLog(user + ', ' + keys[i] +  ' = ' + values.get(keys[i]));
+
messageLog(user + ', ' + keys[i] +  ' = ' + values.get(keys[i]));
−
}
+
}
−
return "";
+
return "";
−
}
+
}
−
}
+
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 530: Line 702:
 
=== WebRootRequestEvent ===
 
=== WebRootRequestEvent ===
  
−
WebRootRequestEvent(addr, secure, useragent)
+
<source lang="java">WebRootRequestEvent(addr, secure, useragent)</source>
  
 
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.
 
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.
 +
 +
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}
  
  
Line 552: Line 726:
  
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
−
function WebRootRequestEvent(addr, secure, useragent) : {
+
function WebRootRequestEvent(addr, secure, useragent) : {
−
return "hsycoserver/manager";
+
return "hsycoserver/manager";
−
}
+
}
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
 
−
 
−
 
−
= Command and Utility Functions =
 
−
 
−
== System Functions ==
 
−
 
−
=== dateSet ===
 
−
dateSet(year, month, day, hour, minute, second)
 
−
 
−
Sets the HSYCO Server operating system’s clock and hardware clock, in the local time zone.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* year: numeric - the year, greater than 1900
 
−
* month: numeric - the month, between 1-12
 
−
* day: numeric - the day, between 1-31
 
−
* hour: numeric - the hour, between 0-23
 
−
* minute: numeric - the minute, between 0-59
 
−
* second: numeric - the second, between 0-59.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true if successful, false if not.
 
−
 
−
 
−
=== getNextSunrise ===
 
−
getNextSunrise(now, withoffset)
 
−
 
−
Computes the time of the next sunrise after the time set in the now parameter.
 
−
 
−
The sunrise time is returned in milliseconds since midnight, January 1, 1970 UTC.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* now: numeric - the reference time in milliseconds
 
−
* withoffset: boolean - true to take the sunrise offset into account, as defined with the SunriseOffsetMinutes in hsyco.ini, false to ignore the offset and return the actual sunrise time (Based on civil dawn, begins when the geometric center of the sun is 6° below the horizon).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - the next sunrise time in milliseconds since midnight, January 1, 1970 UTC.
 
−
 
−
 
−
=== getNextSunset ===
 
−
getNextSunset(now, withoffset)
 
−
 
−
Computes the time of the next sunset after the time set in the now parameter.
 
−
 
−
The sunset time is returned in milliseconds since midnight, January 1, 1970 UTC.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* now: numeric - the reference time in milliseconds
 
−
* withoffset: boolean - true to take the sunset offset into account, as defined with the SunriseOffsetMinutes in hsyco.ini, false to ignore the offset and return the actual sunrise time (Based on civil dusk, ends when the geometric center of the sun reaches 6° below the horizon).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - the next sunset time in milliseconds since midnight, January 1, 1970 UTC.
 
−
 
−
 
−
=== haActiveState ===
 
−
haActiveState()
 
−
 
−
When HSYCO is installed in a high availability configuration, this method returns true if the system (master or slave) is active, false if it is not active.
 
−
 
−
If high availability is not configured, the method returns true.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - high availability current state.
 
−
 
−
 
−
=== haActive ===
 
−
haActive(active)
 
−
 
−
Force a master HSYCO server to become inactive, or return to the active state.
 
−
 
−
This method should be called on the master only, and has no effect on the slave server.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* active: boolean - set to true to force a master to become inactive, or false to return it to the active state after the master was forced to become inactive.
 
−
 
−
 
−
=== isDaylight ===
 
−
isDaylight()
 
−
 
−
Returns the day or night status at present time.
 
−
 
−
The result is based on the latitude and longitude data set in hsyco.ini and the SunriseOffsetMinutes and SunsetOffsetMinutes parameters.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true during the day, false at night.
 
−
 
−
 
−
=== powerSet ===
 
−
powerSet(power)
 
−
 
−
Sets the electric power state variable.
 
−
 
−
The power value is shown in the navigation or status bar of the Web interface.
 
−
 
−
Besides setting the power value, this method also triggers the execution of the powerEvent() callback and the POWER event in EVENTS.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* power: numeric - the power in Watt units.
 
−
 
−
 
−
=== programTimerClear ===
 
−
programTimerClear(name)
 
−
 
−
Cancels a program timer.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the program timer name.
 
−
 
−
 
−
=== programTimerRepeat ===
 
−
programTimerRepeat(name, seconds)
 
−
 
−
Sets a program timer that is executed repeatedly with an interval  equal to the specified number of seconds.
 
−
 
−
If a program timer with the same name has already been set, the number of seconds to the timer’s execution is reset to the new value.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the program timer name
 
−
* seconds: numeric - the interval in seconds of the timer’s execution.
 
−
 
−
 
−
=== programTimerReset ===
 
−
programTimerReset(name, seconds)
 
−
 
−
Sets a program timer to be executed after the specified number of seconds.
 
−
 
−
If a program timer with the same name has already been set, the number of seconds to the timer’s execution is reset to the new value.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the program timer name
 
−
* seconds: numeric - the number of seconds to the timer’s execution.
 
−
 
−
 
−
=== programTimerSet ===
 
−
programTimerSet(name, seconds)
 
−
 
−
Sets a program timer to be executed after the specified number of seconds.
 
−
If a program timer with the same name has already been set, the action will be ignored.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the program timer name
 
−
* seconds: numeric - the number of seconds to the timer’s execution.
 
−
 
−
 
−
=== schedulerRegister ===
 
−
schedulerRegister(groupname, schedulename, interval)
 
−
 
−
This function registers a new scheduled callback.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* groupname: string - the group name
 
−
* schedulename: string - the schedule name
 
−
* interval: numeric - interval in milliseconds.
 
−
 
−
 
−
=== schedulerRemove ===
 
−
schedulerRemove(groupname, schedulename)
 
−
 
−
Deletes a schedule.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* groupname: string - the group name
 
−
* schedulename: string - the schedule name.
 
−
 
−
 
−
=== sleep ===
 
−
sleep(millis)
 
−
 
−
Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* millis: numeric - the length of time to sleep in milliseconds.
 
−
 
−
 
−
=== varGet ===
 
−
varGet(name)
 
−
 
−
Returns the value of a program variable, or null if no variable with the given name has been defined.
 
−
 
−
Program variables can be set using varSet() in user.java or in the EVENTS programming environment.
 
−
 
−
To access a variable used in EVENTS, the name used in varGet() should start with the $ character.
 
−
 
−
Variables names ending with ! are considered persistent and their values are preserved when HSYCO restarts; normal variables are deleted when HSYCO starts.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the variable name. Names are case-insensitive.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* string - the current value of the program variable.
 
−
 
−
 
−
=== varSet ===
 
−
varSet(name, value)
 
−
 
−
Sets a program variable to the value parameter.
 
−
 
−
Variables set with varSet() can be read using varGet() and are also available in the EVENTS programming environment, if the variable name starts with $.
 
−
 
−
If you need to use variables in Java or JavaScript but don’t want these variables to be available in EVENTS, just use names that don’t start with the $ character.
 
−
 
−
Variables names ending with ! are considered persistent and their values are preserved when HSYCO restarts; normal variables are deleted when HSYCO starts.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the variable name. Names are case-insensitive
 
−
* value: string - the value to be assigned to the program variable.
 
−
 
−
 
−
== Cameras ==
 
−
 
−
=== cameraCommand ===
 
−
cameraCommand(func, action, camera)
 
−
 
−
Sends PTZ and focus commands to cameras.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* function: string - see the table below
 
−
* action: string - see the table below
 
−
* camera: string - the camera name.
 
−
 
−
{{ui_camerapanel_ptz_table}}
 
−
 
−
 
−
=== cameraMode ===
 
−
cameraMode(cameraName, enabled)
 
−
 
−
Disables or enables a camera.
 
−
When the live view is disabled, recording is also disabled.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* camera: string - the camera name
 
−
* enabled: boolean - true to enable the camera, false to disable.
 
−
 
−
 
−
=== cameraRecMode ===
 
−
cameraRecMode(cameraName, enabled)
 
−
 
−
Disables or enables recording from a camera, not affecting live view.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* camera: string - the camera name
 
−
* enabled: boolean - true to enable the recording, false to disable.
 
−
 
−
 
−
=== cameraRecTrigger ===
 
−
cameraRecTrigger(cameraName, source, seconds)
 
−
 
−
Records video from a camera.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* camera: string - the camera name
 
−
* source: string - a string used to generate a log message, to identify the source that triggered the recording
 
−
* seconds: numeric - recording time in seconds. If set on 0, stops the current recording.
 
−
 
−
 
−
=== cameraRecTriggerFull ===
 
−
cameraRecTriggerFull(cameraName, source, seconds)
 
−
 
−
Records video from a camera, like cameraRecTrigger(), but ignores the DroppedFrames parameter in hsyco.ini, so that all frames captured from the camera during the recording period are recorded with no skips.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* camera: string - the camera name
 
−
* source: string - a string used to generate a log message, to identify the source that triggered the recording
 
−
* seconds: numeric - recording time in seconds. If set on 0, stops the current recording.
 
−
 
−
 
−
== Data Logger ==
 
−
 
−
=== dataLoggerClear ===
 
−
dataLoggerClear(name)
 
−
 
−
Permanently deletes all historical data of the specified data logger.
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - data logger name.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true if successful, false if not.
 
−
 
−
 
−
=== dataLoggerOptions ===
 
−
dataLoggerOptions(name, param, value)
 
−
 
−
Sets a specific option for the specified data logger.
 
−
 
−
So far the only available option is “origin” which sets the x-bar of all the charts linked to the data logger to the passed value.
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - data logger name
 
−
* param: string - option to be set (“origin” is the only option you can currently set with this method)
 
−
* value: string - value for the specified option.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true if successful, false if not.
 
−
 
−
 
−
=== dataLoggerSave ===
 
−
dataLoggerSave(type, names, path, timestamp)
 
−
 
−
Creates or updates a CSV file containing the data processed by the specified data loggers.
 
−
 
−
The possible types are:
 
−
* log: append the last acquired value by the data logger to the specified file
 
−
* stat: updates the specified file with the currently gathered data by the specified data logger.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* type: string - log type (log or stat)
 
−
* names: string array - data logger names
 
−
* path: string - path of the file to be created
 
−
* timestamp: boolean - if true and the type is log adds a timestamp column in the CSV file for the logged values.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true if successful, false if not.
 
−
 
−
 
−
'''Examples:'''
 
−
 
−
The following code appends a new line every minute to the userdata/log.csv file with the most recent values of three data loggers, "a", "b" and "c".
 
−
 
−
<syntaxhighlight lang="javascript">
 
−
time : { dataLoggerSave('log', ['a','b','c'], 'userdata/log.csv', true); }
 
−
</syntaxhighlight>
 
−
 
−
 
−
=== dataLoggerUpdate ===
 
−
dataLoggerUpdate(name, value)
 
−
 
−
Supplies the specified data logger with a new value to be processed.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - data logger name
 
−
* value: numeric - value to be processed. Setting value to null, with counter data loggers only, resets the internal delta baseline.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true if successful, false if not.
 
−
 
−
 
−
== DMX ==
 
−
 
−
=== dmxGet ===
 
−
dmxGet(channel)
 
−
 
−
Returns the current status of a channel on the DMX-512 bus.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* channel: numeric - 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.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - channel current status, between 0 and 255, or UNKNOWN (-1) if the status is unknown.
 
−
 
−
 
−
=== dmxOff ===
 
−
dmxOff(channel)
 
−
 
−
Sets a channel on the DMX-512 bus to 0. It also saves the previous value, so it can be restored with dmxOn().
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* channel: numeric - 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.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, 0 if not.
 
−
 
−
 
−
=== dmxOn ===
 
−
dmxOn(channel)
 
−
 
−
Sets a DMX-512 channel to the value preceding the last call to dmxOff().
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* channel: numeric - 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.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, 0 if not.
 
−
 
−
 
−
=== dmxMerge ===
 
−
dmxMerge(fromchannel, tochannel, merge)
 
−
 
−
Sets all DMX-512 channels between the parameters from and to to merge mode or normal mode. In merge mode, the channels on the DMX OUT bus of the gateway follow the values of the channels of the DMX IN bus.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* fromchannel: numeric - first address of the range. 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
 
−
* tochannel: numeric - last address of the range
 
−
* merge: boolean - true to enable merge mode, false to return to normal mode.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, -1 if to < from, 0 for other errors.
 
−
 
−
 
−
=== dmxSet ===
 
−
dmxSet(channel, state)
 
−
 
−
Sets the value of a single DMX-512 channel.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* channel: numeric - 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.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, 0 if not.
 
−
 
−
 
−
== Infrared Control ==
 
−
 
−
=== irtransCommand ===
 
−
irtransCommand(irid, command)
 
−
 
−
Sends a command to an IRTrans.
 
−
 
−
 
−
{{infrared_commands}}
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* irid: string - identifies the IRTrans, as defined with the IRTrans parameter in hsyco.ini
 
−
* command: string - the sequence of IR commands to be sent.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, 0 if not.
 
−
 
−
 
−
== I/O Servers ==
 
−
 
−
=== ioGet ===
 
−
ioGet(id)
 
−
 
−
Retrieves the current status of an I/O data point.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* id: string - the full data point name, including the I/O server id prefix.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* string - the data point value.
 
−
 
−
 
−
=== ioServersRestart ===
 
−
ioServersRestart(name)
 
−
 
−
Restarts an I/O server that was previously stopped.
 
−
 
−
This command has no effect on a running I/O server.
 
−
 
−
{{tip|Note that this command will return before the I/O server is actually restarted.}}
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the I/O server name.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, -1 if the server name is not defined.
 
−
 
−
 
−
=== ioServersStop ===
 
−
ioServersStop(name)
 
−
 
−
Stops the execution of an I/O server.
 
−
 
−
{{tip|Note that this command will return before the I/O server is actually stopped.}}
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the I/O server name.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, -1 if the server name is not defined.
 
−
 
−
 
−
=== ioSet ===
 
−
ioSet(id, value)
 
−
 
−
Writes to I/O servers variables or data points.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* id: string - the full data point name, including the I/O server id prefix
 
−
* value: string - the new value.
 
−
 
−
 
−
== Leak Detector ==
 
−
 
−
{{leak_detector_description}}
 
−
 
−
 
−
=== leakDetectorClear ===
 
−
leakDetectorClear(name)
 
−
 
−
Clears the detector’s internal state.
 
−
 
−
In normal applications, there is no need to call this method, as the detector automatically clears its state from old data.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - leak detector name.
 
−
 
−
 
−
=== leakDetectorOptions ===
 
−
leakDetectorOptions(name, param, value)
 
−
 
−
The detector’s logic uses two parameters to set its sensitivity and time base. You can change the defaults to adapt to your specific conditions.
 
−
 
−
The “period” parameter changes the time base, expressed in seconds. The default is 1200 seconds.
 
−
The detector generates a warning if the flow deviation constantly remains below the deviation threshold for the time period.
 
−
 
−
The “deviation” parameter changes the deviation percentage, and should be a number between 1 and 100. The default is 50.
 
−
Set the period or deviation to 0 to temporarily disable the detector.
 
−
 
−
{{tip|Small deviation values cause the algorithm to activate leak warnings only when the flow is very constant in time, becoming less susceptible to false alarms, but a value that is too low could miss actual leaks. Larger values could easily generate false alarms.}}
 
−
 
−
Both period and deviation parameters can be changed anytime, even when the detector is already processing data.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - leak detector name
 
−
* param: string - set to “period” or “deviation”
 
−
* value: numeric - the period or deviation value.
 
−
 
−
 
−
=== leakDetectorUpdate ===
 
−
leakDetectorUpdate(name, value)
 
−
 
−
Calls the leak detector passing the current liters counter value.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - leak detector name
 
−
* value: numeric - the flow counter value.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - -1 if the detector status is not changed, 0 if the status has changed to a reset condition, and 1 if the status has changed to a leak condition.
 
−
 
−
== Log ==
 
−
 
−
=== errorLog ===
 
−
errorLog(message)
 
−
 
−
Generates an error message in the daily log file.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* message: string - the text of the error message.
 
−
 
−
 
−
=== fileLog ===
 
−
fileLog(pathname, message)
 
−
 
−
Appends a generic text message at the end of a file.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* pathname: string - the file name. You can specify any path, starting from HSYCO’s base directory. If the file or parent directories don’t exist, they will be created automatically
 
−
* message: string - the message that will be appended at the last line of the text file.
 
−
 
−
 
−
=== messageLog ===
 
−
messageLog(message)
 
−
 
−
Generates an information message in the daily log file.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* message: string - the text of the error message.
 
−
 
−
 
−
== Mail ==
 
−
 
−
=== sendMail ===
 
−
sendMail(to, from, subject, body)
 
−
 
−
Sends a multipart email message, mixing text and multiple images from cameras, live or recorded.
 
−
 
−
{{mail_send}}
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* to: string - a valid email address of the intended recipient. You can optionally specify the destination SMTP server name or IP address by appending :<server name or address to the recipient's email address, for example: john@example.com:192.168.1.1
 
−
* from: string - a valid email address to be used as the sender address
 
−
* subject: string - the message subject
 
−
* body: string array - the message body. To send an ordinary text, just fill the vector with the desired text strings. To send an image, add a string to the vector with the following format: “cam:<cameraname>[:<seconds_back>]”. For example, “cam:door” sends a live frame from the camera called “door”; “cam:door:2” sends a frame that was recorded two seconds before the last recorded frame; “cam:door:0” sends the last recorded frame. To send files as attachments, use the following format: “file:<file name>”. The file path is relative to the HSYCO root directory.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1: message sent; 0: message not sent; -1: other errors, including address errors.
 
−
 
−
 
−
'''Examples:'''
 
−
... : { sendMail('ulde@hsyco.com', 'test@hsyco.net', 'this is a test', ['Door camera','cam:door:2']); }
 
−
 
−
sends an email message with body containing a short text and a camera snapshot.
 
−
 
−
 
−
 
−
== Modbus ==
 
−
 
−
=== modbusReadCoils ===
 
−
modbusReadCoils(name, unit, address, quantity)
 
−
 
−
Reads the content of a contiguous block of coils in a MODBUS device, using function code '''0x01'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x01, the second to the byte count of the data part, and the data starts from the third byte.
 
−
 
−
If there is an error, the first byte is set to 0x81 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the starting address of the block of coils
 
−
* quantity: numeric - the quantity of coils you are reading (1 to 2000).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusReadDiscreteInputs ===
 
−
modbusReadDiscreteInputs(name, unit, address, quantity)
 
−
 
−
Reads the content of a contiguous block of discrete inputs in a MODBUS device, using function code '''0x02'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x02, the second to the byte count of the data part, and the data starts from the third byte.
 
−
 
−
If there is an error, the first byte is set to 0x82 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the starting address of the block of discrete inputs
 
−
* quantity: numeric - the quantity of discrete inputs you are reading (1 to 2000).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusReadHoldingRegisters ===
 
−
modbusReadHoldingRegisters(name, unit, address, quantity)
 
−
 
−
Reads the content of a contiguous block of holding registers in a MODBUS device, using function code '''0x03'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x03, the second to the byte count of the data part, and the data starts from the third byte.
 
−
 
−
If there is an error, the first byte is set to 0x83 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the starting address of the block of registers
 
−
* quantity: numeric - the quantity of registers you are reading (1 to 125).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusReadInputRegisters ===
 
−
modbusReadInputRegisters(name, unit, address, quantity)
 
−
 
−
Reads the content of a contiguous block of input registers in a MODBUS device, using function code '''0x04'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x04, the second to the byte count of the data part, and the data starts from the third byte.
 
−
 
−
If there is an error, the first byte is set to 0x84 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the starting address of the block of registers
 
−
* quantity: numeric - the quantity of registers you are reading (1 to 125).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusWriteMaskRegister ===
 
−
modbusWriteMaskRegister(name, unit, address, mask, bytes)
 
−
 
−
Writes a register with a bit mask in a MODBUS device, using function code '''0x16'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x16, the next two bytes to the mask and the last two to register value.
 
−
 
−
If there is an error, the first byte is set to 0x96 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* mask: numeric - the AND mask to be applied to the register
 
−
* bytes: numeric array - data to be written in the register, using big-endian encoding (the most significant byte is sent first).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusWriteMultipleCoils ===
 
−
modbusWriteMultipleCoils(name, unit, address, coils, bytes)
 
−
 
−
Writes multiple coils in a MODBUS device, using function code '''0x0F'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x0F, the next two to the data address of the first coil, and the last two to the number of coils written.
 
−
 
−
If there is an error, the first byte is set to 0x8F and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the coil’s address
 
−
* coils: numeric - the number of coils to be written
 
−
* bytes: numeric array - The requested ON/OFF states are specified by contents of the request data field, following the same data format defined in the Modbus specification for function 0x0F. A logical '1' in a bit position of the field requests the corresponding output to be ON. A logical '0' requests it to be OFF. The first byte represents coils with the lowest address, with the least significant bit addressing the lowest address coil.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusWriteMultipleRegisters ===
 
−
modbusWriteMultipleRegisters(name, unit, address, bytes)
 
−
 
−
Writes a block of contiguous registers in a MODBUS device, using function code '''0x10'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x10, the next two bytes to the starting address and the last two to the quantity of registers.
 
−
 
−
If there is an error, the first byte is set to 0x90 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the starting address of the block of registers
 
−
* bytes: numeric array - data to be written in the registers, using big-endian encoding (the most significant byte is sent first).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusWriteSingleCoil ===
 
−
modbusWriteSingleCoil(name, unit, address, value)
 
−
 
−
Writes a single coil in a MODBUS device, using function code '''0x05'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x05 and the last two to 0xFF00 if the coil is on, and 0x0000 if the coil is off.
 
−
 
−
If there is an error, the first byte is set to 0x85 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the coil’s address
 
−
* value: boolean - true to turn the coil on, false to turn it off.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
 
−
=== modbusWriteSingleRegister ===
 
−
modbusWriteSingleRegister(name, unit, address, bytes)
 
−
 
−
Writes a single register in a MODBUS device, using function code '''0x06'''.
 
−
 
−
Returns a standard response PDU.
 
−
 
−
If there is a correct response from the device, the first byte is set to 0x06 and the last two to register value.
 
−
 
−
If there is an error, the first byte is set to 0x86 and the second byte to the error code.
 
−
 
−
This function can be invoked passing a name parameter that represents either a predefined I/O Server, or the host name or IP address of the MODBUS gateway.
 
−
 
−
When using the gateways’s IP address or name, you can call this function to access gateways that are not defined as I/O servers.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* name: string - the id of the I/O Server as defined in hsyco.ini, or the host name or IP address of the MODBUS gateway
 
−
* unit: numeric - the MODBUS slave unit identifier (1 to 247)
 
−
* address: numeric - the register’s address
 
−
* bytes: numeric array - data to be written in the register, using big-endian encoding (the most significant byte is sent first).
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric array - response PDU.
 
−
 
−
== Network Services ==
 
−
 
−
=== ping ===
 
−
ping(host, timeout)
 
−
 
−
Sends an IP network ping command to the host specified.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* host: string - the hostname or IP address
 
−
* timeout: numeric - timeout in milliseconds.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* boolean - true if the host is reachable, false otherwise.
 
−
 
−
 
−
=== wakeOnLan ===
 
−
wakeOnLan(broadcast, address)
 
−
 
−
Sends a Wake on LAN command to the LAN specified in the broadcast.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* broadcast: string - the LAN broadcast address. For example “192.168.0.255”
 
−
* address: string - the IP or MAC address of the network interface. For example,  IP address “192.168.0.1” or MAC address “45-ab-44-00-00-ba”.
 
−
 
−
{{tip|If the IP address is used to identify the destination interface, HSYCO will try to automatically determine the corresponding MAC address, permanently saving this association27. So, when using the IP address, and only the first time this method is called, the device with have to be on to allow HSYCO to determine the MAC address.}}
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - 1 if successful, -1 if not.
 
−
 
−
 
−
== Public Announcement ==
 
−
 
−
The audioPlayFile() and audioPlayText() functions are used to play recorded audio files or text-to-speech messages.
 
−
 
−
Audio can be sent to the Web browser, the server’s audio line out connector, the internal speaker or audio out line of Axis cameras, and the speaker of SNOM phones or PA devices.
 
−
 
−
See the Public Announcement Appendix for additional information.
 
−
 
−
 
−
{| class="wikitable"  width="600"
 
−
! Audio Destination
 
−
! Description
 
−
|-
 
−
| width="150" | speaker
 
−
| the server’s audio line out connector
 
−
|-
 
−
| web
 
−
| the Web browser’s audio output<br>{{tip|this feature is supported only on Firefox and Chrome browsers}}
 
−
|-
 
−
| axis@camera id
 
−
| audio sent to an Axis camera, using the camera id defined in the Cameras parameter in hsyco.ini
 
−
|-
 
−
| snom@ip:port
 
−
| audio sent to SNOM phones and public announcement devices, to the multicast IP address and port specified (the IP address and port should be configured as multicast addresses on each phone)
 
−
|}
 
−
 
−
 
−
=== audioPlayFile ===
 
−
audioPlayFile(where, file)
 
−
 
−
Plays a pre-recorded audio file.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* where: string - the audio destination; see the table above
 
−
* file: string - the audio file name pathname, relative to HSYCO's root directory.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - the index of this message in the play back queue if successful, -1 in case of errors.
 
−
 
−
 
−
=== audioPlayText ===
 
−
audioPlayText(where, voice, text)
 
−
 
−
Converts a text message to audio using the installed text-to-speech engine, and plays the audio.
 
−
 
−
 
−
'''Parameters:'''
 
−
 
−
* where: string - the audio destination; see the table above
 
−
* voice: string - the voice name for the text-to-speech engine; see the Public Announcement Appendix for additional information
 
−
* text: string - the text message for text-to-speech conversion.
 
−
 
−
 
−
'''Returns:'''
 
−
 
−
* numeric - the index of this message in the play back queue if successful, -1 in case of errors.
 
−
 
−
== Serial Communication Ports ==
 
−
 
−
=== closeComm ===
 
−
closeComm(portName)
 
−
 
−
=== readComm ===
 
−
readComm(portName, len)
 
−
 
−
=== writeComm ===
 
−
writeComm(portName, data)
 
−
 
−
== Squeezebox ==
 
−
 
−
=== slimButton ===
 
−
slimButton(player, button)
 
−
 
−
=== slimCommand ===
 
−
slimCommand(player, command)
 
−
 
−
== User Interface ==
 
−
 
−
=== uiClear ===
 
−
uiClear(session)
 
−
 
−
=== uiGet ===
 
−
uiGet(id, attr)
 
−
 
−
=== uiSessionGet ===
 
−
uiSessionGet(session, id, attr)
 
−
 
−
=== uiSessionSet ===
 
−
uiSessionSet(session, id, attr, value)
 
−
 
−
=== uiSet ===
 
−
uiSet(id, attr, value)
 
−
 
−
=== user ===
 
−
user(name, param)
 

Latest revision as of 14:36, 13 October 2020

System Functions

DaylightEvent

DaylightEvent(day)

Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.


Parameters:

  • day: boolean - true at sunrise, false at sunset.

haActiveEvent

haActiveEvent(active)

Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.


Parameters:

  • active: boolean - true if the server is active, false if not active.

PowerEvent

PowerEvent(power)

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

Thanks to this function, you can alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.


Parameters:

  • power: numeric - the power level, in Watts.


Returns:

  • numeric - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.

Note The JavaScript PowerEvent function is always called, but its return value is used only when the Java PowerEvent callback is not defined or returned -1.

programTimerEvent

programTimerEvent(name)

Called when a program timer is activated.

Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.


Parameters:

  • name: string - program timer name.

SchedulerEvent

SchedulerEvent(groupname, schedulename)

This callback blocking function allows to call user methods at configurable intervals.

Schedules are defined using a group name and a schedule name.

Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.


Parameters:

  • groupname: string - the scheduler’s group name
  • schedulename: string - the scheduler’s name.

StartupEvent

StartupEvent()

Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.

SunPositionEvent

SunPositionEvent(azimuth, elevation)

Called when the Sun changes its height with respect to the horizon or its angle from true north.


Parameters:

  • azimuth: numeric - the current Sun angle from true north, in decimal degrees
  • elevation: numeric - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.


TimeEvent

TimeEvent(time)

Called every 60 seconds.

HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.

Note However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.


Parameters:

  • time: numeric - the current time in milliseconds.


varEvent

varEvent(name, value)

Triggered by the change of value of a program variable.


Parameters:

  • name: string - the variable name. Names are case-insensitive
  • value: string - the value to be assigned to the program variable.

Cameras

CameraCommandEvent

CameraCommandEvent(camerafunction, action, camera)

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, or to replace some or all of the standard PTZ commands with custom actions.


Parameters:

  • camerafunction: string - see the table below
  • action: string - see the table below
  • camera: string - the camera name.


Returns:

  • numeric - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.

Note The JavaScript CameraCommandEvent camerafunction is always called, but its return value is used only when the Java CameraCommandEvent callback is not defined or returned -1.

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

CameraMotionEvent

CameraMotionEvent(event, time)

Called when HSYCO starts recording video from a camera.

Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional): 

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

Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.


Parameters:

  • event: string - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter
  • time: numeric - the current time in milliseconds.

CameraViewEvent

CameraViewEvent(camera, active)

CameraViewEvent() is called on changes of the live view status of cameras.

When at least one web client is showing the live feed from a camera, the camera is marked as active.

When no live feed request is received for a several consecutive seconds, the camera is marked as not active.


Parameters:

  • camera: string - the camera name
  • active: boolean - true if active, false if not.

DMX

DmxEvent

DmxEvent(channel, state)

Called after changes to DMX-512 channels.


Parameters:

  • channel: numeric - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0
  • state: numeric - the new channel value, from 0 to 255.


DmxFilter

DmxFilter(channel, state, reverse)

This function allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.

This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.

Note This is a blocking function and is called when sending commands to the DMX gateway.

It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.


Parameters:

  • channel: numeric - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0
  • state: numeric - the unfiltered value of the channel, from 0 to 255
  • reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.


Returns:

  • numeric - the channel value that will be sent to the DMX gateway.

Note The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.


DmxStartupEvent

DmxStartupEvent(index)

Called 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, for example after communication errors.

It is safe, inside this function, to execute commands for the same DMX gateway.

Note This is a blocking function. The DMX driver will start after this function returns.


Parameters:

  • Index: numeric - number of the DMX bus, starting from 0.

Infrared Control

IREvent

IREvent(received, irtransid, event)

This function is called when an IRTrans receives or sends an IR command from its local IR database.

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


Parameters:

  • received: boolean - true if the command has been received by the IRTrans, false if sent
  • irtransid: numeric - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini
  • event: string - the string of the command received or issued, formatted as: "remote_name,command".

I/O Servers

IOEvent

IOEvent(name, value)

Triggered by the value change of any data point of an I/O server.


Parameters:

  • id: string - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system
  • value: string - the new value. For binary inputs or outputs, the returned values are “0” or “1”.


IOStartupEvent

IOStartupEvent(index)

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.

Note This is a blocking method. The I/O server driver will start after this function returns.


Parameters:

  • index: numeric - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.


Modbus

For detailed information about the Modbus protocol, and the response PDU formats, you should refer to the MODBUS Application Protocol Specification V1.1b documentation at: http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf


ModbusEvent

ModbusEvent(name, addr, unitid, pdu)

Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.

The returned byte array is used as the Modbus response PDU (function code and data).


Parameters:

  • name: string - the name of the Modbus Server I/O server
  • addr: string - IP address of the Modbus client
  • unitid: numeric - the unit id set in the received Modbus request
  • pdu: string - the request PDU data, in hexadecimal string format.

Returns:

  • string - the response PDU data, in hexadecimal string format.

Note The JavaScript ModbusEvent function is called only when the Java ModbusEvent callback is not defined or returned a null value.

Network Services

httpCallEvent

httpCallEvent(address, secure, query)

Called 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

This function shoud return a string, that will be sent as the 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.

If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.


Parameters:

  • address: string - the IP address of the HTTP client
  • secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server
  • query: string - the string following the ? in the URL path.


Returns:

  • string - the string to send as the text/plain answer to the HTTP client.

httpRawEvent

 httpRawEvent(host, secure, version, httpmethod, gzip, contenttype, query, session, userid, indata)

Called when the HSYCO HTTP server receives a GET or POST request with the following path: 

/x/raw

Note httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie

The application code inside the httpRawEvent() function should return a complete HTTP response (both headers and body).

If multiple httpRawEvent() callbacks or functions are defined, only one should write the HTTP response.


Parameters:

  • host: string - the IP address of the HTTP client
  • secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server
  • version: string - the HTTP version, as passed in the HTTP request header
  • httpmethod: string - the HTTP request's method, "GET", "POST" or "HEAD"
  • gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")
  • contenttype: string - the HTTP request's content type (value of Content-Type header)
  • query: string - the string following the ? in the URL path, or null if not present
  • session: string - the authenticated session id, or null
  • userid: string - the user id for requests having a valid authentication cookie, null otherwise
  • indata: string - the POST data, or an empty string for GET or HEAD requests.


Returns:

  • string - the application code should return the full HTTP response, including all headers.


Example: 

function httpRawEvent(host, secure, version, httpmethod, gzip, contenttype, query, session, userid, indata) : {
	messageLog("host: " + host);
	messageLog("secure: " + secure);
	messageLog("version: " + version);
	messageLog("httpmethod: " + httpmethod);
	messageLog("gzip: " + gzip);
	messageLog("contenttype: " + contenttype);
	messageLog("query: " + query);
	messageLog("session: " + session);
	messageLog("userid: " + userid);
	messageLog("in: " + indata);
	
	var outdata = httpmethod + " data echoed from host [" + host + "] : " + indata + "\r\n";
	var httpreply = version + " 200 OK\r\n";
	httpreply += "Server: HSYCO\r\n";
	httpreply += "Content-length: " + outdata.length + "\r\n";
	httpreply += "Content-type: text/plain\r\n";
	httpreply += "Cache-Control: no-store, no-cache\r\n\r\n";
	httpreply += outdata;
	return httpreply;
}

LocationEvent

LocationEvent(mac, ip, zoneId)

Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.


Parameters:

  • mac: string - the MAC address of the client
  • ip: string - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)
  • zoneId: numeric - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.

LocationBeaconEvent

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

LocationBeaconEvent(session, address, userid, zone, distance, background)

Called when the HSYCO App detects a change in the proximity of one of the configured beacons. See Beacons on HSYCO App for iOS for additional information.

There is no guarantee that the event would be fired.

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


Parameters:

  • session: string - session id string that uniquely identifies the client session
  • address: string - the beacon's address
  • userid: string - the user id
  • zone: string - the beacon's zone
  • distance: string - far, near, immediate or off
  • background: boolean - true if the app called the server while in background mode (app closed)

SysLogEvent

 SysLogEvent(address, log)

Called when the HSYCO SYSLOG server receives a log message from a network client.

Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.


Parameters:

  • address: string - the IP address of the SYSLOG client
  • log: string - SYSLOG log message.

PBX

PBXCallEvent

PBXCallEvent(host, caller, called)

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

If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.

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.


Parameters:

  • host: string - the IP address of the PBX server
  • caller: string - the caller number
  • called: string - the called number.


Returns:

  • boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.

Squeezebox

SlimPowerEvent

SlimPowerEvent(index, power)

Called when a Squeezebox player is turned on or off.


Parameters:

  • index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
  • power: numeric - 0: OFF, 1: ON.

SlimStatusEvent

SlimStatusEvent()

Called when a Squeezebox player changes its playback mode.


Parameters:

  • index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
  • status: numeric - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.


SlimVolumeEvent

SlimVolumeEvent(index, volume)

Called when a Squeezebox player changes its volume level.


Parameters:

  • index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
  • volume: numeric - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.


Timers and Schedulers

UserTimerEvent

UserTimerEvent(name, active)

Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.

It is also executed at the timer or scheduler’s rule deactivation.

This method must return a true value in order to make the timer or rule actually active and the associated actions executed.

Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.

In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.

This is a blocking method.


Parameters:

  • name: string - timer name or scheduler’s rule name
  • active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.


Returns:

  • boolean - true to confirm the timer event, false to block the event.


Note The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.


User Interface

pageEvent

pageEvent(address, session, userid, project, page)

Called when a Web client initially loads a project and when navigating between pages.

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.


Parameters:

  • address: string - the client’s IP address
  • session: string - session id string that uniquely identifies the client session
  • userid: string - the user id
  • project: string - project’s id
  • page: string - the page id, with the #landscape or #portrait suffix if the page has distinct orientation versions in the project.

loginEvent

loginEvent(address, session, userid)

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

Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.


Parameters:

  • address: string - the client’s IP address string in textual presentation
  • session: string - session id string that uniquely identifies the client session
  • userid: string - the user id.

logoutEvent

logoutEvent(address, session, userid, lock)

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

Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.


Parameters:

  • address: string - the client’s IP address string in textual presentation
  • session: string - session id string that uniquely identifies the client session
  • userid: string - the user id
  • lock: boolean - false when logging out; true when the user locks the user interface.

uiClearEvent

uiClearEvent(session)

Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).


Parameters:

  • session: string - session id string that uniquely identifies the client session.

userCommand

userCommand(session, userid, name, param)

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

This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.

If you want to navigate to a specific page when the button is pressed (it would be like pressing a Link object), return a string starting with "page:" followed by the page name; in this case, userCommand() will be called again when that popup or page is closed, with "/close" appended to param.

You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.

When the interface is loaded inside the HSYCO App (iOS or Android), you can send a specific command to the app by returning a string that starts with “app:“ followed by the command; the commands currently supported are “speech“, which enables the speech recognition, and “codescan“ which enables qr/bar code scanning.

Use "copy:<text>" to copy a text in the clipboard. In the HSYCO App you can also use "share:<text>" to open a popup with various options. This will behave like "copy" on browser.

Note As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.


Parameters:

  • session: string - a session id string that uniquely identifies the client session
  • userid: string - the user id
  • name: string - the name field of the user object
  • param: string - the param of the user object


Returns:

  • string - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.

Note The JavaScript userCommand function is alway called, but its return value is used only when the Java userCommand callback is not defined or returned null or an empty string.

userSubmit

userSubmit(session, userid, name, fields)

This function is similar to userCommand(session, userid, name, param).

When userSubmit() is defined, it will be called when a submit button is pressed, while userCommand() will continue to be called on user buttons.

userSubmit() provides a more convenient access to the values of multiple input fields in a form.

This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.

If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a link object), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called when that popup or page is closed, with "/close" appended to param.

You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.

Note As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.


Parameters:

  • session: string - a session id string that uniquely identifies the client session
  • userid: string - the user id
  • name: string - the id of the (submit!id) object
  • fields: array - the array of all input fields in the container where the (submit) object is located.


Returns:

  • string - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.

Note The JavaScript userSubmit function is alway called, but its return value is used only when the Java userCommand or userSubmit callback are not defined or returned null or an empty string.


Examples:

The following code shows how to retrieve all field names and values of a submitted form. 

function userSubmit(session, user, name, values) : {
	if (session.length > 0) {
		messageLog(user + ', ' + name + '=' + values);
		var keys = values.keySet().toArray();
		for (var i = 0; i < keys.length; i++) {
			messageLog(user + ', ' + keys[i] +  ' = ' + values.get(keys[i]));
		}
		return "";
	}
}

Create a project with a form and a few input fields in a container. Pressing the submit button should return something like this in the log file: 

2014.01.31 13:54:32.034 - staff, submit1={keypad1=344, date1=20140131, input1=this is a text field} 
2014.01.31 13:54:32.038 - staff, keypad1 = 344 
2014.01.31 13:54:32.039 - staff, date1 = 20140131 
2014.01.31 13:54:32.042 - staff, input1 = this is a text field 
2014.01.31 13:54:32.043 - WEB USER COMMAND [submit1]: input1@this is a text field@date1@20140131@keypad1@344 [OK]

WebRootRequestEvent

WebRootRequestEvent(addr, secure, useragent)

This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.

Note As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.


Parameters:

  • addr: string - the HTTP client’s address
  • secure: boolean - true if this is an HTTPS request
  • useragent: string - the Web browser’s user agent information.


Returns:

  • string - optional return string containing a valid absolute or relative URL


Examples:

The following code redirects any root HTTP request received by the HSYCO server to the manager page. 

function WebRootRequestEvent(addr, secure, useragent) : {
	return "hsycoserver/manager";
}
Retrieved from "https://wiki.hsyco.com/3.7/index.php?title=JavaScript_Callback_Functions_API&oldid=9183"