Action Keywords

An action is defined as a keyword that identifies the action type, usually followed by one or more parameters and sometimes the equal (assignment) operator.

Every keyword uses a specific syntax that interprets parameters according to its own rules.

Most actions take values: the new state of a data point, a text, a number of seconds, and so on. A value can combine constants, quoted strings, variables, the current value of data points (IO name) and arithmetic computations with +, -, *, / and round brackets:

IO tempmeter.indoor : UISET temperature.value = (IO tempmeter.indoor * 1.8 + 32) " °F"

See Values in Actions and Arithmetic for the rules. The description of each action below lists the parameters that accept values.

System Keywords

DATESET

Set the HSYCO Server’s system clock.

Action	Description
DATESET = datetime	set the HSYCO Server operating system’s clock and hardware clock

Parameters:

• datetime - date and time formatted as "YYYY-MM-DD hh:mm:ss" or "YYYYMMDDhhmmss", in the local time zone. It is a value, so it can be read from a variable or a data point, or built by concatenating several parts.

Examples:

DATESET = "2014-10-31 20:00:00"
DATESET = "20141031200000"

Set the clock from the date and time reported by a GPS receiver:

USER syncclock : DATESET = IO gps.datetime

HAACTIVE

Force a master HSYCO server to become inactive, or return to the active state.

Action	Description
HAACTIVE = FALSE	force a master to become inactive (has no effect on the slave system)
HAACTIVE = TRUE	used after the master was forced to become inactive, returns it to the active state (has no effect on the slave system)

Parameters:

• active - true or false (or 1 or 0). It is a value, so it can be read from a variable or a data point.

Examples:

IO mygate.connection = offline : HAACTIVE = false

Follow the state of a switch, where 1 keeps the master active and 0 forces it inactive:

IO contacts.haswitch : HAACTIVE = IO contacts.haswitch

NLP

Send a text to the Natural Language Processor (NLP). See the NLP engine page for additional information.

Action	Description
NLP area = text	the text string is passed to the NLP for processing and to execute the corresponding actions if a match is found. Area can be either one of the area IDs defined in the NLP dictionary files, or a text string that will be matched against the defined areas

Parameters:

• text - natural language text string. It is a value, so it can be built from quoted strings, variables and data points.

Examples:

NLP = "turn on the kitchen lights"
NLP = "turn " $state " the " $room " lights"

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.

Action	Description
POWER = power	sets the electric power state variable to a specific value, in Watts

Parameters:

• power - the power in Watt units. It is a value, so it can be read from a data point or computed.

Examples:

POWER = IO meter.power

Sum the three phases of a meter that measures kW:

IO meter.l1 OR IO meter.l2 OR IO meter.l3 : POWER = (IO meter.l1 + IO meter.l2 + IO meter.l3) * 1000

PROGRAMTIMER

Creates or deletes a program timer.

Action	Description
PROGRAMTIMER name = SET seconds	a program timer will be executed after the number of seconds specified in SET. If a program timer with the same name has already been set, the action will be ignored
PROGRAMTIMER name = CLEAR	deletes a timer
PROGRAMTIMER name = RESET seconds	similar to SET, but if a program timer with the same name has already been set, the timer settings will be changed to the new timeout
PROGRAMTIMER name = REPEAT seconds	sets a program timer that is executed repeatedly with an interval equal to the specified number of seconds

Parameters:

• name - the program timer name
• seconds - the timeout, in seconds. It is a value, so it can be read from a variable or a data point, or computed; the result must be a whole number.

If the program timer name starts with $, then the server will also automatically set a variable, with a name equal to the program timer's name, to the remaining number of seconds. Note that the variable is not guarateed to be updated at every second, as some updates may be skipped due to timing constraints.

Examples:

IO knx.1/2/3 = 1 : PROGRAMTIMER presence = REPEAT 3600
IO knx.1/2/3 = 0 : PROGRAMTIMER presence = CLEAR

Keep the stairs light on for the number of minutes set in the $stairsminutes variable:

IO button.stairs = 1 : IO k.33 = 1, PROGRAMTIMER stairs = RESET $stairsminutes * 60
PROGRAMTIMER stairs : IO k.33 = 0

WAIT

Pauses before the execution of the next action.

Action	Description
WAIT = s	causes a pause in the execution of actions for the specified number of seconds. It can be also set in decimal format

Parameters:

