JavaScript Callback Functions API

Callback Functions

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 method it is possible to 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.

 The JavaScript PowerEvent 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 the EVENTS.

Parameters:

• name: string - program timer name.

SchedulerEvent

SchedulerEvent(groupname, schedulename)

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

You define schedules 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.

 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(function, 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:

• function: 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.

 The JavaScript CameraCommandEvent return value is used only when the Java CameraCommandEvent callback is not defined or returned -1.

icon function action focus far focus near zoom tele zoom wide move left move right move up move down move stop

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

 This is a blocking method 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.

 The JavaScript DmxFilter 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 method, to execute command methods for the same DMX gateway.

 This is a blocking method. 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 method is called when an IRTrans receives or sends an IR command from its local IR database.

Parameters:

• received: boolean - true if the command has been received21 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.

 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.

Network Location Services

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.

Modbus

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.

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