Custom Drivers Command and Utility Methods API

Constants

LIGHT

LIGHT

Used for the function field of deviceSet().

AUTOM

AUTOM

Used for the function field of deviceSet().

DIMMER

DIMMER

Used for the function field of deviceSet().

BINARY

BINARY

Used for the function field of deviceSet().

System Functions

dateSet

boolean dateSet(int year, int month, int day, int hour, int minute, int second)

Sets the HSYCO Server operating system’s clock and hardware clock, in the local time zone.

Parameters:

• year: int - the year, greater than 1900
• month: int - the month, between 1-12
• day: int - the day, between 1-31
• hour: int - the hour, between 0-23
• minute: int - the minute, between 0-59
• second: int - the second, between 0-59.

Returns:

• boolean - true if successful, false if not.

getNextSunrise

long getNextSunrise(long now, boolean 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: long - 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:

• long - the next sunrise time in milliseconds since midnight, January 1, 1970 UTC.

getNextSunset

long getNextSunset(long now, boolean 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: long - 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:

• long - the next sunset time in milliseconds since midnight, January 1, 1970 UTC.

haActiveState

boolean 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

void haActive(boolean 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.

isVerboseLog

boolean isVerboseLog()

Checks if verbose log is enabled.

Returns:

• boolean - returns true when verbose log is enabled.

sleep

void sleep(long millis)

Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.

Parameters:

• millis: long - the length of time to sleep in milliseconds.

varGet

String varGet(String 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

void varSet(String name, String 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.

Driver Control

init

boolean init(String name)

Must be called once inside the init() callback.

public class Driver extends driverBase {

public boolean init(String name, HashMap<String, String> config) {

super.init(name); // do not remove
		return true;
	}
}

Parameters:

• name: String - the driver's identifier.

Driver I/O

ioSet

boolean ioSet(String name, String value)

Writes back a command to this driver.

This method should only be used to push back a command to the command queue, to be processed again after all currently pending commands.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

Returns:

• true if the I/O Server command is successfully queued or executed (for synchronous commands), false if the queue is full or command failed for any other reason

ioWrite

void ioWrite(String name, String value)

Writes a new value to a data point.

Events will be triggered only the new value is different from the current one.

note

Note that, in order to optimise both the driver and HSYCO's overall performance, you should call ioWrite() only when an actual change to a datapoint has happened. Calling ioWrite() when the value has not changed since the previous call will not have any functional effects, as HSYCO checks for changes anyways, but will add some overhead.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

ioWriteNoLog

void ioWriteNoLog(String name, String value)

Writes a new value to a data point.

Events will be triggered only the new value is different from the current one.

The change is not logged.

note

Note that, in order to optimise both the driver and HSYCO's overall performance, you should call ioWriteNoLog() only when an actual change to a datapoint has happened. Calling ioWriteNoLog() when the value has not changed since the previous call will not have any functional effects, as HSYCO checks for changes anyways, but will add some overhead.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

ioWriteNoEvents

void ioWriteNoEvents(String name, String value)

Writes a new value to a data point.

Events are not triggered.

note

Note that, in order to optimise both the driver and HSYCO's overall performance, you should call ioWriteNoEvents() only when an actual change to a datapoint has happened. Calling ioWriteNoEvents() when the value has not changed since the previous call will not have any functional effects, as HSYCO checks for changes anyways, but will add some overhead.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

ioWriteNoEventsNoLog

void ioWriteNoEventsNoLog(String name, String value)

Writes a new value to a data point.

Events are not triggered.

The change is not logged.

note

Note that, in order to optimise both the driver and HSYCO's overall performance, you should call ioWriteNoEventsNoLog() only when an actual change to a datapoint has happened. Calling ioWriteNoEventsNoLog() when the value has not changed since the previous call will not have any functional effects, as HSYCO checks for changes anyways, but will add some overhead.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

ioWriteForced

void ioWriteForced(String name, String value)

Writes a new value to a data point.

Events are always triggered, even if there is no change to the value.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

ioWriteForcedNoLog

void ioWriteForcedNoLog(String name, String value)

Writes a new value to a data point.

Events are always triggered, even if there is no change to the value.

The change is not logged.

Parameters:

• name: String - the data point name, without the I/O server id prefix
• value: String - the new value.

Log

errorLog

void errorLog(String message)

Generates an error message in the daily log file.

Parameters:

• message: String - the text of the error message.

fileLog

void fileLog(String pathname, String 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

void messageLog(String message)

Generates an information message in the daily log file.

Parameters:

• message: String - the text of the error message.

Mail

sendMail - simple text message

int sendMail(String to, String from, String subject, String body)

Sends a multipart email message, mixing text and multiple images from cameras, live or recorded.

HSYCO SERVER sends the mail either directly to the recipient’s domain mail server if the SmtpName parameter is not defined in hsyco.ini, or using a specific email account with user authentication and traffic encryption if the SMTP server and account parameters are set.

If the email message is sent directly to the recipient’s domain mail server, you need to ensure that the mail server accepts mail to the destination address being sent with the from address and the public IP of the HSYCO SERVER.

note

HSYCO does not automatically retry sending the message if the destination mail server is not available when the send mail function is called.

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 - the message text.

Returns:

• int - 1: message sent:::note

message not sent; -1: other errors, including address errors.

sendMail - multi-part message

int sendMail(String to, String from, String subject, Vector<String> body)

Sends a multipart email message, mixing text and multiple images from cameras, live or recorded.

HSYCO SERVER sends the mail either directly to the recipient’s domain mail server if the SmtpName parameter is not defined in hsyco.ini, or using a specific email account with user authentication and traffic encryption if the SMTP server and account parameters are set.

If the email message is sent directly to the recipient’s domain mail server, you need to ensure that the mail server accepts mail to the destination address being sent with the from address and the public IP of the HSYCO SERVER.

note

HSYCO does not automatically retry sending the message if the destination mail server is not available when the send mail function is called.

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: Vector<String> - the message body. To send an ordinary text, just fill the vector with the desired text strings. To send an image, append strings with the following format: cam:cameraname[:seconds_back[:frames_back]]. For example, cam:camera1 sends a live frame from the camera called camera1
camera:camera1:0 sends the last recorded frame; cam:door:2 sends a frame that was recorded two seconds before the last recorded frame and cam:door:2:5 sends a frame that is 5 frames earlier than the one recorded two seconds before the last recording. To send files as attachments, use the following format: file:<file name>. The file path is relative to the HSYCO root directory.

Returns:

• int - 1: message sent:::note

message not sent; -1: other errors, including address errors.

Network Services

urlGet

String urlGet(String url, String user, String password)

Sends a GET HTTP or HTTPS request.

The request has a 10 sec. connection timeout, and 30 sec. response timeout.

The HTTP basic or digest access authentication methods are supported.

Parameters:

• url: String - a full url, including the mandatory http:// or https:// query scheme and optional query string
• user: String - the user for HTTP authentication (set to null if authentication is not needed)
• password: String - the password for HTTP authentication (set to null if authentication is not needed).

Returns:

• String - a string with the HTTP return code, followed by ":" and the response content, or null if a generic error occurred (including malformed URLs).

urlPost

String urlPost(String url, String contenttype, String data, String user, String password)

Sends a POST HTTP or HTTPS request.

The request has a 10 sec. connection timeout, and 30 sec. response timeout.

The HTTP basic or digest access authentication methods are supported.

Note that if contenttype is set to null, you will have to pass all required HTTP headers in the data parameter, including Content-Type and Content-Length, and the mandatory empty line (CRLF only) between the headers and message body. If contenttype is set to the appropriate content type, all headers will be set internally by urlPost() and the data parameter should only contain the actual message body, without the leading empty line, that is added automatically.

Parameters:

• url: String - a full url, including the mandatory http:// or https:// query scheme and optional query string
• contenttype: String - the MIME content type of the data being sent (e.g. "application/x-www-form-urlencoded")
• data: String - the data being sent with the POST request
• user: String - the user for HTTP authentication (set to null if authentication is not needed)
• password: String - the password for HTTP authentication (set to null if authentication is not needed).

Returns:

• String - a string with the HTTP return code, followed by ":" and the response content, or null if a generic error occurred (including malformed URLs).

Public Announcement

The audioPlay() 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, SNOM's phones or PA devices, and I/O servers with audio playback capabilities.

Audio Destination	Description
speaker	the server’s audio line out connector
web	the Web browser’s audio output 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
axis@host name	audio sent to an Axis geric audio device. Use the host name or IP address of the device. The device must allow anonymous commands via HTTP on the default port 80
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)
io@I/O server id[.zone id]	audio sent to I/O servers with audio playback capabilities, e.g. the Sonos I/O server

Audio and Public Announcement

HSYCO can play audio for public announcement, as pre-recorded files or using a text-to-speech engine that converts text to audio. 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, SNOM's phones or PA devices, and I/O servers with audio capabilities.

When playing a pre-recorded audio file, the file format should be supported by the audio destination you are using.

Destination	Audio Formats
speaker	most of the audio formats that are supported by Linux or Mac OS X should work
web	use an audio format that is supported by the target Web browser (only the most recent versions of Chrome and Firefox are supported)
axis	use uLaw, 8 KHz, 8 bit, mono, WAV files
snom	use uLaw, 8 KHz, 8 bit, mono, WAV files
io	use an audio format that is supported by the target I/O server

The Text-to-Speech Engine

HSYCO uses different text-to-speech engines on Linux and Mac OS X.

On Linux, the default engine is eSpeak, with the possibility to use the optional Acapela engine that offers a wide selection of very high quality voices.

note

Go to http://espeak.sourceforge.net/ for more information about the eSpeak software.

On Mac OS X, HSYCO uses the integrated text-to-speech service and all its voices.

eSpeak

When using eSpeak, set the voice name to any of its supported voices.

Some voices are listed in the following table, but check the on-line documentation for the complete list.

Voice	Description
voice:en	English
voice:en-us	American English
voice:it	Italian
voice:fr	French

The AudioServerSpeed and AudioServerVolume configuration parameters are supported.

The AudioServerSpeed default is 100: higher numbers increase the speech speed.

The AudioServerVolume default is 10, and should be set between 0 and 20, where 20 generates an audio file with the greatest possible amplitude.

Acapela

When using Acapela, it is mandatory to set the AudioServerTTS configuration parameter to acapela:

AudioServerTTS = acapela

Moreover, set the voice name to any of its installed voices.

When playing to the SNOM phones, use 8k and 22k voices.

When playing to Axis cameras, use 8kmu voices.

Mac OS X

HSYCO supports text-to-speech on Mac OS X 10.7 or later, using the integrated text-to-speech engine.

You can install additional voices through the speech system preferences panel.

Voice names in HSYCO are the same names you see in this panel.

note

With OS X 10.9, the text-to-speech engine needs to be executed using an operating system account with voices properly defined in the user's Preferences panel. Because of this, HSYCO needs to know the user name to play a specific voice, and you should prefix the voice name with the user id and a colon character, like user_id:voice Text-to-speech will not work otherwise.

note

The text-to-speech engine works only if a user's desktop is open. It is recommended to configure OSX with automatic login.

The AudioServerSpeed and AudioServerQuality configuration parameters are supported.

AudioServerSpeed is a positive number that represents speech rate, in words per minute.

AudioServerQuality sets the audio converter quality level between 0 (lowest) and 127 (highest).

audioPlay - file

int audioPlay(String where, File file)

Plays a pre-recorded audio file.

Parameters:

• where: String - the audio destination; see the table above
• File: String - the audio file, relative to HSYCO's root directory.

Returns:

• int - the index of this message in the play back queue if successful, -1 in case of errors.

audioPlay - text to speech

int audioPlay(String where, String voice, String 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 [[Audio and Public Announcement]] section for additional information
• text: String - the text message for text-to-speech conversion.

Returns:

• int - the index of this message in the play back queue if successful, -1 in case of errors.

Serial Communication Ports

closeComm

void closeComm(String portname)

Closes a serial port connection when the serial port is defined ad a server type, and is ignored otherwise.

note

When used with serial servers having a fail-over configuration, this method forces a reconnect at the next call of readComm() or writeComm(), so that a switch between the fail-over IPs would happen if the current IP is not responding.

Parameters:

• portname: String - the name of the communications port, as defined in the CommPorts parameter in hsyco.ini.

readComm

String readComm(String portname, int len)

Reads a sequence of bytes from a communication port.

The number of bytes read depends on the availability of data in the buffer of the communication port, until the maximum number specified in the len parameter.

note

There is a 2 seconds default time-out on reads. If the buffer is empty, this function will wait until the time-out expires before returning.

If len is set to 0, the function doesn’t return data, but it empties the communication port’s buffer from older data.

note

If both verboseLog and userLog are true, the full trace of received and sent bytes is written to the log file.

Parameters:

• portname: String - the name of the communications port, as defined in the CommPorts parameter in hsyco.ini
• len: int - maximum number of bytes to be read from the port, or 0 to empty the buffer without reading data.

Returns:

• String - null in case of errors, a string with the hexadecimal representation of the received byte sequence, or an empty string if the buffer of the incoming data is empty. For example 45AB4400BA.

readCommBytes

byte[] readCommBytes(String portname, int len)

Reads a sequence of bytes from a communication port.

The number of bytes read depends on the availability of data in the buffer of the communication port, until the maximum number specified in the len parameter.

note

There is a 2 seconds default time-out on reads. If the buffer is empty, this function will wait until the time-out expires before returning.

If len is set to 0, the function doesn’t return data, but it empties the communication port’s buffer from older data.

note

If both verboseLog and userLog are true, the full trace of received and sent bytes is written to the log file.

Parameters:

• portname: String - the name of the communications port, as defined in the CommPorts parameter in hsyco.ini
• len: int - maximum number of bytes to be read from the port, or 0 to empty the buffer without reading data.

Returns:

• byte[] - null in case of errors, a byte array of the received byte sequence, or an empty byte array if the incoming data buffer is empty.

writeComm

int writeComm(String portname, String data)

Sends a sequence of bytes to a communication port.

note

If both verboseLog and userLog are true, the full trace of received and sent bytes is written to the log file.

Parameters:

• portname: String - the name of the communications port, as defined in the CommPorts parameter in hsyco.ini
• data: String - a string with the hexadecimal representation of the sequence of bytes to be sent. For example 45AB4400BA.

Returns:

• int - the number of bytes sent if successful, or 0 in case of errors.

writeCommBytes

int writeCommBytes(String portname, byte[] data)

Sends a sequence of bytes to a communication port.

note

If both verboseLog and userLog are true, the full trace of received and sent bytes is written to the log file.

Parameters:

• portname: String - the name of the communications port, as defined in the CommPorts parameter in hsyco.ini
• data: byte[] - the bytes to be sent.

Returns:

• int - the number of bytes sent if successful, or 0 in case of errors.

User Interface

deviceSet

void deviceSet(int function, String address, String value, String comment)

Used to set the current state of the button object.

It should be called inside the init() callback to set the initial state of all user interface device objects and to have systemtopo.txt automatically updated with new devices after init() ends successfully. It should also be called inside the loop() callback to update the run-time state of the objects.

note

Note that, in order to optimise both the driver and HSYCO's overall performance, you should call deviceSet() only when an actual change of value has happened. Calling deviceSet() when the value has not changed since the previous call will not have any functional effects, as HSYCO checks for changes anyways, but will add some overhead.

note

When implementing a driver that directly supports device objects, you should normally call both deviceSet() and ioWrite() to set the user interface objects and also a corresponding I/O data point.}}

Parameters:

• function: int - the function name. Use LIGHT, AUTOM, DIMMER or BINARY
• address: String - the address (or identifier) of the user interface device object, without the I/O server id prefix
• value: String - the data point value. null sets the data point value to "unknown"
• comment: String - a description text that will be written to systemtopo.txt at the end of the initialization process, when still inside the init() callback, or null for normal operation (after the initialization phase).

enableSystemtopoDiscovery

void enableSystemtopoDiscovery()

Enables the systemtopo.txt update process.

note

This method should only be called from the init() callback code, and should be followed by deviceSet() calls before leaving the init() callback.

uiClear

void uiClear(String session)

Removes all session specific UI object attributes set with uiSet().

uiClear() is also implicitly called after the client session inactivity timeout expires.

Parameters:

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

uiSet - session

void uiSet(String session, String id, String attr, String value)

Changes the dynamic attributes of identified user interface (UI) objects for a specific client session.

note

Session specific attributes values will override values set globally.

id is the unique name that identifies the object, specified in the index.xml file with the extension !id after the object type.

Parameters:

• session: String - session id string that uniquely identifies the client session.
• id: String - object id
• attr: String - attribute name
• value: String - attribute value.

uiSet - global

void uiSet(String id, String attr, String value)

Changes the dynamic attributes of the identified user interface (UI) objects.

id is the unique name that identifies the object, specified in the index.xml file with the extension !id after the object type.

Parameters:

• id: String - object id
• attr: String - attribute name
• value: String - attribute value.

user

void user(String name, String param)

Triggers a USER event, the execution of the userCommand() JavaScript function and of the userCommand() Java method.

It can be used as a calling mechanism between Java, JavaScript and EVENTS.

Parameters:

• name: String - the name parameter, passed to userCommand() and the USER event
• param: String -the param parameter, passed to userCommand() and the USER event.