• s - wait time in seconds. It is a value, so it can be read from a variable or a data point, or computed.

Examples:

WAIT = 5
WAIT = 0.3
WAIT = $delay * 1.5
WAIT = IO config.delayms / 1000

Cameras

CAMERA

The CAMERA action is used to temporarily disable cameras’ live view and recording features.

Action	Description
CAMERA name = ON	live view enabled
CAMERA name = OFF	live view and recording disabled
CAMERA name = RECON	recording enabled
CAMERA name = RECOFF	recording disabled

Parameters:

• name - the camera’s id. You can specify a list of space separated ids.

The mode after = is a value, so it can also be read from a variable or a data point.

Examples:

CAMERA entrance = ON
USER cameramode : CAMERA entrance = $cameramode

CAMERAREC

Records video from a camera.

Action	Description
CAMERAREC name = sec	records for the number of seconds defined with the set attribute

Parameters:

• name - the camera’s id. You can specify a list of space separated ids
• sec - recording time in seconds. If set to 0, stop the current recording and reset the recording markers, so that the next recording will always show as a distinct record in a camera panel object, even when the interval between two successive recordings is short. It is a value, so it can be read from a variable or a data point, or computed; the result must be a whole number.

Examples:

CAMERAREC openspace = 30
IO alarm.zone1 = 1 : CAMERAREC openspace = $recminutes * 60

CAMERARECFULL

Records video from a camera, like CAMERAREC, 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.

Action	Description
CAMERARECFULL name = sec	records for the number of seconds defined with the set attribute

Parameters:

• name - the camera’s id. You can specify a list of space separated ids
• sec - recording time in seconds. If set to 0, stop the current recording and reset the recording markers, so that the next recording will always show as a distinct record in a camera panel object, even when the interval between two successive recordings is short. It is a value, so it can be read from a variable or a data point, or computed; the result must be a whole number.

Examples:

CAMERARECFULL openspace = 30
IO alarm.zone1 = 1 : CAMERARECFULL openspace = $recminutes * 60

Data Logger

Data loggers collect and display statistical data on the variation of a specified value.

They can be used to automatically generate trend charts and log the data as CSV files.

See the Data Logger documentation for additional information.

DATALOGGER

Updates and performs operations on a data logger.

Action	Description
DATALOGGER name = value	Supplies the data logger with a new value to be processed. It will also trigger the refresh procedure
DATALOGGER name = CLEAR	Clears the data gathered in the data logger
DATALOGGER name = ERROR	Used with counter data loggers, resets the internal delta baseline
DATALOGGER name = FILE LOG filename	Appends the last acquired value to the specified file (filename) using the CSV format.
DATALOGGER name = FILE LOG filename TIMESTAMP	Appends the last acquired value to the specified file (filename) using the CSV format. The timestamp of the record will be reported too
DATALOGGER name = FILE STAT filename	Creates or updates the specified file (filename) with the currently gathered data using the CSV format
DATALOGGER name = FILE CSVWRITE path	Writes a raw dump of all data from a data logger into a CSV file. The file, named <data logger id>.csv is written in the < path> directory
DATALOGGER name = FILE CSVWRITE FROM yyyymmddhhmm TO yyyymmddhhmm GROUPBY year | month | day | hour PATH path	Writes a raw dump of data from a data logger into a CSV file, between the given time interval. The file, named <data logger id>.csv is written in the < path> directory. The date and time must be written as a 12 digit string. Data returned including the first time and excluding the second. The "TO" limit is optional. "GROUPBY" is also optional. If omitted, all individual records matching the time interval are written to the CSV file. If "GROUPBY" is specified, records and their values are grouped together by year, month, day or hour. Note that, to optimise performance and resources allocation, this extended form of the FILE CSVWRITE action can write only up to 10000 rows to the CSV file
DATALOGGER name = FILE CSVREAD path	Upload a CSV file to insert, update or delete records of a data logger. The file, named <data logger id>.csv, is read from the < path> directory
DATALOGGER name = FILE CSVREADOVER path	Upload a CSV file that will replace all records of a data logger

Parameters:

• name - identifier of the data logger. It is possible to use a list of names separated by spaces to address several data loggers. Variables can be used
• value - the new numeric value. It is a value, so it can be read from a variable or a data point, or computed; if the result is not a number, the data logger receives an empty value
• filename - the file pathname. You can use multiple distinct strings, including variables, that will be concatenated to create the file name.

