Difference between revisions of "Custom Drivers Command and Utility Methods API"
| (One intermediate revision by the same user not shown) | |||
| Line 254: | Line 254: | ||
The change is not logged. | 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.}} | ||
| Line 585: | Line 587: | ||
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. | 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.}} | ||
{{tip|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.}} | {{tip|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.}} | ||
Latest revision as of 18:20, 17 October 2022
Contents
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
void 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.
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.
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.
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.
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.
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.
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.
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; 0: 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.
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, 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:
- int - 1: message sent; 0: 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.
See the Audio and Public Announcement section for additional information.
| 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 |
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.
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.
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.
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.
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.
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.
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.
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 following user interface device objects: (button), (3button), (buttonicon), (buttonimage) and (dimmer).
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.
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.
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.
Session specific attributes values will override values set globally.
id is the unique name that identifies the object, specified in the index.hsm 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.hsm 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.
