Difference between revisions of "Java Command and Utility Methods API"
(82 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | + | [[Category:Java]] | |
− | |||
These methods are used to control field devices, to acquire status information and to execute general utility functions. | These methods are used to control field devices, to acquire status information and to execute general utility functions. | ||
− | + | If the userLog option is enabled in the system general settings, commands that execute relevant functions will be logged in the daily log file: | |
2011.07.30 11:39:16.133 - USERCODE: method - parameter | 2011.07.30 11:39:16.133 - USERCODE: method - parameter | ||
Line 10: | Line 9: | ||
=== dateSet === | === dateSet === | ||
− | dateSet(year, month, day, hour, minute, second) | + | static 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. | Sets the HSYCO Server operating system’s clock and hardware clock, in the local time zone. | ||
Line 17: | Line 16: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * year: | + | * year: int - the year, greater than 1900 |
− | * month: | + | * month: int - the month, between 1-12 |
− | * day: | + | * day: int - the day, between 1-31 |
− | * hour: | + | * hour: int - the hour, between 0-23 |
− | * minute: | + | * minute: int - the minute, between 0-59 |
− | * second: | + | * second: int - the second, between 0-59. |
Line 28: | Line 27: | ||
* boolean - true if successful, false if not. | * boolean - true if successful, false if not. | ||
− | |||
=== getNextSunrise === | === getNextSunrise === | ||
− | getNextSunrise(now, withoffset) | + | static long getNextSunrise(long now, boolean withoffset) |
Computes the time of the next sunrise after the time set in the now parameter. | Computes the time of the next sunrise after the time set in the now parameter. | ||
Line 40: | Line 38: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * now: | + | * 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). | * 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). | ||
Line 46: | Line 44: | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * long - the next sunrise time in milliseconds since midnight, January 1, 1970 UTC. |
− | |||
=== getNextSunset === | === getNextSunset === | ||
− | getNextSunset(now, withoffset) | + | static long getNextSunset(long now, boolean withoffset) |
Computes the time of the next sunset after the time set in the now parameter. | Computes the time of the next sunset after the time set in the now parameter. | ||
Line 59: | Line 56: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * now: | + | * 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). | * 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). | ||
Line 65: | Line 62: | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * long - the next sunset time in milliseconds since midnight, January 1, 1970 UTC. |
− | |||
=== haActiveState === | === haActiveState === | ||
− | haActiveState() | + | static 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. | 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. | ||
Line 79: | Line 75: | ||
* boolean - high availability current state. | * boolean - high availability current state. | ||
− | |||
=== haActive === | === haActive === | ||
− | haActive(active) | + | static void haActive(boolean active) |
Force a master HSYCO server to become inactive, or return to the active state. | Force a master HSYCO server to become inactive, or return to the active state. | ||
Line 92: | Line 87: | ||
* 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. | * 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 === | ||
− | isDaylight() | + | static boolean isDaylight() |
Returns the day or night status at present time. | Returns the day or night status at present time. | ||
Line 105: | Line 99: | ||
* boolean - true during the day, false at night. | * boolean - true during the day, false at night. | ||
− | |||
=== powerSet === | === powerSet === | ||
− | powerSet(power) | + | static void powerSet(int power) |
Sets the electric power state variable. | Sets the electric power state variable. | ||
Line 119: | Line 112: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * power: | + | * power: int - the power in Watt units. |
− | |||
=== programTimerClear === | === programTimerClear === | ||
− | programTimerClear(name) | + | static void programTimerClear(String name) |
Cancels a program timer. | Cancels a program timer. | ||
Line 130: | Line 122: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the program timer name. |
− | |||
=== programTimerRepeat === | === programTimerRepeat === | ||
− | programTimerRepeat(name, seconds) | + | static void programTimerRepeat(String name, int seconds) |
Sets a program timer that is executed repeatedly with an interval equal to the specified number of seconds. | Sets a program timer that is executed repeatedly with an interval equal to the specified number of seconds. | ||
Line 143: | Line 134: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the program timer name |
− | * seconds: | + | * seconds: int - the interval in seconds of the timer’s execution. |
− | |||
=== programTimerReset === | === programTimerReset === | ||
− | programTimerReset(name, seconds) | + | static void programTimerReset(String name, int seconds) |
Sets a program timer to be executed after the specified number of seconds. | Sets a program timer to be executed after the specified number of seconds. | ||
Line 157: | Line 147: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the program timer name |
− | * seconds: | + | * seconds: int - the number of seconds to the timer’s execution. |
− | |||
=== programTimerSet === | === programTimerSet === | ||
− | programTimerSet(name, seconds) | + | static void programTimerSet(String name, int seconds) |
Sets a program timer to be executed after the specified number of seconds. | Sets a program timer to be executed after the specified number of seconds. | ||
Line 170: | Line 159: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the program timer name |
− | * seconds: | + | * seconds: int - the number of seconds to the timer’s execution. |
− | |||
=== schedulerRegister === | === schedulerRegister === | ||
− | schedulerRegister(groupname, schedulename, interval) | + | static void schedulerRegister(String groupname, String schedulename, int interval) |
This function registers a new scheduled callback. | This function registers a new scheduled callback. | ||
Line 182: | Line 170: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * groupname: | + | * groupname: String - the group name |
− | * schedulename: | + | * schedulename: String - the schedule name |
− | * interval: | + | * interval: int - interval in milliseconds. |
− | |||
=== schedulerRemove === | === schedulerRemove === | ||
− | schedulerRemove(groupname, schedulename) | + | static void schedulerRemove(String groupname, String schedulename) |
Deletes a schedule. | Deletes a schedule. | ||
Line 195: | Line 182: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * groupname: | + | * groupname: String - the group name |
− | * schedulename: | + | * schedulename: String - the schedule name. |
− | |||
=== sleep === | === sleep === | ||
− | sleep(millis) | + | static void sleep(long millis) |
Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. | Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. | ||
Line 207: | Line 193: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * millis: | + | * millis: long - the length of time to sleep in milliseconds. |
− | |||
=== varGet === | === varGet === | ||
− | varGet(name) | + | static String varGet(String name) |
Returns the value of a program variable, or null if no variable with the given name has been defined. | Returns the value of a program variable, or null if no variable with the given name has been defined. | ||
Line 224: | Line 209: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the variable name. Names are case-insensitive. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * String - the current value of the program variable. |
− | |||
=== varSet === | === varSet === | ||
− | varSet(name, value) | + | static void varSet(String name, String value) |
Sets a program variable to the value parameter. | Sets a program variable to the value parameter. | ||
Line 246: | Line 230: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the variable name. Names are case-insensitive |
− | * value: | + | * value: String - the value to be assigned to the program variable. |
− | |||
== Cameras == | == Cameras == | ||
Line 305: | Line 288: | ||
* camera: String - the camera name | * camera: String - the camera name | ||
* source: String - a string used to generate a log message, to identify the source that triggered the recording | * source: String - a string used to generate a log message, to identify the source that triggered the recording | ||
− | * seconds: int - recording time in seconds. If set | + | * seconds: int - recording time in seconds. If set to 0, stops the current recording. |
=== cameraRecTriggerFull === | === cameraRecTriggerFull === | ||
Line 317: | Line 300: | ||
* camera: String - the camera name | * camera: String - the camera name | ||
* source: String - a string used to generate a log message, to identify the source that triggered the recording | * source: String - a string used to generate a log message, to identify the source that triggered the recording | ||
− | * seconds: int - recording time in seconds. If set | + | * seconds: int - recording time in seconds. If set to 0, stops the current recording. |
== Data Logger == | == Data Logger == | ||
=== dataLoggerClear === | === dataLoggerClear === | ||
− | dataLoggerClear(name) | + | static boolean dataLoggerClear(String name) |
Permanently deletes all historical data of the specified data logger. | Permanently deletes all historical data of the specified data logger. | ||
Line 328: | Line 311: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - data logger name. |
Line 334: | Line 317: | ||
* boolean - true if successful, false if not. | * boolean - true if successful, false if not. | ||
− | |||
=== dataLoggerOptions === | === dataLoggerOptions === | ||
− | dataLoggerOptions(name, param, value) | + | static boolean dataLoggerOptions(String name, String param, String value) |
Sets a specific option for the specified data logger. | Sets a specific option for the specified data logger. | ||
Line 345: | Line 327: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - data logger name |
− | * param: | + | * param: String - option to be set (“origin” is the only option you can currently set with this method) |
− | * value: | + | * value: String - value for the specified option. |
Line 353: | Line 335: | ||
* boolean - true if successful, false if not. | * boolean - true if successful, false if not. | ||
− | |||
=== dataLoggerSave === | === dataLoggerSave === | ||
− | dataLoggerSave( | + | static boolean dataLoggerSave(String action, String[] names, String path, boolean timestamp) |
Creates or updates a CSV file containing the data processed by the specified data loggers. | Creates or updates a CSV file containing the data processed by the specified data loggers. | ||
− | The possible | + | Also used to import and export of raw data logger data in CSV format. See [[Data_Loggers#CSV_Import.2FExport|Data Loggers CSV Import/Export]] for additional information. |
+ | |||
+ | The possible actions are: | ||
* log: append the last acquired value by the data logger to the specified file | * 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. | + | * stat: updates the specified file with the currently gathered data by the specified data logger |
+ | * csvwrite: create a CSV file with all raw data of a data logger | ||
+ | * csvread: insert, update or delete records to a data logger | ||
+ | * csvreadover: insert records to a data logger, replacing all existing data. | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * | + | * action: String - set to "log", "stat", "csvwrite", "csvread" or "csvreadover" |
− | * names: | + | * names: String[] - data logger names |
− | * path: | + | * path: String - path of the file to be created |
− | * timestamp: boolean - if true and the | + | * timestamp: boolean - if true and the action is log adds a timestamp column in the CSV file for the logged values. |
Line 376: | Line 362: | ||
* boolean - true if successful, false if not. | * boolean - true if successful, false if not. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== dataLoggerUpdate === | === dataLoggerUpdate === | ||
− | dataLoggerUpdate(name, value) | + | static boolean dataLoggerUpdate(String name, Double value) |
Supplies the specified data logger with a new value to be processed. | Supplies the specified data logger with a new value to be processed. | ||
Line 395: | Line 371: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - data logger name |
− | * value: | + | * value: Double - value to be processed. Setting value to null, with counter data loggers only, resets the internal delta baseline. |
Line 402: | Line 378: | ||
* boolean - true if successful, false if not. | * boolean - true if successful, false if not. | ||
− | |||
== DMX == | == DMX == | ||
Line 598: | Line 573: | ||
=== ioServersRestart === | === ioServersRestart === | ||
− | ioServersRestart(name) | + | static int ioServersRestart(String name) |
Restarts an I/O server that was previously stopped. | Restarts an I/O server that was previously stopped. | ||
Line 609: | Line 584: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the I/O server name. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - 1 if successful, -1 if the server name is not defined. |
− | |||
=== ioServersStop === | === ioServersStop === | ||
− | ioServersStop(name) | + | static int ioServersStop(String name) |
Stops the execution of an I/O server. | Stops the execution of an I/O server. | ||
Line 627: | Line 601: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the I/O server name. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - 1 if successful, -1 if the server name is not defined. |
− | |||
=== ioSet === | === ioSet === | ||
Line 652: | Line 625: | ||
=== leakDetectorClear === | === leakDetectorClear === | ||
− | leakDetectorClear(name) | + | static void leakDetectorClear(String name) |
Clears the detector’s internal state. | Clears the detector’s internal state. | ||
Line 661: | Line 634: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - leak detector name. |
− | |||
=== leakDetectorOptions === | === leakDetectorOptions === | ||
− | leakDetectorOptions(name, param, value) | + | static void leakDetectorOptions(String name, String param, String 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 detector’s logic uses two parameters to set its sensitivity and time base. You can change the defaults to adapt to your specific conditions. | ||
Line 682: | Line 654: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - leak detector name |
− | * param: | + | * param: String - set to “period” or “deviation” |
− | * value: | + | * value: String - the period or deviation value. |
− | |||
=== leakDetectorUpdate === | === leakDetectorUpdate === | ||
− | leakDetectorUpdate(name, value) | + | static int leakDetectorUpdate(String name, double value) |
Calls the leak detector passing the current liters counter value. | Calls the leak detector passing the current liters counter value. | ||
Line 695: | Line 666: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - leak detector name |
− | * value: | + | * value: double - the flow counter value. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - -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 == | == Log == | ||
=== errorLog === | === errorLog === | ||
− | errorLog(message) | + | static void errorLog(String message) |
Generates an error message in the daily log file. | Generates an error message in the daily log file. | ||
Line 713: | Line 684: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * message: | + | * message: String - the text of the error message. |
− | |||
=== fileLog === | === fileLog === | ||
− | fileLog(pathname, message) | + | static void fileLog(String pathname, String message) |
Appends a generic text message at the end of a file. | Appends a generic text message at the end of a file. | ||
Line 724: | Line 694: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * pathname: | + | * 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: | + | * message: String - the message that will be appended at the last line of the text file. |
− | |||
=== messageLog === | === messageLog === | ||
− | messageLog(message) | + | static void messageLog(String message) |
Generates an information message in the daily log file. | Generates an information message in the daily log file. | ||
Line 736: | Line 705: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * message: | + | * message: String - the text of the error message. |
− | |||
== Mail == | == Mail == | ||
− | === sendMail === | + | === sendMail - simple text message === |
− | sendMail(to, from, subject, body) | + | static 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. | Sends a multipart email message, mixing text and multiple images from cameras, live or recorded. | ||
Line 751: | Line 719: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * to: | + | * 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: | + | * from: String - a valid email address to be used as the sender address |
− | * subject: | + | * subject: String - the message subject |
− | * body: | + | * body: String - the message text. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - 1: message sent; 0: message not sent; -1: other errors, including address errors. |
+ | |||
+ | === sendMail - multi-part message === | ||
+ | static 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. | ||
− | + | {{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: 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. | ||
== 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] | ||
+ | |||
=== modbusReadCoils === | === modbusReadCoils === | ||
Line 779: | Line 762: | ||
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 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. | ||
+ | |||
+ | {{tip|<nowiki>The coils in the response message are packed as one coil per bit of the data field. Status is indicated as 1= ON and 0= OFF. The LSB of the first data byte contains the output addressed in the query. The other coils follow toward the high order end of this byte, and from low order to high order in subsequent bytes. | ||
+ | If the returned output quantity is not a multiple of eight, the remaining bits in the final data byte will be padded with zeros (toward the high order end of the byte). The byte count field in the response PDU specifies the quantity of complete bytes of data.</nowiki>}} | ||
+ | |||
If there is an error, the first byte is set to 0x81 and the second byte to the error code. | If there is an error, the first byte is set to 0x81 and the second byte to the error code. | ||
Line 807: | Line 794: | ||
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 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. | ||
+ | |||
+ | {{tip|<nowiki>The discrete inputs in the response message are packed as one input per bit of the data field. Status is indicated as 1= ON; 0= OFF. The LSB of the first data byte contains the input addressed in the query. The other inputs follow toward the high order end of this byte, and from low order to high order in subsequent bytes. | ||
+ | If the returned input quantity is not a multiple of eight, the remaining bits in the final data byte will be padded with zeros (toward the high order end of the byte). The byte count field of the response PDU specifies the quantity of complete bytes of data.</nowiki>}} | ||
+ | |||
If there is an error, the first byte is set to 0x82 and the second byte to the error code. | If there is an error, the first byte is set to 0x82 and the second byte to the error code. | ||
Line 882: | Line 873: | ||
* byte[] - response PDU. | * byte[] - response PDU. | ||
+ | |||
+ | === modbusReadWriteMultipleRegisters === | ||
+ | static byte[] modbusReadWriteMultipleRegisters(String name, int unit, int readaddress, int readquantity, int writeaddress, byte[] bytes) | ||
+ | |||
+ | Writes a block of contiguous registers in a MODBUS device, then reads the content of a contiguous block of holding registers, using function code '''0x17'''. | ||
+ | |||
+ | Returns a standard response PDU. | ||
+ | |||
+ | If there is a correct response from the device, the first byte is set to 0x17, 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 0x97 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: int - the MODBUS slave unit identifier (1 to 247) | ||
+ | * readaddress: int - the starting address of the block of registers to read | ||
+ | * readquantity: int - the quantity of registers you are reading (1 to 125) | ||
+ | * writeaddress: int - the starting address of the block of registers to write | ||
+ | * bytes: byte[] - data to be written in the registers, using big-endian encoding (the most significant byte is sent first). | ||
+ | |||
+ | |||
+ | '''Returns:''' | ||
+ | |||
+ | * numeric array - response PDU. | ||
=== modbusWriteMaskRegister === | === modbusWriteMaskRegister === | ||
Line 1,027: | Line 1,048: | ||
=== ping === | === ping === | ||
− | ping(host, timeout) | + | static boolean ping(String host, int timeout) |
Sends an IP network ping command to the host specified. | Sends an IP network ping command to the host specified. | ||
Line 1,034: | Line 1,055: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * host: | + | * host: String - the hostname or IP address |
− | * timeout: | + | * timeout: int - timeout in milliseconds. |
Line 1,042: | Line 1,063: | ||
* boolean - true if the host is reachable, false otherwise. | * boolean - true if the host is reachable, false otherwise. | ||
+ | === urlGet === | ||
+ | static 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 === | ||
+ | static 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). | ||
=== wakeOnLan === | === wakeOnLan === | ||
− | wakeOnLan(broadcast, address) | + | static int wakeOnLan(String broadcast, String address) |
Sends a Wake on LAN command to the LAN specified in the broadcast. | Sends a Wake on LAN command to the LAN specified in the broadcast. | ||
Line 1,051: | Line 1,116: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * broadcast: | + | * broadcast: String - the LAN broadcast address. For example “192.168.0.255” |
− | * address: | + | * 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.}} | {{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.}} | ||
Line 1,059: | Line 1,124: | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - 1 if successful, -1 if not. |
− | |||
== Public Announcement == | == Public Announcement == | ||
− | The | + | 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, | + | 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 Public Announcement | + | See the [[Audio and Public Announcement]] section for additional information. |
Line 1,083: | Line 1,147: | ||
| axis@camera id | | axis@camera id | ||
| audio sent to an Axis camera, using the camera id defined in the Cameras parameter in hsyco.ini | | 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 | ||
+ | |- | ||
+ | | axis@host:user:password name | ||
+ | | audio sent to an Axis geric audio device. Use the host name or IP address of the device, authenticating with user and password. The device must allow commands via HTTP on the default port 80 | ||
|- | |- | ||
| snom@ip:port | | 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) | | 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 === |
− | + | static int audioPlay(String where, File file) | |
Plays a pre-recorded audio file. | Plays a pre-recorded audio file. | ||
Line 1,097: | Line 1,170: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * where: | + | * where: String - the audio destination; see the table above |
− | * file: | + | * file: File - the audio file, relative to HSYCO's root directory. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - the index of this message in the play back queue if successful, -1 in case of errors. |
− | |||
− | === | + | === audioPlay - text to speech === |
− | + | static 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. | Converts a text message to audio using the installed text-to-speech engine, and plays the audio. | ||
Line 1,114: | Line 1,186: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * where: | + | * where: String - the audio destination; see the table above |
− | * voice: | + | * voice: String - the voice name for the text-to-speech engine; see the [[Audio and Public Announcement]] section for additional information |
− | * text: | + | * text: String - the text message for text-to-speech conversion. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - the index of this message in the play back queue if successful, -1 in case of errors. |
− | |||
== Serial Communication Ports == | == Serial Communication Ports == | ||
Line 1,161: | Line 1,232: | ||
'''Returns:''' | '''Returns:''' | ||
− | * String - null in case of errors, a string with the hexadecimal representation of the received byte sequence, or an empty string if | + | * String - null in case of errors, a string with the hexadecimal representation of the received byte sequence, or an empty string if the incoming data buffer is empty. For example “45AB4400BA”. |
=== writeComm === | === writeComm === | ||
Line 1,184: | Line 1,255: | ||
=== slimButton === | === slimButton === | ||
− | slimButton(player, button) | + | static int slimButton(String player, String button) |
Controls the Squeezebox players, simulating a remote control button. | Controls the Squeezebox players, simulating a remote control button. | ||
Line 1,191: | Line 1,262: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * player: | + | * player: String - the Squeezebox name, as listed in the slimPlayers parameter in hsyco.ini |
− | * button: | + | * button: String - the Squeezebox command. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * int - 1 if successful, 0 otherwise. |
− | |||
=== slimCommand === | === slimCommand === | ||
Line 1,215: | Line 1,285: | ||
* String - the protocol answer to the command if successful, or null in case of errors. | * String - the protocol answer to the command if successful, or null in case of errors. | ||
+ | |||
+ | == Timers and Schedulers == | ||
+ | === userTimerSet === | ||
+ | |||
+ | static boolean userTimerSet(String name, Boolean on, Integer hour, Integer minute, Integer duration, String days) | ||
+ | |||
+ | Sets a user timer. | ||
+ | |||
+ | |||
+ | '''Parameters:''' | ||
+ | |||
+ | * on: Boolean - true enables the timer; false disables the timer; null leaves the mode unchanged | ||
+ | * hour: Integer - start hour, from 0 to 23; null leaves the start hour unchanged | ||
+ | * minute: Integer - start minute, from 0 to 59; null leaves the start minute unchanged | ||
+ | * duration: Integer - duration in minutes, from 0 to 1439; null leaves the duration unchanged | ||
+ | * days: String - activation days, as a string of up to 7 characters from 1 to 7, 1 is Monday, 7 is Sunday; null or empty string leaves the days unchanged. | ||
+ | |||
+ | |||
+ | '''Returns:''' | ||
+ | |||
+ | * boolean - true if successful. | ||
== User Interface == | == User Interface == | ||
+ | |||
+ | {{ui_sessions_and_scope_description}} | ||
=== uiClear === | === uiClear === | ||
− | uiClear(session) | + | static void uiClear(String session) |
Removes all session specific UI object attributes set with uiSet(). | Removes all session specific UI object attributes set with uiSet(). | ||
Line 1,230: | Line 1,323: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * session: | + | * session: String - session id string that uniquely identifies the client session. |
− | === uiGet === | + | === uiGet - global === |
− | uiGet(id, attr) | + | static String uiGet(String id, String attr) |
Gets the current value of an attribute of an identified UI object, set with the uiSet() function or the UISET action in EVENTS. | Gets the current value of an attribute of an identified UI object, set with the uiSet() function or the UISET action in EVENTS. | ||
Line 1,241: | Line 1,334: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * id: | + | * id: String - object id |
− | * attr: | + | * attr: String - attribute name. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * String - the current value of the attribute of an identified UI object, or null if the object attribute has not been set. |
− | + | === uiGet - session === | |
− | === | + | static String uiGet(String session, String id, String attr) |
− | |||
Gets the session-specific value of an attribute of an identified UI object, set with the uiSessionSet() function or the UISESSIONSET action in EVENTS | Gets the session-specific value of an attribute of an identified UI object, set with the uiSessionSet() function or the UISESSIONSET action in EVENTS | ||
Line 1,258: | Line 1,350: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * id: | + | * session: String - session id string that uniquely identifies the client session. |
− | * attr: | + | * id: String - object id |
+ | * attr: String - attribute name. | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * String - the session value of the attribute of an identified UI object, or null if the object attribute has not been set. |
− | + | === uiSet - session === | |
− | === | + | static 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. | Changes the dynamic attributes of identified user interface (UI) objects for a specific client session. | ||
Line 1,274: | Line 1,366: | ||
{{tip|Session specific attributes values will override values set globally.}} | {{tip|Session specific attributes values will override values set globally.}} | ||
+ | |||
+ | Calling this method with a null value, if a global UI value exists, removes the session value and restores the global one. | ||
+ | Passing a null value has no effect if there is no previous session UI value, or no global UI value exists. | ||
Line 1,281: | Line 1,376: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * id: | + | * session: String - session id string that uniquely identifies the client session. |
− | * attr: | + | * id: String - object id |
− | * value: | + | * attr: String - attribute name |
− | + | * value: String - attribute value, or null to remove a previously set session value. | |
− | === uiSet === | + | === uiSet - global === |
− | uiSet(id, attr, value) | + | static void uiSet(String id, String attr, String value) |
Changes the dynamic attributes of the identified user interface (UI) objects. | Changes the dynamic attributes of the identified user interface (UI) objects. | ||
Line 1,296: | Line 1,391: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * id: | + | * id: String - object id |
− | * attr: | + | * attr: String - attribute name |
− | * value: | + | * value: String - attribute value. |
=== user === | === user === | ||
− | user(name, param) | + | static void user(String name, String param) |
Triggers a USER event, the execution of the userCommand() JavaScript function and of the userCommand() Java method. | Triggers a USER event, the execution of the userCommand() JavaScript function and of the userCommand() Java method. | ||
Line 1,311: | Line 1,406: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the name parameter, passed to userCommand() and the USER event |
− | * param: | + | * param: String -the param parameter, passed to userCommand() and the USER event. |
Latest revision as of 14:08, 21 July 2017
These methods are used to control field devices, to acquire status information and to execute general utility functions.
If the userLog option is enabled in the system general settings, commands that execute relevant functions will be logged in the daily log file:
2011.07.30 11:39:16.133 - USERCODE: method - parameter
Contents
- 1 System Functions
- 2 Cameras
- 3 Data Logger
- 4 DMX
- 5 Infrared Control
- 6 I/O Servers
- 7 Leak Detector
- 8 Log
- 9 Mail
- 10 Modbus
- 10.1 modbusReadCoils
- 10.2 modbusReadDiscreteInputs
- 10.3 modbusReadHoldingRegisters
- 10.4 modbusReadInputRegisters
- 10.5 modbusReadWriteMultipleRegisters
- 10.6 modbusWriteMaskRegister
- 10.7 modbusWriteMultipleCoils
- 10.8 modbusWriteMultipleRegisters
- 10.9 modbusWriteSingleCoil
- 10.10 modbusWriteSingleRegister
- 11 Network Services
- 12 Public Announcement
- 13 Serial Communication Ports
- 14 Squeezebox
- 15 Timers and Schedulers
- 16 User Interface
System Functions
dateSet
static 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
static 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
static 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
static 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
static 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.
isDaylight
static boolean 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
static void powerSet(int 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: int - the power in Watt units.
programTimerClear
static void programTimerClear(String name)
Cancels a program timer.
Parameters:
- name: String - the program timer name.
programTimerRepeat
static void programTimerRepeat(String name, int 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: int - the interval in seconds of the timer’s execution.
programTimerReset
static void programTimerReset(String name, int 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: int - the number of seconds to the timer’s execution.
programTimerSet
static void programTimerSet(String name, int 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: int - the number of seconds to the timer’s execution.
schedulerRegister
static void schedulerRegister(String groupname, String schedulename, int interval)
This function registers a new scheduled callback.
Parameters:
- groupname: String - the group name
- schedulename: String - the schedule name
- interval: int - interval in milliseconds.
schedulerRemove
static void schedulerRemove(String groupname, String schedulename)
Deletes a schedule.
Parameters:
- groupname: String - the group name
- schedulename: String - the schedule name.
sleep
static 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
static 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
static 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.
Cameras
cameraCommand
static int cameraCommand(String function, String action, String 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.
|
Returns:
- int - the returned value is included in the log message, and has no other purpose.
cameraMode
static void cameraMode(String camera, boolean 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
static void cameraRecMode(String camera, boolean 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
static void cameraRecTrigger(String camera, String source, int 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: int - recording time in seconds. If set to 0, stops the current recording.
cameraRecTriggerFull
static void cameraRecTriggerFull(String camera, String source, int 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: int - recording time in seconds. If set to 0, stops the current recording.
Data Logger
dataLoggerClear
static boolean dataLoggerClear(String 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
static boolean dataLoggerOptions(String name, String param, String 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
static boolean dataLoggerSave(String action, String[] names, String path, boolean timestamp)
Creates or updates a CSV file containing the data processed by the specified data loggers.
Also used to import and export of raw data logger data in CSV format. See Data Loggers CSV Import/Export for additional information.
The possible actions 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
- csvwrite: create a CSV file with all raw data of a data logger
- csvread: insert, update or delete records to a data logger
- csvreadover: insert records to a data logger, replacing all existing data.
Parameters:
- action: String - set to "log", "stat", "csvwrite", "csvread" or "csvreadover"
- names: String[] - data logger names
- path: String - path of the file to be created
- timestamp: boolean - if true and the action is log adds a timestamp column in the CSV file for the logged values.
Returns:
- boolean - true if successful, false if not.
dataLoggerUpdate
static boolean dataLoggerUpdate(String name, Double value)
Supplies the specified data logger with a new value to be processed.
Parameters:
- name: String - data logger name
- value: Double - 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
static int dmxGet(int channel)
Returns the current status of a channel on the DMX-512 bus.
Parameters:
- channel: int - 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:
- int - channel current status, between 0 and 255, or UNKNOWN (-1) if the status is unknown.
dmxOff
static int dmxOff(int 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: int - 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:
- int - 1 if successful, 0 if not.
dmxOff - multi channel
static int dmxOff(int[] channels)
Sets a list of DMX-512 channels to 0, also saving the previous values, so they can be restored with dmxOn().
When changing status to multiple channels, this method is more efficient than the single channel command, and updates all the channels at the same time.
When this method is executed, the variation of even only one of the channels listed in the array causes the execution of the callback methods associated to the DMX events for all the channels listed in the array, even those which are not modified by this call.
Parameters:
- channels: int[] - an array that contains the list of channels. When using one DMX gateway, the channel address will be a standard DMX-512 address between 1 and 512.
Returns:
- int - 1 if successful, 0 if not.
dmxOn
static int dmxOn(int channel)
Sets a DMX-512 channel to the value preceding the last call to dmxOff().
Parameters:
- channel: int - 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:
- int - 1 if successful, 0 if not.
dmxOn - multi channel
static int dmxOn(int[] channels)
Sets a list of DMX-512 channels to the values preceding the last call to dmxOff() for each channel.
When changing status to multiple channels, this method is more efficient than the single channel command, and updates all the channels at the same time.
When this method is executed, the variation of even only one of the channels listed in the array causes the execution of the callback methods associated to the DMX events for all the channels listed in the array, even those which are not modified by this call.
Parameters:
- channels: int[] - an array that contains the list of channels. When using one DMX gateway, the channel address will be a standard DMX-512 address between 1 and 512.
Returns:
- int - 1 if successful, 0 if not.
dmxMerge - range
static int dmxMerge(int from, int to, boolean 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:
- from: int - 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
- to: int - last address of the range
- merge: boolean - true to enable merge mode, false to return to normal mode.
Returns:
- int - 1 if successful, -1 if to < from, 0 for other errors.
dmxMerge - multi channel
static int dmxMerge(int[] channels, boolean merge)
Sets a list of DMX-512 channels 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:
- channels: int[] - an array that contains the list of channels. When using one DMX gateway, the channel address will be a standard DMX-512 address between 1 and 512.
- merge: boolean - true to enable merge mode, false to return to normal mode.
Returns:
- int - 1 if successful, -1 if to < from, 0 for other errors.
dmxSet
static int dmxSet(int channel, int state)
Sets the value of a single DMX-512 channel.
Parameters:
- channel: int - 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
state: int - the new value of the channel, from 0 to 255.
Returns:
- int - 1 if successful, 0 if not.
dmxSet - multi channel
static int dmxSet(int[] channels, int[] state)
Sets a list of DMX-512 channels.
When changing status to multiple channels, this method is more efficient than the single channel command, and updates all the channels at the same time.
When this method is executed, the variation of even only one of the channels listed in the array causes the execution of the callback methods associated to the DMX events for all the channels listed in the array, even those which are not modified by this call.
Parameters:
- channels: int[] - an array that contains the list of channels. When using one DMX gateway, the channel address will be a standard DMX-512 address between 1 and 512.
- states: int[] - an array that contains the list of values for each channel, from 0 to 255.
Returns:
- int - 1 if successful, 0 if not.
Infrared Control
irtransCommand
static int irtransCommand(String irid, String command)
Sends a command to an IRTrans.
An infrared command is composed by the name that identifies the commands database, followed by a comma and the name of the command in the database.
More commands in a sequence can be separated by “;”.
It is possible to insert the special command @N, which introduces a wait time of N milliseconds before sending the next command.
This command:
denon1036,on;@4000;denon1036,tv
sends the “on” command of the “denon-1036” remote, then waits 4 seconds before sending the “tv” command.
Moreover, the special command @0 allows to send IR commands without wait times before sending the next command.
When the @N delay before an IR command is not specified, there will be a default 500ms pause between commands; with @0 this pause will be reduced to 1ms.
For example:
denon,on;@0;nad,on
sends the “on” command of the “denon” remote, immediately followed by the “on” command of the “nad” remote.
Every IRTrans can contain a database of several remote controls, and each database stores the list of the distinct IR commands. If the hsyco/ir directory contains a .ccfhex file corresponding to the database name, then the CCF string in the file is used instead of sending the command stored in the IRTrans internal database.
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:
- int - 1 if successful, 0 if not.
I/O Servers
ioGet
static String ioGet(String 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
static int ioServersRestart(String name)
Restarts an I/O server that was previously stopped.
This command has no effect on a running I/O server.
Note that this command will return before the I/O server is actually restarted.
Parameters:
- name: String - the I/O server name.
Returns:
- int - 1 if successful, -1 if the server name is not defined.
ioServersStop
static int ioServersStop(String name)
Stops the execution of an I/O server.
Note that this command will return before the I/O server is actually stopped.
Parameters:
- name: String - the I/O server name.
Returns:
- int - 1 if successful, -1 if the server name is not defined.
ioSet
static void ioSet(String id, String 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
The Intelligent Leak Detector is used to generate warning for potential water or other quantities leaks by analyzing any generic flow counter.
The detector should be called at regular intervals, possibly faster than the minimum time needed for the counter to increment its value by one.
It will generate a leak warning when the measured flow remains relatively constant over a certain amount of time.
Use this function at your own risk!
The Intelligent Leak Detector uses a correlation algorithm to distinguish between a constant flow and an irregular flow. A relatively constant flow over a certain amount of time is considered as a potential leak and generates a leak event.
In some conditions, also depending on the type of flow counter used, this algorithm could fail from properly and timely recognizing a real leak, or it could generate false leak warnings.
Use different names to implement multiple independent leak detectors.
leakDetectorClear
static void leakDetectorClear(String 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
static void leakDetectorOptions(String name, String param, String 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.
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: String - the period or deviation value.
leakDetectorUpdate
static int leakDetectorUpdate(String name, double value)
Calls the leak detector passing the current liters counter value.
Parameters:
- name: String - leak detector name
- value: double - the flow counter value.
Returns:
- int - -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
static void errorLog(String message)
Generates an error message in the daily log file.
Parameters:
- message: String - the text of the error message.
fileLog
static 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
static 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
static 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
static 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.
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
modbusReadCoils
static byte[] modbusReadCoils(String name, int unit, int address, int 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.
The coils in the response message are packed as one coil per bit of the data field. Status is indicated as 1= ON and 0= OFF. The LSB of the first data byte contains the output addressed in the query. The other coils follow toward the high order end of this byte, and from low order to high order in subsequent bytes.
If the returned output quantity is not a multiple of eight, the remaining bits in the final data byte will be padded with zeros (toward the high order end of the byte). The byte count field in the response PDU specifies the quantity of complete bytes of data.
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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the starting address of the block of coils
- quantity: int - the quantity of coils you are reading (1 to 2000).
Returns:
- byte[] - response PDU.
modbusReadDiscreteInputs
static byte[] modbusReadDiscreteInputs(String name, int unit, int address, int 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.
The discrete inputs in the response message are packed as one input per bit of the data field. Status is indicated as 1= ON; 0= OFF. The LSB of the first data byte contains the input addressed in the query. The other inputs follow toward the high order end of this byte, and from low order to high order in subsequent bytes.
If the returned input quantity is not a multiple of eight, the remaining bits in the final data byte will be padded with zeros (toward the high order end of the byte). The byte count field of the response PDU specifies the quantity of complete bytes of data.
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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the starting address of the block of discrete inputs
- quantity: int - the quantity of discrete inputs you are reading (1 to 2000).
Returns:
- byte[] - response PDU.
modbusReadHoldingRegisters
static byte[] modbusReadHoldingRegisters(String name, int unit, int address, int 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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the starting address of the block of registers
- quantity: int - the quantity of registers you are reading (1 to 125).
Returns:
- byte[] - response PDU.
modbusReadInputRegisters
static byte[] modbusReadInputRegisters(String name, int unit, int address, int 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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the starting address of the block of registers
- quantity: int - the quantity of registers you are reading (1 to 125).
Returns:
- byte[] - response PDU.
modbusReadWriteMultipleRegisters
static byte[] modbusReadWriteMultipleRegisters(String name, int unit, int readaddress, int readquantity, int writeaddress, byte[] bytes)
Writes a block of contiguous registers in a MODBUS device, then reads the content of a contiguous block of holding registers, using function code 0x17.
Returns a standard response PDU.
If there is a correct response from the device, the first byte is set to 0x17, 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 0x97 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: int - the MODBUS slave unit identifier (1 to 247)
- readaddress: int - the starting address of the block of registers to read
- readquantity: int - the quantity of registers you are reading (1 to 125)
- writeaddress: int - the starting address of the block of registers to write
- bytes: byte[] - data to be written in the registers, using big-endian encoding (the most significant byte is sent first).
Returns:
- numeric array - response PDU.
modbusWriteMaskRegister
static byte[] modbusWriteMaskRegister(String name, int unit, int address, byte[] mask, byte[] 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: int - the MODBUS slave unit identifier (1 to 247)
- mask: byte[] - the AND mask to be applied to the register
- bytes: byte[] - data to be written in the register, using big-endian encoding (the most significant byte is sent first).
Returns:
- byte[] - response PDU.
modbusWriteMultipleCoils
static byte[] modbusWriteMultipleCoils(String name, int unit, int address, int coils, byte[] data)
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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the coil’s address
- coils: int - the number of coils to be written
- bytes: byte[] - 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:
- byte[] - response PDU.
modbusWriteMultipleRegisters
static byte[] modbusWriteMultipleRegisters(String name, int unit, int address, byte[] 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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the starting address of the block of registers
- bytes: byte[] - data to be written in the registers, using big-endian encoding (the most significant byte is sent first).
Returns:
- byte[] - response PDU.
modbusWriteSingleCoil
static byte[] modbusWriteSingleCoil(String name, int unit, int address, boolean 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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the coil’s address
- value: boolean - true to turn the coil on, false to turn it off.
Returns:
- byte[] - response PDU.
modbusWriteSingleRegister
static byte[] modbusWriteSingleRegister(String name, int unit, int address, byte[] 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: int - the MODBUS slave unit identifier (1 to 247)
- address: int - the register’s address
- bytes: byte[] - data to be written in the register, using big-endian encoding (the most significant byte is sent first).
Returns:
- byte[] - response PDU.
Network Services
ping
static boolean ping(String host, int timeout)
Sends an IP network ping command to the host specified.
Parameters:
- host: String - the hostname or IP address
- timeout: int - timeout in milliseconds.
Returns:
- boolean - true if the host is reachable, false otherwise.
urlGet
static 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
static 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).
wakeOnLan
static int wakeOnLan(String broadcast, String 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”.
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:
- int - 1 if successful, -1 if not.
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![]() |
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 |
axis@host:user:password name | audio sent to an Axis geric audio device. Use the host name or IP address of the device, authenticating with user and password. The device must allow 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
static int audioPlay(String where, File file)
Plays a pre-recorded audio file.
Parameters:
- where: String - the audio destination; see the table above
- file: File - 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
static 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
static 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
static 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 incoming data buffer is empty. For example “45AB4400BA”.
writeComm
static 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.
Squeezebox
slimButton
static int slimButton(String player, String button)
Controls the Squeezebox players, simulating a remote control button.
Parameters:
- player: String - the Squeezebox name, as listed in the slimPlayers parameter in hsyco.ini
- button: String - the Squeezebox command.
Returns:
- int - 1 if successful, 0 otherwise.
slimCommand
static String slimCommand(String player, String command)
Sends commands to the Squeezebox players.
Parameters:
- player: String - the Squeezebox name, as listed in the slimPlayers parameter in hsyco.ini
- command: String - the Squeezebox command, as described in the documentation of the Command Line Interface (CLI) of SqueezeCenter.
Returns:
- String - the protocol answer to the command if successful, or null in case of errors.
Timers and Schedulers
userTimerSet
static boolean userTimerSet(String name, Boolean on, Integer hour, Integer minute, Integer duration, String days)
Sets a user timer.
Parameters:
- on: Boolean - true enables the timer; false disables the timer; null leaves the mode unchanged
- hour: Integer - start hour, from 0 to 23; null leaves the start hour unchanged
- minute: Integer - start minute, from 0 to 59; null leaves the start minute unchanged
- duration: Integer - duration in minutes, from 0 to 1439; null leaves the duration unchanged
- days: String - activation days, as a string of up to 7 characters from 1 to 7, 1 is Monday, 7 is Sunday; null or empty string leaves the days unchanged.
Returns:
- boolean - true if successful.
User Interface
All identified UI objects support dynamic attributes that can be changed at run-time.
The primary commands used to set dynamic attributes are the UISET action in EVENTS, and the uiSet() Java and JavaScript function.
Set levels
You can set dynamic attributes at different levels:
- global, using UISET and not specifying any session information - will set the attribute to the desired value for all clients
- client session, using UISESSIONSET on USER and PAGE events, or uiSessionSet(session, id, attr, value) in JavaScript and uiSet(String session, String id, String attr, String value) in Java - will set the attribute for a single specific client session
- application scope, using uiSessionSet(session, id, attr, value) in JavaScript and uiSet(String session, String id, String attr, String value) in Java - will set the attribute only for projects and pages that are explicitly bound (subscribed) to the same scope. You can use any string literal to identify a scope, and simply use that string in the session parameter of uiSet or uiSessionSet, instead of the client session id.
Priority rules
Overlapping global, session or scope UI attributes set on the same object is possible. In this case, a session set has the highest priority, followed by global set and finally the scope set. So, if you have a scope set on an object, and a global set is called on the same attribute of the same object, this global set will override the scope set. A session set will override both the scope and global set.
Session lifetime
While a global set will last until HSYCO is restarted, the client sessions have a limited lifetime.
Basically a client session is created whenever you load a URL pointing to an HSYCO project, and is automatically cleared after one hour of inactivity, where session activity is defined as the client being actively connected to the HSYCO server.
Scopes also have the same lifetime of client sessions, but activity in this case is defined as at least one client that is showing a page or project that is bound to the scope.
You can also create persistent scopes, simply using scope literals ending with the ! character. Persistent scopes will not follow be cleared, even after prolonged inactivity, and will last until HSYCO is restarted.
uiClear
static 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.
The uiClearEvent() callback is called following the uiClear() execution 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.
uiGet - global
static String uiGet(String id, String attr)
Gets the current value of an attribute of an identified UI object, set with the uiSet() function or the UISET action in EVENTS.
Parameters:
- id: String - object id
- attr: String - attribute name.
Returns:
- String - the current value of the attribute of an identified UI object, or null if the object attribute has not been set.
uiGet - session
static String uiGet(String session, String id, String attr)
Gets the session-specific value of an attribute of an identified UI object, set with the uiSessionSet() function or the UISESSIONSET action in EVENTS
Parameters:
- session: String - session id string that uniquely identifies the client session.
- id: String - object id
- attr: String - attribute name.
Returns:
- String - the session value of the attribute of an identified UI object, or null if the object attribute has not been set.
uiSet - session
static 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.
Calling this method with a null value, if a global UI value exists, removes the session value and restores the global one. Passing a null value has no effect if there is no previous session UI value, or no global UI value exists.
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, or null to remove a previously set session value.
uiSet - global
static 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
static 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.