Examples:

$value : DATALOGGER energy = $value,
DATALOGGER energy = FILE LOG userdata/energylog.csv TIMESTAMP,
DATALOGGER energy = FILE STAT userdata/energystat.csv

TIME : DATALOGGER temperature = IO ste.1
TIME : DATALOGGER humidity = IO ste.2

Log the power in Watt from a meter that measures kW, and the difference between two temperatures:

TIME : DATALOGGER power = IO meter.kw * 1000
TIME : DATALOGGER deltat = IO ste.1 - IO ste.3

Example of code to export and import a data logger called "loggermem" (path: "logger", data logger id: "loggermem")

user dataimport : DATALOGGER loggermem = FILE CSVREADOVER "logger"
user dataexport : DATALOGGER loggermem = FILE CSVWRITE "logger"
user dataexport : DATALOGGER loggermem = FILE CSVWRITE FROM "201801010000" TO "202101010000" GROUPBY "month" PATH "logger"

CSV Import/Export Examples

Using the HSYCO's development API, in Events, JavaScript and Java, you can export a full dump of all data underlying each data logger.

The CSV file uses \r\n as line separator and ';' as field separator.

This is an example of the CSV file for a counter data logger.

ts;delta;cost;locked
20160129130000;2.0830569986031082;0.0;1
20160129140000;3.464736775902562;0.0;1
20160129150000;0.04146936782360733;0.0;1
20160220120100;0.005090918751661816;0.0;0
20160220120200;0.039745587753242655;0.0;0

The record format has the following four fields:

• ts: the timestamp as YYYYMMDDhhmmss
• delta: a double precision floating point of the accumulated values for the period between this record's timestamp and the next
• cost: a double precision floating point of the cost value for the period
• locked: a boolean, represented as 1 for locked records, and 0 for unlocked records. A record is marked as locked when its cost value is permanently set, and will not change if the rates rules are changed in the future.

This is an example of the CSV file for a range data logger.

ts;vmin;vmax;vavg;vcount
20170114150100;3.607471109385042;4.694435324229342;4.241931611566256;15
20170114150200;3.8066206378643987;5.446351986025894;4.575574507553171;16
20170114150300;2.398800160049782;5.2533792997638775;3.6368449963207854;17
20170114150400;1.5474068317929874;3.1531099637853406;2.290833667227986;10

The record format has the following four fields:

• ts: the timestamp as YYYYMMDDhhmmss
• vmin: a double precision floating point for the minimum value logged in the period
• vmax: a double precision floating point for the maximum value logged in the period
• vavg: a double precision floating point for the average value logged in the period
• vcount: a positive integer counter of the number of values logged in the period; this is used to compute a weighted average when new values are passed to the data logger.

Export API

Use the following event action to create a CSV file for a data logger. The file, named <data logger id>.csv is written in the <path> directory:

DATALOGGER name = FILE CSVWRITE path

You can also use the equivalent JavaScript command API:

dataLoggerSave("csvwrite", names, path, timestamp)

And the Java command API (setting action to "csvwrite"):

static boolean dataLoggerSave(String action, String[] names, String path, boolean timestamp)

Import API

Raw data, using the same CSV format of the export APIs, can be imported to a data logger.

You can selectively update existing records, delete records, but also completely wipe existing data and replace them with the data from a the CSV file or a string. To delete records, leave just the timestamp value in the CSV file for the records you want to delete, for example:

ts;vmin;vmax;vavg;vcount
20170114150200;3.8066206378643987;5.446351986025894;4.575574507553171;16
20170114150300
20170114150400

This file will update record with update the values of one record, and delete two records.

Note that the first record in the CSV file is assumed to be the header, and not considered as valid data.

At the end of the import process, one or two files are generated, with the same name of the import file, with the "-ok" and "-err" suffixes to the data logger id, before the .csv extension. The ok file contains a copy of all records that have been successfully processed, while the err file will contain all records that were discarded due to format errors or other error conditions. If no errors are detected, only the ok file is created during the import process.

Use the following event action to upload a CSV file to insert, update or delete records of a data logger. The file, named <data logger id>.csv, is read from the < path> directory:

DATALOGGER name = FILE CSVREAD path

Use the following event action to upload a CSV file that will replace all records of a data logger:

DATALOGGER name = FILE CSVREADOVER path

You can upload a CSV line directly from a string instead of from a file, just replace the file path with the complete CSV string:

DATALOGGER name = FILE CSVREAD "20170114150200;3.8066206378643987;5.446351986025894;4.575574507553171;16"
DATALOGGER name = FILE CSVREAD "20170114150300"

You can also use the equivalent JavaScript command API:

dataLoggerSave("csvread", names, path, timestamp)
dataLoggerSave("csvreadover", names, path, timestamp)

And the Java command API (setting action to "csvread" or "csvreadover"):

static boolean dataLoggerSave(String action, String[] names, String path, boolean timestamp)

I/O Servers

IO

Writes to I/O servers data points.

Action	Description
IO name = value	sets the data point to a value. Values are specific to the type of I/O server
IO name = FLIP	inverts the output of the I/O data point. If the status of the output is 0 the new status will be 1, if different from 0 the new status will be 0
IO name1 = IO name2	sets the I/O interface output name1 to the current value of the I/O interface name2. If name2 is not defined, name1 is not changed
IO name = expression	sets the data point to the result of a computation or to a text built from several parts, including other data points and variables

Parameters:

• name - the server id, followed by a single dot and the data point suffix. The EVENTS interpreter converts data points names to lower case
• value - a value: you can use multiple unquoted words, quoted strings, variables and data points, that will be appended to the value string, and arithmetic computations. The ON, OFF and FLIP keywords keep their meaning when they are the only word of the value.

caution

Dimmer levels and other percentages are read as fractions in computations: 50% is 0.5. To compute a level, multiply by 100 and append the % as a quoted string.

Examples:

IO contacts.c1 contacts.c3 = 1
IO sensors.c1 = FLIP
IO contacts.o1 contacts.o2 = IO sensors.flood

Write a setpoint half a degree above the current temperature, and set a dimmer 10% above another one:

USER comfort : IO thermo.setpoint = IO tempmeter.indoor + 0.5
USER brighter : IO dimmer.1 = (IO dimmer.2 * 100 + 10) "%"

Write the average of three sensors to a virtual data point:

IO tempmeter.t1 OR IO tempmeter.t2 OR IO tempmeter.t3 : IO virtual.average = (IO tempmeter.t1 + IO tempmeter.t2 + IO tempmeter.t3) / 3

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.

caution

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.

note

Use different names to implement multiple independent leak detectors.

LEAK

Controls the integrated leak detector.

The detector’s logic uses two parameters to set its sensitivity and time base.

The detector generates a warning if the flow deviation constantly remains below the deviation threshold for the time period.

You can change the defaults to adapt to your specific conditions.

Action	Description
LEAK name = value	calls the leak detector passing the current liters counter value. Using variables or references to IO data points is supported
LEAK name = PERIOD t	changes the time base. The default is 1200 seconds. Set the period to 0 to temporarily disable the detector. The time base can be changed anytime, even when the detector is already processing data
LEAK name = DEVIATION d	changes the deviation percentage. d should be a number between 1 and 100. The default is 50. Set the deviation to 0 to temporarily disable the detector. Lower 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. Higher values could easily generate false alarms. The deviation can be changed anytime
LEAK name = CLEAR	clears the detector’s internal state. In normal applications, there is no need to call this function, as the detector automatically clears its state from old data

Parameters:

• name - the name of a leak detector. Using different names you can implement several independent leak detectors
• value - the counter value. It is a value, so it can be read from a variable or a data point, or computed
• t - time base
• d - deviation percentage

Examples:

HSYCOSTART : PROGRAMTIMER modbusread = repeat 4
PROGRAMTIMER modbusread :  IO modbus.2.768 = readholdingregisters:uint, LEAK water = IO modbus.2.768
LEAK water = ON : MAIL "john@example.com" = "hsyco@example.com" "Urgent Message from HSYCO" "Leak Detected"
LEAK water = OFF : MAIL "john@example.com" = "hsyco@example.com" "Message from HSYCO" "Leak Reset"

Feed the detector in liters from a counter that counts tens of liters:

PROGRAMTIMER modbusread : LEAK water = IO modbus.2.768 * 10

Log

FILELOG

Appends a generic text message at the end of a file.

Action	Description
FILELOG filename = text	you can use multiple unquoted words, quoted strings, variables, data points and computations, that will be appended at the last line of the text file

Parameters:

• filename - 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. The filename parameter can be a variable
• text - the message that will be appended at the last line of the text file. It is a value, so it can contain data points and computations.

Examples:

HSYCOSTART : FILELOG logs/mylog.txt = "log message example"

Append a CSV line with the date, the time, a temperature and its difference from the outdoor one every minute:

TIME : FILELOG logs/temperature.csv = $DATE:Y-M-D$ ";" $TIME:H:M$ ";" IO tempmeter.indoor ";" IO tempmeter.indoor - IO tempmeter.outdoor

LOG

Generates an information message in the daily log file.

Action	Description
LOG = text	you can use multiple unquoted words, quoted strings, variables, data points and computations, that will be appended to the log message

Parameters:

• text - the log message. It is a value, so it can contain data points and computations.

Examples:

LOG = "log message example"
LOG = "Time: " $TIME:H-M-S$ " DATE: " $DATE:D/M/Y$

Log the current value of two data points, their difference, and their average:

IO tempmeter.indoor : LOG = "Indoor " IO tempmeter.indoor " C, outdoor " IO tempmeter.outdoor " C"
IO tempmeter.indoor : LOG = "Difference: " IO tempmeter.indoor - IO tempmeter.outdoor " C"
IO tempmeter.indoor : LOG = "Average: " (IO tempmeter.indoor + IO tempmeter.outdoor) / 2 " C"

Without brackets, "Average: " IO tempmeter.indoor + IO tempmeter.outdoor " / 2" would log the sum followed by the / 2 text, as the division sign inside a quoted string is plain text.

SAVELOG

Writes the most recent log messages, kept in memory, to the daily log file, when the persistentLog option is false.

Action	Description
SAVELOG	writes the log messages kept in memory, and not written yet, to the daily log file

SAVELOG has no parameters.

With persistentLog set to false, log messages are not written to files, and HSYCO keeps only the last 1000 messages in memory, shown in the Manager's Log Viewer. SAVELOG writes them to the daily log files, so you can keep persistentLog disabled and still save the most recent log when something goes wrong, for later analysis.

Each message is written to the file of the day it was logged, in the same format used when persistentLog is true. Messages that are already in the file are not written again, so SAVELOG can be executed repeatedly: each time, it only adds the messages logged since the previous one. If more than 1000 messages were logged in between, the oldest are lost.

When persistentLog is false, HSYCO also writes them automatically just before it restarts because of an error, for example when the Exception Watchdog restarts it.

When persistentLog is true, SAVELOG has no effect.

Examples:

Save the log when the alarm panel reports a fault, together with a message that explains why:

IO alarm.fault = 1 : LOG = "Alarm panel fault", SAVELOG

Save the log when an I/O Server goes offline:

IO plc.connection = offline : SAVELOG

Mail

MAIL

Sends an email message.

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

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

note

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

Action	Description
MAIL to = from subject body	sends text and camera images. The body part of the mail is the last attribute. You can email the same message to multiple recipients

Parameters:

• to - the recipient address. It is possible to send the same email to a space separated list of email addresses. 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 - the sender e-mail address, as a single constant, quoted string, variable or data point (IO name)
• subject - a quoted string, variable or data point (IO name) with the message object
• body - the message body. To send an ordinary text, just enter a quoted text string. To send an image, append strings with the following format: cam:cameraname[:seconds_back[:frames_back]]. For example, “cam:camera1” sends a live frame from the camera called “camera1”; cam:camera1:0 sends the last recorded frame; cam:camera1:2 sends a frame that was recorded two seconds before the last recorded frame and cam:camera1:2:5 sends a frame that is 5 frames earlier than the one recorded two seconds before the last recording. To send files as attachments, use the following format: “file:file name”. The file path is relative to the HSYCO root directory. Each body part is a single term, like a quoted string, a variable or a data point (IO name), or a computation: as the body parts are not concatenated, use a variable to build a text from several parts.

Examples:

In this example, we send a message every minute, with the measured power load, to two email addresses:

TIME : $BODY = "Energy consumption for " $DATE:y/m/d$ " at " $TIME:h:m:s$ " is " $power$ " Watt"
$BODY : MAIL email1@hsyco.com email2@hsyco.com = hsyco@hsyco.net "Sent from HSYCO" $BODY

40 seconds after the alarm event, an email from the address hsyco@hsyco.net is sent to emal1@hsyco.com, with three images attached: the first is a real time image, the second is the last recorded image, the third one is the frame that was recorded 15 seconds before:

user "security" = "alarm" : CAMERAREC entrance = 30, PROGRAMTIMER rec = SET 40
PROGRAMTIMER rec : MAIL email1@hsyco.com = hsyco@hsyco.net "Sent from HSYCO" "Camera entrance" "cam:entrance" "cam:entrance:0" "cam:entrance:15"

At midnight, we are sending the energy.csv file in the data sub-directory as an attachment:

TIME = 0000: MAIL email1@hsyco.com = hsyco@hsyco.net "Sent from HSYCO" "Energy daily report." file:data/energy.csv

Send the current temperatures and their difference, each in its own body part:

USER report : MAIL email1@hsyco.com = hsyco@hsyco.net "Temperature report" "Indoor:" IO tempmeter.indoor "Outdoor:" IO tempmeter.outdoor "Difference:" IO tempmeter.indoor - IO tempmeter.outdoor

Network Services

PING

Tests the reachability of one or more hosts, identified by their hostnames or IP addresses, within the optional timeout defined in milliseconds (or using a default timeout of 200 ms).

This test generates PING events like PING hostname = ON if the host is reachable, or PING hostname = OFF if not reachable.

Action	Description
PING hostname	test the reachability of hostname, with 200ms response time-out
PING hostname = time	test the reachability of hostname, with a specific response time-out

Parameters:

• hostname - the IP device name or IP address
• time - response time-out, in milliseconds.

Examples:

TIME : PING 192.168.1.1
TIME : PING 192.168.1.200 192.168.1.201 = 1000

URL

Sends a GET or POST HTTP or HTTPS request to the specified url.

The HTTP basic or digest access authentication methods are supported.

Responses can be checked using the corresponding URL event.

Action	Description
URL GET "url"	sends a GET request without authentication
URL GET "user:password" "url"	sends a GET request with authentication
URL POST "url" "content_type" "data"	sends a POST request without authentication
URL POST "user:password" "url" "content_type" "data"	sends a POST request with authentication

Parameters:

• url - a full url, including the mandatory http:// or https:// query scheme and optional query string
• user:password - user and password for basic or digest access authentication
• content_type - the MIME type descriptor for the POST data
• data - the POST data (HTTP message body) sent with the request, encoded according to the content_type parameter (usually application/x-www-form-urlencoded for POST messages)

The URL parameters are single constants, quoted strings or variables; data points (IO name) and computations are not supported. To send a computed value, assign it to a variable first.

Examples:

HSYCOSTART: URL POST "http://10.0.0.5/cgi-bin/cmd.sh" "text/xml" "%3C%3Fxml%20version%3D%22..."

TIME = 0800 : URL GET "usr1:qi3qw" "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1"

URL "http://10.0.0.5/cgi-bin/cmd.sh?id=relay1" = 200 : LOG = "relay opened"

Public Announcement

AUDIO

See the Audio and Public Announcement documentation.

The AUDIO action is used to play text-to-speech messages or recorded audio files.

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.

Action	Description
AUDIO to = FILE filename	plays a pre-recorded audio file
AUDIO to = VOICE:voicename message	converts a text message to speech and plays the audio

Parameters:

• to - the audio destination (see table below)
• filename - the pathname of the audio file, relative to the HSYCO’s main directory
• voicename - the voice name for the text-to-speech engine; see the [[Audio and Public Announcement]] section for additional information
• message - the text message for text-to-speech conversion; you can use multiple strings, variables, data points and computations that will be automatically appended.

Examples:

The gong.mp3 audio file is played every minute through the server’s audio line out or internal speaker:

TIME : audio speaker = file "audio/gong.mp3"

Same as above, but played at the same time on all phones registered to the 239.255.255.245 multicast address and port 5555:

TIME : audio snom@239.255.255.245:5555 = file "audio/gong.mp3"

Same as above, but played to the Axis camera with id cam1:

TIME : audio axis@cam1 = file "audio/gong.mp3"

Converts a text message to speech using the en voice of the text-to-speech engine, and play the audio on an Axis camera:

TIME : audio axis@cam1 = "voice:en" "the time is " $time:h:m$

Same as above, but played by web browser with Acapela "Ryan" voice:

TIME : audio web = "voice:ryan22k" "the time is " $time:h:m$

Announce the indoor temperature and how much warmer it is than outdoor:

USER temperature : audio speaker = "voice:en" "the temperature is " IO tempmeter.indoor " degrees, " IO tempmeter.indoor - IO tempmeter.outdoor " more than outdoor"

Serial Communication Ports

COMM

Sends a sequence of bytes to the specified communication port.

Action	Description
COMM name = hexbytes	sends bytes to a serial port

note

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

Parameters:

• name - the name of the communications port, as defined in the CommPorts parameter in hsyco.ini
• hexbytes - string with the hexadecimal representation of the sequence of bytes to be sent. You can use multiple unquoted words, quoted strings, variables and data points, that will be appended to generate the byte stream sent to the communication port. Computations are supported too, but their result is a decimal number, not hexadecimal.

Examples:

COMM serialport = FE03C9104B27
COMM serialport = FE $body 27
COMM serialport = FE IO panel.code 27

Timers and Schedulers

USERTIMERSET

Sets a user timer.

Action	Description
USERTIMERSET timerid = on hour minute duration days	set the user timer

Parameters:

• on - true enables the timer; false disables the timer; null or empty string leaves the mode unchanged
• hour - start hour, from 0 to 23; null or empty string leaves the start hour unchanged
• minute - start minute, from 0 to 59; null or empty string leaves the start minute unchanged
• duration - duration in minutes, from 0 to 1439; null or empty string leaves the duration unchanged
• days - 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.

Each parameter is a single constant, variable or data point (IO name), so that the parameters can be told apart; computations are not supported, except in the last parameter (days). The user timer must be defined in the user interface.

Examples:

USERTIMERSET t1 = TRUE 11 50 null 67

enables timer "t1", setting the start time at 11:50, Saturday and Sunday, leaving the duration unchanged.

USER settimer : USERTIMERSET t1 = TRUE IO config.hour IO config.minute $duration 12345

enables timer "t1" from Monday to Friday, reading the start time from two data points and the duration from a variable.

User Interface

UISESSIONSET

Changes the dynamic attributes of an identified GUI object, just like UISET, but only affects the client session that generated the event that triggered this action.

UISESSIONSET can only be used with PAGE and USER events, and will override settings made with UISET.

Action	Description
UISESSIONSET id.attr = value	changes the attribute of every object with the specified ID in the client session. IDs are not unique, see Object IDs

Parameters:

• id - object id
• attr - attribute name
• value - attribute value. You can use multiple unquoted words, quoted strings, variables, data points and computations, that will be appended to form the value parameter.

Examples:

USER mybutton = 1 : UISESSIONSET mytext.italic = true
PAGE "myproject" = "climate" : UISESSIONSET mytext.text = "Indoor " IO tempmeter.indoor " C"

UISET

Changes the dynamic attributes of an identified GUI object.

Action	Description
UISET id.attr = value	changes the attribute of every object with the specified ID, in all pages and projects. IDs are not unique, see Object IDs

Parameters:

• id - object id. You can also target all objects of a type by specifying as id (<object's type>) (e.g. "UISET (user).fontweight = bold" will target all user objects)
• attr - attribute name
• value - attribute value. You can use multiple unquoted words, quoted strings, variables, data points and computations, that will be appended to form the value parameter.

Examples:

UISET mytext.italic = true
UISET mychart.barcolor = "#000000"

Show a temperature in Fahrenheit, and a dimmer level as a percentage:

IO tempmeter.indoor : UISET temperature.value = (IO tempmeter.indoor * 1.8 + 32) " °F"
IO dimmer.1 : UISET level.text = "Level " (IO dimmer.1 * 100) "%"

USER

Triggers a USER event and the userCommand(String name, String param) Java method and JavaScript function.

Can be used like a function call in EVENTS, and as a calling mechanism between EVENTS, JavaScript and Java.

Action	Description
USER name = param	executes the userCommand(name, param) Java method and JavaScript function, and the USER name = param event. Either name or param can be omitted, and will be passed as empty strings, but not both

Parameters:

• name - passed as the name parameter to USER and userCommand(). You can use multiple unquoted words, quoted strings and variables, that will be appended to form the name parameter
• param - passed as the param parameter to USER and userCommand(). You can use multiple unquoted words, quoted strings, variables, data points and computations, that will be appended to form the param parameter.

Examples:

USER hometheater = "on"
USER hometheater = "changed" $newvalue

Pass a computed value to a USER event, used as a function call:

IO tempmeter.indoor : USER setpoint = IO tempmeter.indoor + 0.5
USER setpoint : LOG = "new setpoint requested"