https://wiki.hsyco.com/3.7/api.php?action=feedcontributions&user=Gionatan&feedformat=atomHSYCO - User contributions [en]2024-03-29T06:07:54ZUser contributionsMediaWiki 1.33.0https://wiki.hsyco.com/3.7/index.php?title=Project&diff=9459Project2022-02-11T15:32:27Z<p>Gionatan: /* Project attributes */</p>
<hr />
<div>[[Category:User Interface]]<br />
A project defines a custom user interface, that allows the user to interact with the system.<br />
Each project has one or more [[page|pages]] that contain [[UI Objects]].<br />
<br />
On the index.hsm, the project's parameters are defined as directives (#<directive>)<br />
<br />
{{TOClimit|3}}<br />
<br />
== Parameters ==<br />
=== Skin ===<br />
Defines the graphical appearance of the project.<br />
<br />
==== Values ====<br />
*'''skin name''': the name of the skin. The standard skin provided with HSYCO is "blue"<br />
<br />
==== Syntax ====<br />
(#skin <skin name>)<br />
<br />
=== Language ===<br />
Defines the language used for all standard text messages of the Web interface.<br />
<br />
==== Values ====<br />
*'''language id''': the language used for the project:<br />
**cn: Chinese<br />
**en: English<br />
**fr: French<br />
**de: German<br />
**dk: Danish<br />
**it: Italian<br />
**pl: Polish<br />
**sl: Slovenian<br />
<br />
==== Syntax ====<br />
(#language <language id>)<br />
<br />
=== Header ===<br />
Specifies the page header, the text that normally appears in bookmarks and as the title of the browser's window.<br />
<br />
==== Values ====<br />
*'''title''': the project's title<br />
<br />
==== Syntax ====<br />
The header must be declared after all the directives and before the pages.<br />
(header <title>)<br />
<br />
=== Size ===<br />
Sets the project size as width and height. If the orientation mode is enabled, a second set of width and height is required. The first set refers to landscape mode, the second to portrait mode.<br />
<br />
==== Values ====<br />
*'''width''': the project's width in pixels<br />
*'''height''': the project's height in pixels<br />
<br />
==== Syntax ====<br />
(#size <width>x<height>)<br />
Or to enable orientation mode:<br />
(#size <width (landscape)>x<height (landscape)>x; <width (portrait)>x<height (portrait)>x)<br />
<br />
=== Device Image ===<br />
Enables or disables the camera or image pop-ups associated to devices in the project, as configured in the systemtopo.txt file.<br />
<br />
==== Syntax ====<br />
If omitted, the default value is "enabled".<br />
(#deviceimage disable)<br />
<br />
=== Kiosk ===<br />
The kiosk mode removes the menu bar and borders, for digital signage or kiosks applications where you want to have a full-screen display of your pages. "lock" also disables the navigation functions.<br />
<br />
==== Values ====<br />
*'''mode''': disabled, enabled or locked<br />
<br />
==== Syntax ====<br />
If omitted, the default value is "disabled".<br />
"enabled" mode:<br />
(#kiosk nolock)<br />
"locked" mode:<br />
(#kiosk lock)<br />
<br />
=== Scale ===<br />
Sets a scaling value to resize the whole page area from the original size.<br />
<br />
==== Values ====<br />
*'''auto''': the user interface is automatically expanded to fill the available browser area<br />
*'''fit''': the user interface is expanded as with auto, but also reduced if the available browser area is smaller than the original project's size<br />
*'''factor''': scale factor, as a decimal positive number. Numbers greater than 1.0 create a magnification effect, proportionally increasing the size of the page and its content; numbers smaller than 1.0 make the page and its content smaller than the original<br />
<br />
==== Syntax ====<br />
(#scale <value>)<br />
<br />
=== Locked ===<br />
Disables any user command for this project. Users will be able to navigate between pages and see the current status, but all commands will be locked.<br />
<br />
==== Syntax ====<br />
If omitted, the project is unlocked.<br />
(#locked <true>)<br />
<br />
=== Background ===<br />
Defines the project's background for all pages.<br />
<br />
==== Values ====<br />
*'''image''': the image file name<br />
<br />
==== Syntax ====<br />
It must be defined after the header object, before the pages.<br />
(background!<project's name>.background <image>)<br />
<br />
{{Note: IMG Filename}}<br />
<br />
=== Camera List ===<br />
Defines the display name of each camera. It is required when you are displaying cameras in the index.hsm file. If you need to prevent access to one or more cameras for a specific index.hsm page, you can set that camera with an empty name, “”, or the reserved words “null” or “empty”. These cameras will be skipped by the camera rolling function, or when manually going from one camera to the next.<br />
<br />
==== Values ====<br />
*'''list''': the comma separated list of all cameras, in the same order in which the cameras' ids appear in the Cameras parameter in hsyco.ini. The names must be enclosed in double quotes.<br />
<br />
==== Syntax ====<br />
(#cameralist <list>)<br />
E.g.<br />
(#cameralist "garden","openspace")<br />
<br />
=== Camera Overlay ===<br />
Defines custom overlay image masks for each camera. It is optional, and if not specified HSYCO will use the standard overlays.<br />
<br />
==== Values ====<br />
*'''list''': the list of the type of overlay for each camera defined in hsyco.ini, the elements are separated by commas:<br />
** "default": default overlay for the PTZ cameras<br />
** "": default overlay for the PTZ cameras<br />
** "null": no overlay<br />
** "filename.png": customized file, in the www/<project's name>/img or www/img directory.<br />
<br />
==== Syntax ====<br />
(#cameraoverlay <overlay list>)<br />
E.g.<br />
(#cameraoverlay "","null","myoverlay.png")<br />
<br />
=== Camera Grid Headers ===<br />
Defines the display name of each camera grid. It is required when you are including camera grids in the project.<br />
<br />
==== Values ====<br />
*'''list''': the list of the cameras grids’ names, listed in order starting from 1, as they appear in the CameraGrid.id parameters in hsyco.ini. The names must be enclosed in double quotes and separated by commas.<br />
<br />
==== Syntax ====<br />
(#cameragridlist <list>)<br />
E.g.<br />
(#cameragridlist "Garden","Living Room")<br />
<br />
=== Style ===<br />
Defines style attributes that modify the appearance of the current skin. It is used to customize a skin, changing for example the color of the background.<br />
For a complete description of possible values, see [[Project Style]].<br />
<br />
==== Values ====<br />
*'''style''': the semicolon separated list of attributes and values.<br />
<br />
==== Syntax ====<br />
(#style <style>)<br />
E.g.<br />
(#style body-background-color=red; pages-background-color=green; header-background-color=blue)<br />
<br />
=== UISet ===<br />
Defines a set of UISets that apply to the specified [[UI Objects]]. Sets are specified as ''<object's id>.<attribute name>=<value>''. A UISet without the object's id is applied directly to the project object (E.g. ''autoreload=false'' is the same as ''<project's name>.autoreload=false'').<br />
To apply a UISet to all objects of a type, specify it as ''(<object's type>).<attribute name>=<value>'' (e.g. "(user).fontweight=bold").<br />
<br />
==== Values ====<br />
*'''uiset list''': list of attributes and values.<br />
<br />
==== Syntax ====<br />
(#uiset <uiset list>)<br />
E.g.<br />
(#uiset autoreload=false; myinput.value=hello)<br />
<br />
== Accessibility ==<br />
The accessible mode, which can be enabled through a UISet (see the '''accessibility''' attribute below), adds enhancements for VoiceOver when the browser supports it. These allow VoiceOver to recognize buttons and their states. A custom interface optimized for VoiceOver can include the following [[UI Objects|UI objects]]:<br />
* [[link]]<br />
* [[text]]<br />
* [[button]]<br />
* [[user]]<br />
<br />
== HSYCO App Support ==<br />
=== Favorite Pages ===<br />
Selected pages can be passed to the HSYCO App as favorite pages.<br />
These pages will appear on the HSYCO App interface for quick access, when the current interface is displayed.<br />
Favorite pages are specified through the "app_favpages" UISet, with the following JSON format:<br />
{"label":"<page label>", "page":"<page id>"}, {"label":"...<br />
<br />
E.g.<br />
{"label":"Home", "page":"menu"}, {"label":"Cam", "page":"cameras"}<br />
<br />
=== Apple Watch Page ===<br />
Through the HSYCO app it's possible to configure a page for the Apple Watch. This can be done visually with the Project Editor or through the "app_watch" UISet, which is useful for interfaces built dinamically.<br />
<br />
An "app_watch" UISet is structured as follows:<br />
{type:<type>, label:<label>, action:<action>}, {type: ...} ...<br />
<br />
Each comma separated { ... } block defines a UI object with its attributes.<br />
Each object has a type attribute (ex. label, button, slider...) and various additional attributes, depending on its type.<br />
<br />
For more information read the [[Apple_Watch_Interface|Apple Watch Interface documentation]].<br />
<br />
== UI Attributes ==<br />
=== Project attributes ===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|accessibility<br />
|true<br />
|Enabled accessible mode<br />
|-<br />
|false<br />
|Disable accessible mode<br />
|-<br />
<br />
|app_favpages<br />
|<configuration string><br />
|Configure the favorite pages, displayed as links on the HSYCO App interface<br />
|-<br />
<br />
|app_watch<br />
|<configuration string><br />
|Configure the apple watch page associated to this project, accessible through the HSYCO App<br />
|-<br />
<br />
|audiochannel<br />
|<string><br />
|The name of an audio channel, to use with [[Audio and Public Announcement]]. If set, audio from a different channel won't be played. The default value is the name of the project.<br />
|-<br />
<br />
|rowspan="2"|autoreload<br />
|true<br />
|Default, the browser will automatically reload the page when the project changes<br />
|-<br />
|false<br />
|The browser won't automatically reload the page when the project changes<br />
|-<br />
<br />
|blink<br />
|false<br />
|Disable all blinking animations in the project<br />
|-<br />
<br />
|rowspan="2"|fullwindow<br />
|true<br />
|When an object (e.g. camerapanel, datalogger) switches to fullscreen mode, it will occupy the whole browser's window instead of actually going fullscreen<br />
|-<br />
|false<br />
|Default value. When an object (e.g. camerapanel, datalogger) switches to fullscreen mode, the browser page will switch to fullscreen<br />
|-<br />
<br />
|gestures<br />
|false<br />
|Disable all gestures for the project<br />
|-<br />
<br />
|gohome<br />
|<seconds><br />
|After <seconds> seconds of inactivity, go to the menu page, or the page set with the page=<page name> URL option<br />
|-<br />
<br />
|rowspan="4"|kiosk<br />
|nolock<br />
|Kiosk mode, not locked<br />
|-<br />
|lock<br />
|Kiosk mode, locked (user navigation is disabled)<br />
|-<br />
|strict<br />
|Kiosk mode, total height excludes the height of the header/footer, so the kiosk layout can stay the same as a non-kiosk<br />
|-<br />
|false<br />
|Kiosk mode disabled<br />
|-<br />
<br />
|rowspan="2"|lock<br />
|<page name><br />
|Show the specified page (or modal pop-up) and disable user navigation<br />
|-<br />
|"" (empty string)<br />
|Unlock the interface, default<br />
|-<br />
<br />
|rowspan="3"|page<br />
|<page name><br />
|Show a page.<br />
This UISet shows the page only if the project is running. Setting this attribute and then loading the project won't trigger the page change.<br />
|-<br />
|"" (empty string)<br />
|Goes to the previous page (same as pressing the back button), without permorming any checks (as opposed to the pageback attribute).<br />
|-<br />
|logout<br />
|forces a log out of the current session and shows the PIN pop-up<br />
|-<br />
<br />
|pageback<br />
|<page name><br />
|If the current page was set with a "page" attribute and its name is the same as <page name>, navigate to the previous page<br />
|-<br />
<br />
|rowspan="3"|scale<br />
|auto<br />
|The user interface is automatically expanded to fill the available browser area<br />
|-<br />
|fit<br />
|The user interface is expanded as with auto, but also reduced if the available browser area is smaller than the original project's size<br />
|-<br />
|factor<br />
|The user interfaced is scaled to the specified factor, a decimal positive number. <br />
Numbers greater than 1.0 create a magnification effect, proportionally increasing the size of the page and its content; numbers smaller than 1.0 make the page and its content smaller than the original<br />
|-<br />
<br />
|rowspan="2"|screensaver<br />
|<seconds><br />
|Enters screensaver mode after <seconds> time of inactivity (see the '''[[Screensaver| Screensaver]]''' page for more details)<br />
|-<br />
|false<br />
|disables screensaver mode (0 has the same effect)<br />
|-<br />
<br />
|rowspan="3"|screensaverimage<br />
|&lt;full url <nowiki>(http://...)</nowiki>&gt; <br />
|rowspan="2"|Set the image source<br />
|-<br />
|<nowiki>&lt;path relative to the project's img/ path&gt;</nowiki><br />
|-<br />
|<empty string><br />
|No screensaver image (default value)<br />
|-<br />
<br />
|rowspan="2"|screensaverimagesize<br />
|fit<br />
|Set the screensaver image size so that it is fully contained in the interface (default value)<br />
|-<br />
|crop<br />
|Set the screensaver image size so that it covers the interface<br />
|-<br />
<br />
|}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Project&diff=9452Project2021-05-13T10:53:21Z<p>Gionatan: /* Project attributes */</p>
<hr />
<div>[[Category:User Interface]]<br />
A project defines a custom user interface, that allows the user to interact with the system.<br />
Each project has one or more [[page|pages]] that contain [[UI Objects]].<br />
<br />
On the index.hsm, the project's parameters are defined as directives (#<directive>)<br />
<br />
{{TOClimit|3}}<br />
<br />
== Parameters ==<br />
=== Skin ===<br />
Defines the graphical appearance of the project.<br />
<br />
==== Values ====<br />
*'''skin name''': the name of the skin. The standard skin provided with HSYCO is "blue"<br />
<br />
==== Syntax ====<br />
(#skin <skin name>)<br />
<br />
=== Language ===<br />
Defines the language used for all standard text messages of the Web interface.<br />
<br />
==== Values ====<br />
*'''language id''': the language used for the project:<br />
**cn: Chinese<br />
**en: English<br />
**fr: French<br />
**de: German<br />
**dk: Danish<br />
**it: Italian<br />
**pl: Polish<br />
**sl: Slovenian<br />
<br />
==== Syntax ====<br />
(#language <language id>)<br />
<br />
=== Header ===<br />
Specifies the page header, the text that normally appears in bookmarks and as the title of the browser's window.<br />
<br />
==== Values ====<br />
*'''title''': the project's title<br />
<br />
==== Syntax ====<br />
The header must be declared after all the directives and before the pages.<br />
(header <title>)<br />
<br />
=== Size ===<br />
Sets the project size as width and height. If the orientation mode is enabled, a second set of width and height is required. The first set refers to landscape mode, the second to portrait mode.<br />
<br />
==== Values ====<br />
*'''width''': the project's width in pixels<br />
*'''height''': the project's height in pixels<br />
<br />
==== Syntax ====<br />
(#size <width>x<height>)<br />
Or to enable orientation mode:<br />
(#size <width (landscape)>x<height (landscape)>x; <width (portrait)>x<height (portrait)>x)<br />
<br />
=== Device Image ===<br />
Enables or disables the camera or image pop-ups associated to devices in the project, as configured in the systemtopo.txt file.<br />
<br />
==== Syntax ====<br />
If omitted, the default value is "enabled".<br />
(#deviceimage disable)<br />
<br />
=== Kiosk ===<br />
The kiosk mode removes the menu bar and borders, for digital signage or kiosks applications where you want to have a full-screen display of your pages. "lock" also disables the navigation functions.<br />
<br />
==== Values ====<br />
*'''mode''': disabled, enabled or locked<br />
<br />
==== Syntax ====<br />
If omitted, the default value is "disabled".<br />
"enabled" mode:<br />
(#kiosk nolock)<br />
"locked" mode:<br />
(#kiosk lock)<br />
<br />
=== Scale ===<br />
Sets a scaling value to resize the whole page area from the original size.<br />
<br />
==== Values ====<br />
*'''auto''': the user interface is automatically expanded to fill the available browser area<br />
*'''fit''': the user interface is expanded as with auto, but also reduced if the available browser area is smaller than the original project's size<br />
*'''factor''': scale factor, as a decimal positive number. Numbers greater than 1.0 create a magnification effect, proportionally increasing the size of the page and its content; numbers smaller than 1.0 make the page and its content smaller than the original<br />
<br />
==== Syntax ====<br />
(#scale <value>)<br />
<br />
=== Locked ===<br />
Disables any user command for this project. Users will be able to navigate between pages and see the current status, but all commands will be locked.<br />
<br />
==== Syntax ====<br />
If omitted, the project is unlocked.<br />
(#locked <true>)<br />
<br />
=== Background ===<br />
Defines the project's background for all pages.<br />
<br />
==== Values ====<br />
*'''image''': the image file name<br />
<br />
==== Syntax ====<br />
It must be defined after the header object, before the pages.<br />
(background!<project's name>.background <image>)<br />
<br />
{{Note: IMG Filename}}<br />
<br />
=== Camera List ===<br />
Defines the display name of each camera. It is required when you are displaying cameras in the index.hsm file. If you need to prevent access to one or more cameras for a specific index.hsm page, you can set that camera with an empty name, “”, or the reserved words “null” or “empty”. These cameras will be skipped by the camera rolling function, or when manually going from one camera to the next.<br />
<br />
==== Values ====<br />
*'''list''': the comma separated list of all cameras, in the same order in which the cameras' ids appear in the Cameras parameter in hsyco.ini. The names must be enclosed in double quotes.<br />
<br />
==== Syntax ====<br />
(#cameralist <list>)<br />
E.g.<br />
(#cameralist "garden","openspace")<br />
<br />
=== Camera Overlay ===<br />
Defines custom overlay image masks for each camera. It is optional, and if not specified HSYCO will use the standard overlays.<br />
<br />
==== Values ====<br />
*'''list''': the list of the type of overlay for each camera defined in hsyco.ini, the elements are separated by commas:<br />
** "default": default overlay for the PTZ cameras<br />
** "": default overlay for the PTZ cameras<br />
** "null": no overlay<br />
** "filename.png": customized file, in the www/<project's name>/img or www/img directory.<br />
<br />
==== Syntax ====<br />
(#cameraoverlay <overlay list>)<br />
E.g.<br />
(#cameraoverlay "","null","myoverlay.png")<br />
<br />
=== Camera Grid Headers ===<br />
Defines the display name of each camera grid. It is required when you are including camera grids in the project.<br />
<br />
==== Values ====<br />
*'''list''': the list of the cameras grids’ names, listed in order starting from 1, as they appear in the CameraGrid.id parameters in hsyco.ini. The names must be enclosed in double quotes and separated by commas.<br />
<br />
==== Syntax ====<br />
(#cameragridlist <list>)<br />
E.g.<br />
(#cameragridlist "Garden","Living Room")<br />
<br />
=== Style ===<br />
Defines style attributes that modify the appearance of the current skin. It is used to customize a skin, changing for example the color of the background.<br />
For a complete description of possible values, see [[Project Style]].<br />
<br />
==== Values ====<br />
*'''style''': the semicolon separated list of attributes and values.<br />
<br />
==== Syntax ====<br />
(#style <style>)<br />
E.g.<br />
(#style body-background-color=red; pages-background-color=green; header-background-color=blue)<br />
<br />
=== UISet ===<br />
Defines a set of UISets that apply to the specified [[UI Objects]]. Sets are specified as ''<object's id>.<attribute name>=<value>''. A UISet without the object's id is applied directly to the project object (E.g. ''autoreload=false'' is the same as ''<project's name>.autoreload=false'').<br />
To apply a UISet to all objects of a type, specify it as ''(<object's type>).<attribute name>=<value>'' (e.g. "(user).fontweight=bold").<br />
<br />
==== Values ====<br />
*'''uiset list''': list of attributes and values.<br />
<br />
==== Syntax ====<br />
(#uiset <uiset list>)<br />
E.g.<br />
(#uiset autoreload=false; myinput.value=hello)<br />
<br />
== Accessibility ==<br />
The accessible mode, which can be enabled through a UISet (see the '''accessibility''' attribute below), adds enhancements for VoiceOver when the browser supports it. These allow VoiceOver to recognize buttons and their states. A custom interface optimized for VoiceOver can include the following [[UI Objects|UI objects]]:<br />
* [[link]]<br />
* [[text]]<br />
* [[button]]<br />
* [[user]]<br />
<br />
== HSYCO App Support ==<br />
=== Favorite Pages ===<br />
Selected pages can be passed to the HSYCO App as favorite pages.<br />
These pages will appear on the HSYCO App interface for quick access, when the current interface is displayed.<br />
Favorite pages are specified through the "app_favpages" UISet, with the following JSON format:<br />
{"label":"<page label>", "page":"<page id>"}, {"label":"...<br />
<br />
E.g.<br />
{"label":"Home", "page":"menu"}, {"label":"Cam", "page":"cameras"}<br />
<br />
=== Apple Watch Page ===<br />
Through the HSYCO app it's possible to configure a page for the Apple Watch. This can be done visually with the Project Editor or through the "app_watch" UISet, which is useful for interfaces built dinamically.<br />
<br />
An "app_watch" UISet is structured as follows:<br />
{type:<type>, label:<label>, action:<action>}, {type: ...} ...<br />
<br />
Each comma separated { ... } block defines a UI object with its attributes.<br />
Each object has a type attribute (ex. label, button, slider...) and various additional attributes, depending on its type.<br />
<br />
For more information read the [[Apple_Watch_Interface|Apple Watch Interface documentation]].<br />
<br />
== UI Attributes ==<br />
=== Project attributes ===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|accessibility<br />
|true<br />
|Enabled accessible mode<br />
|-<br />
|false<br />
|Disable accessible mode<br />
|-<br />
<br />
|app_favpages<br />
|<configuration string><br />
|Configure the favorite pages, displayed as links on the HSYCO App interface<br />
|-<br />
<br />
|app_watch<br />
|<configuration string><br />
|Configure the apple watch page associated to this project, accessible through the HSYCO App<br />
|-<br />
<br />
|audiochannel<br />
|<string><br />
|The name of an audio channel, to use with [[Audio and Public Announcement]]. If set, audio from a different channel won't be played. The default value is the name of the project.<br />
|-<br />
<br />
|rowspan="2"|autoreload<br />
|true<br />
|Default, the browser will automatically reload the page when the project changes<br />
|-<br />
|false<br />
|The browser won't automatically reload the page when the project changes<br />
|-<br />
<br />
|blink<br />
|false<br />
|Disable all blinking animations in the project<br />
|-<br />
<br />
|rowspan="2"|fullwindow<br />
|true<br />
|When an object (e.g. camerapanel, datalogger) switches to fullscreen mode, it will occupy the whole browser's window instead of actually going fullscreen<br />
|-<br />
|false<br />
|Default value. When an object (e.g. camerapanel, datalogger) switches to fullscreen mode, the browser page will switch to fullscreen<br />
|-<br />
<br />
|gestures<br />
|false<br />
|Disable all gestures for the project<br />
|-<br />
<br />
|gohome<br />
|<seconds><br />
|After <seconds> seconds of inactivity, go to the menu page, or the page set with the page=<page name> URL option<br />
|-<br />
<br />
|rowspan="4"|kiosk<br />
|nolock<br />
|Kiosk mode, not locked<br />
|-<br />
|lock<br />
|Kiosk mode, locked (user navigation is disabled)<br />
|-<br />
|strict<br />
|Kiosk mode, total height excludes the height of the header/footer, so the kiosk layout can stay the same as a non-kiosk<br />
|-<br />
|false<br />
|Kiosk mode disabled<br />
|-<br />
<br />
|rowspan="2"|lock<br />
|<page name><br />
|Show the specified page (or modal pop-up) and disable user navigation<br />
|-<br />
|"" (empty string)<br />
|Unlock the interface, default<br />
|-<br />
<br />
|rowspan="2"|page<br />
|<page name><br />
|Show a page.<br />
This UISet shows the page only if the project is running. Setting this attribute and then loading the project won't trigger the page change.<br />
|-<br />
|"" (empty string)<br />
|Goes to the previous page (same as pressing the back button), without permorming any checks (as opposed to the pageback attribute).<br />
|-<br />
|logout<br />
|forces a log out of the current session and shows the PIN pop-up<br />
|-<br />
<br />
|pageback<br />
|<page name><br />
|If the current page was set with a "page" attribute and its name is the same as <page name>, navigate to the previous page<br />
|-<br />
<br />
|rowspan="3"|scale<br />
|auto<br />
|The user interface is automatically expanded to fill the available browser area<br />
|-<br />
|fit<br />
|The user interface is expanded as with auto, but also reduced if the available browser area is smaller than the original project's size<br />
|-<br />
|factor<br />
|The user interfaced is scaled to the specified factor, a decimal positive number. <br />
Numbers greater than 1.0 create a magnification effect, proportionally increasing the size of the page and its content; numbers smaller than 1.0 make the page and its content smaller than the original<br />
|-<br />
<br />
|rowspan="2"|screensaver<br />
|<seconds><br />
|Enters screensaver mode after <seconds> time of inactivity (see the '''[[Screensaver| Screensaver]]''' page for more details)<br />
|-<br />
|false<br />
|disables screensaver mode (0 has the same effect)<br />
|-<br />
<br />
|rowspan="3"|screensaverimage<br />
|&lt;full url <nowiki>(http://...)</nowiki>&gt; <br />
|rowspan="2"|Set the image source<br />
|-<br />
|<nowiki>&lt;path relative to the project's img/ path&gt;</nowiki><br />
|-<br />
|<empty string><br />
|No screensaver image (default value)<br />
|-<br />
<br />
|rowspan="2"|screensaverimagesize<br />
|fit<br />
|Set the screensaver image size so that it is fully contained in the interface (default value)<br />
|-<br />
|crop<br />
|Set the screensaver image size so that it covers the interface<br />
|-<br />
<br />
|}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Project&diff=9451Project2021-05-13T10:52:11Z<p>Gionatan: /* Project attributes */</p>
<hr />
<div>[[Category:User Interface]]<br />
A project defines a custom user interface, that allows the user to interact with the system.<br />
Each project has one or more [[page|pages]] that contain [[UI Objects]].<br />
<br />
On the index.hsm, the project's parameters are defined as directives (#<directive>)<br />
<br />
{{TOClimit|3}}<br />
<br />
== Parameters ==<br />
=== Skin ===<br />
Defines the graphical appearance of the project.<br />
<br />
==== Values ====<br />
*'''skin name''': the name of the skin. The standard skin provided with HSYCO is "blue"<br />
<br />
==== Syntax ====<br />
(#skin <skin name>)<br />
<br />
=== Language ===<br />
Defines the language used for all standard text messages of the Web interface.<br />
<br />
==== Values ====<br />
*'''language id''': the language used for the project:<br />
**cn: Chinese<br />
**en: English<br />
**fr: French<br />
**de: German<br />
**dk: Danish<br />
**it: Italian<br />
**pl: Polish<br />
**sl: Slovenian<br />
<br />
==== Syntax ====<br />
(#language <language id>)<br />
<br />
=== Header ===<br />
Specifies the page header, the text that normally appears in bookmarks and as the title of the browser's window.<br />
<br />
==== Values ====<br />
*'''title''': the project's title<br />
<br />
==== Syntax ====<br />
The header must be declared after all the directives and before the pages.<br />
(header <title>)<br />
<br />
=== Size ===<br />
Sets the project size as width and height. If the orientation mode is enabled, a second set of width and height is required. The first set refers to landscape mode, the second to portrait mode.<br />
<br />
==== Values ====<br />
*'''width''': the project's width in pixels<br />
*'''height''': the project's height in pixels<br />
<br />
==== Syntax ====<br />
(#size <width>x<height>)<br />
Or to enable orientation mode:<br />
(#size <width (landscape)>x<height (landscape)>x; <width (portrait)>x<height (portrait)>x)<br />
<br />
=== Device Image ===<br />
Enables or disables the camera or image pop-ups associated to devices in the project, as configured in the systemtopo.txt file.<br />
<br />
==== Syntax ====<br />
If omitted, the default value is "enabled".<br />
(#deviceimage disable)<br />
<br />
=== Kiosk ===<br />
The kiosk mode removes the menu bar and borders, for digital signage or kiosks applications where you want to have a full-screen display of your pages. "lock" also disables the navigation functions.<br />
<br />
==== Values ====<br />
*'''mode''': disabled, enabled or locked<br />
<br />
==== Syntax ====<br />
If omitted, the default value is "disabled".<br />
"enabled" mode:<br />
(#kiosk nolock)<br />
"locked" mode:<br />
(#kiosk lock)<br />
<br />
=== Scale ===<br />
Sets a scaling value to resize the whole page area from the original size.<br />
<br />
==== Values ====<br />
*'''auto''': the user interface is automatically expanded to fill the available browser area<br />
*'''fit''': the user interface is expanded as with auto, but also reduced if the available browser area is smaller than the original project's size<br />
*'''factor''': scale factor, as a decimal positive number. Numbers greater than 1.0 create a magnification effect, proportionally increasing the size of the page and its content; numbers smaller than 1.0 make the page and its content smaller than the original<br />
<br />
==== Syntax ====<br />
(#scale <value>)<br />
<br />
=== Locked ===<br />
Disables any user command for this project. Users will be able to navigate between pages and see the current status, but all commands will be locked.<br />
<br />
==== Syntax ====<br />
If omitted, the project is unlocked.<br />
(#locked <true>)<br />
<br />
=== Background ===<br />
Defines the project's background for all pages.<br />
<br />
==== Values ====<br />
*'''image''': the image file name<br />
<br />
==== Syntax ====<br />
It must be defined after the header object, before the pages.<br />
(background!<project's name>.background <image>)<br />
<br />
{{Note: IMG Filename}}<br />
<br />
=== Camera List ===<br />
Defines the display name of each camera. It is required when you are displaying cameras in the index.hsm file. If you need to prevent access to one or more cameras for a specific index.hsm page, you can set that camera with an empty name, “”, or the reserved words “null” or “empty”. These cameras will be skipped by the camera rolling function, or when manually going from one camera to the next.<br />
<br />
==== Values ====<br />
*'''list''': the comma separated list of all cameras, in the same order in which the cameras' ids appear in the Cameras parameter in hsyco.ini. The names must be enclosed in double quotes.<br />
<br />
==== Syntax ====<br />
(#cameralist <list>)<br />
E.g.<br />
(#cameralist "garden","openspace")<br />
<br />
=== Camera Overlay ===<br />
Defines custom overlay image masks for each camera. It is optional, and if not specified HSYCO will use the standard overlays.<br />
<br />
==== Values ====<br />
*'''list''': the list of the type of overlay for each camera defined in hsyco.ini, the elements are separated by commas:<br />
** "default": default overlay for the PTZ cameras<br />
** "": default overlay for the PTZ cameras<br />
** "null": no overlay<br />
** "filename.png": customized file, in the www/<project's name>/img or www/img directory.<br />
<br />
==== Syntax ====<br />
(#cameraoverlay <overlay list>)<br />
E.g.<br />
(#cameraoverlay "","null","myoverlay.png")<br />
<br />
=== Camera Grid Headers ===<br />
Defines the display name of each camera grid. It is required when you are including camera grids in the project.<br />
<br />
==== Values ====<br />
*'''list''': the list of the cameras grids’ names, listed in order starting from 1, as they appear in the CameraGrid.id parameters in hsyco.ini. The names must be enclosed in double quotes and separated by commas.<br />
<br />
==== Syntax ====<br />
(#cameragridlist <list>)<br />
E.g.<br />
(#cameragridlist "Garden","Living Room")<br />
<br />
=== Style ===<br />
Defines style attributes that modify the appearance of the current skin. It is used to customize a skin, changing for example the color of the background.<br />
For a complete description of possible values, see [[Project Style]].<br />
<br />
==== Values ====<br />
*'''style''': the semicolon separated list of attributes and values.<br />
<br />
==== Syntax ====<br />
(#style <style>)<br />
E.g.<br />
(#style body-background-color=red; pages-background-color=green; header-background-color=blue)<br />
<br />
=== UISet ===<br />
Defines a set of UISets that apply to the specified [[UI Objects]]. Sets are specified as ''<object's id>.<attribute name>=<value>''. A UISet without the object's id is applied directly to the project object (E.g. ''autoreload=false'' is the same as ''<project's name>.autoreload=false'').<br />
To apply a UISet to all objects of a type, specify it as ''(<object's type>).<attribute name>=<value>'' (e.g. "(user).fontweight=bold").<br />
<br />
==== Values ====<br />
*'''uiset list''': list of attributes and values.<br />
<br />
==== Syntax ====<br />
(#uiset <uiset list>)<br />
E.g.<br />
(#uiset autoreload=false; myinput.value=hello)<br />
<br />
== Accessibility ==<br />
The accessible mode, which can be enabled through a UISet (see the '''accessibility''' attribute below), adds enhancements for VoiceOver when the browser supports it. These allow VoiceOver to recognize buttons and their states. A custom interface optimized for VoiceOver can include the following [[UI Objects|UI objects]]:<br />
* [[link]]<br />
* [[text]]<br />
* [[button]]<br />
* [[user]]<br />
<br />
== HSYCO App Support ==<br />
=== Favorite Pages ===<br />
Selected pages can be passed to the HSYCO App as favorite pages.<br />
These pages will appear on the HSYCO App interface for quick access, when the current interface is displayed.<br />
Favorite pages are specified through the "app_favpages" UISet, with the following JSON format:<br />
{"label":"<page label>", "page":"<page id>"}, {"label":"...<br />
<br />
E.g.<br />
{"label":"Home", "page":"menu"}, {"label":"Cam", "page":"cameras"}<br />
<br />
=== Apple Watch Page ===<br />
Through the HSYCO app it's possible to configure a page for the Apple Watch. This can be done visually with the Project Editor or through the "app_watch" UISet, which is useful for interfaces built dinamically.<br />
<br />
An "app_watch" UISet is structured as follows:<br />
{type:<type>, label:<label>, action:<action>}, {type: ...} ...<br />
<br />
Each comma separated { ... } block defines a UI object with its attributes.<br />
Each object has a type attribute (ex. label, button, slider...) and various additional attributes, depending on its type.<br />
<br />
For more information read the [[Apple_Watch_Interface|Apple Watch Interface documentation]].<br />
<br />
== UI Attributes ==<br />
=== Project attributes ===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|accessibility<br />
|true<br />
|Enabled accessible mode<br />
|-<br />
|false<br />
|Disable accessible mode<br />
|-<br />
<br />
|app_favpages<br />
|<configuration string><br />
|Configure the favorite pages, displayed as links on the HSYCO App interface<br />
|-<br />
<br />
|app_watch<br />
|<configuration string><br />
|Configure the apple watch page associated to this project, accessible through the HSYCO App<br />
|-<br />
<br />
|audiochannel<br />
|<string><br />
|The name of an audio channel, to use with [[Audio and Public Announcement]]. If set, audio from a different channel won't be played. The default value is the name of the project.<br />
|-<br />
<br />
|rowspan="2"|autoreload<br />
|true<br />
|Default, the browser will automatically reload the page when the project changes<br />
|-<br />
|false<br />
|The browser won't automatically reload the page when the project changes<br />
|-<br />
<br />
|blink<br />
|false<br />
|Disable all blinking animations in the project<br />
|-<br />
<br />
|rowspan="2"|fullwindow<br />
|true<br />
|When an object (e.g. camerapanel, datalogger) switches to fullscreen mode, it will occupy the whole browser's window instead of actually going fullscreen<br />
|-<br />
|false<br />
|Default value. When an object (e.g. camerapanel, datalogger) switches to fullscreen mode, the browser page will switch to fullscreen<br />
|-<br />
<br />
|gestures<br />
|false<br />
|Disable all gestures for the project<br />
|-<br />
<br />
|gohome<br />
|<seconds><br />
|After <seconds> seconds of inactivity, go to the menu page, or the page set with the page=<page name> URL option<br />
|-<br />
<br />
|rowspan="4"|kiosk<br />
|nolock<br />
|Kiosk mode, not locked<br />
|-<br />
|lock<br />
|Kiosk mode, locked (user navigation is disabled)<br />
|-<br />
|strict<br />
|Kiosk mode, total height excludes the height of the header/footer, so the kiosk layout can stay the same as a non-kiosk<br />
|-<br />
|false<br />
|Kiosk mode disabled<br />
|-<br />
<br />
|rowspan="2"|lock<br />
|<page name><br />
|Show the specified page (or modal pop-up) and disable user navigation<br />
|-<br />
|"" (empty string)<br />
|Unlock the interface, default<br />
|-<br />
<br />
|rowspan="2"|page<br />
|<page name><br />
|Show a page. This UISet shows the page only if the project is running. Setting this attribute and then loading the project won't trigger the page change.<br />
|-<br />
|"" (empty string)<br />
|Goes to the previous page (same as pressing the back button), without permorming any checks (as opposed to the pageback attribute).<br />
|-<br />
|logout<br />
|forces a log out of the current session and shows the PIN pop-up<br />
|-<br />
<br />
|pageback<br />
|<page name><br />
|If the current page was set with a "page" attribute and its name is the same as <page name>, navigate to the previous page<br />
|-<br />
<br />
|rowspan="3"|scale<br />
|auto<br />
|The user interface is automatically expanded to fill the available browser area<br />
|-<br />
|fit<br />
|The user interface is expanded as with auto, but also reduced if the available browser area is smaller than the original project's size<br />
|-<br />
|factor<br />
|The user interfaced is scaled to the specified factor, a decimal positive number. <br />
Numbers greater than 1.0 create a magnification effect, proportionally increasing the size of the page and its content; numbers smaller than 1.0 make the page and its content smaller than the original<br />
|-<br />
<br />
|rowspan="2"|screensaver<br />
|<seconds><br />
|Enters screensaver mode after <seconds> time of inactivity (see the '''[[Screensaver| Screensaver]]''' page for more details)<br />
|-<br />
|false<br />
|disables screensaver mode (0 has the same effect)<br />
|-<br />
<br />
|rowspan="3"|screensaverimage<br />
|&lt;full url <nowiki>(http://...)</nowiki>&gt; <br />
|rowspan="2"|Set the image source<br />
|-<br />
|<nowiki>&lt;path relative to the project's img/ path&gt;</nowiki><br />
|-<br />
|<empty string><br />
|No screensaver image (default value)<br />
|-<br />
<br />
|rowspan="2"|screensaverimagesize<br />
|fit<br />
|Set the screensaver image size so that it is fully contained in the interface (default value)<br />
|-<br />
|crop<br />
|Set the screensaver image size so that it covers the interface<br />
|-<br />
<br />
|}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Input&diff=9450Input2021-04-28T08:23:38Z<p>Gionatan: /* Input attributes */</p>
<hr />
<div>{{UI Object Header}}<br />
Input field that allows the user to input a text.<br />
Can be used with a [[submit]] button.<br />
<br />
Requires an ID.<br />
<br />
For a tutorial on using this object, see [[Working with Forms]]<br />
<br />
[[File:UI Object input.png]]<br />
<br />
== Parameters ==<br />
*'''id''': the object's ID, used by UISets<br />
*'''position''': the object's position. Use the pixels or rows and columns coordinates format<br />
*'''css''': optional. Defines the CSS style for the input field<br />
*'''type''': optional. Defines the input type, see [[#Input attributes|inputtype UI attribute]]<br />
<br />
== Syntax ==<br />
(input!id <position>; [<css>]; [<type>])<br />
E.g.<br />
(input!myinput r1c1; color:blue; password)<br />
<br />
<br />
For a scrollable multiline input:<br />
<br />
(input!myinput r1c1; overflow:scroll; multiline)<br />
<br />
== UI Attributes ==<br />
{{UI Object Attributes (Common)}}<br />
{{UI Object Attributes (Field)}}<br />
===Input attributes===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|changedelay<br />
|<number><br />
|Sets the delay in milliseconds by which changes are detected. If the field is working in autosend mode, this value determines the delay between the last button press and the value being sent to the server<br />
|-<br />
|off<br />
|If the field is working in autosend mode, values aren't sent on a delay, but only when the field loses the focus (also when the tab or enter keys are pressed)<br />
|-<br />
<br />
|cssstyle<br />
|<css><br />
|Sets the field's CSS style<br />
|-<br />
<br />
|rowspan="2"|eraseicon<br />
|true<br />
|Show an erase icon that can be clicked to quickly erase the input's content<br />
|-<br />
|false<br />
|Default: no erase icon<br />
|-<br />
<br />
|rowspan="3"|inputtype<br />
|input<br />
|Default behaviour<br />
|-<br />
|multiline<br />
|for input fields with more than a line. Use the height attribute on the css parameter to set the size<br />
|-<br />
|password<br />
|hides typed characters<br />
|-<br />
<br />
|maxlength<br />
|<number><br />
|Specify the maximum length that can be typed<br />
|-<br />
<br />
|rowspan="2"|readonly<br />
|true<br />
|Value not editable<br />
|-<br />
|false<br />
|Default:editable<br />
|-<br />
<br />
|helptext<br />
|<string><br />
|Text to show when the field is empty<br />
|-<br />
<br />
|validatekey<br />
|<regular expression><br />
|A regular expression to be validated on a keypress. E.g. "[a-z]" will allow only lowercase letters.<br />
Won't work on Android devices.<br />
|-<br />
<br />
|validatevalue<br />
|<regular expression><br />
|A regular expression to be validated before the value is sent to the server. If the expression doesn't match the value, the previous value will be restored and the input will flash in red. E.g. "^([1-9][0-9]?&#124;100&#124;0)$" will allow only numbers from 0 to 100, without leading 0s.<br />
|-<br />
<br />
|value<br />
|<string><br />
|Input value<br />
|-<br />
<br />
|}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Redirect_variables&diff=9395Redirect variables2020-11-05T10:07:17Z<p>Gionatan: /* Example: Userlist object (redirecting the object's ID) */</p>
<hr />
<div>Redirect variables allow [[UI Objects]] to be linked dynamically to a source.<br />
<br />
Redirect variables can be used in:<br />
* any object's id<br />
* I/O Server Objects, in server id and address parameters<br />
* [[Button]] objects, in the address parameter<br />
<br />
<br />
== Syntax ==<br />
Variables are defined with the following syntax:<br />
[<variable name>]<br />
E.g.<br />
[myaddr]<br />
<br />
== Setting Values ==<br />
Server UISets (from events or java) are used to set a redirect variable's value.<br />
Each redirect variable is a property of the "redirect" object.<br />
For example, a redirect variable called "myaddr" can be set to "70" with a [[Action_Keywords#UISET|UISet]] command on events:<br />
UISET redirect.myaddr=70<br />
<br />
== Example: Userlist object (redirecting the object's ID) ==<br />
In this example we use a single [[UserList]] object to display different values associated with distinct IDs.<br />
In a project we place a [[UserList]] and two [[User]] buttons.<br />
We use a redirect variable as the ID: myid. We leave parameters and labels empty, to be set by UISets.<br />
<br />
[[File:redirect_vars_03.png|570px]]<br />
<br />
Each [[User]] button will have "changeid" as name and "ulist1" or "ulist2" respectively as param.<br />
<br />
In [[JavaScript_Callback_Functions_API#userCommand|events]] we add: <br />
<br />
# initialize two UserList objects with different values<br />
init : {<br />
uiSet("ulist1", "parameters", "1,2,3");<br />
uiSet("ulist1", "labels", "one,two,three");<br />
uiSet("ulist2", "parameters", "a,b,c");<br />
uiSet("ulist2", "labels", "A,B,C");<br />
}<br />
<br />
# change the id to show different lists<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changeid") {<br />
uiSet("redirect", "myid", param);<br />
}<br />
}<br />
<br />
The parameters and labels for ulist1 and ulist2 will be initialized.<br />
Clicking on a button in the interface will execute the above callback, which sets the redirect variables' values and changes the ID of the UserList object accordingly, which will in turn display one of the two sets of values.<br />
<br />
== Example: TempMini Object ==<br />
In this example we will use a single [[TempMini]] object to display different sources.<br />
In hsyco.ini we have an ioServer with 3 zones.<br />
ioServers = bmne500<br />
ioServersType.bmne500 = MYHOME<br />
ioServersOptions.bmne500 = tempzones=1;2;3<br />
<br />
In a project we place a [[TempMini]] and three [[User]] buttons.<br />
On the TempMini parameters, we use two redirect variables: mysid and myzone.<br />
<br />
[[File:redirect_vars_01.png]]<br />
<br />
Each [[User]] button will have "changetemp" as name and "1", "2" or "3" respectively as param.<br />
<br />
In [[JavaScript_Callback_Functions_API#userCommand|events]] we declare: <br />
<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changetemp") {<br />
uiSet("redirect", "mysid", "bmne500");<br />
uiSet("redirect", "myzone", param); // address: "temp."+ myzone<br />
return "ok";<br />
}<br />
}<br />
<br />
Clicking on a button in the interface will execute the above callback, which sets the redirect variables' values and changes the source of the TempMini object accordingly.<br />
<br />
== Example: Button object ==<br />
Similarly to the previous example, in a project we place a [[Button]] object with a redirect variable called myaddr.<br />
We also place two User buttons with name "changeaddr" and param "light.1" and "autom.1"<br />
<br />
[[File:redirect_vars_02.png]]<br />
<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changeaddr") {<br />
uiSet("redirect", "myaddr", "dummy."+param); // dummy.light.1<br />
}<br />
}<br />
<br />
Once again clicking on a User button will cause the Button object to change its source, from a light to an autom.</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=File:Redirect_vars_03.png&diff=9394File:Redirect vars 03.png2020-11-05T10:06:18Z<p>Gionatan: </p>
<hr />
<div></div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Redirect_variables&diff=9393Redirect variables2020-11-05T10:05:51Z<p>Gionatan: </p>
<hr />
<div>Redirect variables allow [[UI Objects]] to be linked dynamically to a source.<br />
<br />
Redirect variables can be used in:<br />
* any object's id<br />
* I/O Server Objects, in server id and address parameters<br />
* [[Button]] objects, in the address parameter<br />
<br />
<br />
== Syntax ==<br />
Variables are defined with the following syntax:<br />
[<variable name>]<br />
E.g.<br />
[myaddr]<br />
<br />
== Setting Values ==<br />
Server UISets (from events or java) are used to set a redirect variable's value.<br />
Each redirect variable is a property of the "redirect" object.<br />
For example, a redirect variable called "myaddr" can be set to "70" with a [[Action_Keywords#UISET|UISet]] command on events:<br />
UISET redirect.myaddr=70<br />
<br />
== Example: Userlist object (redirecting the object's ID) ==<br />
In this example we use a single [[UserList]] object to display different values associated with distinct IDs.<br />
In a project we place a [[UserList]] and two [[User]] buttons.<br />
We use a redirect variable as the ID: myid. We leave parameters and labels empty, to be set by UISets.<br />
<br />
[[File:redirect_vars_03.png]]<br />
<br />
Each [[User]] button will have "changeid" as name and "ulist1" or "ulist2" respectively as param.<br />
<br />
In [[JavaScript_Callback_Functions_API#userCommand|events]] we add: <br />
<br />
# initialize two UserList objects with different values<br />
init : {<br />
uiSet("ulist1", "parameters", "1,2,3");<br />
uiSet("ulist1", "labels", "one,two,three");<br />
uiSet("ulist2", "parameters", "a,b,c");<br />
uiSet("ulist2", "labels", "A,B,C");<br />
}<br />
<br />
# change the id to show different lists<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changeid") {<br />
uiSet("redirect", "myid", param);<br />
}<br />
}<br />
<br />
The parameters and labels for ulist1 and ulist2 will be initialized.<br />
Clicking on a button in the interface will execute the above callback, which sets the redirect variables' values and changes the ID of the UserList object accordingly, which will in turn display one of the two sets of values.<br />
<br />
<br />
<br />
== Example: TempMini Object ==<br />
In this example we will use a single [[TempMini]] object to display different sources.<br />
In hsyco.ini we have an ioServer with 3 zones.<br />
ioServers = bmne500<br />
ioServersType.bmne500 = MYHOME<br />
ioServersOptions.bmne500 = tempzones=1;2;3<br />
<br />
In a project we place a [[TempMini]] and three [[User]] buttons.<br />
On the TempMini parameters, we use two redirect variables: mysid and myzone.<br />
<br />
[[File:redirect_vars_01.png]]<br />
<br />
Each [[User]] button will have "changetemp" as name and "1", "2" or "3" respectively as param.<br />
<br />
In [[JavaScript_Callback_Functions_API#userCommand|events]] we declare: <br />
<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changetemp") {<br />
uiSet("redirect", "mysid", "bmne500");<br />
uiSet("redirect", "myzone", param); // address: "temp."+ myzone<br />
return "ok";<br />
}<br />
}<br />
<br />
Clicking on a button in the interface will execute the above callback, which sets the redirect variables' values and changes the source of the TempMini object accordingly.<br />
<br />
== Example: Button object ==<br />
Similarly to the previous example, in a project we place a [[Button]] object with a redirect variable called myaddr.<br />
We also place two User buttons with name "changeaddr" and param "light.1" and "autom.1"<br />
<br />
[[File:redirect_vars_02.png]]<br />
<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changeaddr") {<br />
uiSet("redirect", "myaddr", "dummy."+param); // dummy.light.1<br />
}<br />
}<br />
<br />
Once again clicking on a User button will cause the Button object to change its source, from a light to an autom.</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Redirect_variables&diff=9392Redirect variables2020-11-05T09:42:58Z<p>Gionatan: /* Example: Button object */</p>
<hr />
<div>Redirect variables allow [[UI Objects]] to be linked dynamically to a source.<br />
<br />
Redirect variables can be used in:<br />
* any object's id<br />
* I/O Server Objects, in server id and address parameters<br />
* [[Button]] objects, in the address parameter<br />
<br />
<br />
== Syntax ==<br />
Variables are defined with the following syntax:<br />
[<variable name>]<br />
E.g.<br />
[myaddr]<br />
<br />
== Setting Values ==<br />
Server UISets (from events or java) are used to set a redirect variable's value.<br />
Each redirect variable is a property of the "redirect" object.<br />
For example, a redirect variable called "myaddr" can be set to "70" with a [[Action_Keywords#UISET|UISet]] command on events:<br />
UISET redirect.myaddr=70<br />
<br />
== Example: TempMini Object ==<br />
In this example we will use a single [[TempMini]] object to display different sources.<br />
In hsyco.ini we have an ioServer with 3 zones.<br />
ioServers = bmne500<br />
ioServersType.bmne500 = MYHOME<br />
ioServersOptions.bmne500 = tempzones=1;2;3<br />
<br />
In a project we place a [[TempMini]] and three [[User]] buttons.<br />
On the TempMini parameters, we use two redirect variables: mysid and myzone.<br />
<br />
[[File:redirect_vars_01.png]]<br />
<br />
Each [[User]] button will have "changetemp" as name and "1", "2" or "3" respectively as param.<br />
<br />
In [[JavaScript_Callback_Functions_API#userCommand|events]] we declare: <br />
<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changetemp") {<br />
uiSet("redirect", "mysid", "bmne500");<br />
uiSet("redirect", "myzone", param); // address: "temp."+ myzone<br />
return "ok";<br />
}<br />
}<br />
<br />
Clicking on a button in the interface will execute the above callback, which sets the redirect variables' values and changes the source of the TempMini object accordingly.<br />
<br />
== Example: Button object ==<br />
Similarly to the previous example, in a project we place a [[Button]] object with a redirect variable called myaddr.<br />
We also place two User buttons with name "changeaddr" and param "light.1" and "autom.1"<br />
<br />
[[File:redirect_vars_02.png]]<br />
<br />
function userCommand(session, userid, name, param) : {<br />
if (name == "changeaddr") {<br />
uiSet("redirect", "myaddr", "dummy."+param); // dummy.light.1<br />
}<br />
}<br />
<br />
Once again clicking on a User button will cause the Button object to change its source, from a light to an autom.</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=HSYCO&diff=9389HSYCO2020-10-28T10:53:36Z<p>Gionatan: </p>
<hr />
<div>__NOTITLE__<br />
{| role="presentation" style="border:0; margin: 0;" width="100%" cellspacing="10"<br />
| width="100%" valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle welcome">Welcome to the HSYCO Wiki 3.7</div><br />
<div class="mainpageContent"><br />
'''HSYCO''' is an innovative Java-based software framework for home and building automation applications.<br />
<br />
It is highly scalable, portable, secure, reliable and customizable.<br />
HSYCO combines an efficient HTML5 GUI, with web-based design tools, and an extensive Java and JavaScript server API for the automation and control logic.<br />
<br />
Compared to legacy building automation solutions, it offers a state-of-the-art architecture that is fully based on leading modern standards, like HTML5, CSS3, JavaScript and Java.<br />
<br />
<br />
<br />
This wiki contains all relevant configuration and development information of the latest version of HSYCO.<br />
<br />
The documentation of previous versions is available in the [[Download]] page.<br />
</div><br />
<div class="mainpageLinks"><br />
'''[[Download]] | [[About HSYCO]] | [[Products]] | [[Support]] | [[FAQ]]'''<br />
</div><br />
|}<br />
<br />
{| role="presentation" style="border:0; margin: 0;" width="100%" cellspacing="10"<br />
| width="33%" valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle">Installation and Configuration</div><br />
<div class="mainpageContent"><br />
[[File:Main Page System Administrator.png|x80px|center|link=]]<br />
Install and configure HSYCO Server<br />
*'''[[Installation Guide]]'''<br />
*'''[[Settings|Configuration Guide]]'''<br />
*'''[[HSYCO_App|HSYCO App for iOS and Android]]'''<br />
*'''[[System Architecture]]'''<br />
</div><br />
| width="33%" valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle">Development</div><br />
<div class="mainpageContent"><br />
[[File:Main Page Development.png|x80px|center|link=]]<br />
Design your interfaces and develop your applications<br />
*'''[[User Interface|User Interface Design]]'''<br />
*'''[[Programming]]'''<br />
*'''[[Advanced Programming]]'''<br />
</div><br />
| width="33%" valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle">Integration</div><br />
<div class="mainpageContent"><br />
[[File:Main Page Integration.png|x80px|center|link=]]<br />
How to interface external systems<br />
*'''[[Introduction to I/O Servers]]'''<br />
*'''[[I/O Servers|I/O Servers Application Notes]]'''<br />
</div><br />
|}<br />
<br />
{| role="presentation" style="border:0; margin: 0;" width="100%" cellspacing="10"<br />
| width="33%" valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle">Versions</div><br />
<div class="mainpageContent"><br />
*The latest stable release is 3.7.0<br />
*The latest release of the previous version is 3.6.1<br />
<br />
<br />
'''[[Release_Notes_3.7.0|3.7.0 Release Notes]]'''<br />
<br />
'''[[Release_Notes_3.6.1|3.6.1 Release Notes]]''' and '''[http://wiki.hsyco.com/3.6.0 Documentation]'''<br />
<br />
'''[[Release_Notes_3.6.0|3.6.0 Release Notes]]''' and '''[http://wiki.hsyco.com/3.6.0 Documentation]'''<br />
<br />
'''[[Release_Notes_3.5.1|3.5.1 Release Notes]]''' and '''[http://wiki.hsyco.com/3.5.1 Documentation]'''<br />
<br />
'''[[Release_Notes_3.5.0|3.5.0 Release Notes]]''' and '''[http://wiki.hsyco.com/3.5.0 Documentation]'''<br />
<br />
'''[[Release_Notes_3.4.0|3.4.0 Release Notes]]''' and '''[http://wiki.hsyco.com/3.4.0 Documentation]'''<br />
<br />
'''[[Release_Notes_3.3.0|3.3.0 Release Notes]]''' and '''[http://wiki.hsyco.com/3.3.0 Documentation]'''<br />
<br />
<br />
<br />
<br />
'''Visit the [[Download]] page to download all current and past versions of the HSYCO server software.'''<br />
</div><br />
| valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle">News</div><br />
<div class="mainpageContent"><br />
*2020/10/21<br />
**HSYCO 3.7.0 release is available for download<br />
*2019/08/08<br />
**HSYCO 3.7.0 B0129 BETA is available for download. All users are advised to upgrade to build 0129<br />
*2019/02/01<br />
**HSYCO 3.7.0 B0128 BETA is available for download. This build fixes a bug introduced with previous beta build, that could cause an abnormal number of HTTP requests to the weather service provider. All users are advised to upgrade to build 0128<br />
*2019/01/15<br />
**HSYCO 3.7.0 B0127 BETA is available for download<br />
*2018/03/01<br />
**HSYCO 3.6.1 release is available for download<br />
*2017/11/28<br />
**HSYCO 3.6.0 release is available for download<br />
*2016/04/15<br />
**HSYCO 3.5.1 release is available for download<br />
*2016/1/26<br />
**HSYCO 3.5.1 B0122 BETA is available for download<br />
*2015/10/15<br />
**HSYCO 3.5.0 release is available for download<br />
*2015/9/26<br />
**HSYCO Remote App for iOS and Apple Watch is now available on the [https://itunes.apple.com/app/hsyco/id1038105480 Apple App Store]. Version 1.0.1 with improved support for iOS 9 coming soon<br />
*2015/7/31<br />
**HSYCO 3.5.0 B0120 BETA is available for download<br />
*2015/5/18<br />
**HSYCO 3.5.0 B0119 BETA is available for download<br />
*2015/4/24<br />
**HSYCO 3.5.0 BETA documentation is on-line<br />
*2014/12/22<br />
**HSYCO 3.4.0 release is available for download<br />
*2014/10/24<br />
**Due to the large number of enhancements (not only bug fixes) in the current beta release, formerly known as 3.3.1, we are now promoting it to 3.4.0. There will be no official release of 3.3.1, and all changes are merged in the upcoming 3.4.0 release<br />
*2014/8/7<br />
**HSYCO 3.3.1 B0115 BETA is now available for download<br />
*2014/6/4<br />
**HSYCO 3.3.1 B0114 BETA is available for download<br />
*2014/3/25<br />
**HSYCO 3.3.0 release is available for download<br />
*2014/2/24<br />
**HSYCO 3.3.0 B0112 BETA is available for download<br />
*2013/12/23<br />
**HSYCO 3.3.0 B0109 BETA is available for download<br />
*2013/9/10<br />
**HSYCO 3.2.3 release is available for download<br />
*2013/6/12<br />
**HSYCO 3.2.2 release is available for download<br />
*2013/4/19<br />
**HSYCO 3.2.1 release is available for download<br />
<br />
<br />
'''Older news have been removed from this site. If you need specific information about old releases, please contact us.'''<br />
</div><br />
|}<br />
<br />
{| role="presentation" style="border:0; margin: 0;" width="100%" cellspacing="10"<br />
| width="100%" valign="top" class="mainpageBox" |<br />
<div class="mainpageTitle">Service Bulletins</div><br />
<div class="mainpageContent"><br />
*2020/2/5: '''[[Service_Bulletin_20200205_Telegram_BOT|Telegram now requires the TLSv1.2 cryptographic protocol, breaking compatibility on Java 6 and Java 7 virtual machines]]'''<br />
*2019/1/3: '''[[Service_Bulletin_20190103_Yahoo_Weather_API_EOL|Yahoo drops supports for its weather API used in the WXOnline HSYCO I/O Server]]'''<br />
*2016/3/15: '''[[Service_Bullettin_20160315_Yahoo_Weather_API|Yahoo drops supports for previous version of its weather API and introduces new API]]'''<br />
*2015/9/10: '''[[Service_Bullettin_20150911_Weak_DH_HTTPS_Server_Keys|Chrome and Firefox drop support for servers using weak Diffie-Hellman public keys]]'''<br />
</div><br />
|}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=MediaWiki:ExportDocSnippets.js&diff=9267MediaWiki:ExportDocSnippets.js2020-10-19T12:11:03Z<p>Gionatan: </p>
<hr />
<div>var myWindow;<br />
<br />
var oReq = new XMLHttpRequest();<br />
oReq.addEventListener("load", reqListener);<br />
var l = -1;<br />
var baseUrl = "https://wiki.hsyco.com/3.7/index.php/"<br />
var urls = [{<br />
url: "Event_Keywords",<br />
sub: "Events",<br />
opt: {<br />
event: true<br />
},<br />
arr: "events"<br />
},<br />
{<br />
url: "Action_Keywords",<br />
sub: "Actions",<br />
opt: {<br />
action: true<br />
},<br />
arr: "actions"<br />
},<br />
{<br />
url: "JavaScript_Callback_Functions_API",<br />
sub: "Javascript Callback Functions",<br />
opt: {<br />
jsEvent: true<br />
},<br />
arr: "events"<br />
},<br />
{<br />
url: "JavaScript_Command_and_Utility_Functions_API",<br />
sub: "Javascript Command and Utility Functions",<br />
opt: {<br />
jsAction: true<br />
},<br />
arr: "js"<br />
},<br />
{<br />
url: "Index.js",<br />
sub: "Javascript",<br />
opt: {<br />
js: true<br />
},<br />
arr: "indexjs"<br />
},<br />
];<br />
<br />
function reqListener() {<br />
console.log("loaded " + urls[l].url);<br />
var div = document.createElement('div');<br />
div.innerHTML = this.responseText;<br />
urls[l].res = parse(div, urls[l].sub, urls[l].opt);<br />
next();<br />
}<br />
<br />
// CALL THIS<br />
function next() {<br />
if (!myWindow) {<br />
initWin();<br />
myWindow.document.write("Please wait...");<br />
}<br />
l++;<br />
if (urls[l]) {<br />
oReq.open("GET", baseUrl + urls[l].url);<br />
oReq.send();<br />
} else {<br />
var head = "\<br />
ace.define('ace/snippets/%what',['require','exports','module'], function(require, exports, module) {\n\<br />
var s = {\n\<br />
\t// scopes\n\<br />
\tevents:[],\n\<br />
\tactions:[],\n\<br />
\tjs:[]\n\<br />
};\n\n\<br />
exports.snippetText = s;\n\n\n";<br />
<br />
var tail = "exports.scope = '%what';\n});";<br />
<br />
str = head.replace("%what", "events");<br />
for (var i = 0; i < urls.length - 1; i++) { // skip index.js<br />
str += "var a = s." + urls[i].arr + ";\n";<br />
str += urls[i].res;<br />
str += "\n\n\n";<br />
}<br />
str += tail.replace("%what", "events");;<br />
openWin("events.js", str);<br />
<br />
<br />
str = head.replace("%what", "javascript");<br />
str += "var a = s.js;\n";<br />
str += urls[4].res;<br />
str += "\n\n\n// js\n\n";<br />
var s;<br />
for (var i = 0; i < jsSnippets.length; i++) {<br />
s = jsSnippets[i];<br />
str += "a.push({\n";<br />
str += "\ttitle:\"" + s.title.split("(")[0] + "\",\n";<br />
str += "\ttabTrigger:\"" + s.tabTrigger + "\",\n";<br />
str += "\tcontent:\"" + s.content.replace(/\t/g, "\\t").replace(/\n/g, "\\n") + "\"\n";<br />
str += "});\n";<br />
}<br />
str += "\n\n\n";<br />
str += tail.replace("%what", "javascript");;<br />
openWin("javascript.js", str);<br />
<br />
<br />
<br />
console.log("done");<br />
}<br />
}<br />
<br />
function download(filename, text) {<br />
var pom = document.createElement('a');<br />
pom.setAttribute('href', 'data:text/plain;charset=utf-8,' + encodeURIComponent(text));<br />
pom.setAttribute('download', filename);<br />
<br />
if (document.createEvent) {<br />
var event = document.createEvent('MouseEvents');<br />
event.initEvent('click', true, true);<br />
pom.dispatchEvent(event);<br />
} else {<br />
pom.click();<br />
}<br />
}<br />
<br />
function print(sub, opt) {<br />
var url = "";<br />
for (var i = 0; i < urls.length; i++) {<br />
if (window.location.href.indexOf(urls[i].url) != -1) {<br />
sub = urls[i].sub;<br />
opt = urls[i].opt;<br />
url = urls[i].url;<br />
break;<br />
}<br />
}<br />
<br />
var str = parse(document, sub, opt, baseUrl + url);<br />
openWin("", str);<br />
}<br />
<br />
function initWin() {<br />
myWindow = window.open("about:blank", "Editor Snippets");<br />
<br />
myWindow.document.write("\<br />
<script>\n\<br />
function addDownload(n,f) {\n\<br />
var data = document.getElementById('txt'+n).value;\n\<br />
var link = document.createElement('a');\n\<br />
link.setAttribute('href','data:text/text;charset=utf-8,'+encodeURI(data));\n\<br />
link.setAttribute('download', f);\n\<br />
link.innerHTML = 'download file';\n\<br />
document.getElementById('p'+n).appendChild(link);\n\<br />
}\n\<br />
</script>");<br />
}<br />
<br />
var _no = 0; // number of outputs<br />
function openWin(title, str) {<br />
if (!myWindow)<br />
initWin();<br />
<br />
_no++;<br />
<br />
myWindow.document.write("<hr>");<br />
myWindow.document.write("<h1>" + title + "</h1>");<br />
myWindow.document.write("<p id='p" + _no + "'>");<br />
myWindow.document.write("</p>");<br />
myWindow.document.write("<textarea id='txt" + _no + "' style='width:800px; height:400px'>" + str + "</textarea>");<br />
myWindow.document.write("<script>addDownload(" + _no + ",'" + title + "')</script>");<br />
myWindow.document.write("<p></p>");<br />
myWindow.document.getElementById('txt' + _no).select();<br />
}<br />
<br />
function parse(e, asub, opt, url) {<br />
function rr(s) { // remove return and trim<br />
s = s.trim();<br />
while (s[s.length - 1] == "\n")<br />
s = s.substr(0, s.length - 1);<br />
return s;<br />
}<br />
<br />
function stripDescr(d) {<br />
d = d.replace(/\n+/g, "");<br />
d = d.replace(/(^(<br>)+|(<br>)+$)/g, ""); // initial, end br<br />
d = d.replace(/\n+/g, "<br>");<br />
d = d.replace(/(<br>)+/g, "<br>");<br />
d = d.replace(/\<(\/?(ul|li|string|br))\>/g, "+___$1___-"); // keep these<br />
d = d.replace(/<(?:.|\n)*?>/gm, ''); // strip html<br />
d = d.replace(/\+___/g, "<"); // restore<br />
d = d.replace(/___-/g, ">");<br />
d = d.replace(/(<br>)?<\/li>(<br>)?/g, "</li>"); // remove breaklines inside/outside li<br />
d = d.trim();<br />
return d;<br />
}<br />
var a = e.getElementsByClassName("mw-headline");<br />
if (!opt) opt = {};<br />
<br />
var nl = "\\n\\" + "\n";<br />
<br />
var snippets = [];<br />
var variations = [];<br />
var pE, nE;<br />
var str = "";<br />
var title, subtitle, descr, snippet, content;<br />
var bsub; // combined with asub to create subtitle<br />
for (var i = 0; i < a.length; i++) {<br />
pE = a[i].parentElement;<br />
nE = pE ? pE.nextElementSibling : null;<br />
<br />
title = rr(a[i].innerHTML);<br />
subtitle = asub + (bsub ? ", " + bsub : "");<br />
<br />
snippet = "";<br />
if (pE.nodeName == "H3") {<br />
// if (nE && (nE.nodeName == "PRE" || nE.className.indexOf("mw-code") != -1)) { // old ver<br />
if (nE && (nE.nodeName == "PRE" || (nE.childNodes[0] && nE.childNodes[0].nodeName == "PRE")) && nE.innerHTML.indexOf("\t") == -1) {<br />
snippet = nE.innerHTML;<br />
snippet = snippet.replace(/<(?:.|\n)*?>/gm, ''); // strip html<br />
content = snippet;<br />
title = snippet;<br />
nE = nE.nextElementSibling;<br />
}<br />
descr = "";<br />
var grabAll = true; //opt.event || opt.action; // grab all html<br />
while (nE) {<br />
if (!grabAll && nE.nodeName != "P" && nE.nodeName != "UL")<br />
break;<br />
if (nE.className == "mw-headline" || nE.getElementsByClassName("mw-headline").length)<br />
break;<br />
if (nE.getAttribute("data-skipeditordoc") != null) // like CameraCommandEvent on JavaScript_Callback_Functions_API<br />
break;<br />
<br />
var d = rr(grabAll ? nE.outerHTML : nE.innerHTML);<br />
<br />
if (!grabAll) {<br />
d = stripDescr(d);<br />
if (nE.nodeName == "UL")<br />
d = "<ul>" + d + "</ul>";<br />
<br />
if (d.indexOf("Examples:") != -1)<br />
break;<br />
<br />
if (d.indexOf("Parameters:") != -1 ||<br />
d.indexOf("Returns:") != -1) {<br />
descr += "<br>";<br />
}<br />
if (d)<br />
descr += (descr ? "<br>" : "") + d;<br />
} else {<br />
// bulb image<br />
d = d.replace(/<img .+src=".+Bulbgraph.png".+(width="[^"]+").+(height="[^"]+")[^>]+>/g,<br />
"<img src=\"/manager/pic/bulb.png\" $1 $2>");<br />
// replace \n\t<br />
d = d.replace(/\n/g, "\\n").replace(/\t/g, "\\t");<br />
// variations?<br />
if (nE.nodeName == "TABLE") {<br />
var f = nE.getElementsByTagName("TD")[0];<br />
if (f && f.innerHTML &&<br />
(f.innerHTML.indexOf("Action") != -1 || f.innerHTML.indexOf("Event") != -1)) {<br />
var rows = nE.getElementsByTagName("TR");<br />
var cols;<br />
var txt, atxt;<br />
for (var r = 1; r < rows.length; r++) {<br />
cols = rows[r].getElementsByTagName("TD");<br />
txt = cols[0] ? cols[0].innerHTML : "";<br />
if (txt && txt != title) {<br />
atxt = txt.split(/\s*\<br[^\>]*\>\s*/);<br />
for (var v = 0; v < atxt.length; v++) {<br />
variations.push({<br />
src: atxt[v].trim(),<br />
descr: cols[1] ? cols[1].innerHTML : ""<br />
});<br />
}<br />
}<br />
}<br />
}<br />
}<br />
if (d)<br />
descr += d;<br />
}<br />
<br />
nE = nE.nextElementSibling;<br />
}<br />
// check variations<br />
var s, c;<br />
for (var v = 0; v < variations.length; v++) {<br />
s = variations[v].src;<br />
s = s.replace("&lt;", "<");<br />
s = s.replace("&gt;", ">");<br />
// replace variables (lowercase words), separated by space or start/end line<br />
c = s.replace(/(^|\s*|:)("?)([a-z0-9:_\.]+)("?)($|\n|\s*|:)/g, "$1$2\${0:$3}$4$5");<br />
var count = 1;<br />
c = c.replace(/\$\{0/g, function (match, capture) {<br />
return '${' + count++;<br />
});<br />
<br />
// strip html, new lines<br />
s = s.replace(/<(?:.|\n)*?>/gm, '').replace(/\n/g, "");<br />
c = c.replace(/<(?:.|\n)*?>/gm, '').replace(/\n/g, "");<br />
variations[v].snippet = s;<br />
variations[v].content = c; // strip html;<br />
}<br />
<br />
if (!snippet) {<br />
snippet = title;<br />
content = snippet;<br />
}<br />
<br />
title = rr(title);<br />
snippet = rr(snippet);<br />
content = rr(content);<br />
<br />
if (opt.jsEvent || (opt.js && bsub == "Events")) {<br />
if (title.indexOf("function") != 0)<br />
title = "function " + title;<br />
if (snippet.indexOf("function") != 0)<br />
snippet = "function " + snippet;<br />
if (content.indexOf("function") != 0)<br />
content = "function " + content;<br />
content += (opt.js ? " {" : " : {") + "\\n";<br />
content += "\\t${1:// body...} " + "\\n";<br />
content += "}";<br />
} else if (opt.jsAction || (opt.js && bsub == "Functions")) {<br />
content = content.replace(/([\(,]+\s?)([^\)^\s^,]+)/g, "$1\${0:$2}");<br />
var count = 1;<br />
content = content.replace(/\$\{0/g, function (match, capture) {<br />
return '${' + count++;<br />
});<br />
} else if (opt.js && (bsub == "Examples" || bsub == "User Object")) {<br />
continue;<br />
} else {<br />
content += " ";<br />
}<br />
<br />
if (title && descr) {<br />
descr = descr.replace(/["“”]/g, '\\"');<br />
if (variations.length) {<br />
for (var v = 0; v < variations.length; v++) {<br />
snippets.push({<br />
title: variations[v].snippet,<br />
subtitle: subtitle,<br />
descr: v ? "_again_" : descr, //+"<br><br>"+variations[v].descr+_url,<br />
snippet: variations[v].snippet,<br />
content: variations[v].content<br />
});<br />
}<br />
variations = [];<br />
} else {<br />
snippets.push({<br />
title: title,<br />
subtitle: subtitle,<br />
descr: descr,<br />
snippet: snippet,<br />
content: content<br />
});<br />
}<br />
}<br />
} else if (pE.nodeName == "H2") {<br />
bsub = title;<br />
}<br />
}<br />
<br />
if (false && !opt.noSort) {<br />
snippets.sort(function (a, b) {<br />
if (a.snippet > b.snippet) {<br />
return 1;<br />
}<br />
if (a.snippet < b.snippet) {<br />
return -1;<br />
}<br />
// a must be equal to b<br />
return 0;<br />
});<br />
}<br />
<br />
var s;<br />
for (var i = 0; i < snippets.length; i++) {<br />
s = snippets[i];<br />
str += "a.push({\n";<br />
str += "\ttitle:\"" + s.title.replace(/["“”]/g, '\\"') + "\",\n";<br />
str += "\tsubTitle:\"" + s.subtitle.replace(/["“”]/g, '\\"') + "\",\n";<br />
<br />
if (s.descr == "_again_")<br />
str += "\tdocHTML:a.last().docHTML,\n";<br />
else<br />
str += "\tdocHTML:\"" + s.descr + "\",\n";<br />
<br />
//str += "\ttabTrigger:\""+s.snippet.replace(/["“”]/g,'\\"')+"\",\n";<br />
str += "\tcontent:\"" + s.content.replace(/["“”]/g, '\\"') + "\"\n";<br />
str += "});\n";<br />
}<br />
<br />
return str;<br />
}<br />
<br />
//////////////////////////////////////////////////////////////////////<br />
// DEFAULT JS<br />
//////////////////////////////////////////////////////////////////////<br />
var jsSnippets = [];<br />
var a = jsSnippets;<br />
a.push({<br />
title: "fun",<br />
tabTrigger: "fun",<br />
content: "function ${1?:function_name}(${2:argument}) {\n\t${3:// body...}\n}"<br />
});<br />
a.push({<br />
title: "if",<br />
tabTrigger: "if",<br />
content: "if (${1:true}) {\n\t${0}\n}"<br />
});<br />
a.push({<br />
title: "ife",<br />
tabTrigger: "ife",<br />
content: "if (${1:true}) {\n\t${2}\n} else {\n\t${0}\n}"<br />
});<br />
a.push({<br />
title: "ter",<br />
tabTrigger: "ter",<br />
content: "${1:/* condition */} ? ${2:a} : ${3:b}"<br />
});<br />
a.push({<br />
title: "switch",<br />
tabTrigger: "switch",<br />
content: "switch (${1:expression}) {\n\tcase '${3:case}':\n\t\t${4:// code}\n\t\tbreak;\n\t${5}\n\tdefault:\n\t\t${2:// code}\n}"<br />
});<br />
a.push({<br />
title: "case",<br />
tabTrigger: "case",<br />
content: "case '${1:case}':\n\t${2:// code}\n\tbreak;\n${3}"<br />
});<br />
a.push({<br />
title: "wh",<br />
tabTrigger: "wh",<br />
content: "while (${1:/* condition */}) {\n\t${0:/* code */}\n}"<br />
});<br />
a.push({<br />
title: "try",<br />
tabTrigger: "try",<br />
content: "try {\n\t${0:/* code */}\n} catch (e) {}"<br />
});<br />
a.push({<br />
title: "do",<br />
tabTrigger: "do",<br />
content: "do {\n\t${2:/* code */}\n} while (${1:/* condition */});"<br />
});<br />
a.push({<br />
title: "setTimeout",<br />
tabTrigger: "setTimeout",<br />
content: "setTimeout(function() {${3:$TM_SELECTED_TEXT}}, ${1:10});"<br />
});<br />
a.push({<br />
title: "gett",<br />
tabTrigger: "gett",<br />
content: "getElementsBy${1:TagName}('${2}')${3}"<br />
});<br />
a.push({<br />
title: "get",<br />
tabTrigger: "get",<br />
content: "getElementBy${1:Id}('${2}')${3}"<br />
});<br />
a.push({<br />
title: "cl",<br />
tabTrigger: "cl",<br />
content: "console.log(${1});"<br />
});<br />
a.push({<br />
title: "ret",<br />
tabTrigger: "ret",<br />
content: "return ${1:result}"<br />
});<br />
a.push({<br />
title: "fori",<br />
tabTrigger: "fori",<br />
content: "for (var ${1:prop} in ${2:Things}) {\n\t${0:$2[$1]}\n}"<br />
});<br />
a.push({<br />
title: "jsonp",<br />
tabTrigger: "jsonp",<br />
content: "JSON.parse(${1:jstr});"<br />
});<br />
a.push({<br />
title: "jsons",<br />
tabTrigger: "jsons",<br />
content: "JSON.stringify(${1:object});"<br />
});<br />
a.push({<br />
title: "for-",<br />
tabTrigger: "for-",<br />
content: "for (var ${1:i} = ${2:Things}.length; ${1:i}--; ) {\n\t${0:${2:Things}[${1:i}];}\n}"<br />
});<br />
a.push({<br />
title: "for",<br />
tabTrigger: "for",<br />
content: "for (var ${1:i} = 0; $1 < ${2:Things}.length; $1++) {\n\t${3:$2[$1]}$0\n}"<br />
});<br />
a.push({<br />
title: "forr",<br />
tabTrigger: "forr",<br />
content: "for (var ${1:i} = ${2:Things}.length - 1; $1 >= 0; $1--) {\n\t${3:$2[$1]}$0\n}"<br />
});</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=MediaWiki:Common.js&diff=9264MediaWiki:Common.js2020-10-19T12:06:23Z<p>Gionatan: </p>
<hr />
<div>/* Any JavaScript here will be loaded for all users on every page load. */<br />
<br />
function ModifySidebar( action, section, name, link ) {<br />
try {<br />
switch ( section ) {<br />
case 'languages':<br />
var target = 'p-lang';<br />
break;<br />
case 'toolbox':<br />
var target = 'p-tb';<br />
break;<br />
case 'navigation':<br />
var target = 'p-navigation';<br />
break;<br />
default:<br />
var target = 'p-' + section;<br />
break;<br />
}<br />
<br />
if ( action == 'add' ) {<br />
var node = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var aNode = document.createElement( 'a' );<br />
var liNode = document.createElement( 'li' );<br />
<br />
aNode.appendChild( document.createTextNode( name ) );<br />
aNode.setAttribute( 'href', link );<br />
liNode.appendChild( aNode );<br />
liNode.className = 'plainlinks';<br />
node.appendChild( liNode );<br />
}<br />
<br />
if ( action == 'remove' ) {<br />
var list = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var listelements = list.getElementsByTagName( 'li' );<br />
<br />
for ( var i = 0; i < listelements.length; i++ ) {<br />
if (<br />
listelements[i].getElementsByTagName( 'a' )[0].innerHTML == name ||<br />
listelements[i].getElementsByTagName( 'a' )[0].href == link<br />
)<br />
{<br />
list.removeChild( listelements[i] );<br />
}<br />
}<br />
}<br />
<br />
} catch( e ) {<br />
// let's just ignore what's happened<br />
return;<br />
}<br />
}<br />
<br />
function CustomizeModificationsOfSidebar() {<br />
ModifySidebar( 'remove', 'toolbox', 'Related changes', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Special pages', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Page information', '' );<br />
}<br />
<br />
$( function () {<br />
CustomizeModificationsOfSidebar();<br />
} );<br />
<br />
if (window.location.href.indexOf("Talk:HSYCO" != -1)) {<br />
mw.loader.load( '/3.7/index.php?title=MediaWiki:ExportDocSnippets.js&action=raw&ctype=text/javascript' );<br />
document.getElementById("generatedoc").innerHTML = '<a href="#" onclick="next()">generate</a>';<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=MediaWiki:Common.js&diff=9263MediaWiki:Common.js2020-10-19T12:05:58Z<p>Gionatan: </p>
<hr />
<div>/* Any JavaScript here will be loaded for all users on every page load. */<br />
<br />
function ModifySidebar( action, section, name, link ) {<br />
try {<br />
switch ( section ) {<br />
case 'languages':<br />
var target = 'p-lang';<br />
break;<br />
case 'toolbox':<br />
var target = 'p-tb';<br />
break;<br />
case 'navigation':<br />
var target = 'p-navigation';<br />
break;<br />
default:<br />
var target = 'p-' + section;<br />
break;<br />
}<br />
<br />
if ( action == 'add' ) {<br />
var node = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var aNode = document.createElement( 'a' );<br />
var liNode = document.createElement( 'li' );<br />
<br />
aNode.appendChild( document.createTextNode( name ) );<br />
aNode.setAttribute( 'href', link );<br />
liNode.appendChild( aNode );<br />
liNode.className = 'plainlinks';<br />
node.appendChild( liNode );<br />
}<br />
<br />
if ( action == 'remove' ) {<br />
var list = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var listelements = list.getElementsByTagName( 'li' );<br />
<br />
for ( var i = 0; i < listelements.length; i++ ) {<br />
if (<br />
listelements[i].getElementsByTagName( 'a' )[0].innerHTML == name ||<br />
listelements[i].getElementsByTagName( 'a' )[0].href == link<br />
)<br />
{<br />
list.removeChild( listelements[i] );<br />
}<br />
}<br />
}<br />
<br />
} catch( e ) {<br />
// let's just ignore what's happened<br />
return;<br />
}<br />
}<br />
<br />
function CustomizeModificationsOfSidebar() {<br />
ModifySidebar( 'remove', 'toolbox', 'Related changes', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Special pages', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Page information', '' );<br />
}<br />
<br />
$( function () {<br />
CustomizeModificationsOfSidebar();<br />
} );<br />
<br />
if (window.location.href.indexOf("Talk:HSYCO" != -1)) {<br />
mw.loader.load( 'index.php?title=MediaWiki:ExportDocSnippets.js&action=raw&ctype=text/javascript' );<br />
document.getElementById("generatedoc").innerHTML = '<a href="#" onclick="next()">generate</a>';<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=MediaWiki:Common.js&diff=9262MediaWiki:Common.js2020-10-19T12:05:40Z<p>Gionatan: </p>
<hr />
<div>/* Any JavaScript here will be loaded for all users on every page load. */<br />
<br />
function ModifySidebar( action, section, name, link ) {<br />
try {<br />
switch ( section ) {<br />
case 'languages':<br />
var target = 'p-lang';<br />
break;<br />
case 'toolbox':<br />
var target = 'p-tb';<br />
break;<br />
case 'navigation':<br />
var target = 'p-navigation';<br />
break;<br />
default:<br />
var target = 'p-' + section;<br />
break;<br />
}<br />
<br />
if ( action == 'add' ) {<br />
var node = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var aNode = document.createElement( 'a' );<br />
var liNode = document.createElement( 'li' );<br />
<br />
aNode.appendChild( document.createTextNode( name ) );<br />
aNode.setAttribute( 'href', link );<br />
liNode.appendChild( aNode );<br />
liNode.className = 'plainlinks';<br />
node.appendChild( liNode );<br />
}<br />
<br />
if ( action == 'remove' ) {<br />
var list = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var listelements = list.getElementsByTagName( 'li' );<br />
<br />
for ( var i = 0; i < listelements.length; i++ ) {<br />
if (<br />
listelements[i].getElementsByTagName( 'a' )[0].innerHTML == name ||<br />
listelements[i].getElementsByTagName( 'a' )[0].href == link<br />
)<br />
{<br />
list.removeChild( listelements[i] );<br />
}<br />
}<br />
}<br />
<br />
} catch( e ) {<br />
// let's just ignore what's happened<br />
return;<br />
}<br />
}<br />
<br />
function CustomizeModificationsOfSidebar() {<br />
ModifySidebar( 'remove', 'toolbox', 'Related changes', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Special pages', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Page information', '' );<br />
}<br />
<br />
$( function () {<br />
CustomizeModificationsOfSidebar();<br />
} );<br />
<br />
if (window.location.href.indexOf("Talk:HSYCO" != -1)) {<br />
importScript('MediaWiki:ExportDocSnippets.js');<br />
mw.loader.load( 'index.php?title=MediaWiki:ExportDocSnippets.js&action=raw&ctype=text/javascript' );<br />
document.getElementById("generatedoc").innerHTML = '<a href="#" onclick="next()">generate</a>';<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=MediaWiki:Common.js&diff=9261MediaWiki:Common.js2020-10-19T12:03:22Z<p>Gionatan: </p>
<hr />
<div>/* Any JavaScript here will be loaded for all users on every page load. */<br />
<br />
function ModifySidebar( action, section, name, link ) {<br />
try {<br />
switch ( section ) {<br />
case 'languages':<br />
var target = 'p-lang';<br />
break;<br />
case 'toolbox':<br />
var target = 'p-tb';<br />
break;<br />
case 'navigation':<br />
var target = 'p-navigation';<br />
break;<br />
default:<br />
var target = 'p-' + section;<br />
break;<br />
}<br />
<br />
if ( action == 'add' ) {<br />
var node = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var aNode = document.createElement( 'a' );<br />
var liNode = document.createElement( 'li' );<br />
<br />
aNode.appendChild( document.createTextNode( name ) );<br />
aNode.setAttribute( 'href', link );<br />
liNode.appendChild( aNode );<br />
liNode.className = 'plainlinks';<br />
node.appendChild( liNode );<br />
}<br />
<br />
if ( action == 'remove' ) {<br />
var list = document.getElementById( target )<br />
.getElementsByTagName( 'div' )[0]<br />
.getElementsByTagName( 'ul' )[0];<br />
<br />
var listelements = list.getElementsByTagName( 'li' );<br />
<br />
for ( var i = 0; i < listelements.length; i++ ) {<br />
if (<br />
listelements[i].getElementsByTagName( 'a' )[0].innerHTML == name ||<br />
listelements[i].getElementsByTagName( 'a' )[0].href == link<br />
)<br />
{<br />
list.removeChild( listelements[i] );<br />
}<br />
}<br />
}<br />
<br />
} catch( e ) {<br />
// let's just ignore what's happened<br />
return;<br />
}<br />
}<br />
<br />
function CustomizeModificationsOfSidebar() {<br />
ModifySidebar( 'remove', 'toolbox', 'Related changes', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Special pages', '' );<br />
ModifySidebar( 'remove', 'toolbox', 'Page information', '' );<br />
}<br />
<br />
$( function () {<br />
CustomizeModificationsOfSidebar();<br />
} );<br />
<br />
if (window.location.href.indexOf("Talk:HSYCO" != -1)) {<br />
importScript('MediaWiki:ExportDocSnippets.js');<br />
document.getElementById("generatedoc").innerHTML = '<a href="#" onclick="next()">generate</a>';<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=9001Beacons on HSYCO App for iOS2020-09-23T11:50:17Z<p>Gionatan: /* HSYCO Implementation */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See the documentation of LocationBeaconEvent for more information: [[JavaScript_Callback_Functions_API#LocationBeaconEvent|JavaScript Callback]] and [[Java_Callback_Methods_API#LocationBeaconEvent|Java Callback]]. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini or [[Settings#Location_Services|Location Services]] under [[Settings]]:<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=9000Beacons on HSYCO App for iOS2020-09-23T11:50:02Z<p>Gionatan: /* HSYCO Implementation */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See the documentation for LocationBeaconEvent for more information: [[JavaScript_Callback_Functions_API#LocationBeaconEvent|JavaScript Callback]] and [[Java_Callback_Methods_API#LocationBeaconEvent|Java Callback]]. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini or [[Settings#Location_Services|Location Services]] under [[Settings]]:<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8999Beacons on HSYCO App for iOS2020-09-23T11:49:32Z<p>Gionatan: /* HSYCO Implementation */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See the documentation for LocationBeaconEvent for more information: [[JavaScript_Callback_Functions_API#LocationBeaconEvent|JavaScript Callback]] and [[Java_Callback_Functions_API#LocationBeaconEvent|Java Callback]]. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini or [[Settings#Location_Services|Location Services]] under [[Settings]]:<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8998Java Callback Methods API2020-09-23T10:01:56Z<p>Gionatan: </p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
<source lang="java">static void DaylightEvent(boolean day)</source><br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
<source lang="java">static String getUserVersion()</source><br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
<source lang="java">static void haActiveEvent(boolean active)</source><br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
<source lang="java">static int PowerEvent(int power)</source><br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
<source lang="java">static void programTimerEvent(String name)</source><br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
<source lang="java">static void SchedulerEvent(String groupname, String schedulename)</source><br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
<source lang="java">static void StartupEvent()</source><br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
<source lang="java">static void SunPositionEvent(int azimuth, int elevation)</source><br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
<source lang="java">static void TimeEvent(long time)</source><br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
<source lang="java">static void varEvent(String name, String value)</source><br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
<source lang="java">static int cameraCommandEvent(String function, String action, String camera)</source><br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
<source lang="java">static void CameraMotionEvent(String eventName, long remoteTime)</source><br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
<source lang="java">static void CameraViewEvent(String camera, boolean active)</source><br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
<source lang="java">static void DmxEvent(int channel, int state)</source><br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
<source lang="java">static int DmxFilter(int channel, int state, boolean reverse)</source><br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
<source lang="java">static void DmxStartupEvent(int serverIndex)</source><br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
<source lang="java">static void IREvent(boolean received, int irtransid, String event)</source><br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
<source lang="java">static void IOEvent(String id, String value)</source><br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
<source lang="java">static void IOStartupEvent(int serverIndex)</source><br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
<source lang="java">static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)</source><br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
<source lang="java">static String httpCallEvent(String address, boolean secure, String query)</source><br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
<source lang="java">static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)</source><br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
<source lang="java"><br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
</source><br />
<br />
=== LocationEvent ===<br />
<br />
<source lang="java">static void LocationEvent(long mac, InetAddress ip, int zoneId)</source><br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
<source lang="java">static void SysLogEvent(String address, String log)</source><br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
<source lang="java">static boolean PBXCallEvent(String host, String caller, String called)</source><br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
<source lang="java">static void SlimPowerEvent(int index, int power)</source><br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
<source lang="java">static void SlimStatusEvent(int index, int status)</source><br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
<source lang="java">static void SlimVolumeEvent(int index, int volume)</source><br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
<source lang="java">static boolean UserTimerEvent(String name, boolean active)</source><br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
<source lang="java">static void pageEvent(String address, String session, String userid, String project, String page)</source><br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
<source lang="java">static void loginEvent(String address, String session, String userid)</source><br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
<source lang="java">static void logoutEvent(String address, String session, String userid, boolean lock)</source><br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
<source lang="java">static void uiClearEvent(String session)</source><br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
<source lang="java">static String userCommand(String name, String param)</source><br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
<source lang="java">static String userCommand(String session, String userid, String name, String param)</source><br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userSubmit ===<br />
<br />
<source lang="java">static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)</source><br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
<source lang="java">static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)</source><br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL<br />
<br />
== Location ==<br />
<br />
=== LocationBeaconEvent ===<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<source lang="java">void LocationBeaconEvent(String session, String address, String userid, String zone, String distance, boolean background)</source><br />
<br />
Called when the HSYCO App detects a change in the proximity of one of the configured beacons.<br />
<br />
There is no guarantee that the event would be fired.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - session id string that uniquely identifies the client session<br />
* address: string - the beacon's address<br />
* userid: string - the user id<br />
* zone: string - the beacon's zone<br />
* distance: string - far, near, immediate or off<br />
* background: boolean - true if the app called the server while in background mode (app closed)</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8997Java Callback Methods API2020-09-23T09:58:20Z<p>Gionatan: /* DaylightEvent */</p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
<source lang="java">static void DaylightEvent(boolean day)</source><br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
static String getUserVersion()<br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
static void haActiveEvent(boolean active)<br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
static int PowerEvent(int power)<br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
static void programTimerEvent(String name)<br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
static void SchedulerEvent(String groupname, String schedulename)<br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
static void StartupEvent()<br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
static void SunPositionEvent(int azimuth, int elevation)<br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
static void TimeEvent(long time)<br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
static void varEvent(String name, String value)<br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
static int cameraCommandEvent(String function, String action, String camera)<br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
static void CameraMotionEvent(String eventName, long remoteTime)<br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
static void CameraViewEvent(String camera, boolean active)<br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
static void DmxEvent(int channel, int state)<br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
static int DmxFilter(int channel, int state, boolean reverse)<br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
static void DmxStartupEvent(int serverIndex)<br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
static void IREvent(boolean received, int irtransid, String event)<br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
static void IOEvent(String id, String value)<br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
static void IOStartupEvent(int serverIndex)<br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)<br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
static String httpCallEvent(String address, boolean secure, String query)<br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)<br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
static void LocationEvent(long mac, InetAddress ip, int zoneId)<br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
static void SysLogEvent(String address, String log)<br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
static boolean PBXCallEvent(String host, String caller, String called)<br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
static void SlimPowerEvent(int index, int power)<br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
static void SlimStatusEvent(int index, int status)<br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
static void SlimVolumeEvent(int index, int volume)<br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
static boolean UserTimerEvent(String name, boolean active)<br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
static void pageEvent(String address, String session, String userid, String project, String page)<br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
static void loginEvent(String address, String session, String userid)<br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
static void logoutEvent(String address, String session, String userid, boolean lock)<br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
static void uiClearEvent(String session)<br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
static String userCommand(String name, String param)<br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
static String userCommand(String session, String userid, String name, String param)<br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userSubmit ===<br />
<br />
static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)<br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)<br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL<br />
<br />
== Location ==<br />
<br />
=== LocationBeaconEvent ===<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<source lang="java">void LocationBeaconEvent(String session, String address, String userid, String zone, String distance, boolean background)</source><br />
<br />
Called when the HSYCO App detects a change in the proximity of one of the configured beacons.<br />
<br />
There is no guarantee that the event would be fired.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - session id string that uniquely identifies the client session<br />
* address: string - the beacon's address<br />
* userid: string - the user id<br />
* zone: string - the beacon's zone<br />
* distance: string - far, near, immediate or off<br />
* background: boolean - true if the app called the server while in background mode (app closed)</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8996Java Callback Methods API2020-09-23T09:57:07Z<p>Gionatan: /* User Interface */</p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
static void DaylightEvent(boolean day)<br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
static String getUserVersion()<br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
static void haActiveEvent(boolean active)<br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
static int PowerEvent(int power)<br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
static void programTimerEvent(String name)<br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
static void SchedulerEvent(String groupname, String schedulename)<br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
static void StartupEvent()<br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
static void SunPositionEvent(int azimuth, int elevation)<br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
static void TimeEvent(long time)<br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
static void varEvent(String name, String value)<br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
static int cameraCommandEvent(String function, String action, String camera)<br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
static void CameraMotionEvent(String eventName, long remoteTime)<br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
static void CameraViewEvent(String camera, boolean active)<br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
static void DmxEvent(int channel, int state)<br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
static int DmxFilter(int channel, int state, boolean reverse)<br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
static void DmxStartupEvent(int serverIndex)<br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
static void IREvent(boolean received, int irtransid, String event)<br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
static void IOEvent(String id, String value)<br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
static void IOStartupEvent(int serverIndex)<br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)<br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
static String httpCallEvent(String address, boolean secure, String query)<br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)<br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
static void LocationEvent(long mac, InetAddress ip, int zoneId)<br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
static void SysLogEvent(String address, String log)<br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
static boolean PBXCallEvent(String host, String caller, String called)<br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
static void SlimPowerEvent(int index, int power)<br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
static void SlimStatusEvent(int index, int status)<br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
static void SlimVolumeEvent(int index, int volume)<br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
static boolean UserTimerEvent(String name, boolean active)<br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
static void pageEvent(String address, String session, String userid, String project, String page)<br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
static void loginEvent(String address, String session, String userid)<br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
static void logoutEvent(String address, String session, String userid, boolean lock)<br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
static void uiClearEvent(String session)<br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
static String userCommand(String name, String param)<br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
static String userCommand(String session, String userid, String name, String param)<br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userSubmit ===<br />
<br />
static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)<br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)<br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL<br />
<br />
== Location ==<br />
<br />
=== LocationBeaconEvent ===<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<source lang="java">void LocationBeaconEvent(String session, String address, String userid, String zone, String distance, boolean background)</source><br />
<br />
Called when the HSYCO App detects a change in the proximity of one of the configured beacons.<br />
<br />
There is no guarantee that the event would be fired.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - session id string that uniquely identifies the client session<br />
* address: string - the beacon's address<br />
* userid: string - the user id<br />
* zone: string - the beacon's zone<br />
* distance: string - far, near, immediate or off<br />
* background: boolean - true if the app called the server while in background mode (app closed)</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8995Beacons on HSYCO App for iOS2020-09-23T09:03:33Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[JavaScript_Callback_Functions_API#LocationBeaconEvent|LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini or [[Settings#Location_Services|Location Services]] under [[Settings]]:<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8994Beacons on HSYCO App for iOS2020-09-21T13:55:32Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[JavaScript_Callback_Functions_API#LocationBeaconEvent|LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini or [[Settings#Location_Services|Location Services]] under [[Settings]]:<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Settings&diff=8993Settings2020-09-21T13:53:28Z<p>Gionatan: /* Location Services */</p>
<hr />
<div>[[Category:Manager]]<br />
[[File:Manager Settings Icon.png|class=appIcon|The '''Settings''' icon]]<br />
HSYCO can be configured using the Settings application in the Manager.<br />
<br />
Settings stores all configuration parameters in the hsyco.ini file.<br />
<br />
<br />
{{tip|You can copy this file to save the current configuration, or manually change it. In this case, be sure to reopen the Settings application after the changes have been saved.}}<br />
<br />
<br />
The configuration is read at start-up, so any changes become effective only after restarting the HSYCO process.<br />
<br />
HSYCO is factory configured to automatically restart when hsyco.ini is saved.<br />
<br />
<br />
[[File:Manager_settings_menu.png|border|center|600px]]<br />
<br />
<br />
When you make changes using Settings, the hsyco.ini file will be overwritten when you press the Save button.<br />
<br />
You can’t return to the previous configuration once it is saved.<br />
<br />
The Revert button allows you to reload the current configuration if you have made changes in Setting that have not yet been saved.<br />
<br />
Settings parameters are grouped in several sections.<br />
<br />
You can make changes to any parameter, even in different sections, and then save all changes together.<br />
<br />
== System ==<br />
<br />
The Systems section contains all general configuration parameters, including vital parameters affecting system’s security and reliability.<br />
<br />
These parameters are further split in several sub-sections.<br />
<br />
=== General ===<br />
<br />
<br />
[[File:Manager settings general.png|border|center|600px]]<br />
<br />
<br />
'''URLKey'''<br />
<br />
'''Default:''' hsycoserver<br />
<br />
'''Format:''' string of at least 8 characters<br />
<br />
<br />
To protect against malicious service discovery robots, HSYCO does not answer to Web requests where only the server address is defined, for example https://192.168.0.50, but requires an extended URL, which must include an access key, called URLKey.<br />
<br />
{{tip|The URLKey must be at least 8 characters long.}}<br />
<br />
It is possible to specify more than one URLKEY, separated by a comma; in this case all the specified URLKEYs will be valid for the web access to HSYCO.<br />
<br />
The factory default URLKey is hsycoserver.<br />
<br />
The URLKey is not a secret password, but only an additional protection feature.<br />
<br />
<br />
'''Language'''<br />
<br />
'''Default:''' en<br />
<br />
'''Format:''' cn | en | fr | it<br />
<br />
<br />
Some I/O Servers and other core services use localized text messages. This parameter defines the default system language for these services.<br />
<br />
<br />
'''AutoKillFiles'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' list of file names separated by commas<br />
<br />
<br />
This parameter is usually set as: "hsyco.ini,hsyco.jar,com/hsyco/user.class" forcing the automatic restart after the changes of the three files listed.<br />
<br />
<br />
'''DatabaseTransactionLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
If true the HSQLDB embedded database transaction log file is used to log individual transactions between checkpoints.<br />
<br />
If false the log file is not used, improving the performance and reducing I/O but, in case of uncontrolled shutdown of the HSYCO process, all data updates after the last checkpoint (a database checkpoint is automatically perfomed every 60 seconds) will be lost.<br />
<br />
<br />
'''StartupDelay'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' 0 or positive integer number of seconds<br />
<br />
<br />
When set to a positive number, the HSYCO server will wait for the specified number of seconds at start-up before becoming active.<br />
<br />
This start-up delay could be useful to prevent HSYCO from starting before other peripherals or devices, like external storage systems, are completely initialized.<br />
<br />
<br />
'''ExceptionWatchdog'''<br />
<br />
'''Default:''' 5<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
After N uncaught Java execution exceptions, the HSYCO server will be killed and restarted.<br />
<br />
Set to 0 to disable the exception watchdog.<br />
<br />
<br />
'''EventsLoadTimeout'''<br />
<br />
'''Default:''' 20<br />
<br />
'''Format:''' positive integer number of seconds<br />
<br />
<br />
When an EVENTS file is saved, If any code section takes more than the specified amount of time to execute during the test run and INIT events sections, HSYCO will abort the JavaScript engine, rename events.txt to events_unsafe.txt and, a few seconds later, will restart the whole HSYCO server engine to protect the integrity of the system.<br />
<br />
If you have code in EVENTS that requires more than the default 20 seconds to run, you should set a larger value for EventsLoadTimeout.<br />
<br />
<br />
'''userLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Set to true to enable the log of the Java methods called in user.java or of the commands defined in the EVENTS programming environment.<br />
<br />
<br />
'''eventsLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
If true, the log of events received from field devices is enabled, for example the events related to the IO Servers.<br />
<br />
<br />
'''verboseLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
If true, the extended log is enabled.<br />
<br />
It is useful for debugging, or during the advanced customization phase or the development of Java code.<br />
<br />
<br />
'''persistentLog'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to false, message and error logs are not written to files, and are only visible in the Manager's Log Viewer.<br />
<br />
You may want to avoid writing log files when using servers with limited disk space or when the mass storage device is an SSD with limited write cycles.<br />
<br />
<br />
'''securityLogDailyFiles'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to true, the security logs are written in daily files named MMDD-security.log.<br />
<br />
<br />
'''LogMaxAge'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' 0, or positive integer number<br />
<br />
<br />
Log files are automatically deleted when older than the number of days defined with this parameter.<br />
<br />
When set to 0 or not defined, log files are not deleted automatically.<br />
<br />
=== Access Control ===<br />
<br />
<br />
<br />
[[File:Configuration Access Control.png|border|center|600px]]<br />
<br />
<br />
'''trustedNet'''<br />
<br />
'''Default:''' local<br />
<br />
'''Format:''' local, or nn.nn.nn.nn-nn.nn.nn.nn<br />
<br />
<br />
IP addresses that define the group of network addresses belonging to the secure local network.<br />
<br />
It is possible to enter multiple, comma-separated IP ranges or individual IP addresses, or simply enter “local”, so that HSYCO will assume all IP addresses in the LAN as trusted.<br />
<br />
The loop-back IP address (127.0.0.1) is considered part of the trusted network only when the trustedNet option is set to "local", or when explicitly listed.<br />
<br />
The Web clients connecting to HSYCO from these addresses are subject to the time-out defined in KeysTrustedValidityHours, which is usually longer than the one used for all the other IP addresses, defined in KeysNotTrustedValidityHours.<br />
<br />
<br />
'''KeysTrustedValidityHours'''<br />
<br />
'''Default:''' 24<br />
<br />
'''Format:''' integer > 0 or hh:mm<br />
<br />
<br />
Login time-out in hours for the connections from trusted IP addresses.<br />
<br />
Set on a very high value, e.g. 100000, to practically avoid the time-out of sessions.<br />
<br />
It can also be set using the hh:mm hours and minutes format.<br />
<br />
<br />
'''KeysNotTrustedValidityHours'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer > 0 or hh:mm<br />
<br />
<br />
Login time-out in hours for not trusted IP addresses.<br />
<br />
It can also be set using the hh:mm hours and minutes format.<br />
<br />
<br />
'''KeysInactivityHours'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer > 0 or hh:mm<br />
<br />
<br />
Inactivity time-out in hours.<br />
<br />
This is an optional parameter; if not set there will be no inactivity time-out and the user session will be automatically logged out based on the login time-out only.<br />
<br />
It can also be set using the hh:mm hours and minutes format.<br />
<br />
<br />
'''KeysInactivityMode'''<br />
<br />
'''Default:''' browser<br />
<br />
'''Format:''' browser | cameras | commands<br />
<br />
<br />
Inactivity time-out mode.<br />
<br />
This is an optional parameter.<br />
<br />
It is significant only when KeysInactivityHours is also defined.<br />
<br />
In browser mode, having the Web browser open on the HSYCO page will keep the session alive.<br />
<br />
In cameras mode the session will remain alive only when sending commands or watching cameras.<br />
<br />
In commands mode the session will stay alive only if commands are sent before the inactivity timer expires.<br />
<br />
<br />
'''HTTPServerPublicDirectory'''<br />
<br />
'''Default:''' browser<br />
<br />
'''Format:''' directory name<br />
<br />
<br />
If defined, enables a simple Web server that serves files, without any parsing, via HTTP and HTTPS, only to clients in the trusted range of IP addresses.<br />
<br />
This parameter sets the name of the directory, under the www root Web directory, used for the public files.<br />
<br />
If, for example, you have HTTPServerPublicDirectory=public, and an HTML file named home.html in the public directory, then the <nowiki>https://192.168.0.50/public/home.html</nowiki> URL will point to that file.<br />
<br />
As you see, you shouldn’t add the URLKey in public URLs.<br />
<br />
<br />
'''HTTPServerLowSecurityEnabled'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
Usually, the HTTP server is only active to let cameras and PBX systems send motion detection and calls notifications.<br />
<br />
To avoid the authentication keys, PIN and PUK codes and all traffic to be transmitted in the clear, the HTTP protocol is not normally used for Web access to HSYCO.<br />
<br />
Set the parameter to true only when you want to enable the not-secure HTTP protocol for Web access to HSYCO.<br />
<br />
<br />
'''WebAdminNetConfigLock'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
If true, the Web network settings functions are disabled.<br />
<br />
This parameter should be set to true once you expect no changes in the network configuration of HSYCO Server.<br />
<br />
=== Network ===<br />
<br />
<br />
[[File:Configuration Network.png|border|center|600px]]<br />
<br />
<br />
'''HTTPServerPort'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number < 65535<br />
<br />
<br />
TCP/IP port of HSYCO HTTP Web Server. If not defined, the HTTP server is not enabled.<br />
<br />
Normally set to 80.<br />
<br />
<br />
'''HTTPSSLServerPort'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number < 65535<br />
<br />
<br />
TCP/IP port of HSYCO HTTPS Web Server.<br />
<br />
If not defined, the HTTPS server is not enabled.<br />
<br />
Normally set to 443.<br />
<br />
<br />
'''SysLogServerPort'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number < 65535<br />
<br />
<br />
TCP/IP port of HSYCO SYSLOG Web server.<br />
<br />
The SYSLOG server is used to receive from the Access Points (AP) the information to determine which AP every user in the Wi-Fi LAN is using to connect.<br />
<br />
If not defined, the SYSLOG server is not enabled.<br />
<br />
It is usually set to 514.<br />
<br />
<br />
'''ServerName'''<br />
<br />
'''Default:''' hsyco<br />
<br />
'''Format:''' domain name<br />
<br />
<br />
Name used to generate the SSL certificate.<br />
<br />
It is necessary for the cryptography of the HTTPS Web traffic and should correspond to the domain name through which the HSYCO server is accessed via the Internet.<br />
<br />
The certificate is saved in the hsyco.keys file.<br />
<br />
When HSYCO is started, if this file is not available or its name doesn’t match the ServerName parameter in hsyco.ini, a new SSL certificate is automatically generated according to the name defined in ServerName.<br />
<br />
<br />
'''OffLineCache'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
HSYCO implements the off-line cache feature of the Web browsers that support the HTML 5.0 standard.<br />
<br />
To enable the off-line storage on the Web browser of all HSYCO HTML static content, set this parameter to true.<br />
<br />
{{tip|Note that all files saved under any subdirectory named "nocache" will not be listed in the persistent cache's manifest file.}}<br />
<br />
<br />
'''HTTPServerThreads'''<br />
<br />
'''Default:''' 256<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
Sets the total number of processing threads for the HTTP and HTTPS internal web servers.<br />
<br />
You should change this parameter only when you have a very large number of active web clients.<br />
<br />
Web browsers normally use only a few (up to about 6) concurrent connections for each session, and the default should be fine to support up to at least 40 active clients.<br />
<br />
When the HTTP and HTTPS servers run low of threads, some clients could see their requests rejected, causing page load errors or becoming unresponsive.<br />
<br />
In this case you should see “too many connections” error messages in HSYCO’s log files.<br />
<br />
{{tip|Increasing this parameter also increases memory and I/O resources requirements to the underlying operating system.}}<br />
<br />
<br />
'''HTTPRootRedirect'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' relative or absolute URL<br />
<br />
<br />
Set to a valid absolute or relative URL to redirect root requests.<br />
<br />
<br />
'''HTTPSCompatibility'''<br />
<br />
'''Default:''' new<br />
<br />
'''Format:''' new | old<br />
<br />
<br />
Set to "old" to retain support for older browsers when using HTTPS.<br />
<br />
{{tip|You should be aware of the security and compatibility implications, specific of your application environment, when setting this option.}}<br />
<br />
=== Clock ===<br />
<br />
<br />
[[File:Configuration Clock.png|border|center|600px]]<br />
<br />
<br />
'''TimeAutoUpdate'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' false | true | NTP server name/address<br />
<br />
<br />
HSYCO automatically sets the local date and time by polling Network Time Protocol (NTP) servers.<br />
<br />
To disable this feature, set this parameter to false.<br />
<br />
To use a specific NTP server, set this parameter to the name or IP address of the NTP server.<br />
<br />
<br />
'''TimeZone'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' the time zone id<br />
<br />
<br />
Set the current time zone.<br />
<br />
The time zone information is used to obtain the correct local time and automatically adjust for daylight saving time.<br />
<br />
If this parameter is not set, HSYCO will use the operating system’s time zone settings.<br />
<br />
The time zone id is either in the form “Area/Location”, or a generic “GMT+NN”, “GMT-NN” format that simply defines the hours offset from UTC time.<br />
<br />
When the “Area/Location” format is used, the clock is automatically adjusted for daylight saving time.<br />
<br />
The TimeZone value should have no spaces; replace spaces in area or location names with underscores, for example “America/New_York”.<br />
<br />
When HSYCO starts, you can check the message.log file to see the actual time zone and DST setting, just after the start-up message, for example:<br />
<br />
2013.07.10 15:28:30.113 - HSYCO Ver. 3.3.0 Build 0112 (USER Ver. No User Code) started<br />
2013.07.10 15:28:30.425 - Time zone is: Europe/Rome (Central European Summer Time)<br />
<br />
<br />
'''Latitude'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative numerical value, decimals separated by “.”<br />
<br />
<br />
Latitude in decimal degrees (positive for the Northern Hemisphere), to calculate the sun position and sunrise/sunset time.<br />
<br />
<br />
'''Longitude'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative numerical value, decimals separated by “.”<br />
<br />
<br />
Longitude in decimal degrees (positive for the Eastern Hemisphere), to calculate the sun position and sunrise/sunset time.<br />
<br />
<br />
'''SunriseOffsetMinutes'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative integer number<br />
<br />
<br />
Deviation in minutes from the civil sunrise time (in advance if negative, delayed if positive).<br />
<br />
<br />
'''SunsetOffsetMinutes'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative integer number<br />
<br />
<br />
Deviation in minutes from the civil sunset time (in advance if negative, delayed if positive).<br />
<br />
=== High Availability ===<br />
<br />
<br />
[[File:Configuration High Availability.png|border|center|600px]]<br />
<br />
<br />
'''haMode'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' master | slave<br />
<br />
<br />
Enables the high availability configuration of HSYCO.<br />
<br />
The high availability configuration uses two different HSYCO systems, one is configured as the master system, the other as slave.<br />
<br />
<br />
'''haMasterIP'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' IP address: nnn.nnn.nnn.nnn<br />
<br />
<br />
Mandatory parameter for the high availability configuration.<br />
<br />
It specifies the IP address of the HSYCO master system.<br />
<br />
<br />
'''haSlaveIP'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' IP address: nnn.nnn.nnn.nnn<br />
<br />
<br />
Mandatory parameter for the high availability configuration.<br />
<br />
It specifies the IP address of the HSYCO slave system.<br />
<br />
<br />
'''haActiveIP'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' IP address: nnn.nnn.nnn.nnn<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
Defines an IP address that the active server, master or slave, will assign as an IP alias to its main Ethernet port (eth0).<br />
Using this IP address, clients will be able to access the active server with the same address, regardless of the active server being the master or the slave.<br />
<br />
<br />
'''haDisableCommandEvents'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
If true, command methods and actions in Java and EVENTS are automatically disabled on the HSYCO Server that is not active (for example the system defined as slave is not active when the master system works properly) for the following systems: Audio, Cameras, Comm ports, DMX, I/O Servers, IRTrans, Modbus (write command are disabled) Squeezebox, URL.<br />
<br />
<br />
'''haDisableFilesSync'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
If true, files changes on the master will not be synched to the slave server (changes to access.ini, scheduler.ini and timers.data will not be synched too).<br />
<br />
<br />
'''haClientSessionsFailover'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
When true the slave server will mirror the master's authentication keys, allowing a clean transition of authenticated sessions from master to slave.<br />
<br />
{{tip|To ensure a proper transition of the client sessions from master to slave, the ServerName option and the hsyco.keys file of the slave server must also be the same as on the master.}}<br />
<br />
<br />
<br />
<br />
'''haTimeoutSeconds'''<br />
<br />
'''Default:''' 4<br />
<br />
'''Format:''' >1 integer number<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
The slave unit becomes active if it doesn't receive the keep-alive packet from the master unit for more than the number of seconds set with this parameter.<br />
<br />
{{tip|Always set this parameter with the same value on both the master and slave units.}}<br />
<br />
=== Backup ===<br />
<br />
<br />
[[File:Manager settings backup.png|border|center|600px]]<br />
<br />
<br />
'''DatabaseBackup'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to true, a hot backup of the core database is automatically executed on a daily basis, saving data in the data_backup directory, and overwriting the previous backup files.<br />
<br />
The data_backup directory can be used to restore the database. The [[Database Maintenance]] document explains how to safely perform the database restore procedure.<br />
<br />
{{note|Only one process can access the database files at any time. If you need to access these files using other applications or SQL utilities, you should stop the HSYCO process, otherwise all data could be lost.}}<br />
<br />
<br />
'''DatabaseRecovery'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to true, and DatabaseBackup is also enabled, if an unrecoverable database error occurs at startup, HSYCO will rename the corrupted database directory to "data_original" and try to recover from last backup, if available.<br />
<br />
<br />
'''RootBackupDay'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' *, mon, tue, wed, thu, fri, sat, sun, 1-31<br />
<br />
<br />
Day schedule for automatic root backup:<br />
* *: every day<br />
* mon: every Monday (weekly schedule)<br />
* tue: every Tuesday (weekly schedule)<br />
* wed: every Wednesday (weekly schedule)<br />
* thu: every Thursday (weekly schedule)<br />
* fri: every Friday (weekly schedule)<br />
* sat: every Saturday (weekly schedule)<br />
* sun: every Sunday (weekly schedule)<br />
* 1-31: on the day (monthly schedule)<br />
<br />
<br />
'''RootBackupHour'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' *, 0-23<br />
<br />
<br />
Hour schedule for automatic root backup:<br />
* *: every hour<br />
* 0-23: on the hour (daily schedule)<br />
<br />
<br />
'''RootBackupMinute'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' 0-59<br />
<br />
<br />
Minute schedule for automatic root backup:<br />
* 0-59: on the minute<br />
<br />
<br />
{{note|<br />
Using the RootBackupDay, RootBackupHour and RootBackupMinute you can set a monthly, weekly, daily or hourly schedule for the automatic root backup.<br />
<br />
To schedule a single backup every month, set RootBackupDay to the N-th day of the month, for example 1, then set RootBackupHour and RootBackupMinute to the preferred hour and minute.<br />
<br />
To schedule a weekly backup, set RootBackupDay to a day of the week, for example Sunday, then set RootBackupHour and RootBackupMinute to the preferred hour and minute.<br />
<br />
To schedule a daily backup, set RootBackupDay to "*", then set RootBackupHour and RootBackupMinute to the preferred hour and minute.<br />
<br />
Finally, to schedule an hourly backup, set RootBackupDay to "*", RootBackupHour to "*" and RootBackupMinute to the preferred minute.<br />
}}<br />
<br />
<br />
'''RootBackupDestinations'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' comma-separated list of local or remote destination paths.<br />
<br />
<br />
The backup file destinations.<br />
<br />
The automatic root backup engine creates a single zip file and saves copies of it locally on the HSYCO server file system or on remote servers using the SSH secure copy protocol.<br />
<br />
To copy the backup zip file to the local file system (including remote network storage mounted on the server's file system), simply use the absolute pathname of the destination file, for example "/backup/mybackup.zip".<br />
<br />
To copy the backup zip file to a remote SSH server, use the following format:<br />
<br />
scp:<login>:<password>@<host>:<port>:<path><br />
<br />
where:<br />
*<login> is the remote user<br />
*<password> is the remote user's SSH password<br />
*<host> is the remote server's name or IP address<br />
*<port> is the SSH port number. The port number can be omitted if the SSH service is using the standard SSH port 22. In this case the format becomes: scp:<login>:<password>@<host>:<path><br />
*<path> the pathname of the zip file on the remote server. The pathname can be absolute (starting with / on Unix systems) or relative to the user's home directory.<br />
<br />
You can also use a few special parameters in the pathname to generate dynamic names based on the backup date and time:<br />
* %date is replaced by the date and time as yyyyMMddHHmm<br />
* %day is replace by the day of the month as two digits, from 01 to 31<br />
* %dow is replaced by the day of week, mon-sun<br />
* %hour is replaced by the hour of day as two digits, from 00 to 23.<br />
<br />
Using these parameters you will be able to create permanent log files (using %date in the path name) or rolling files (using %day, %dow or %hour) with backup files automatically overwriting older files.<br />
<br />
Example: the following RootBackupDestinations will save one file on remote server 192.168.1.201, accessing it as user "john" with password "mypassword1", saving the file in the /hsyco_backup/ directory and with rolling names like hsyco-office-mon.zip, hsyco-office-tue.zip, etc. It will also save the backup locally, at /mnt/usb/hsyco_backup/hsyco-office.zip (this file is replaced at every new backup).<br />
<br />
scp:john:mypassword1@192.168.1.201:/hsyco_backup/hsyco-office-%dow.zip,/mnt/usb/hsyco_backup/hsyco-office.zip<br />
<br />
<br />
'''RootBackupExclude'''<br />
<br />
'''Default:''' empty or undefined (logs and motion directories, and the hsyco.jar file are excluded)<br />
<br />
'''Format:''' comma-separated list of paths that should be skipped during the backup process<br />
<br />
<br />
You can set this parameter to skip directories and files you don't need be saved in the backup zip file. If you set this parameter, it is recommended to also explicitly list logs, motion and hsyco.jar, if you don't want these in the backup.<br />
<br />
=== Remote HSYCO Servers ===<br />
<br />
The HSYCO Remote I/O Server is a powerful and secure server-to-server communication system that allows an HSYCO server read and write access to all the I/O data points and GUI variables of other remote HSYCO servers. The remote HSYCO Servers settings are used to enable remote HSYCO servers access to this server.<br />
<br />
The HSYCO Remote I/O Server uses a secure HTTPS API based on the REST (Representational state transfer) model and the JSON data format. A subset of this API can be used by third-party HTTP client applications. Read the [[HSYCO Remote API]] specification for additional details.<br />
<br />
<br />
[[File:Configuration Remote HSYCO Servers.png|border|center|600px]]<br />
<br />
<br />
'''RemoteServerPassword'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers), 8 characters or longer<br />
<br />
<br />
Set this password to enable this HSYCO server to be accessed by another HSYCO server via the HSYCO Remote I/O Server (see the HSYCO Remote I/O Server Application Note for further information).<br />
<br />
{{note|The password must be at least 8 characters long. Use a very long and randomly generated string to reduce the risk of unauthorized access.}}<br />
<br />
<br />
'''RemoteServerAddress'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' comma separated list of IP addresses, or *<br />
<br />
<br />
Set to the IP addresses of the remote HSYCO servers that should be allowed to access this HSYCO server.<br />
<br />
Set to * to allow any remote IP address.<br />
<br />
<br />
'''RemoteServerControl'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Set to true to allow the remote server to modify the data points values of this HSYCO server.<br />
<br />
<br />
'''RemoteServerIOFilter'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' comma separated list of I/O Servers IDs<br />
<br />
<br />
If you want to limit remote access and control to just some of the I/O Servers defined in this HSYCO, use this parameter to list the I/O Servers that should be available to the remote HSYCO system.<br />
<br />
Filtering out I/O Servers that are not used remotely could have a positive impact on performance and network traffic.<br />
<br />
<br />
'''RemoteServerUIFilter'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' comma separated list of I/O Servers IDs<br />
<br />
<br />
If you want to limit remote access and control to just some of the user interface objects defined in this HSYCO, use this parameter to list the objects’ IDs prefixes (a prefix is the first part of the ID, before the first dot character, if you are using a dot-separated notation; use the full ID if not using the dot notation) that should be available to the remote HSYCO system.<br />
<br />
Filtering out UI objects that are not used remotely could have a positive impact on performance and network traffic.<br />
<br />
=== Email ===<br />
<br />
<br />
[[File:Configuration Email.png|border|center|600px]]<br />
<br />
<br />
'''SmtpName'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' SMTP server name or IP address<br />
<br />
<br />
SMTP server name or numeric IP address.<br />
<br />
This parameter is used by the MAIL action and sendMail() method to send email messages through a specific authenticated and secured SMTP account rather than directly to the recipient’s SMTP server.<br />
<br />
<br />
'''SmtpPort'''<br />
<br />
'''Default:''' 25, 465 or 587<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
SMTP server’s port number, if different from the default port.<br />
<br />
The default port is:<br />
* 25 for not encrypted traffic<br />
* 465 for SMTP over SSL<br />
* 587 for ESMTP.<br />
<br />
<br />
'''SmtpUser'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string<br />
<br />
<br />
Account’s username to authenticate the connection to the SMTP server.<br />
<br />
<br />
'''SmtpPassword'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string<br />
<br />
<br />
Account’s password to authenticate the connection to the SMTP server.<br />
<br />
<br />
'''SmtpSSL'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true | esmtp<br />
<br />
<br />
Set to “true” for SMTP server that support SMTP over SSL (default port is 465).<br />
<br />
Set to “esmtp” for SMTP server that support ESMTP (default port is 587).<br />
<br />
Set to “false” for SMTP servers that don’t support traffic encryption.<br />
<br />
<br />
'''SmtpDebug'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Set to “true” to dump all SMTP sessions data to the console log file. This option is for debugging purposes only, and should not be left set to true when not needed.<br />
<br />
=== Audio Server ===<br />
<br />
<br />
[[File:Configuration Audio Server.png|border|center|600px]]<br />
<br />
<br />
'''AudioServerTTS'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string<br />
<br />
<br />
This parameter is only needed if you are using a text-to-speech engine that is not the default one for the operating system.<br />
<br />
See the [[Audio and Public Announcement]] section for additional information.<br />
<br />
<br />
'''AudioServerVolume'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Change the default output volume for pre-recorded audio files and the text-to-speech engine.<br />
<br />
<br />
'''AudioServerQuality'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Change the default quality for the text-to-speech engine.<br />
<br />
<br />
'''AudioServerSpeed'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Change the default speed for pre-recorded audio files and the text-to-speech engine.<br />
<br />
=== Extras ===<br />
<br />
<br />
[[File:Configuration Extras.png|border|center|600px]]<br />
<br />
<br />
This section is used to set other not standard parameters that should be saved in hsyco.ini, like application-specific parameters.<br />
<br />
== I/O Servers ==<br />
<br />
HSYCO Server interfaces to several field sub-systems, including lighting and automation systems, video cameras, HVAC controllers, security systems, and other special-purpose devices. HSYCO supports several standard protocols, like BACnet, DALI, DMX, KNX, Modbus, as well as quite a few proprietary protocols.<br />
<br />
Most of these field systems are represented inside HSYCO as “I/O servers”. An I/O server is a software module that offers a standardized abstraction layer so that even very different systems can be interfaced using a consistent naming convention and programming model.<br />
<br />
<br />
[[File:Configuration IO Servers.png|border|center|600px]]<br />
<br />
<br />
Each I/O server must have a unique ID. You can add a new I/O server pressing the + button.<br />
<br />
<br />
[[File:Configuration IO Servers New IO.png|border|center]]<br />
<br />
<br />
Select the type and enter the server’s unique ID.<br />
<br />
Already defined I/O servers could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
Each server type may require different configuration parameters, like IP address and port, serial port id, or authentication information.<br />
<br />
Refer to the Application Notes documentation for detailed configuration and interfacing information for I/O servers.<br />
<br />
The “Shutdown when inactive” parameter, that is available for all I/O server types, is only used in high availability configurations. <br />
<br />
Set it to true to automatically stop the I/O server when the HSYCO server (master or slave) is not the active system. Set to false to keep the I/O server running even when the HSYCO server is not the active system.<br />
<br />
== Communication Ports ==<br />
<br />
<br />
[[File:Configuration Communication Ports.png|border|center|600px]]<br />
<br />
<br />
The Comm Ports section is used to define all serial ports and their configuration parameters.<br />
<br />
Each port must have a unique ID. You can add a new ports pressing the + button.<br />
<br />
<br />
[[File:Configuration Communication Ports New Comm.png|border|center]]<br />
<br />
<br />
Select the type and enter the port’s unique ID.<br />
<br />
Already defined ports could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
The different types of comm ports have different configuration parameters.<br />
<br />
=== Serial ports ===<br />
<br />
<br />
[[File:Configuration Serial ports.png|border|center|600px]]<br />
<br />
<br />
To configure one of the real serial ports of the server, or a USB serial adapter, create a port of type “serial”.<br />
<br />
'''Port'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Complete or partial system name of the associated communication port. In the Linux based architecture of the HSYCO servers this is the naming convention:<br />
<br />
* COM1: ttyS0 or /dev/ttyS0<br />
* COM2: ttyS1 or /dev/ttyS1<br />
* COM3: ttyS2 or /dev/ttyS2<br />
* COM4: ttyS3 or /dev/ttyS3<br />
<br />
For USB connected devices:<br />
<br />
* 1st USB device: ttyUSB0 or /dev/ttyUSB0<br />
* 2nd USB device: ttyUSB1 or /dev/ttyUSB1<br />
* ...etc etc<br />
<br />
<br />
'''Baud rate'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Port speed.<br />
<br />
<br />
'''Data bits'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
The number of bits can be 8, 7, 6 or 5. It should be set to 8 in most cases.<br />
<br />
<br />
<br />
'''Stop bits'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
The number of stop bits can be 1, 1.5 or 2.<br />
<br />
<br />
'''Parity'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Parity can be none, odd, even, mark or space.<br />
<br />
<br />
'''Flow control'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Flow control can be none, XON/XOFF or RTS/CTS.<br />
<br />
<br />
'''Timeout'''<br />
<br />
'''Default:''' 2000<br />
<br />
'''Format:'''<br />
<br />
<br />
The timeout parameter is optional and could be omitted. It defines the serial port receive timeout, in milliseconds. Defaults to 2 seconds if not defined.<br />
<br />
=== Serial Gateways ===<br />
<br />
Generic serial gateways that provide bi-directional serial port communication via a TCP connection are supported by HSYCO. <br />
<br />
[[File:Configuration Server ports.png|border|center|600px]]<br />
<br />
To configure a comm port to send data to the serial port of a serial gateway, you should set the comm port type to “server”, and set the gateway’s IP address and TCP port number.<br />
<br />
The serial port handshake parameters must be set on the gateway using its configuration utilities.<br />
<br />
HSYCO supports a high-availability, failover configuration for serial gateways.<br />
<br />
HSYCO supports a high-availability, failover configuration for serial gateways. You enable failover by adding a second IP address to the IP parameter.<br />
<br />
HSYCO will try to establish a connection using the first IP address, automatically switching to the failover address if a communication error occurs.<br />
<br />
In this configuration, the JavaScript or Java closeComm() function can be used to force a reconnect on the next call to readComm() or writeComm(), so that a switch between the fail-over IPs would happen if the current IP is not responding.<br />
<br />
=== HWG I/O Server ports ===<br />
<br />
Some network I/O controllers produced by HWG have a serial port, that could be used as fully functional serial port by HSYCO. To configure these ports, select type “io”, then select the I/O server id of the HWG controller and enter the normal serial port configuration parameters.<br />
<br />
<br />
[[File:Configuration HWG Server ports.png|border|center|600px]]<br />
<br />
<br />
=== IRTrans ports ===<br />
<br />
Some IRTrans network IR controllers have a local serial port. HSYCO can use this port as an output-only serial port.<br />
<br />
To configure an IRTrans serial port, select type “irtrans”, and select the id of the IRTrans device. The serial port communication parameters, like speed, flow control etc., should be configured on the IRTrans.<br />
<br />
<br />
[[File:Configuration IRTrans ports.png|border|center|600px]]<br />
<br />
== IRTrans Servers ==<br />
<br />
The IRTrans Servers section is used to define the IRTrans network infrared devices.<br />
<br />
<br />
[[File:Configuration IRTrans Servers1.png|border|center|600px]]<br />
<br />
<br />
Each IRTrans must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration IRTrans Servers2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration IRTrans Servers3.png|border|center|600px]]<br />
<br />
<br />
The only configuration parameter is the IRTrans IP address.<br />
<br />
<br />
== Cameras == <br />
<br />
This section is used to define individual IP cameras, to set general configuration parameters for video processing, and to define camera grids for the user interface.<br />
<br />
<br />
[[File:Configuration Cameras1.png|border|center|600px]]<br />
<br />
<br />
=== General parameters ===<br />
<br />
'''CamerasRecordingMotionTriggerSeconds'''<br />
<br />
'''Default:''' 5<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
Number of seconds during which HSYCO keeps on recording from a camera after a recording trigger event for that camera. It is possible to set this parameter at 0, disabling the triggered recording of events; this can be useful in case it is preferred to control recording only through the Java user code or EVENTS.<br />
<br />
<br />
'''CamerasRefreshMillis'''<br />
<br />
'''Default:''' 1000<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
Camera frames acquisition interval, in milliseconds. For example, for a frequency of 4 frames a second, set the value to 250. A low value corresponds to a higher number of frames acquired and recorded in the time unit, with a heavier load in terms of CPU resources and disk space.<br />
<br />
<br />
'''CamerasResizedQuality'''<br />
<br />
'''Default:''' 0.7<br />
<br />
'''Format:''' decimal number between 0 and 1 (decimals separated by “.”)<br />
<br />
<br />
Image quality for images processing and resizing. Numbers close to 1 produce a better quality, but heavier load and larger size for each frame.<br />
<br />
<br />
'''CamerasMinFreeSpaceBytes'''<br />
<br />
'''Default:''' if not set, HSYCO will start deleting older frames when free space is less than 2GB, and stop recording if free space drops below 1GB. If the motion directory is on a separate file system, the default limits are 15% and 10% of total file systems space<br />
<br />
'''Format:''' positive integer number, followed by K for kilobytes, M for megabytes, G for gigabytes or T for terabytes<br />
<br />
Cameras recording is disabled and older frames could be deleted if the file systems's free space drops below this level.<br />
<br />
Use the "Extras" tab in "System" settings to set this option.<br />
<br />
=== Cameras parameters ===<br />
<br />
Each camera must have a unique ID. You can add a new cameras pressing the + button in the cameras list panel.<br />
<br />
<br />
[[File:Configuration Cameras2.png|border|center]]<br />
<br />
<br />
Already defined cameras could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration Cameras3.png|border|center|600px]]<br />
<br />
<br />
'''URL'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:''' complete URL<br />
<br />
<br />
Complete URL to acquire single frames in JPEG format, or MJPEG streams, in the desired resolution. Mandatory for each camera.<br />
Recording is based on frames acquired with this URL.<br />
<br />
When using MJPEG streams, it is advisable to configure the number of frames per second the camera streams to a value that is very close to HSYCO’s frame rate as set with CamerasRefreshMillis.<br />
<br />
<br />
'''URL Small'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' complete URL<br />
<br />
In order to optimize camera processing performance, set this optional parameter. The URL fetches frames at a lower resolution. When serving frames to the Web interface, HSYCO will automatically choose the most appropriate frame resolution to use, based on the size of the frame in the Web interface.<br />
<br />
Small frames are also normally used to create grids, improving processing performance.<br />
<br />
<br />
{{note|For a list of supported URLs check here: [[Camera URLs]] and here: [[Encoder URLs]].}}<br />
<br />
<br />
'''PTZ'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' name of the PTZ driver<br />
<br />
<br />
Defines the PTZ features of a camera and family of PTZ driver. The PTZ control of a camera is automatically added to the Web interface. <br />
<br />
You can click on the edges of the camera image to control the camera: up, down, right, left, zoom and focus.<br />
<br />
Supported types are:<br />
<br />
Camera.''id''.PTZ = axis (AXIS PTZ cameras)<br />
Camera.''id''.PTZ = axis-vptz (AXIS fixed cameras with virtual PTZ support)<br />
Camera.''id''.PTZ = panasonic (Panasonic BB and BL Series cameras)<br />
Camera.''id''.PTZ = panasonic-wv (Panasonic WV Series cameras)<br />
Camera.''id''.PTZ = mobotix (Mobotix cameras)<br />
Camera.''id''.PTZ = rovio (the WowWee Rovio camera)<br />
Camera.''id''.PTZ = SNV-3120, SNP-3120, SNP-3120V, SNP-3120H (Samsung cameras)<br />
Camera.''id''.PTZ = vptz (fixed cameras with virtual PTZ support implemented by HSYCO)<br />
Camera.''id''.PTZ = user (to associate custom Java code to the control areas of the image).<br />
<br />
<br />
'''Type'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
Defines the camera model type for cameras that support this option. For example, ''Camera.samsung.Type = SND-5080''.<br />
<br />
<br />
'''IO'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' ''enabled''<br />
<br />
<br />
For some camera models, you can enable I/O and VA (Visual Analysis) option for a camera. For example, Camera.<camid>.IO=enabled. If you want to enable I/O only, set it to “enabled:io”, or to “enabled:va” to enable VA only.<br />
<br />
<br />
'''User'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
When this parameter is defined, the access requests to the frames and the commands for PTZ control of the camera are sent with user and password authentication.<br />
<br />
<br />
'''Password'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
When this parameter is defined, the access requests to the frames and the commands for PTZ control of the camera are sent with user and password authentication.<br />
<br />
<br />
'''Dropped Frames'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' integer number &ge; 0<br />
<br />
<br />
This parameter specifies the number of frames that should be discarded during recording. <br />
<br />
For example, setting the value to 1, half of the frames will be recorded out of those normally acquired from the camera; setting the value to 3, 3 frames will be discarded for each frame acquired, thus recording only 1/4 of the acquired frames. Dropping frames reduces space used to store frames on disk, and causes accelerated playback of recorded video.<br />
<br />
<br />
'''Max Age'''<br />
<br />
'''Default:''' 30d<br />
<br />
'''Format:''' positive integer number followed by “''d''” character, for days, “''h''” for hours or “''m''” for minutes<br />
<br />
<br />
Period of time, from when each frame acquired by the camera corresponding is recorded, during which the frames remain on HSYCO’s hard disk. <br />
<br />
When this time expires the frames are automatically deleted from the HSYCO motion directory. The older frames can be automatically erased even before their expiration time, in case the space available on disk drops below a safe margin.<br />
<br />
<br />
'''Motion Buffer'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive integer number <br />
<br />
<br />
Recording normally starts exactly when a recording trigger or command is issued. Using this parameter you can have HSYCO start recording some time ahead of the recording command. This is particularly important to capture video a few seconds before an event happens.<br />
<br />
When this parameter is set, HSYCO constantly acquires images from the camera, not only when necessary to display or record video. Moreover, the temporary recording of this buffer requires memory resources, and it is therefore convenient not to use high values (values included between 10 and 20, with an acquisition rate of about 400 milliseconds, can be considered normal).<br />
<br />
Enable motion buffering only when actually needed.<br />
<br />
<br />
'''Remote Password'''<br />
<br />
'''Default:''' <br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
HSYCO can optionally serve live images of its cameras through a password protected HTTP request, for example:<br />
<br />
<nowiki>https://<hsycoserver>/x/camera/<cameraid>?password=<password>&size=<width>x<height></nowiki><br />
<br />
(size is optional) for single frames or: <br />
<br />
<nowiki>https://<hsycoserver>/x/camerastream/<cameraid>?size=<width>x<height>&password=<pwd>[&period=<millis>]</nowiki><br />
<br />
to retrieve a MJPEG stream.<br />
<br />
It is also possible to define different passwords for clients inside the trusted range of IP addresses and outside.<br />
<br />
<br />
'''Trusted Password'''<br />
<br />
'''Default:''' <br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
Similar to RemoteRequestPassword, you can use this optional parameter to set remote passwords for clients inside the trusted range of IO addresses.<br />
<br />
Note that requests with the TrustedRequestPassword value will be also served via HTTP, without SSL.<br />
<br />
<br />
'''Rotate'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Allows the rotation of the images acquired by a camera. Set to the number of decimal degrees of rotation. A positive number causes a clockwise rotation. Because of the rotation, the images could be cut or have bars at their edges to adapt the rotated picture to the frame size. Setting this parameter could cause a noticeable impact of performance, especially when processing high resolution images.<br />
<br />
=== Grids ===<br />
<br />
You can define up to 99 different combinations of cameras to create matrix displays of multiple cameras. The id is automatically generated when the + button is pressed, starting from 1 and up to 99 with consecutive numbers.<br />
<br />
Grids could be deleted using the - button.<br />
<br />
<br />
[[File:Configuration Grids.png|border|center|600px]]<br />
<br />
<br />
Select an item in the grids list to define the grid’s number of rows and columns and select the cameras for each position. You can leave some positions empty.<br />
You should also define the other grid parameters.<br />
<br />
'''Resolution'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' <width> x <height> in pixels<br />
<br />
<br />
This optional parameter is used to optimize grid processing performance, especially on large grids when using large size skins for the Web interface.<br />
<br />
You can define a maximum resolution for the grid. HSYCO will always deliver this grid with a resolution that is never larger than the width and height defined with this parameter. <br />
<br />
The effect is to reduce the byte size of the resulting image, improving performance on remote connections, and to offload the CPU processing required to generate the grid, having a potential benefit on frame rate.<br />
<br />
<br />
'''Remote Password'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
HSYCO can optionally serve live images of its grids through a password protected HTTP request, for example:<br />
<br />
<nowiki>https://<hsycoserver>/x/camera/grid<N>?password=<password>&size=<width>x<height></nowiki><br />
<br />
(size is optional) for single frames or: <br />
<br />
<nowiki>https://<hsycoserver>/x/camerastream/grid<N>?size=<width>x<height>&password=<pwd>[&period=<millis>]</nowiki><br />
<br />
to retrieve a MJPEG stream.<br />
<br />
It is also possible to define different passwords for clients inside the trusted range of IP addresses and outside.<br />
<br />
<br />
'''Trusted Password'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
Similar to RemoteRequestPassword, you can use this optional parameter to set remote access passwords for clients inside the trusted range of IP addresses.<br />
<br />
Note that requests with the TrustedRequestPassword value will be also served via HTTP, without SSL.<br />
<br />
== Data Loggers ==<br />
<br />
The Data Loggers section is used to define HSYCO’s data loggers and their configuration parameters.<br />
<br />
<br />
[[File:Configuration Data Loggers1.png|border|center|600px]]<br />
<br />
<br />
There is one general configuration parameter:<br />
<br />
'''CSV Separator'''<br />
<br />
'''Default:''' comma<br />
<br />
'''Format:''' tab | comma | semicolon<br />
<br />
<br />
This parameter defines the field separator character for CSV files generated by the data loggers.<br />
<br />
<br />
Each data logger must have a unique ID. You can add a new data loggers pressing the + button.<br />
<br />
<br />
[[File:Configuration Data Loggers2.png|border|center]]<br />
<br />
<br />
Select the type, range or counter, and enter the data logger unique ID.<br />
<br />
Already defined data loggers could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
Counter and range data loggers have different configuration parameters.<br />
<br />
<br />
=== Counter Data Loggers ===<br />
<br />
<br />
[[File:Configuration Data Loggers Counter.png|border|center|600px]]<br />
<br />
<br />
'''Decimals'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
The number of decimal digits to be used for the input data.<br />
<br />
<br />
'''Resolution'''<br />
<br />
'''Default:''' hour<br />
<br />
'''Format:''' minute | hour | day | month<br />
<br />
<br />
Data aggregation maximum resolution.<br />
<br />
<br />
'''Hour Interval'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' divisor of 24<br />
<br />
<br />
Specifies the number of hours to be grouped into a single interval. For example, if set to 6, the day will be divided in groups of 6 hours: 1-6, 7-12, 13-18, and 19-24.<br />
<br />
<br />
'''Set Variables'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
If set to true (checked), the following variables will be generated:<br />
*<code>$dlog.<datalogger_id>.hour.tot</code>: its value is updated to the total value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.past.tot</code>: its value is updated to the total value of the past hour<br />
*<code>$dlog.<datalogger_id>.day.tot</code>: its value is updated to the total value of today<br />
*<code>$dlog.<datalogger_id>.day.past.tot</code>: its value is updated to the total value of yesteday<br />
*<code>$dlog.<datalogger_id>.month.tot</code>: its value is updated to the total value of the current month<br />
*<code>$dlog.<datalogger_id>.month.past.tot</code>: its value is updated to the total value of the past month<br />
*<code>$dlog.<datalogger_id>.year.tot</code>: its value is updated to the total value of the current year<br />
*<code>$dlog.<datalogger_id>.year.past.tot</code>: its value is updated to the total value of the past year<br />
<br />
If slots are used, the following variables will be generated for each slot:<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.hour.tot</code>: its value is updated to the total value of the current hour for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.hour.past.tot</code>: its value is updated to the total value of the past hour for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.day.tot</code>: its value is updated to the total value of today for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.day.past.tot</code>: its value is updated to the total value of yesteday for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.month.tot</code>: its value is updated to the total value of the current month for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.month.past.tot</code>: its value is updated to the total value of the past month for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.year.tot</code>: its value is updated to the total value of the current year for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.year.past.tot</code>: its value is updated to the total value of the past year for this slot<br />
<br />
<br />
'''Delete data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, data older than the specified amount of days will be deleted.<br />
<br />
<br />
'''Consolidate months data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one month.<br />
<br />
<br />
'''Consolidate days data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one day.<br />
<br />
<br />
'''Consolidate hours data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one hour.<br />
<br />
<br />
'''Max Delta'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' positive float number<br />
<br />
<br />
Sets the maximum valid delta between consecutive readings. If the calculated delta exceed such value, the read value is ignored. If not specified, all values are accepted.<br />
<br />
{{tip|It is highly recommended to set the delta limit in order to prevent the data series from being corrupted in case of false readings.}}<br />
<br />
<br />
'''Upper Limit'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive float number<br />
<br />
<br />
Specifies the maximum value that can be reached by the input value. This value will be used in case of counter roll-over. A value of 0 indicates that no upper limit is specified.<br />
<br />
<br />
'''Separate Slot Charts'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
Option for counter data loggers using time slots. Specifies wether or not to use different monthly and yearly charts for each defined time slot.<br />
<br />
<br />
'''Align Slots'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
Option for counter data loggers using time slots with separate charts. Specifies wether or not to align the scale of the slot charts belonging to the same period.<br />
<br />
<br />
<br />
'''Rates Log File'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' file path. e.g.: ''hsyco/rates.csv''<br />
<br />
<br />
Option for counter data loggers using time slots. Specifies the path of the file where the processed data will be logged. If omitted, no log file will be created.<br />
<br />
If the path includes the strings “%Y”, “%M”, or “%D” they will be replaced respectively by the current year, month, or day.<br />
<br />
=== Range Data Loggers ===<br />
<br />
<br />
[[File:Configuration Data Loggers Range.png|border|center|600px]]<br />
<br />
<br />
'''Decimals'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
The number of decimal digits to be used for the input data.<br />
<br />
<br />
'''Resolution'''<br />
<br />
'''Default:''' hour<br />
<br />
'''Format:''' minute | hour | day | month<br />
<br />
<br />
Data aggregation maximum resolution.<br />
<br />
<br />
'''Hour Interval'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' divisor of 24<br />
<br />
<br />
Specifies the number of hours to be grouped into a single interval. For example, if set to 6, the day will be divided in groups of 6 hours: 1-6, 7-12, 13-18, and 19-24.<br />
<br />
<br />
'''Set Variables'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
If set to true (checked), the following variables will be generated:<br />
*<code>$dlog.<datalogger_id>.hour.min.tot</code>: its value is updated to the minimum value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.max.tot</code>: its value is updated to the maximum value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.avg.tot</code>: its value is updated to the average value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.past.min.tot</code>: its value is updated to the minimum value of the past hour<br />
*<code>$dlog.<datalogger_id>.hour.past.max.tot</code>: its value is updated to the maximum value of the past hour<br />
*<code>$dlog.<datalogger_id>.hour.past.avg.tot</code>: its value is updated to the average value of the past hour<br />
<br />
*<code>$dlog.<datalogger_id>.day.min.tot</code>: its value is updated to the minimum value of today<br />
*<code>$dlog.<datalogger_id>.day.max.tot</code>: its value is updated to the maximum value of today<br />
*<code>$dlog.<datalogger_id>.day.avg.tot</code>: its value is updated to the average value of today<br />
*<code>$dlog.<datalogger_id>.day.past.min.tot</code>: its value is updated to the minimum value of yesterday<br />
*<code>$dlog.<datalogger_id>.day.past.max.tot</code>: its value is updated to the maximum value of yesterday<br />
*<code>$dlog.<datalogger_id>.day.past.avg.tot</code>: its value is updated to the average value of yesterday<br />
<br />
*<code>$dlog.<datalogger_id>.month.min.tot</code>: its value is updated to the minimum value of the current month<br />
*<code>$dlog.<datalogger_id>.month.max.tot</code>: its value is updated to the maximum value of the current month<br />
*<code>$dlog.<datalogger_id>.month.avg.tot</code>: its value is updated to the average value of the current month<br />
*<code>$dlog.<datalogger_id>.month.past.min.tot</code>: its value is updated to the minimum value of the past month<br />
*<code>$dlog.<datalogger_id>.month.past.max.tot</code>: its value is updated to the maximum value of the past month<br />
*<code>$dlog.<datalogger_id>.month.past.avg.tot</code>: its value is updated to the average value of the past month<br />
<br />
*<code>$dlog.<datalogger_id>.year.min.tot</code>: its value is updated to the minimum value of the current year<br />
*<code>$dlog.<datalogger_id>.year.max.tot</code>: its value is updated to the maximum value of the current year<br />
*<code>$dlog.<datalogger_id>.year.avg.tot</code>: its value is updated to the average value of the current year<br />
*<code>$dlog.<datalogger_id>.year.past.min.tot</code>: its value is updated to the minimum value of the past year<br />
*<code>$dlog.<datalogger_id>.year.past.max.tot</code>: its value is updated to the maximum value of the past year<br />
*<code>$dlog.<datalogger_id>.year.past.avg.tot</code>: its value is updated to the average value of the past year<br />
<br />
<br />
'''Delete data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, data older than the specified amount of days will be deleted.<br />
<br />
<br />
'''Consolidate months data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one month.<br />
<br />
<br />
'''Consolidate days data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one day.<br />
<br />
<br />
'''Consolidate hours data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one hour.<br />
<br />
<br />
'''Origin'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' float number<br />
<br />
<br />
Specifies the origin of the charts.<br />
<br />
<br />
<br />
'''Range'''<br />
<br />
'''Default:''' <br />
<br />
'''Format:''' low:up<br />
<br />
<br />
Specifies the range of the charts as “low:up”, where “low” indicates the lower limit and “up” the upper one. The lower and upper limits can be specified as rigid or flexible: if the value of a limit is followed by a “!” (e.g. 0!:20!) then it is rigid, meaning it will not change even if the data logger has processed a value exceeding the range. On the contrary, flexible ranges (e.g. 0:20) will be modified whenever a value exceed it. <br />
<br />
If the parameter is omitted, the charts will range from the lowest processed value to the highest one.<br />
<br />
<br />
'''Out of Range Mode'''<br />
<br />
'''Default:''' cut<br />
<br />
'''Format:''' cut | ignore<br />
<br />
<br />
Option for range data loggers with a predefined range. Specifies the behavior of the data logger when updated with a value which exceed the set value range: if “cut” is specified then the value is adjusted to the limits, else, if this parameter is set to “ignore”, the passed value is not taken into account. In both cases, an error message is reported for out of range values.<br />
<br />
=== Tools ===<br />
<br />
By clicking on the tools icon it is possible to access the data recovery and size functions.<br />
<br />
==== Data Recovery ====<br />
<br />
The data recovery tool allows to import data loggers' data from an old backup of the "data" folder. It can be used in case of database corruption or hard disk failure.<br />
<br />
[[File:Configuration Data Loggers Recovery.png|border|center]]<br />
<br />
Enter the name of the folder containing the backup (default: "data_backup", must be located in HSYCO's root folder) and specify whether or not to overwrite existing data. This option specifies how to handle data which are stored both in the backup database and in the current database and relative to the same time. If the checkbox is set the data in the backup will overwrite the current data, otherwise the current data will be preserved.<br />
<br />
When clicking on "Restore" all the data of the currently defined and enabled data loggers available in the backup will be imported.<br />
<br />
==== Size Report ====<br />
<br />
Clicking on the data logger size button opens the size report page, where all counter and range data loggers are listed with the number of data rows stored in the database for each data logger, and the grand total. This is quite useful to fine tune the data decimation and data expiration settings.<br />
<br />
[[File:Configuration Data Loggers Size.png|border|center]]<br />
<br />
<br />
Please note that, if you have a large amount of data stored in data loggers, the report will take some time to become available.<br />
<br />
== DMX ==<br />
<br />
The DMX section is used to define the DMX-512 gateways.<br />
<br />
<br />
[[File:Configuration DMX1.png|border|center|600px]]<br />
<br />
<br />
Each DMX gateway must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration DMX2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
HSYCO supports three different DMX solutions, using different configuration parameters.<br />
<br />
=== KissBox DMX Network Gateways ===<br />
<br />
For KissBox network gateways, check IP and enter the IP address and port number.<br />
<br />
<br />
[[File:Configuration DMX KissBox.png|border|center]]<br />
<br />
<br />
=== ENTTEC DMX USB PRO DMX Gateways ===<br />
<br />
For the ENTTEC DMX USB PRO DMX gateways, check Comm and enter the virtual serial port name assigned to the USB port. See the [[Enttec|ENTTEC DMX USB PRO]] application note for additional information.<br />
<br />
<br />
[[File:Configuration DMX Enttec.png|border|center]]<br />
<br />
=== Domino and Contatto DMX devices ===<br />
<br />
When using Doemmegi’s Domino or Contatto systems DMX devices, check ID and enter the full device name, including the I/O server prefix. See the [[Domino]] or [[Contatto]] application notes for additional information.<br />
<br />
<br />
[[File:Configuration DMX Duemmegi.png|border|center]]<br />
<br />
== Location Services ==<br />
<br />
The Location Services section is used to define the WiFi access points used to locate the WiFi clients position.<br />
<br />
<br />
[[File:Configuration Location Services1.png|border|center|600px]]<br />
<br />
<br />
Each access point must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration Location Services2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration Location Services3.png|border|center|600px]]<br />
<br />
<br />
There are two options:<br />
- IP address, for access points<br />
- iBeacon, with UUID, Major, Minor (see [[Beacons on HSYCO App for iOS]])<br />
<br />
== Timers ==<br />
<br />
The Timers section is used to define user timers.<br />
<br />
<br />
[[File:Configuration Timers1.png|border|center|600px]]<br />
<br />
<br />
Each timer must have a unique ID. You can add a new timers pressing the + button.<br />
<br />
<br />
[[File:Configuration Timers2.png|border|center]]<br />
<br />
<br />
Already defined timers could be deleted with the - button or disabled by unchecking the Enabled checkbox.<br />
Timers don’t require any configuration parameter besides the id.<br />
<br />
== Squeezebox ==<br />
<br />
This section is used to define the Squeezebox server and music players.<br />
<br />
<br />
[[File:Configuration Squeezebox1.png|border|center|600px]]<br />
<br />
<br />
You should set the Squeezebox server’s IP address or network name and port number.<br />
<br />
Each player must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration Squeezebox2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration Squeezebox3.png|border|center|600px]]<br />
<br />
<br />
The only configuration parameter is the player id, usually its MAC address.</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Settings&diff=8992Settings2020-09-21T13:52:58Z<p>Gionatan: /* Location Services */</p>
<hr />
<div>[[Category:Manager]]<br />
[[File:Manager Settings Icon.png|class=appIcon|The '''Settings''' icon]]<br />
HSYCO can be configured using the Settings application in the Manager.<br />
<br />
Settings stores all configuration parameters in the hsyco.ini file.<br />
<br />
<br />
{{tip|You can copy this file to save the current configuration, or manually change it. In this case, be sure to reopen the Settings application after the changes have been saved.}}<br />
<br />
<br />
The configuration is read at start-up, so any changes become effective only after restarting the HSYCO process.<br />
<br />
HSYCO is factory configured to automatically restart when hsyco.ini is saved.<br />
<br />
<br />
[[File:Manager_settings_menu.png|border|center|600px]]<br />
<br />
<br />
When you make changes using Settings, the hsyco.ini file will be overwritten when you press the Save button.<br />
<br />
You can’t return to the previous configuration once it is saved.<br />
<br />
The Revert button allows you to reload the current configuration if you have made changes in Setting that have not yet been saved.<br />
<br />
Settings parameters are grouped in several sections.<br />
<br />
You can make changes to any parameter, even in different sections, and then save all changes together.<br />
<br />
== System ==<br />
<br />
The Systems section contains all general configuration parameters, including vital parameters affecting system’s security and reliability.<br />
<br />
These parameters are further split in several sub-sections.<br />
<br />
=== General ===<br />
<br />
<br />
[[File:Manager settings general.png|border|center|600px]]<br />
<br />
<br />
'''URLKey'''<br />
<br />
'''Default:''' hsycoserver<br />
<br />
'''Format:''' string of at least 8 characters<br />
<br />
<br />
To protect against malicious service discovery robots, HSYCO does not answer to Web requests where only the server address is defined, for example https://192.168.0.50, but requires an extended URL, which must include an access key, called URLKey.<br />
<br />
{{tip|The URLKey must be at least 8 characters long.}}<br />
<br />
It is possible to specify more than one URLKEY, separated by a comma; in this case all the specified URLKEYs will be valid for the web access to HSYCO.<br />
<br />
The factory default URLKey is hsycoserver.<br />
<br />
The URLKey is not a secret password, but only an additional protection feature.<br />
<br />
<br />
'''Language'''<br />
<br />
'''Default:''' en<br />
<br />
'''Format:''' cn | en | fr | it<br />
<br />
<br />
Some I/O Servers and other core services use localized text messages. This parameter defines the default system language for these services.<br />
<br />
<br />
'''AutoKillFiles'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' list of file names separated by commas<br />
<br />
<br />
This parameter is usually set as: "hsyco.ini,hsyco.jar,com/hsyco/user.class" forcing the automatic restart after the changes of the three files listed.<br />
<br />
<br />
'''DatabaseTransactionLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
If true the HSQLDB embedded database transaction log file is used to log individual transactions between checkpoints.<br />
<br />
If false the log file is not used, improving the performance and reducing I/O but, in case of uncontrolled shutdown of the HSYCO process, all data updates after the last checkpoint (a database checkpoint is automatically perfomed every 60 seconds) will be lost.<br />
<br />
<br />
'''StartupDelay'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' 0 or positive integer number of seconds<br />
<br />
<br />
When set to a positive number, the HSYCO server will wait for the specified number of seconds at start-up before becoming active.<br />
<br />
This start-up delay could be useful to prevent HSYCO from starting before other peripherals or devices, like external storage systems, are completely initialized.<br />
<br />
<br />
'''ExceptionWatchdog'''<br />
<br />
'''Default:''' 5<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
After N uncaught Java execution exceptions, the HSYCO server will be killed and restarted.<br />
<br />
Set to 0 to disable the exception watchdog.<br />
<br />
<br />
'''EventsLoadTimeout'''<br />
<br />
'''Default:''' 20<br />
<br />
'''Format:''' positive integer number of seconds<br />
<br />
<br />
When an EVENTS file is saved, If any code section takes more than the specified amount of time to execute during the test run and INIT events sections, HSYCO will abort the JavaScript engine, rename events.txt to events_unsafe.txt and, a few seconds later, will restart the whole HSYCO server engine to protect the integrity of the system.<br />
<br />
If you have code in EVENTS that requires more than the default 20 seconds to run, you should set a larger value for EventsLoadTimeout.<br />
<br />
<br />
'''userLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Set to true to enable the log of the Java methods called in user.java or of the commands defined in the EVENTS programming environment.<br />
<br />
<br />
'''eventsLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
If true, the log of events received from field devices is enabled, for example the events related to the IO Servers.<br />
<br />
<br />
'''verboseLog'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
If true, the extended log is enabled.<br />
<br />
It is useful for debugging, or during the advanced customization phase or the development of Java code.<br />
<br />
<br />
'''persistentLog'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to false, message and error logs are not written to files, and are only visible in the Manager's Log Viewer.<br />
<br />
You may want to avoid writing log files when using servers with limited disk space or when the mass storage device is an SSD with limited write cycles.<br />
<br />
<br />
'''securityLogDailyFiles'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to true, the security logs are written in daily files named MMDD-security.log.<br />
<br />
<br />
'''LogMaxAge'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' 0, or positive integer number<br />
<br />
<br />
Log files are automatically deleted when older than the number of days defined with this parameter.<br />
<br />
When set to 0 or not defined, log files are not deleted automatically.<br />
<br />
=== Access Control ===<br />
<br />
<br />
<br />
[[File:Configuration Access Control.png|border|center|600px]]<br />
<br />
<br />
'''trustedNet'''<br />
<br />
'''Default:''' local<br />
<br />
'''Format:''' local, or nn.nn.nn.nn-nn.nn.nn.nn<br />
<br />
<br />
IP addresses that define the group of network addresses belonging to the secure local network.<br />
<br />
It is possible to enter multiple, comma-separated IP ranges or individual IP addresses, or simply enter “local”, so that HSYCO will assume all IP addresses in the LAN as trusted.<br />
<br />
The loop-back IP address (127.0.0.1) is considered part of the trusted network only when the trustedNet option is set to "local", or when explicitly listed.<br />
<br />
The Web clients connecting to HSYCO from these addresses are subject to the time-out defined in KeysTrustedValidityHours, which is usually longer than the one used for all the other IP addresses, defined in KeysNotTrustedValidityHours.<br />
<br />
<br />
'''KeysTrustedValidityHours'''<br />
<br />
'''Default:''' 24<br />
<br />
'''Format:''' integer > 0 or hh:mm<br />
<br />
<br />
Login time-out in hours for the connections from trusted IP addresses.<br />
<br />
Set on a very high value, e.g. 100000, to practically avoid the time-out of sessions.<br />
<br />
It can also be set using the hh:mm hours and minutes format.<br />
<br />
<br />
'''KeysNotTrustedValidityHours'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer > 0 or hh:mm<br />
<br />
<br />
Login time-out in hours for not trusted IP addresses.<br />
<br />
It can also be set using the hh:mm hours and minutes format.<br />
<br />
<br />
'''KeysInactivityHours'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer > 0 or hh:mm<br />
<br />
<br />
Inactivity time-out in hours.<br />
<br />
This is an optional parameter; if not set there will be no inactivity time-out and the user session will be automatically logged out based on the login time-out only.<br />
<br />
It can also be set using the hh:mm hours and minutes format.<br />
<br />
<br />
'''KeysInactivityMode'''<br />
<br />
'''Default:''' browser<br />
<br />
'''Format:''' browser | cameras | commands<br />
<br />
<br />
Inactivity time-out mode.<br />
<br />
This is an optional parameter.<br />
<br />
It is significant only when KeysInactivityHours is also defined.<br />
<br />
In browser mode, having the Web browser open on the HSYCO page will keep the session alive.<br />
<br />
In cameras mode the session will remain alive only when sending commands or watching cameras.<br />
<br />
In commands mode the session will stay alive only if commands are sent before the inactivity timer expires.<br />
<br />
<br />
'''HTTPServerPublicDirectory'''<br />
<br />
'''Default:''' browser<br />
<br />
'''Format:''' directory name<br />
<br />
<br />
If defined, enables a simple Web server that serves files, without any parsing, via HTTP and HTTPS, only to clients in the trusted range of IP addresses.<br />
<br />
This parameter sets the name of the directory, under the www root Web directory, used for the public files.<br />
<br />
If, for example, you have HTTPServerPublicDirectory=public, and an HTML file named home.html in the public directory, then the <nowiki>https://192.168.0.50/public/home.html</nowiki> URL will point to that file.<br />
<br />
As you see, you shouldn’t add the URLKey in public URLs.<br />
<br />
<br />
'''HTTPServerLowSecurityEnabled'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
Usually, the HTTP server is only active to let cameras and PBX systems send motion detection and calls notifications.<br />
<br />
To avoid the authentication keys, PIN and PUK codes and all traffic to be transmitted in the clear, the HTTP protocol is not normally used for Web access to HSYCO.<br />
<br />
Set the parameter to true only when you want to enable the not-secure HTTP protocol for Web access to HSYCO.<br />
<br />
<br />
'''WebAdminNetConfigLock'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
If true, the Web network settings functions are disabled.<br />
<br />
This parameter should be set to true once you expect no changes in the network configuration of HSYCO Server.<br />
<br />
=== Network ===<br />
<br />
<br />
[[File:Configuration Network.png|border|center|600px]]<br />
<br />
<br />
'''HTTPServerPort'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number < 65535<br />
<br />
<br />
TCP/IP port of HSYCO HTTP Web Server. If not defined, the HTTP server is not enabled.<br />
<br />
Normally set to 80.<br />
<br />
<br />
'''HTTPSSLServerPort'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number < 65535<br />
<br />
<br />
TCP/IP port of HSYCO HTTPS Web Server.<br />
<br />
If not defined, the HTTPS server is not enabled.<br />
<br />
Normally set to 443.<br />
<br />
<br />
'''SysLogServerPort'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number < 65535<br />
<br />
<br />
TCP/IP port of HSYCO SYSLOG Web server.<br />
<br />
The SYSLOG server is used to receive from the Access Points (AP) the information to determine which AP every user in the Wi-Fi LAN is using to connect.<br />
<br />
If not defined, the SYSLOG server is not enabled.<br />
<br />
It is usually set to 514.<br />
<br />
<br />
'''ServerName'''<br />
<br />
'''Default:''' hsyco<br />
<br />
'''Format:''' domain name<br />
<br />
<br />
Name used to generate the SSL certificate.<br />
<br />
It is necessary for the cryptography of the HTTPS Web traffic and should correspond to the domain name through which the HSYCO server is accessed via the Internet.<br />
<br />
The certificate is saved in the hsyco.keys file.<br />
<br />
When HSYCO is started, if this file is not available or its name doesn’t match the ServerName parameter in hsyco.ini, a new SSL certificate is automatically generated according to the name defined in ServerName.<br />
<br />
<br />
'''OffLineCache'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
HSYCO implements the off-line cache feature of the Web browsers that support the HTML 5.0 standard.<br />
<br />
To enable the off-line storage on the Web browser of all HSYCO HTML static content, set this parameter to true.<br />
<br />
{{tip|Note that all files saved under any subdirectory named "nocache" will not be listed in the persistent cache's manifest file.}}<br />
<br />
<br />
'''HTTPServerThreads'''<br />
<br />
'''Default:''' 256<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
Sets the total number of processing threads for the HTTP and HTTPS internal web servers.<br />
<br />
You should change this parameter only when you have a very large number of active web clients.<br />
<br />
Web browsers normally use only a few (up to about 6) concurrent connections for each session, and the default should be fine to support up to at least 40 active clients.<br />
<br />
When the HTTP and HTTPS servers run low of threads, some clients could see their requests rejected, causing page load errors or becoming unresponsive.<br />
<br />
In this case you should see “too many connections” error messages in HSYCO’s log files.<br />
<br />
{{tip|Increasing this parameter also increases memory and I/O resources requirements to the underlying operating system.}}<br />
<br />
<br />
'''HTTPRootRedirect'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' relative or absolute URL<br />
<br />
<br />
Set to a valid absolute or relative URL to redirect root requests.<br />
<br />
<br />
'''HTTPSCompatibility'''<br />
<br />
'''Default:''' new<br />
<br />
'''Format:''' new | old<br />
<br />
<br />
Set to "old" to retain support for older browsers when using HTTPS.<br />
<br />
{{tip|You should be aware of the security and compatibility implications, specific of your application environment, when setting this option.}}<br />
<br />
=== Clock ===<br />
<br />
<br />
[[File:Configuration Clock.png|border|center|600px]]<br />
<br />
<br />
'''TimeAutoUpdate'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' false | true | NTP server name/address<br />
<br />
<br />
HSYCO automatically sets the local date and time by polling Network Time Protocol (NTP) servers.<br />
<br />
To disable this feature, set this parameter to false.<br />
<br />
To use a specific NTP server, set this parameter to the name or IP address of the NTP server.<br />
<br />
<br />
'''TimeZone'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' the time zone id<br />
<br />
<br />
Set the current time zone.<br />
<br />
The time zone information is used to obtain the correct local time and automatically adjust for daylight saving time.<br />
<br />
If this parameter is not set, HSYCO will use the operating system’s time zone settings.<br />
<br />
The time zone id is either in the form “Area/Location”, or a generic “GMT+NN”, “GMT-NN” format that simply defines the hours offset from UTC time.<br />
<br />
When the “Area/Location” format is used, the clock is automatically adjusted for daylight saving time.<br />
<br />
The TimeZone value should have no spaces; replace spaces in area or location names with underscores, for example “America/New_York”.<br />
<br />
When HSYCO starts, you can check the message.log file to see the actual time zone and DST setting, just after the start-up message, for example:<br />
<br />
2013.07.10 15:28:30.113 - HSYCO Ver. 3.3.0 Build 0112 (USER Ver. No User Code) started<br />
2013.07.10 15:28:30.425 - Time zone is: Europe/Rome (Central European Summer Time)<br />
<br />
<br />
'''Latitude'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative numerical value, decimals separated by “.”<br />
<br />
<br />
Latitude in decimal degrees (positive for the Northern Hemisphere), to calculate the sun position and sunrise/sunset time.<br />
<br />
<br />
'''Longitude'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative numerical value, decimals separated by “.”<br />
<br />
<br />
Longitude in decimal degrees (positive for the Eastern Hemisphere), to calculate the sun position and sunrise/sunset time.<br />
<br />
<br />
'''SunriseOffsetMinutes'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative integer number<br />
<br />
<br />
Deviation in minutes from the civil sunrise time (in advance if negative, delayed if positive).<br />
<br />
<br />
'''SunsetOffsetMinutes'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive or negative integer number<br />
<br />
<br />
Deviation in minutes from the civil sunset time (in advance if negative, delayed if positive).<br />
<br />
=== High Availability ===<br />
<br />
<br />
[[File:Configuration High Availability.png|border|center|600px]]<br />
<br />
<br />
'''haMode'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' master | slave<br />
<br />
<br />
Enables the high availability configuration of HSYCO.<br />
<br />
The high availability configuration uses two different HSYCO systems, one is configured as the master system, the other as slave.<br />
<br />
<br />
'''haMasterIP'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' IP address: nnn.nnn.nnn.nnn<br />
<br />
<br />
Mandatory parameter for the high availability configuration.<br />
<br />
It specifies the IP address of the HSYCO master system.<br />
<br />
<br />
'''haSlaveIP'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' IP address: nnn.nnn.nnn.nnn<br />
<br />
<br />
Mandatory parameter for the high availability configuration.<br />
<br />
It specifies the IP address of the HSYCO slave system.<br />
<br />
<br />
'''haActiveIP'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' IP address: nnn.nnn.nnn.nnn<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
Defines an IP address that the active server, master or slave, will assign as an IP alias to its main Ethernet port (eth0).<br />
Using this IP address, clients will be able to access the active server with the same address, regardless of the active server being the master or the slave.<br />
<br />
<br />
'''haDisableCommandEvents'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
If true, command methods and actions in Java and EVENTS are automatically disabled on the HSYCO Server that is not active (for example the system defined as slave is not active when the master system works properly) for the following systems: Audio, Cameras, Comm ports, DMX, I/O Servers, IRTrans, Modbus (write command are disabled) Squeezebox, URL.<br />
<br />
<br />
'''haDisableFilesSync'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
If true, files changes on the master will not be synched to the slave server (changes to access.ini, scheduler.ini and timers.data will not be synched too).<br />
<br />
<br />
'''haClientSessionsFailover'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
When true the slave server will mirror the master's authentication keys, allowing a clean transition of authenticated sessions from master to slave.<br />
<br />
{{tip|To ensure a proper transition of the client sessions from master to slave, the ServerName option and the hsyco.keys file of the slave server must also be the same as on the master.}}<br />
<br />
<br />
<br />
<br />
'''haTimeoutSeconds'''<br />
<br />
'''Default:''' 4<br />
<br />
'''Format:''' >1 integer number<br />
<br />
<br />
Optional parameter for the high availability configuration.<br />
<br />
The slave unit becomes active if it doesn't receive the keep-alive packet from the master unit for more than the number of seconds set with this parameter.<br />
<br />
{{tip|Always set this parameter with the same value on both the master and slave units.}}<br />
<br />
=== Backup ===<br />
<br />
<br />
[[File:Manager settings backup.png|border|center|600px]]<br />
<br />
<br />
'''DatabaseBackup'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to true, a hot backup of the core database is automatically executed on a daily basis, saving data in the data_backup directory, and overwriting the previous backup files.<br />
<br />
The data_backup directory can be used to restore the database. The [[Database Maintenance]] document explains how to safely perform the database restore procedure.<br />
<br />
{{note|Only one process can access the database files at any time. If you need to access these files using other applications or SQL utilities, you should stop the HSYCO process, otherwise all data could be lost.}}<br />
<br />
<br />
'''DatabaseRecovery'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
When set to true, and DatabaseBackup is also enabled, if an unrecoverable database error occurs at startup, HSYCO will rename the corrupted database directory to "data_original" and try to recover from last backup, if available.<br />
<br />
<br />
'''RootBackupDay'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' *, mon, tue, wed, thu, fri, sat, sun, 1-31<br />
<br />
<br />
Day schedule for automatic root backup:<br />
* *: every day<br />
* mon: every Monday (weekly schedule)<br />
* tue: every Tuesday (weekly schedule)<br />
* wed: every Wednesday (weekly schedule)<br />
* thu: every Thursday (weekly schedule)<br />
* fri: every Friday (weekly schedule)<br />
* sat: every Saturday (weekly schedule)<br />
* sun: every Sunday (weekly schedule)<br />
* 1-31: on the day (monthly schedule)<br />
<br />
<br />
'''RootBackupHour'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' *, 0-23<br />
<br />
<br />
Hour schedule for automatic root backup:<br />
* *: every hour<br />
* 0-23: on the hour (daily schedule)<br />
<br />
<br />
'''RootBackupMinute'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' 0-59<br />
<br />
<br />
Minute schedule for automatic root backup:<br />
* 0-59: on the minute<br />
<br />
<br />
{{note|<br />
Using the RootBackupDay, RootBackupHour and RootBackupMinute you can set a monthly, weekly, daily or hourly schedule for the automatic root backup.<br />
<br />
To schedule a single backup every month, set RootBackupDay to the N-th day of the month, for example 1, then set RootBackupHour and RootBackupMinute to the preferred hour and minute.<br />
<br />
To schedule a weekly backup, set RootBackupDay to a day of the week, for example Sunday, then set RootBackupHour and RootBackupMinute to the preferred hour and minute.<br />
<br />
To schedule a daily backup, set RootBackupDay to "*", then set RootBackupHour and RootBackupMinute to the preferred hour and minute.<br />
<br />
Finally, to schedule an hourly backup, set RootBackupDay to "*", RootBackupHour to "*" and RootBackupMinute to the preferred minute.<br />
}}<br />
<br />
<br />
'''RootBackupDestinations'''<br />
<br />
'''Default:''' empty or undefined (automatic root backup disabled)<br />
<br />
'''Format:''' comma-separated list of local or remote destination paths.<br />
<br />
<br />
The backup file destinations.<br />
<br />
The automatic root backup engine creates a single zip file and saves copies of it locally on the HSYCO server file system or on remote servers using the SSH secure copy protocol.<br />
<br />
To copy the backup zip file to the local file system (including remote network storage mounted on the server's file system), simply use the absolute pathname of the destination file, for example "/backup/mybackup.zip".<br />
<br />
To copy the backup zip file to a remote SSH server, use the following format:<br />
<br />
scp:<login>:<password>@<host>:<port>:<path><br />
<br />
where:<br />
*<login> is the remote user<br />
*<password> is the remote user's SSH password<br />
*<host> is the remote server's name or IP address<br />
*<port> is the SSH port number. The port number can be omitted if the SSH service is using the standard SSH port 22. In this case the format becomes: scp:<login>:<password>@<host>:<path><br />
*<path> the pathname of the zip file on the remote server. The pathname can be absolute (starting with / on Unix systems) or relative to the user's home directory.<br />
<br />
You can also use a few special parameters in the pathname to generate dynamic names based on the backup date and time:<br />
* %date is replaced by the date and time as yyyyMMddHHmm<br />
* %day is replace by the day of the month as two digits, from 01 to 31<br />
* %dow is replaced by the day of week, mon-sun<br />
* %hour is replaced by the hour of day as two digits, from 00 to 23.<br />
<br />
Using these parameters you will be able to create permanent log files (using %date in the path name) or rolling files (using %day, %dow or %hour) with backup files automatically overwriting older files.<br />
<br />
Example: the following RootBackupDestinations will save one file on remote server 192.168.1.201, accessing it as user "john" with password "mypassword1", saving the file in the /hsyco_backup/ directory and with rolling names like hsyco-office-mon.zip, hsyco-office-tue.zip, etc. It will also save the backup locally, at /mnt/usb/hsyco_backup/hsyco-office.zip (this file is replaced at every new backup).<br />
<br />
scp:john:mypassword1@192.168.1.201:/hsyco_backup/hsyco-office-%dow.zip,/mnt/usb/hsyco_backup/hsyco-office.zip<br />
<br />
<br />
'''RootBackupExclude'''<br />
<br />
'''Default:''' empty or undefined (logs and motion directories, and the hsyco.jar file are excluded)<br />
<br />
'''Format:''' comma-separated list of paths that should be skipped during the backup process<br />
<br />
<br />
You can set this parameter to skip directories and files you don't need be saved in the backup zip file. If you set this parameter, it is recommended to also explicitly list logs, motion and hsyco.jar, if you don't want these in the backup.<br />
<br />
=== Remote HSYCO Servers ===<br />
<br />
The HSYCO Remote I/O Server is a powerful and secure server-to-server communication system that allows an HSYCO server read and write access to all the I/O data points and GUI variables of other remote HSYCO servers. The remote HSYCO Servers settings are used to enable remote HSYCO servers access to this server.<br />
<br />
The HSYCO Remote I/O Server uses a secure HTTPS API based on the REST (Representational state transfer) model and the JSON data format. A subset of this API can be used by third-party HTTP client applications. Read the [[HSYCO Remote API]] specification for additional details.<br />
<br />
<br />
[[File:Configuration Remote HSYCO Servers.png|border|center|600px]]<br />
<br />
<br />
'''RemoteServerPassword'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers), 8 characters or longer<br />
<br />
<br />
Set this password to enable this HSYCO server to be accessed by another HSYCO server via the HSYCO Remote I/O Server (see the HSYCO Remote I/O Server Application Note for further information).<br />
<br />
{{note|The password must be at least 8 characters long. Use a very long and randomly generated string to reduce the risk of unauthorized access.}}<br />
<br />
<br />
'''RemoteServerAddress'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' comma separated list of IP addresses, or *<br />
<br />
<br />
Set to the IP addresses of the remote HSYCO servers that should be allowed to access this HSYCO server.<br />
<br />
Set to * to allow any remote IP address.<br />
<br />
<br />
'''RemoteServerControl'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Set to true to allow the remote server to modify the data points values of this HSYCO server.<br />
<br />
<br />
'''RemoteServerIOFilter'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' comma separated list of I/O Servers IDs<br />
<br />
<br />
If you want to limit remote access and control to just some of the I/O Servers defined in this HSYCO, use this parameter to list the I/O Servers that should be available to the remote HSYCO system.<br />
<br />
Filtering out I/O Servers that are not used remotely could have a positive impact on performance and network traffic.<br />
<br />
<br />
'''RemoteServerUIFilter'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' comma separated list of I/O Servers IDs<br />
<br />
<br />
If you want to limit remote access and control to just some of the user interface objects defined in this HSYCO, use this parameter to list the objects’ IDs prefixes (a prefix is the first part of the ID, before the first dot character, if you are using a dot-separated notation; use the full ID if not using the dot notation) that should be available to the remote HSYCO system.<br />
<br />
Filtering out UI objects that are not used remotely could have a positive impact on performance and network traffic.<br />
<br />
=== Email ===<br />
<br />
<br />
[[File:Configuration Email.png|border|center|600px]]<br />
<br />
<br />
'''SmtpName'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' SMTP server name or IP address<br />
<br />
<br />
SMTP server name or numeric IP address.<br />
<br />
This parameter is used by the MAIL action and sendMail() method to send email messages through a specific authenticated and secured SMTP account rather than directly to the recipient’s SMTP server.<br />
<br />
<br />
'''SmtpPort'''<br />
<br />
'''Default:''' 25, 465 or 587<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
SMTP server’s port number, if different from the default port.<br />
<br />
The default port is:<br />
* 25 for not encrypted traffic<br />
* 465 for SMTP over SSL<br />
* 587 for ESMTP.<br />
<br />
<br />
'''SmtpUser'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string<br />
<br />
<br />
Account’s username to authenticate the connection to the SMTP server.<br />
<br />
<br />
'''SmtpPassword'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string<br />
<br />
<br />
Account’s password to authenticate the connection to the SMTP server.<br />
<br />
<br />
'''SmtpSSL'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true | esmtp<br />
<br />
<br />
Set to “true” for SMTP server that support SMTP over SSL (default port is 465).<br />
<br />
Set to “esmtp” for SMTP server that support ESMTP (default port is 587).<br />
<br />
Set to “false” for SMTP servers that don’t support traffic encryption.<br />
<br />
<br />
'''SmtpDebug'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' false | true<br />
<br />
<br />
Set to “true” to dump all SMTP sessions data to the console log file. This option is for debugging purposes only, and should not be left set to true when not needed.<br />
<br />
=== Audio Server ===<br />
<br />
<br />
[[File:Configuration Audio Server.png|border|center|600px]]<br />
<br />
<br />
'''AudioServerTTS'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string<br />
<br />
<br />
This parameter is only needed if you are using a text-to-speech engine that is not the default one for the operating system.<br />
<br />
See the [[Audio and Public Announcement]] section for additional information.<br />
<br />
<br />
'''AudioServerVolume'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Change the default output volume for pre-recorded audio files and the text-to-speech engine.<br />
<br />
<br />
'''AudioServerQuality'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Change the default quality for the text-to-speech engine.<br />
<br />
<br />
'''AudioServerSpeed'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Change the default speed for pre-recorded audio files and the text-to-speech engine.<br />
<br />
=== Extras ===<br />
<br />
<br />
[[File:Configuration Extras.png|border|center|600px]]<br />
<br />
<br />
This section is used to set other not standard parameters that should be saved in hsyco.ini, like application-specific parameters.<br />
<br />
== I/O Servers ==<br />
<br />
HSYCO Server interfaces to several field sub-systems, including lighting and automation systems, video cameras, HVAC controllers, security systems, and other special-purpose devices. HSYCO supports several standard protocols, like BACnet, DALI, DMX, KNX, Modbus, as well as quite a few proprietary protocols.<br />
<br />
Most of these field systems are represented inside HSYCO as “I/O servers”. An I/O server is a software module that offers a standardized abstraction layer so that even very different systems can be interfaced using a consistent naming convention and programming model.<br />
<br />
<br />
[[File:Configuration IO Servers.png|border|center|600px]]<br />
<br />
<br />
Each I/O server must have a unique ID. You can add a new I/O server pressing the + button.<br />
<br />
<br />
[[File:Configuration IO Servers New IO.png|border|center]]<br />
<br />
<br />
Select the type and enter the server’s unique ID.<br />
<br />
Already defined I/O servers could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
Each server type may require different configuration parameters, like IP address and port, serial port id, or authentication information.<br />
<br />
Refer to the Application Notes documentation for detailed configuration and interfacing information for I/O servers.<br />
<br />
The “Shutdown when inactive” parameter, that is available for all I/O server types, is only used in high availability configurations. <br />
<br />
Set it to true to automatically stop the I/O server when the HSYCO server (master or slave) is not the active system. Set to false to keep the I/O server running even when the HSYCO server is not the active system.<br />
<br />
== Communication Ports ==<br />
<br />
<br />
[[File:Configuration Communication Ports.png|border|center|600px]]<br />
<br />
<br />
The Comm Ports section is used to define all serial ports and their configuration parameters.<br />
<br />
Each port must have a unique ID. You can add a new ports pressing the + button.<br />
<br />
<br />
[[File:Configuration Communication Ports New Comm.png|border|center]]<br />
<br />
<br />
Select the type and enter the port’s unique ID.<br />
<br />
Already defined ports could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
The different types of comm ports have different configuration parameters.<br />
<br />
=== Serial ports ===<br />
<br />
<br />
[[File:Configuration Serial ports.png|border|center|600px]]<br />
<br />
<br />
To configure one of the real serial ports of the server, or a USB serial adapter, create a port of type “serial”.<br />
<br />
'''Port'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Complete or partial system name of the associated communication port. In the Linux based architecture of the HSYCO servers this is the naming convention:<br />
<br />
* COM1: ttyS0 or /dev/ttyS0<br />
* COM2: ttyS1 or /dev/ttyS1<br />
* COM3: ttyS2 or /dev/ttyS2<br />
* COM4: ttyS3 or /dev/ttyS3<br />
<br />
For USB connected devices:<br />
<br />
* 1st USB device: ttyUSB0 or /dev/ttyUSB0<br />
* 2nd USB device: ttyUSB1 or /dev/ttyUSB1<br />
* ...etc etc<br />
<br />
<br />
'''Baud rate'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Port speed.<br />
<br />
<br />
'''Data bits'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
The number of bits can be 8, 7, 6 or 5. It should be set to 8 in most cases.<br />
<br />
<br />
<br />
'''Stop bits'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
The number of stop bits can be 1, 1.5 or 2.<br />
<br />
<br />
'''Parity'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Parity can be none, odd, even, mark or space.<br />
<br />
<br />
'''Flow control'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:'''<br />
<br />
<br />
Flow control can be none, XON/XOFF or RTS/CTS.<br />
<br />
<br />
'''Timeout'''<br />
<br />
'''Default:''' 2000<br />
<br />
'''Format:'''<br />
<br />
<br />
The timeout parameter is optional and could be omitted. It defines the serial port receive timeout, in milliseconds. Defaults to 2 seconds if not defined.<br />
<br />
=== Serial Gateways ===<br />
<br />
Generic serial gateways that provide bi-directional serial port communication via a TCP connection are supported by HSYCO. <br />
<br />
[[File:Configuration Server ports.png|border|center|600px]]<br />
<br />
To configure a comm port to send data to the serial port of a serial gateway, you should set the comm port type to “server”, and set the gateway’s IP address and TCP port number.<br />
<br />
The serial port handshake parameters must be set on the gateway using its configuration utilities.<br />
<br />
HSYCO supports a high-availability, failover configuration for serial gateways.<br />
<br />
HSYCO supports a high-availability, failover configuration for serial gateways. You enable failover by adding a second IP address to the IP parameter.<br />
<br />
HSYCO will try to establish a connection using the first IP address, automatically switching to the failover address if a communication error occurs.<br />
<br />
In this configuration, the JavaScript or Java closeComm() function can be used to force a reconnect on the next call to readComm() or writeComm(), so that a switch between the fail-over IPs would happen if the current IP is not responding.<br />
<br />
=== HWG I/O Server ports ===<br />
<br />
Some network I/O controllers produced by HWG have a serial port, that could be used as fully functional serial port by HSYCO. To configure these ports, select type “io”, then select the I/O server id of the HWG controller and enter the normal serial port configuration parameters.<br />
<br />
<br />
[[File:Configuration HWG Server ports.png|border|center|600px]]<br />
<br />
<br />
=== IRTrans ports ===<br />
<br />
Some IRTrans network IR controllers have a local serial port. HSYCO can use this port as an output-only serial port.<br />
<br />
To configure an IRTrans serial port, select type “irtrans”, and select the id of the IRTrans device. The serial port communication parameters, like speed, flow control etc., should be configured on the IRTrans.<br />
<br />
<br />
[[File:Configuration IRTrans ports.png|border|center|600px]]<br />
<br />
== IRTrans Servers ==<br />
<br />
The IRTrans Servers section is used to define the IRTrans network infrared devices.<br />
<br />
<br />
[[File:Configuration IRTrans Servers1.png|border|center|600px]]<br />
<br />
<br />
Each IRTrans must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration IRTrans Servers2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration IRTrans Servers3.png|border|center|600px]]<br />
<br />
<br />
The only configuration parameter is the IRTrans IP address.<br />
<br />
<br />
== Cameras == <br />
<br />
This section is used to define individual IP cameras, to set general configuration parameters for video processing, and to define camera grids for the user interface.<br />
<br />
<br />
[[File:Configuration Cameras1.png|border|center|600px]]<br />
<br />
<br />
=== General parameters ===<br />
<br />
'''CamerasRecordingMotionTriggerSeconds'''<br />
<br />
'''Default:''' 5<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
Number of seconds during which HSYCO keeps on recording from a camera after a recording trigger event for that camera. It is possible to set this parameter at 0, disabling the triggered recording of events; this can be useful in case it is preferred to control recording only through the Java user code or EVENTS.<br />
<br />
<br />
'''CamerasRefreshMillis'''<br />
<br />
'''Default:''' 1000<br />
<br />
'''Format:''' positive integer number<br />
<br />
<br />
Camera frames acquisition interval, in milliseconds. For example, for a frequency of 4 frames a second, set the value to 250. A low value corresponds to a higher number of frames acquired and recorded in the time unit, with a heavier load in terms of CPU resources and disk space.<br />
<br />
<br />
'''CamerasResizedQuality'''<br />
<br />
'''Default:''' 0.7<br />
<br />
'''Format:''' decimal number between 0 and 1 (decimals separated by “.”)<br />
<br />
<br />
Image quality for images processing and resizing. Numbers close to 1 produce a better quality, but heavier load and larger size for each frame.<br />
<br />
<br />
'''CamerasMinFreeSpaceBytes'''<br />
<br />
'''Default:''' if not set, HSYCO will start deleting older frames when free space is less than 2GB, and stop recording if free space drops below 1GB. If the motion directory is on a separate file system, the default limits are 15% and 10% of total file systems space<br />
<br />
'''Format:''' positive integer number, followed by K for kilobytes, M for megabytes, G for gigabytes or T for terabytes<br />
<br />
Cameras recording is disabled and older frames could be deleted if the file systems's free space drops below this level.<br />
<br />
Use the "Extras" tab in "System" settings to set this option.<br />
<br />
=== Cameras parameters ===<br />
<br />
Each camera must have a unique ID. You can add a new cameras pressing the + button in the cameras list panel.<br />
<br />
<br />
[[File:Configuration Cameras2.png|border|center]]<br />
<br />
<br />
Already defined cameras could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration Cameras3.png|border|center|600px]]<br />
<br />
<br />
'''URL'''<br />
<br />
'''Default:''' mandatory<br />
<br />
'''Format:''' complete URL<br />
<br />
<br />
Complete URL to acquire single frames in JPEG format, or MJPEG streams, in the desired resolution. Mandatory for each camera.<br />
Recording is based on frames acquired with this URL.<br />
<br />
When using MJPEG streams, it is advisable to configure the number of frames per second the camera streams to a value that is very close to HSYCO’s frame rate as set with CamerasRefreshMillis.<br />
<br />
<br />
'''URL Small'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' complete URL<br />
<br />
In order to optimize camera processing performance, set this optional parameter. The URL fetches frames at a lower resolution. When serving frames to the Web interface, HSYCO will automatically choose the most appropriate frame resolution to use, based on the size of the frame in the Web interface.<br />
<br />
Small frames are also normally used to create grids, improving processing performance.<br />
<br />
<br />
{{note|For a list of supported URLs check here: [[Camera URLs]] and here: [[Encoder URLs]].}}<br />
<br />
<br />
'''PTZ'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' name of the PTZ driver<br />
<br />
<br />
Defines the PTZ features of a camera and family of PTZ driver. The PTZ control of a camera is automatically added to the Web interface. <br />
<br />
You can click on the edges of the camera image to control the camera: up, down, right, left, zoom and focus.<br />
<br />
Supported types are:<br />
<br />
Camera.''id''.PTZ = axis (AXIS PTZ cameras)<br />
Camera.''id''.PTZ = axis-vptz (AXIS fixed cameras with virtual PTZ support)<br />
Camera.''id''.PTZ = panasonic (Panasonic BB and BL Series cameras)<br />
Camera.''id''.PTZ = panasonic-wv (Panasonic WV Series cameras)<br />
Camera.''id''.PTZ = mobotix (Mobotix cameras)<br />
Camera.''id''.PTZ = rovio (the WowWee Rovio camera)<br />
Camera.''id''.PTZ = SNV-3120, SNP-3120, SNP-3120V, SNP-3120H (Samsung cameras)<br />
Camera.''id''.PTZ = vptz (fixed cameras with virtual PTZ support implemented by HSYCO)<br />
Camera.''id''.PTZ = user (to associate custom Java code to the control areas of the image).<br />
<br />
<br />
'''Type'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
Defines the camera model type for cameras that support this option. For example, ''Camera.samsung.Type = SND-5080''.<br />
<br />
<br />
'''IO'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' ''enabled''<br />
<br />
<br />
For some camera models, you can enable I/O and VA (Visual Analysis) option for a camera. For example, Camera.<camid>.IO=enabled. If you want to enable I/O only, set it to “enabled:io”, or to “enabled:va” to enable VA only.<br />
<br />
<br />
'''User'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
When this parameter is defined, the access requests to the frames and the commands for PTZ control of the camera are sent with user and password authentication.<br />
<br />
<br />
'''Password'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
When this parameter is defined, the access requests to the frames and the commands for PTZ control of the camera are sent with user and password authentication.<br />
<br />
<br />
'''Dropped Frames'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' integer number &ge; 0<br />
<br />
<br />
This parameter specifies the number of frames that should be discarded during recording. <br />
<br />
For example, setting the value to 1, half of the frames will be recorded out of those normally acquired from the camera; setting the value to 3, 3 frames will be discarded for each frame acquired, thus recording only 1/4 of the acquired frames. Dropping frames reduces space used to store frames on disk, and causes accelerated playback of recorded video.<br />
<br />
<br />
'''Max Age'''<br />
<br />
'''Default:''' 30d<br />
<br />
'''Format:''' positive integer number followed by “''d''” character, for days, “''h''” for hours or “''m''” for minutes<br />
<br />
<br />
Period of time, from when each frame acquired by the camera corresponding is recorded, during which the frames remain on HSYCO’s hard disk. <br />
<br />
When this time expires the frames are automatically deleted from the HSYCO motion directory. The older frames can be automatically erased even before their expiration time, in case the space available on disk drops below a safe margin.<br />
<br />
<br />
'''Motion Buffer'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive integer number <br />
<br />
<br />
Recording normally starts exactly when a recording trigger or command is issued. Using this parameter you can have HSYCO start recording some time ahead of the recording command. This is particularly important to capture video a few seconds before an event happens.<br />
<br />
When this parameter is set, HSYCO constantly acquires images from the camera, not only when necessary to display or record video. Moreover, the temporary recording of this buffer requires memory resources, and it is therefore convenient not to use high values (values included between 10 and 20, with an acquisition rate of about 400 milliseconds, can be considered normal).<br />
<br />
Enable motion buffering only when actually needed.<br />
<br />
<br />
'''Remote Password'''<br />
<br />
'''Default:''' <br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
HSYCO can optionally serve live images of its cameras through a password protected HTTP request, for example:<br />
<br />
<nowiki>https://<hsycoserver>/x/camera/<cameraid>?password=<password>&size=<width>x<height></nowiki><br />
<br />
(size is optional) for single frames or: <br />
<br />
<nowiki>https://<hsycoserver>/x/camerastream/<cameraid>?size=<width>x<height>&password=<pwd>[&period=<millis>]</nowiki><br />
<br />
to retrieve a MJPEG stream.<br />
<br />
It is also possible to define different passwords for clients inside the trusted range of IP addresses and outside.<br />
<br />
<br />
'''Trusted Password'''<br />
<br />
'''Default:''' <br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
Similar to RemoteRequestPassword, you can use this optional parameter to set remote passwords for clients inside the trusted range of IO addresses.<br />
<br />
Note that requests with the TrustedRequestPassword value will be also served via HTTP, without SSL.<br />
<br />
<br />
'''Rotate'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
Allows the rotation of the images acquired by a camera. Set to the number of decimal degrees of rotation. A positive number causes a clockwise rotation. Because of the rotation, the images could be cut or have bars at their edges to adapt the rotated picture to the frame size. Setting this parameter could cause a noticeable impact of performance, especially when processing high resolution images.<br />
<br />
=== Grids ===<br />
<br />
You can define up to 99 different combinations of cameras to create matrix displays of multiple cameras. The id is automatically generated when the + button is pressed, starting from 1 and up to 99 with consecutive numbers.<br />
<br />
Grids could be deleted using the - button.<br />
<br />
<br />
[[File:Configuration Grids.png|border|center|600px]]<br />
<br />
<br />
Select an item in the grids list to define the grid’s number of rows and columns and select the cameras for each position. You can leave some positions empty.<br />
You should also define the other grid parameters.<br />
<br />
'''Resolution'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' <width> x <height> in pixels<br />
<br />
<br />
This optional parameter is used to optimize grid processing performance, especially on large grids when using large size skins for the Web interface.<br />
<br />
You can define a maximum resolution for the grid. HSYCO will always deliver this grid with a resolution that is never larger than the width and height defined with this parameter. <br />
<br />
The effect is to reduce the byte size of the resulting image, improving performance on remote connections, and to offload the CPU processing required to generate the grid, having a potential benefit on frame rate.<br />
<br />
<br />
'''Remote Password'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
HSYCO can optionally serve live images of its grids through a password protected HTTP request, for example:<br />
<br />
<nowiki>https://<hsycoserver>/x/camera/grid<N>?password=<password>&size=<width>x<height></nowiki><br />
<br />
(size is optional) for single frames or: <br />
<br />
<nowiki>https://<hsycoserver>/x/camerastream/grid<N>?size=<width>x<height>&password=<pwd>[&period=<millis>]</nowiki><br />
<br />
to retrieve a MJPEG stream.<br />
<br />
It is also possible to define different passwords for clients inside the trusted range of IP addresses and outside.<br />
<br />
<br />
'''Trusted Password'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' string (letters and numbers)<br />
<br />
<br />
Similar to RemoteRequestPassword, you can use this optional parameter to set remote access passwords for clients inside the trusted range of IP addresses.<br />
<br />
Note that requests with the TrustedRequestPassword value will be also served via HTTP, without SSL.<br />
<br />
== Data Loggers ==<br />
<br />
The Data Loggers section is used to define HSYCO’s data loggers and their configuration parameters.<br />
<br />
<br />
[[File:Configuration Data Loggers1.png|border|center|600px]]<br />
<br />
<br />
There is one general configuration parameter:<br />
<br />
'''CSV Separator'''<br />
<br />
'''Default:''' comma<br />
<br />
'''Format:''' tab | comma | semicolon<br />
<br />
<br />
This parameter defines the field separator character for CSV files generated by the data loggers.<br />
<br />
<br />
Each data logger must have a unique ID. You can add a new data loggers pressing the + button.<br />
<br />
<br />
[[File:Configuration Data Loggers2.png|border|center]]<br />
<br />
<br />
Select the type, range or counter, and enter the data logger unique ID.<br />
<br />
Already defined data loggers could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
Counter and range data loggers have different configuration parameters.<br />
<br />
<br />
=== Counter Data Loggers ===<br />
<br />
<br />
[[File:Configuration Data Loggers Counter.png|border|center|600px]]<br />
<br />
<br />
'''Decimals'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
The number of decimal digits to be used for the input data.<br />
<br />
<br />
'''Resolution'''<br />
<br />
'''Default:''' hour<br />
<br />
'''Format:''' minute | hour | day | month<br />
<br />
<br />
Data aggregation maximum resolution.<br />
<br />
<br />
'''Hour Interval'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' divisor of 24<br />
<br />
<br />
Specifies the number of hours to be grouped into a single interval. For example, if set to 6, the day will be divided in groups of 6 hours: 1-6, 7-12, 13-18, and 19-24.<br />
<br />
<br />
'''Set Variables'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
If set to true (checked), the following variables will be generated:<br />
*<code>$dlog.<datalogger_id>.hour.tot</code>: its value is updated to the total value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.past.tot</code>: its value is updated to the total value of the past hour<br />
*<code>$dlog.<datalogger_id>.day.tot</code>: its value is updated to the total value of today<br />
*<code>$dlog.<datalogger_id>.day.past.tot</code>: its value is updated to the total value of yesteday<br />
*<code>$dlog.<datalogger_id>.month.tot</code>: its value is updated to the total value of the current month<br />
*<code>$dlog.<datalogger_id>.month.past.tot</code>: its value is updated to the total value of the past month<br />
*<code>$dlog.<datalogger_id>.year.tot</code>: its value is updated to the total value of the current year<br />
*<code>$dlog.<datalogger_id>.year.past.tot</code>: its value is updated to the total value of the past year<br />
<br />
If slots are used, the following variables will be generated for each slot:<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.hour.tot</code>: its value is updated to the total value of the current hour for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.hour.past.tot</code>: its value is updated to the total value of the past hour for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.day.tot</code>: its value is updated to the total value of today for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.day.past.tot</code>: its value is updated to the total value of yesteday for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.month.tot</code>: its value is updated to the total value of the current month for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.month.past.tot</code>: its value is updated to the total value of the past month for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.year.tot</code>: its value is updated to the total value of the current year for this slot<br />
*<code>$dlog.<datalogger_id>.s<slot_id>.year.past.tot</code>: its value is updated to the total value of the past year for this slot<br />
<br />
<br />
'''Delete data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, data older than the specified amount of days will be deleted.<br />
<br />
<br />
'''Consolidate months data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one month.<br />
<br />
<br />
'''Consolidate days data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one day.<br />
<br />
<br />
'''Consolidate hours data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one hour.<br />
<br />
<br />
'''Max Delta'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' positive float number<br />
<br />
<br />
Sets the maximum valid delta between consecutive readings. If the calculated delta exceed such value, the read value is ignored. If not specified, all values are accepted.<br />
<br />
{{tip|It is highly recommended to set the delta limit in order to prevent the data series from being corrupted in case of false readings.}}<br />
<br />
<br />
'''Upper Limit'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' positive float number<br />
<br />
<br />
Specifies the maximum value that can be reached by the input value. This value will be used in case of counter roll-over. A value of 0 indicates that no upper limit is specified.<br />
<br />
<br />
'''Separate Slot Charts'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
Option for counter data loggers using time slots. Specifies wether or not to use different monthly and yearly charts for each defined time slot.<br />
<br />
<br />
'''Align Slots'''<br />
<br />
'''Default:''' true<br />
<br />
'''Format:''' true | false<br />
<br />
<br />
Option for counter data loggers using time slots with separate charts. Specifies wether or not to align the scale of the slot charts belonging to the same period.<br />
<br />
<br />
<br />
'''Rates Log File'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' file path. e.g.: ''hsyco/rates.csv''<br />
<br />
<br />
Option for counter data loggers using time slots. Specifies the path of the file where the processed data will be logged. If omitted, no log file will be created.<br />
<br />
If the path includes the strings “%Y”, “%M”, or “%D” they will be replaced respectively by the current year, month, or day.<br />
<br />
=== Range Data Loggers ===<br />
<br />
<br />
[[File:Configuration Data Loggers Range.png|border|center|600px]]<br />
<br />
<br />
'''Decimals'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' integer number<br />
<br />
<br />
The number of decimal digits to be used for the input data.<br />
<br />
<br />
'''Resolution'''<br />
<br />
'''Default:''' hour<br />
<br />
'''Format:''' minute | hour | day | month<br />
<br />
<br />
Data aggregation maximum resolution.<br />
<br />
<br />
'''Hour Interval'''<br />
<br />
'''Default:''' 1<br />
<br />
'''Format:''' divisor of 24<br />
<br />
<br />
Specifies the number of hours to be grouped into a single interval. For example, if set to 6, the day will be divided in groups of 6 hours: 1-6, 7-12, 13-18, and 19-24.<br />
<br />
<br />
'''Set Variables'''<br />
<br />
'''Default:''' false<br />
<br />
'''Format:''' true | false<br />
<br />
If set to true (checked), the following variables will be generated:<br />
*<code>$dlog.<datalogger_id>.hour.min.tot</code>: its value is updated to the minimum value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.max.tot</code>: its value is updated to the maximum value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.avg.tot</code>: its value is updated to the average value of the current hour<br />
*<code>$dlog.<datalogger_id>.hour.past.min.tot</code>: its value is updated to the minimum value of the past hour<br />
*<code>$dlog.<datalogger_id>.hour.past.max.tot</code>: its value is updated to the maximum value of the past hour<br />
*<code>$dlog.<datalogger_id>.hour.past.avg.tot</code>: its value is updated to the average value of the past hour<br />
<br />
*<code>$dlog.<datalogger_id>.day.min.tot</code>: its value is updated to the minimum value of today<br />
*<code>$dlog.<datalogger_id>.day.max.tot</code>: its value is updated to the maximum value of today<br />
*<code>$dlog.<datalogger_id>.day.avg.tot</code>: its value is updated to the average value of today<br />
*<code>$dlog.<datalogger_id>.day.past.min.tot</code>: its value is updated to the minimum value of yesterday<br />
*<code>$dlog.<datalogger_id>.day.past.max.tot</code>: its value is updated to the maximum value of yesterday<br />
*<code>$dlog.<datalogger_id>.day.past.avg.tot</code>: its value is updated to the average value of yesterday<br />
<br />
*<code>$dlog.<datalogger_id>.month.min.tot</code>: its value is updated to the minimum value of the current month<br />
*<code>$dlog.<datalogger_id>.month.max.tot</code>: its value is updated to the maximum value of the current month<br />
*<code>$dlog.<datalogger_id>.month.avg.tot</code>: its value is updated to the average value of the current month<br />
*<code>$dlog.<datalogger_id>.month.past.min.tot</code>: its value is updated to the minimum value of the past month<br />
*<code>$dlog.<datalogger_id>.month.past.max.tot</code>: its value is updated to the maximum value of the past month<br />
*<code>$dlog.<datalogger_id>.month.past.avg.tot</code>: its value is updated to the average value of the past month<br />
<br />
*<code>$dlog.<datalogger_id>.year.min.tot</code>: its value is updated to the minimum value of the current year<br />
*<code>$dlog.<datalogger_id>.year.max.tot</code>: its value is updated to the maximum value of the current year<br />
*<code>$dlog.<datalogger_id>.year.avg.tot</code>: its value is updated to the average value of the current year<br />
*<code>$dlog.<datalogger_id>.year.past.min.tot</code>: its value is updated to the minimum value of the past year<br />
*<code>$dlog.<datalogger_id>.year.past.max.tot</code>: its value is updated to the maximum value of the past year<br />
*<code>$dlog.<datalogger_id>.year.past.avg.tot</code>: its value is updated to the average value of the past year<br />
<br />
<br />
'''Delete data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, data older than the specified amount of days will be deleted.<br />
<br />
<br />
'''Consolidate months data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one month.<br />
<br />
<br />
'''Consolidate days data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one day.<br />
<br />
<br />
'''Consolidate hours data after'''<br />
<br />
'''Default:'''<br />
<br />
'''Format:''' non-negative integer number<br />
<br />
<br />
If set to a value greater than zero, the resolution of data older than the specified amount of days will be reduced to one hour.<br />
<br />
<br />
'''Origin'''<br />
<br />
'''Default:''' 0<br />
<br />
'''Format:''' float number<br />
<br />
<br />
Specifies the origin of the charts.<br />
<br />
<br />
<br />
'''Range'''<br />
<br />
'''Default:''' <br />
<br />
'''Format:''' low:up<br />
<br />
<br />
Specifies the range of the charts as “low:up”, where “low” indicates the lower limit and “up” the upper one. The lower and upper limits can be specified as rigid or flexible: if the value of a limit is followed by a “!” (e.g. 0!:20!) then it is rigid, meaning it will not change even if the data logger has processed a value exceeding the range. On the contrary, flexible ranges (e.g. 0:20) will be modified whenever a value exceed it. <br />
<br />
If the parameter is omitted, the charts will range from the lowest processed value to the highest one.<br />
<br />
<br />
'''Out of Range Mode'''<br />
<br />
'''Default:''' cut<br />
<br />
'''Format:''' cut | ignore<br />
<br />
<br />
Option for range data loggers with a predefined range. Specifies the behavior of the data logger when updated with a value which exceed the set value range: if “cut” is specified then the value is adjusted to the limits, else, if this parameter is set to “ignore”, the passed value is not taken into account. In both cases, an error message is reported for out of range values.<br />
<br />
=== Tools ===<br />
<br />
By clicking on the tools icon it is possible to access the data recovery and size functions.<br />
<br />
==== Data Recovery ====<br />
<br />
The data recovery tool allows to import data loggers' data from an old backup of the "data" folder. It can be used in case of database corruption or hard disk failure.<br />
<br />
[[File:Configuration Data Loggers Recovery.png|border|center]]<br />
<br />
Enter the name of the folder containing the backup (default: "data_backup", must be located in HSYCO's root folder) and specify whether or not to overwrite existing data. This option specifies how to handle data which are stored both in the backup database and in the current database and relative to the same time. If the checkbox is set the data in the backup will overwrite the current data, otherwise the current data will be preserved.<br />
<br />
When clicking on "Restore" all the data of the currently defined and enabled data loggers available in the backup will be imported.<br />
<br />
==== Size Report ====<br />
<br />
Clicking on the data logger size button opens the size report page, where all counter and range data loggers are listed with the number of data rows stored in the database for each data logger, and the grand total. This is quite useful to fine tune the data decimation and data expiration settings.<br />
<br />
[[File:Configuration Data Loggers Size.png|border|center]]<br />
<br />
<br />
Please note that, if you have a large amount of data stored in data loggers, the report will take some time to become available.<br />
<br />
== DMX ==<br />
<br />
The DMX section is used to define the DMX-512 gateways.<br />
<br />
<br />
[[File:Configuration DMX1.png|border|center|600px]]<br />
<br />
<br />
Each DMX gateway must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration DMX2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
HSYCO supports three different DMX solutions, using different configuration parameters.<br />
<br />
=== KissBox DMX Network Gateways ===<br />
<br />
For KissBox network gateways, check IP and enter the IP address and port number.<br />
<br />
<br />
[[File:Configuration DMX KissBox.png|border|center]]<br />
<br />
<br />
=== ENTTEC DMX USB PRO DMX Gateways ===<br />
<br />
For the ENTTEC DMX USB PRO DMX gateways, check Comm and enter the virtual serial port name assigned to the USB port. See the [[Enttec|ENTTEC DMX USB PRO]] application note for additional information.<br />
<br />
<br />
[[File:Configuration DMX Enttec.png|border|center]]<br />
<br />
=== Domino and Contatto DMX devices ===<br />
<br />
When using Doemmegi’s Domino or Contatto systems DMX devices, check ID and enter the full device name, including the I/O server prefix. See the [[Domino]] or [[Contatto]] application notes for additional information.<br />
<br />
<br />
[[File:Configuration DMX Duemmegi.png|border|center]]<br />
<br />
== Location Services ==<br />
<br />
The Location Services section is used to define the WiFi access points used to locate the WiFi clients position.<br />
<br />
<br />
[[File:Configuration Location Services1.png|border|center|600px]]<br />
<br />
<br />
Each access point must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration Location Services2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration Location Services3.png|border|center|600px]]<br />
<br />
<br />
There are two options:<br />
- IP address, for access points<br />
- iBeacon, with UUID, Major, Minor<br />
<br />
== Timers ==<br />
<br />
The Timers section is used to define user timers.<br />
<br />
<br />
[[File:Configuration Timers1.png|border|center|600px]]<br />
<br />
<br />
Each timer must have a unique ID. You can add a new timers pressing the + button.<br />
<br />
<br />
[[File:Configuration Timers2.png|border|center]]<br />
<br />
<br />
Already defined timers could be deleted with the - button or disabled by unchecking the Enabled checkbox.<br />
Timers don’t require any configuration parameter besides the id.<br />
<br />
== Squeezebox ==<br />
<br />
This section is used to define the Squeezebox server and music players.<br />
<br />
<br />
[[File:Configuration Squeezebox1.png|border|center|600px]]<br />
<br />
<br />
You should set the Squeezebox server’s IP address or network name and port number.<br />
<br />
Each player must have a unique ID. You can add a new devices pressing the + button.<br />
<br />
<br />
[[File:Configuration Squeezebox2.png|border|center]]<br />
<br />
<br />
Already defined devices could be deleted with the - button or disabled without removing their configuration parameters by unchecking the Enabled checkbox.<br />
<br />
<br />
[[File:Configuration Squeezebox3.png|border|center|600px]]<br />
<br />
<br />
The only configuration parameter is the player id, usually its MAC address.</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=File:Configuration_Location_Services3.png&diff=8991File:Configuration Location Services3.png2020-09-21T13:51:16Z<p>Gionatan: Gionatan uploaded a new version of File:Configuration Location Services3.png</p>
<hr />
<div></div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=HSYCO_App_for_iOS_Devices&diff=8990HSYCO App for iOS Devices2020-09-21T13:44:39Z<p>Gionatan: /* Beacons */</p>
<hr />
<div>{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Menu.png|l1=Right menu|w2=150|i2=HSYCO_iOS_FavPages.png|l2=Favorite pages}}<br />
<br />
<br />
HSYCO App is the offical HSYCO iOS application for iPhone, iPad and iPod touch that lets you easily connect to your HSYCO Server, in a more convenient way than traditional Web-based access.<br />
<br />
Its many features enrich and expand the HSYCO experience in many ways:<br />
<br />
* Multiple connections: you can easily setup connections and set your favourite ones to quickly switch between them.<br />
<br />
* Connection setup: customize your connection to your needs with kiosk mode, lock rotation, scale, speech recognition and bar scanner tool. Manage the certificate and saved pin/puk.<br />
<br />
* Export/Import connections: save and restore all your connections with a password-protected file.<br />
<br />
* Authentication: if you wish so, the app handles the PIN/PUK credentials of all your connections automatically, adding a layer of protection with a global password and integrating Touch and Face ID.<br />
<br />
* App Links: share and import connections and send custom user commands with Universal Links that can also be embedded in QR Codes and NFC Tags.<br />
<br />
* Speech Recognition: send vocal commands to the server.<br />
<br />
* QR and Bar code scanning: scan QR and bar codes from your connection, to process app links or send the data directly to the server.<br />
<br />
* Beacons: enable beacon monitoring, to gather data on the device's location.<br />
<br />
* Apple Watch: each connection with a specific Apple Watch interface will be ready for you, on your wrist.<br />
<br />
<br />
{{note|<center>HSYCO App requires iOS 9.3 or later, and HSYCO Server 3.6. The latest features are only available on iOS 13.0 and HSYCO Server 3.7</center>}}<br />
<br />
{{Clear}}<br />
To download the HSYCO App, go to your Apple App Store and enter HSYCO in the search box, or click the App Store badge below.<br />
<br />
<br />
<center>[[File:Download_on_the_App_Store_Badge_US-UK_135x40.png|135x40px|link=https://itunes.apple.com/app/hsyco/id1038105480]]</center><br />
<br />
<br />
<br />
==Connections==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connections_edit.png|l1=Connection list|w2=150|i2=HSYCO_iOS_Connections.png|l2=Editing the connection list}}<br />
<br />
The first time the app is opened, it will automatically add a new connection and show its configuration page.<br />
The connection can be edited from the Connections page, by pressing the Edit button and selecting the connection. From the edit mode it's also possible to add more connections, clicking on Add Connection or the + icon on the bottom, or change the connections' order by dragging vertically the right-most icon.<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connection_edit_1.png|l1=Connection settings|w2=150|i2=HSYCO_iOS_Connection_edit_2.png|l2=More settings}}<br />
<br />
A connection has the following fields:<br />
* '''Name''': the name that will be displayed.<br />
* '''URL''': the URL to access your project on your HSYCO server. If you have a default project on your server, and use a standard port for the HTTPS connection, you can simply enter the DNS name for your server, without the URL key and project name.<br />
* '''Remember PIN/PUK''': if on, it will store the connection's PIN and PUK the first time they're correctly entered. It will then show a "Forget PIN/PUK" option. It has to be enabled to use the Apple Watch interface.<br />
* '''Kiosk Mode''': enables the [[Project#Kiosk|Kiosk Mode]], which removes some elements in the project's interface<br />
* '''Favorite''': if enabled, it will show the connection in the left menu of the app, or in the Home Screen Quick Actions popup that appears when you long-press the app icon.<br />
* '''Lock Rotation''': lock the interface in portrait or landscape mode, ignoring the device's orientation<br />
* '''Scale''': set the interface [[Project#Scale|scale mode]].<br />
* '''[[#Speech Recognition|Speech Recognition]]''': enables speech input on the connection. A specific language has to be selected. A button will appear in the top right corner when opening the connection. Speech is recognized and sent as a command to the HSYCO server. Speech recognition is available from iOS 10.<br />
* '''Monitor Beacons''': if enabled it will monitor beacons and send data to the HSYCO server.<br />
* '''[[#QR.2FBar_code_scanning|QR/Bar Code Scanner]]''': if enabled, it will show a button in the top right corner when opening the connection. Pressing the button opens up the device's camera, to scan and process a barcode or QR code.<br />
* '''Download Certificate''': to enable HTML5 cache the certificate needs to be downloaded and installed on the device.<br />
* '''[[#App Link Tool|App Link Tool]]''': opens a tool to create and share app links <br />
* '''Delete Connection''': permanently deletes the connection<br />
{{Clear}}<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connection_scale.png|l1=Scale setting|w2=150|i2=HSYCO_iOS_Connection_certificate.png|l2=Certificate pinning}}<br />
<br />
If your server has an SSL certificate for HTTPS encryption, the first time you open the connection a prompt will be shown to allow you to accept the certificate and save it within the app. This prompt will appear again if the certificate changes, serving as a protection against “Man in the Middle” (MiTM) attacks.<br />
<br />
{{Clear}}<br />
<br />
==Settings==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_App_Settings_1.png|l1=Settings list|w2=150|i2=HSYCO_App_Settings_2.png|l2=Ask password}}<br />
<br />
These are general app settings:<br />
* '''Ask Password''': if enabled, it will password-protect the app by showing a lock screen. The following options are visible once enabled.<br />
** '''Change Password''': change the current password. If already set you need to specify the old password.<br />
** '''Lock Now''': lock the device now, booting you out immediately to the lock screen<br />
** '''Use FaceID/TouchID''': enables unlocking the app through FaceID and TouchID (it's visible only if the device supports it)<br />
** '''Lock On Exit''': lock the app when it's put in the background or the device's screen is switched off.<br />
** '''Auto-Lock''': here you can set an amount of time after which the app is automatically locked.<br />
* '''Clear Cache''': clears the cache for all the connections.<br />
* '''Reset Settings''': restores all the app's settings to default and '''deletes all connections'''.<br />
*'''Hide Status Bar in Portrait''': if enabled, the app's top status bar (displaying time, battery and signal indicators) will be hidden in portrait mode (it's always hidden in landscape mode).<br />
* '''Hide Navigation Bar in Landscape''': if enabled, hides the header in landscape mode<br />
* '''App Link Tool''': opens the [[#App Link Tool|App Link Tool]], to create App Links, Qr Codes and write NFC Tags.<br />
* If an Apple Watch is paired, two additional options will be available: <br />
** '''Reduce Button Feedback''': it disables sound and vibration when pressing buttons.<br />
** '''Reset Apple Watch''': resets the Apple Watch configuration. Once pressed, to see the connection page you need to open the connection again from the app.<br />
* '''Export/Import Configuration''': saves or restores settings and connections to a password-protected file. Importing a configuration will replace the current settings and list of connections.<br />
{{Clear}}<br />
<br />
==App Link Tool==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_App_App_Link_Tool_1.png|l1=App Link Tool|w2=150|i2=HSYCO_App_App_Link_Tool_2.png|l2=QR Code}}<br />
<br />
The HSYCO App Link generates links that can be used to quickly add a connection to the app, to send a custom user command to the HSYCO server or both. If the device doesn't have the HSYCO App installed, a website will be opened instead, with links to download the app.<br />
Links can be embedded in QR Codes or in NFC Tags.<br />
<br />
QR Codes are automatically scanned by the default iOS camera app, while NFC Tags are automatically scanned by bringing the device near to the tag when the screen is on (only available on devices that support background tag reading: iPhone XS and later).<br />
<br />
The App Link Tool has the following options:<br />
* '''Connection''': if specified, it will bind the link to a specific connection. This link will create the connection if no other connections with the same URL are already configured in the app.<br />
* '''Embed Configuration''': if enabled, it will embed the main configuration settings: name, kiosk mode, scale, lock rotation, speech and qr/bar code scanner. Pin and puk won't be embedded.<br />
* '''Send a command''': if enabled, it will automatically send a command when the connection is open. If no connection was specified in the previous options:<br />
** if a connection is currently open it will send the command immediately<br />
** if no connection is open (app is closed or on a different page) and there's only one connection in the connection list, it will open it and then send the command<br />
<br />
A description of what the link does is displayed above the following options:<br />
* '''Link''': share the link (sharing allows you to copy it, send it to your contacts, send it through email, save it to files etc.)<br />
* '''QR Code''': open up the QR Code tool to display, customize and share the code.<br />
* '''NFC Tag''': shows two options<br />
** Write: write the NFC Tag by bringing your device near the tag<br />
** Write Lock: write and lock the NFC Tag, if the tag supports locking. Once locked it, the data can't be changed anymore. This option is useful to prevent tampering.<br />
<br />
{{Clear}}<br />
<br />
==Speech Recognition==<br />
<br />
If the Speech Recognition option is enabled in the connection settings, when the connection is open and loaded, a speech icon [[File:HSYCO iOS.speech.png|18px]] will be displayed on the top right.<br />
Tapping it will open the speech recognition popup. When you stop speaking or press the OK button, the text will be sent to the HSYCO server's [[NLP#How_to_send_text_messages_to_the_NLP_engine|NLP engine]]. <br />
<br />
==QR/Bar code scanning==<br />
<br />
If the QR/Bar code scanning option is enabled in the connection settings, when the connection is open and loaded, a scan icon [[File:HSYCO iOS.code scan.png|18px]] will be displayed on the top right.<br />
Tapping on it the camera view will open up, allowing QR and bar code scanning.<br />
<br />
Just focus on a code of the supported type and it will be scanned.<br />
If the scanned code is a QR Code with an [[#App Link Tool|App Link]], it will be immediately processed.<br />
Otherwise the code will be sent to the HSYCO server as a user command with the following format:<br />
<pre><br />
name: "code:<code type>"<br />
param:"<scanned code>"<br />
</pre><br />
<br />
The currently supported code types are:<br />
qr, ean8, ean13, pdf417, dataMatrix, aztec, code128, code39, code39Mod43, code93, interleaved2of5, itf14, upce<br />
<br />
==Apple Watch==<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Watch_1.png|l1=Watch Page|w2=150|i2=HSYCO_iOS_Watch_2.png|l2=Camera example}}<br />
<br />
If one or more of your connections are associated with HSYCO projects configured with Apple Watch menus, you will automatically have them configured in the Apple Watch.<br />
<br />
If you change the Apple Watch menu in any project on HSYCO Server, simply open the corresponding connection in HSYCO Remote to load the new version. After this, next time you open HSYCO Remote on your Apple Watch, it will automatically show the updated command menu.<br />
<br />
You can create an Apple Watch page for a project:<br />
* visually, with the [[Project_Editor#Page_Types|Project Editor]], creating a page of type "watch page". For more information about it, see the [[Apple_Watch_Interface|Apple Watch Interface documentation]]<br />
* through a project's UISet to set the [[Project#HSYCO_App_Support|app_watch]] attribute<br />
<br />
==Beacons==<br />
The HSYCO App supports beacon detection. For more info see [[Beacons on HSYCO App for iOS]]</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8989Beacons on HSYCO App for iOS2020-09-21T13:42:35Z<p>Gionatan: /* HSYCO Implementation */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[JavaScript_Callback_Functions_API#LocationBeaconEvent|LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8988Beacons on HSYCO App for iOS2020-09-21T13:42:21Z<p>Gionatan: /* HSYCO Implementation */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[[[JavaScript_Callback_Functions_API#LocationBeaconEvent|LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8987Beacons on HSYCO App for iOS2020-09-21T13:42:01Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[JavaScript_Callback_Functions_API#LocationBeaconEvent|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=JavaScript_Callback_Functions_API&diff=8986JavaScript Callback Functions API2020-09-21T13:39:54Z<p>Gionatan: </p>
<hr />
<div>[[Category:JavaScript]]<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
<source lang="java">DaylightEvent(day)</source><br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== haActiveEvent ===<br />
<br />
<source lang="java">haActiveEvent(active)</source><br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
<source lang="java">PowerEvent(power)</source><br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this function, you can alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: numeric - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* numeric - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
{{tip|The JavaScript PowerEvent function is always called, but its return value is used only when the Java PowerEvent callback is not defined or returned -1.}}<br />
<br />
=== programTimerEvent ===<br />
<br />
<source lang="java">programTimerEvent(name)</source><br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using [[Java_Command_and_Utility_Methods_API#programTimerSet|programTimerSet()]], [[Java_Command_and_Utility_Methods_API#programTimerReset|programTimerReset()]], [[Java_Command_and_Utility_Methods_API#programTimerRepeat|programTimerRepeat()]], or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: string - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
<source lang="java">SchedulerEvent(groupname, schedulename)</source><br />
<br />
This callback blocking function allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: string - the scheduler’s group name<br />
* schedulename: string - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
<source lang="java">StartupEvent()</source><br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
<source lang="java">SunPositionEvent(azimuth, elevation)</source><br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: numeric - the current Sun angle from true north, in decimal degrees<br />
*elevation: numeric - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
<br />
=== TimeEvent ===<br />
<br />
<source lang="java">TimeEvent(time)</source><br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: numeric - the current time in milliseconds.<br />
<br />
<br />
=== varEvent ===<br />
<br />
<source lang="java">varEvent(name, value)</source><br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: string - the variable name. Names are case-insensitive<br />
* value: string - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
<source lang="java">CameraCommandEvent(camerafunction, action, camera)</source><br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camerafunction: string - see the table below<br />
* action: string - see the table below<br />
* camera: string - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* numeric - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{tip|The JavaScript CameraCommandEvent camerafunction is always called, but its return value is used only when the Java CameraCommandEvent callback is not defined or returned -1.}}<br />
<br />
<div data-skipeditordoc><br />
{{ui_camerapanel_ptz_table}}<br />
</div><br />
<br />
=== CameraMotionEvent ===<br />
<br />
<source lang="java">CameraMotionEvent(event, time)</source><br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* event: string - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* time: numeric - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
<source lang="java">CameraViewEvent(camera, active)</source><br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: string - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
<source lang="java">DmxEvent(channel, state)</source><br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: numeric - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: numeric - the new channel value, from 0 to 255.<br />
<br />
<br />
=== DmxFilter ===<br />
<br />
<source lang="java">DmxFilter(channel, state, reverse)</source><br />
<br />
This function allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking function and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: numeric - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: numeric - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* numeric - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
<br />
=== DmxStartupEvent ===<br />
<br />
<source lang="java">DmxStartupEvent(index)</source><br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this function, to execute commands for the same DMX gateway.<br />
<br />
{{tip|This is a blocking function. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* Index: numeric - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
<source lang="java">IREvent(received, irtransid, event)</source><br />
<br />
This function is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: numeric - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: string - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
<source lang="java">IOEvent(name, value)</source><br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: string - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: string - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
<br />
=== IOStartupEvent ===<br />
<br />
<source lang="java">IOStartupEvent(index)</source><br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: numeric - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
<source lang="java">ModbusEvent(name, addr, unitid, pdu)</source><br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: string - the name of the Modbus Server I/O server<br />
* addr: string - IP address of the Modbus client<br />
* unitid: numeric - the unit id set in the received Modbus request<br />
* pdu: string - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* string - the response PDU data, in hexadecimal string format.<br />
<br />
{{tip|The JavaScript ModbusEvent function is called only when the Java ModbusEvent callback is not defined or returned a null value.}}<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
<source lang="java">httpCallEvent(address, secure, query)</source><br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This function shoud return a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: string - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: string - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* string - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
<source lang="java"> httpRawEvent(host, secure, version, httpmethod, gzip, contenttype, query, session, userid, indata)</source><br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() function should return a complete HTTP response (both headers and body).<br />
<br />
If multiple httpRawEvent() callbacks or functions are defined, only one should write the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: string - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: string - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: string - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: string - the HTTP request's content type (value of Content-Type header)<br />
* query: string - the string following the ? in the URL path, or null if not present<br />
* session: string - the authenticated session id, or null<br />
* userid: string - the user id for requests having a valid authentication cookie, null otherwise<br />
* indata: string - the POST data, or an empty string for GET or HEAD requests.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* string - the application code should return the full HTTP response, including all headers.<br />
<br />
<br />
'''Example:'''<br />
<br />
function httpRawEvent(host, secure, version, httpmethod, gzip, contenttype, query, session, userid, indata) : {<br />
messageLog("host: " + host);<br />
messageLog("secure: " + secure);<br />
messageLog("version: " + version);<br />
messageLog("httpmethod: " + httpmethod);<br />
messageLog("gzip: " + gzip);<br />
messageLog("contenttype: " + contenttype);<br />
messageLog("query: " + query);<br />
messageLog("session: " + session);<br />
messageLog("userid: " + userid);<br />
messageLog("in: " + indata);<br />
<br />
var outdata = httpmethod + " data echoed from host [" + host + "] : " + indata + "\r\n";<br />
var httpreply = version + " 200 OK\r\n";<br />
httpreply += "Server: HSYCO\r\n";<br />
httpreply += "Content-length: " + outdata.length + "\r\n";<br />
httpreply += "Content-type: text/plain\r\n";<br />
httpreply += "Cache-Control: no-store, no-cache\r\n\r\n";<br />
httpreply += outdata;<br />
return httpreply;<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
<source lang="java">LocationEvent(mac, ip, zoneId)</source><br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: string - the MAC address of the client<br />
* ip: string - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: numeric - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
<source lang="java"> SysLogEvent(address, log)</source><br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: string - the IP address of the SYSLOG client<br />
* log: string - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
<source lang="java">PBXCallEvent(host, caller, called)</source><br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: string - the IP address of the PBX server <br />
* caller: string - the caller number<br />
* called: string - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
<source lang="java">SlimPowerEvent(index, power)</source><br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: numeric - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
<source lang="java">SlimStatusEvent()</source><br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: numeric - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
<source lang="java">SlimVolumeEvent(index, volume)</source><br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: numeric - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: numeric - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
<source lang="java">UserTimerEvent(name, active)</source><br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: string - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
<source lang="java">pageEvent(address, session, userid, project, page)</source><br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: string - the client’s IP address<br />
* session: string - session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* project: string - project’s id<br />
* page: string - the page id, with the #landscape or #portrait suffix if the page has distinct orientation versions in the project.<br />
<br />
=== loginEvent ===<br />
<br />
<source lang="java">loginEvent(address, session, userid)</source><br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: string - the client’s IP address string in textual presentation<br />
* session: string - session id string that uniquely identifies the client session<br />
* userid: string - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
<source lang="java">logoutEvent(address, session, userid, lock)</source><br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: string - the client’s IP address string in textual presentation<br />
* session: string - session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
<source lang="java">uiClearEvent(session)</source><br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
<source lang="java">userCommand(session, userid, name, param)</source><br />
<br />
Called by user clicks on buttons created in the Web interface with the [[user|user objects]], by a USER action in EVENTS, or by the user() Java method and JavaScript function.<br />
Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: string - the name field of the [[user|user object]]<br />
* param: string - the param of the [[user|user object]]<br />
<br />
<br />
'''Returns:'''<br />
<br />
* string - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
<br />
{{tip|The JavaScript userCommand function is alway called, but its return value is used only when the Java userCommand callback is not defined or returned null or an empty string.}}<br />
<br />
=== userSubmit ===<br />
<br />
<source lang="java">userSubmit(session, userid, name, fields)</source><br />
<br />
This function is similar to userCommand(session, userid, name, param).<br />
<br />
When userSubmit() is defined, it will be called when a [[submit|submit button]] is pressed, while userCommand() will continue to be called on [[user|user buttons]].<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a [[link|link object]]), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called when that popup or page is closed, with "/close" appended to param.<br />
<br />
You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: string - the id of the (submit!id) object<br />
* fields: array - the array of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* string - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status. <br />
<br />
{{tip|The JavaScript userSubmit function is alway called, but its return value is used only when the Java userCommand or userSubmit callback are not defined or returned null or an empty string.}}<br />
<br />
<br />
'''Examples:'''<br />
<br />
The following code shows how to retrieve all field names and values of a submitted form.<br />
<br />
<syntaxhighlight lang="javascript"><br />
function userSubmit(session, user, name, values) : {<br />
if (session.length > 0) {<br />
messageLog(user + ', ' + name + '=' + values);<br />
var keys = values.keySet().toArray();<br />
for (var i = 0; i < keys.length; i++) {<br />
messageLog(user + ', ' + keys[i] + ' = ' + values.get(keys[i]));<br />
}<br />
return "";<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
Create a project with a form and a few input fields in a container. Pressing the submit button should return something like this in the log file:<br />
<br />
2014.01.31 13:54:32.034 - staff, submit1={keypad1=344, date1=20140131, input1=this is a text field} <br />
2014.01.31 13:54:32.038 - staff, keypad1 = 344 <br />
2014.01.31 13:54:32.039 - staff, date1 = 20140131 <br />
2014.01.31 13:54:32.042 - staff, input1 = this is a text field <br />
2014.01.31 13:54:32.043 - WEB USER COMMAND [submit1]: input1@this is a text field@date1@20140131@keypad1@344 [OK]<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
<source lang="java">WebRootRequestEvent(addr, secure, useragent)</source><br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: string - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: string - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* string - optional return string containing a valid absolute or relative URL<br />
<br />
<br />
'''Examples:'''<br />
<br />
The following code redirects any root HTTP request received by the HSYCO server to the manager page.<br />
<br />
<syntaxhighlight lang="javascript"><br />
function WebRootRequestEvent(addr, secure, useragent) : {<br />
return "hsycoserver/manager";<br />
}<br />
</syntaxhighlight><br />
<br />
== Location ==<br />
<br />
=== LocationBeaconEvent ===<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<source lang="java">LocationBeaconEvent(session, address, userid, zone, distance, background)</source><br />
<br />
Called when the HSYCO App detects a change in the proximity of one of the configured beacons.<br />
<br />
There is no guarantee that the event would be fired.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - session id string that uniquely identifies the client session<br />
* address: string - the beacon's address<br />
* userid: string - the user id<br />
* zone: string - the beacon's zone<br />
* distance: string - far, near, immediate or off<br />
* background: boolean - true if the app called the server while in background mode (app closed)</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8985Beacons on HSYCO App for iOS2020-09-21T13:34:53Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[Programming#Events|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
// when a beacon is too far, distance will be "off"<br />
if (distance == "off") {<br />
messageLog("Beacon " + beacon + " is too far");<br />
} else {<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8984Beacons on HSYCO App for iOS2020-09-21T13:19:14Z<p>Gionatan: /* HSYCO Implementation */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
See [[LocationBeaconEvent]] for more information. <br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[Programming#Events|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8983Beacons on HSYCO App for iOS2020-09-21T13:17:23Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[Programming#Events|Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8982Beacons on HSYCO App for iOS2020-09-21T13:17:04Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102<br />
<br />
<br />
and in [[Events|Programming#Events]]:<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
var beacon = "";<br />
switch (address) {<br />
case "1001":<br />
beacon = "B1";<br />
break;<br />
case "1002":<br />
beacon = "B2";<br />
break;<br />
case "1005":<br />
beacon = "B5";<br />
break;<br />
}<br />
<br />
messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);<br />
}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8981Beacons on HSYCO App for iOS2020-09-21T11:46:55Z<p>Gionatan: /* Configuring Beacons */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''1''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 110'''2''' (identifies the Zone)<br />
<br />
In hsyco.ini<br />
LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101<br />
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101<br />
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8980Beacons on HSYCO App for iOS2020-09-21T11:43:45Z<p>Gionatan: /* Working Around the 20 Zone Limit */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
<br />
<br />
==Configuring Beacons==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]<br />
<br />
In this example we will set the beacon's identities as follows:<br />
* Beacon '''"B1"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''01'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 100'''2''' (identifies the Zone)<br />
* Beacon '''"B2"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''02'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 100'''2''' (identifies the Zone)<br />
<br />
...<br />
<br />
* Beacon '''"B5"'''<br />
** '''UUID''': ACFD165E-C0C0-11E3-9BBE-1A51493210'''05'''<br />
** '''Major''': 10'''1''' (identifies the Area)<br />
** '''Minor''': 100'''2''' (identifies the Zone)</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8978Beacons on HSYCO App for iOS2020-09-21T10:43:59Z<p>Gionatan: /* Working Around the 20 Zone Limit */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
<br />
<br />
==Working Around the 20 Zone Limit==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png|700px]]</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=File:IBeacon_Zones.png&diff=8977File:IBeacon Zones.png2020-09-21T10:42:01Z<p>Gionatan: </p>
<hr />
<div></div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Beacons_on_HSYCO_App_for_iOS&diff=8976Beacons on HSYCO App for iOS2020-09-21T09:44:41Z<p>Gionatan: Created page with "Category:INCOMPLETE Category:Advanced Programming <div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject t..."</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
HSYCO App works with beacons to provide location awareness.<br />
<br />
This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.<br />
<br />
==General Concept==<br />
Each beacon is identified with the following values:<br />
* UUID: Universally Unique Identifier, which typically identifies a region<br />
* Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions<br />
* Minor: also called least significant value, used to divide regions even further<br />
<br />
Beacons also have a Proximity property, which describes the distance between the beacon and the user's device.<br />
There are two modes of detecting beacons:<br />
* monitoring: detects entering and exiting a region. This happens even when the app is closed or in background<br />
* ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance<br />
<br />
==HSYCO Implementation==<br />
HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:<br />
* '''Area''': defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.<br />
* '''Zones''': divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.<br />
* '''Beacons''': a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.<br />
Each Beacon is defined in hsyco.ini and given a unique Location ID.<br />
<br />
e.g. Here is an example of the configuration of a beacon in hsyco.ini<br />
LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081<br />
<br />
iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.<br />
<br />
To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:<br />
* monitor '''Areas''': <br />
** only if there are more than 20 Zones defined across all the enabled connections<br />
** only when the device is not inside an Area<br />
** a maximum of 20 Areas can be monitored<br />
** once an Area is entered, the App switches to monitor Zones<br />
* monitor '''Zones'''<br />
** only if there are more than 20 beacons defined across all the enabled connections<br />
** a maximum of 20 Zones can be monitored<br />
** when the device exits all the Zones, the App switched to monitor Areas<br />
* monitor '''Beacons'''<br />
** only if there are less than 20 beacons defined across all the enabled connections<br />
** useful for small applications, it gives the highest accuracy<br />
<br />
Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation.<br />
Ranging is always active for all defined beacons when the app is open (in foreground).<br />
<br />
function LocationBeaconEvent(session, address, userid, zone, distance, background) : {<br />
messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");<br />
}<br />
<br />
<br />
<br />
==Working Around the 20 Zone Limit==<br />
Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. <br />
Multiple beacons can have the same Zone identifier as long as the UUID is different.<br />
<br />
So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.<br />
<br />
Here's an example of how it could work:<br />
<br />
[[File:iBeacon Zones.png]]</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Datalogger&diff=8911Datalogger2020-09-07T07:46:15Z<p>Gionatan: /* Datalogger attributes */</p>
<hr />
<div>{{UI Object Header}}<br />
Works in combination with the data logger function to present a collection of data using time-based statistical charts.<br />
This object automatically adapts the graphical layout and size of the charts based on the overall object's size. The default presentation can be customized using several optional attributes.<br />
A datalogger can have a browser mode (if available server-side) for consulting past data. If a datalogger in browser mode isn't visible for more than a minute, it automatically resets to live mode.<br />
<br />
[[File:UI Object datalogger.1.png]][[File:UI Object datalogger.2.png]][[File:UI Object datalogger.3.png]]<br />
<br />
== Parameters ==<br />
*'''id''': the object's ID, used by UISets. Optional<br />
*'''loggerID''': the datalogger ID (or comma-separated list of multiple IDs)<br />
*'''position''': the object's position. Use the pixels or rows and columns coordinates format<br />
*'''size''': the chart's area's width and height<br />
*'''unit''': list of values axis labels. If the datalogger has slots, one unit for each slot. If there are multiple datalogger ids, one unit for each datalogger<br />
*'''attributes''': list of UI attribute names and values defining the chart's aspect and data. Setting this parameter is the same as setting each UI attribute with a UISet<br />
<br />
== Syntax ==<br />
(datalogger[!<id>] <loggerID>; <pos>; <width>; <height>; <label>; <attributes>)<br />
E.g.<br />
(datalogger!datalogger1 edl; x80y60; 820; 500; kWh; controls=toolbar)<br />
<br />
== Types ==<br />
There are 5 different options to display data, which correspond to five possible values of the '''type''' attribute.<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''bars'''"<br />
|-<br />
| [[File:UI Object datalogger.bars.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''points'''"<br />
|-<br />
| [[File:UI Object datalogger.points.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''line'''"<br />
|-<br />
| [[File:UI Object datalogger.line.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''spline'''"<br />
|-<br />
| [[File:UI Object datalogger.spline.png]]<br />
|}<br />
<br />
{{clear}}<br />
<br />
=== Pie ===<br />
The '''pie''' type is particularly useful to compare multiple dataloggers.<br />
<br />
The optional '''pielegendposition attribute''' determines the legend position relative to the pie chart.<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''pie'''"<br />
|-<br />
| [[File:UI Object datalogger.pie.1.png]]<br />
|}<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''pie'''" (with pielegendposition="right")<br />
|-<br />
| [[File:UI Object datalogger.pie.2.png]]<br />
|}<br />
{{clear}}<br />
<br />
== HD ==<br />
In browser mode, it is possible to display a high definition version of the current resolution, which selects and displays values from the next resolution available.<br />
For example when HD is active, the "month" resolution will display all the data from the "day" resolution, so it will show 744 (31*24) values instead of 31.<br />
HD is displayed only when available (if the next resolution data is available and not consolidated).<br />
<br />
HD is controlled by the hd attribute, which can be either "true"/"false" or "toggle" which will show an icon and let the user control it.<br />
<br />
[[File:UI Object datalogger.4.png]][[File:UI Object datalogger.5.png]]<br />
<br />
== Multiple Dataloggers ==<br />
The Datalogger object can be configured to show multiple dataloggers at once.<br />
The '''loggerID''' parameter (or '''loggerid''' attribute) can contain a list of IDs of visible dataloggers.<br />
<br />
<br />
To give the user the option to select which dataloggers to show, the '''list''' attribute can be used. If a list is set, a drop down menu will appear in the top left of the toolbar (which is visible only if controls is set to toolbar). The '''names''' attribute allows to associate a name to each datalogger of the list (or each datalogger specified in loggerid, if the list is empty).<br />
<br />
[[File:UI Object datalogger.6.png]]<br />
<br />
<br />
By default, all dataloggers are merged on the same scale. The '''multirange''' attribute allows each datalogger to have its own range, with its scale shown on the left of the chart.<br />
<br />
[[File:UI Object datalogger.7.png]]<br />
<br />
<br />
The '''rangegroups''' attribute allows dataloggers to be grouped to a common range.<br />
<br />
[[File:UI Object datalogger.8.png]]<br />
<br />
<br />
The '''valuecolor[n]''' attribute (where n is an index starting from 1) changes the value color of a specific datalogger.<br />
<br />
In a datalogger with type range, the value is used for average, while colors for maximum and minimum are automatically calculated by changing the brightness.<br />
Use only colors in rgb or hex formats.<br />
<br />
<br />
{{tip| }} To avoid strange behaviors when displaying multiple dataloggers, it's better to choose dataloggers that have common properties (such as origin, range, consolidation).<br />
<br />
== Fullscreen ==<br />
The datalogger object has a fullscreen mode, that can be toggled by clicking the fullscreen icon, or by setting the value of the "fullscreen" UI Attribute.<br />
<br />
The fullscreen mode will hide any other object and scale the datalogger to cover the whole screen.<br />
<br />
If the URL query "fullwindow" is present, the datalogger will just expand inside the browser's window instead of actually going fullscreen.<br />
<br />
== UI Attributes ==<br />
{{UI Object Attributes (Common)}}<br />
=== Datalogger attributes ===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|avgvalues<br />
|true<br />
|Show average values, if in range mode<br />
|-<br />
|false<br />
|Hide average values<br />
|-<br />
<br />
|axiscolor<br />
|<CSS color><br />
|Axis color<br />
|-<br />
<br />
|browserdate<br />
|date and time, in the "yyyymmddhh" format<br />
|Set the browser date and time. These formats will also be accepted: "yyyy", "yyyymm", "yyyymmdd"<br />
|-<br />
<br />
|rowspan="5"|browserscale<br />
|10y<br />
|Set the live scale to 10 years<br />
|-<br />
|year<br />
|Set the browser scale to year<br />
|-<br />
|month<br />
|Set the browser scale to month<br />
|-<br />
|day<br />
|Set the browser scale to day<br />
|-<br />
|hour<br />
|Set the browser scale to hour<br />
|-<br />
<br />
|rowspan="2"|byday<br />
|true<br />
|Show daily data (hours)<br />
|-<br />
|false<br />
|Hide daily data<br />
|-<br />
<br />
|rowspan="2"|byhour<br />
|true<br />
|Show hourly data (minutes)<br />
|-<br />
|false<br />
|Hide hourly data<br />
|-<br />
<br />
|rowspan="2"|byminute<br />
|true<br />
|Show data by minute (seconds)<br />
|-<br />
|false<br />
|Hide data by minute<br />
|-<br />
<br />
|rowspan="2"|bymonth<br />
|true<br />
|Show monthly data (days)<br />
|-<br />
|false<br />
|Hide monthly data<br />
|-<br />
<br />
|rowspan="3"|controls<br />
|tabs<br />
|Show tabs on live mode for scale and slots<br />
|-<br />
|toolbar<br />
|Show a toolbar to control live and browser modes<br />
|-<br />
|none<br />
|Don't show any controls<br />
|- <br />
<br />
|csvseparator<br />
|<character><br />
|Specifies a character used to separate columns in the generated csv file. Rows are separated with the newline character.<br />
|-<br />
<br />
|rowspan="2"|download<br />
|true<br />
|Display a button in browser mode that downloads a CSV file with the currently displayed data<br />
|-<br />
|false<br />
|Default. No download icon<br />
|-<br />
<br />
|rowspan="2"|drawaxis<br />
|true<br />
|Default. The axes are visible (also notches and labels)<br />
|-<br />
|false<br />
|The axes are not visible (also notches and labels)<br />
|-<br />
<br />
|rowspan="2"|fullscreen<br />
|true<br />
|Enables fullscreen mode<br />
|-<br />
|false<br />
|Disables fullscreen mode<br />
|-<br />
<br />
|group<br />
|<value><br />
|Name of a group. Dataloggers with the same group are synchronized (controlling one affects the others)<br />
|-<br />
<br />
|rowspan="3"|hd<br />
|true<br />
|Enables HD<br />
|-<br />
|false<br />
|Disables HD<br />
|-<br />
|toggle<br />
|Shows an HD icon that lets the user toggle HD on and off<br />
|-<br />
<br />
|labelcolor<br />
|<CSS color><br />
|Color of the axis and bars labels<br />
|-<br />
<br />
|rowspan="3"|legend<br />
|true<br />
|Show all legends<br />
|-<br />
|false<br />
|Hide legends<br />
|-<br />
|<comma-separated list of values><br />
|List of legends (min, avg, max) to show<br />
|-<br />
<br />
|list<br />
|<comma-separated list of datalogger IDs><br />
|List of IDs of dataloggers selectable by the user. Shows an icon in the control bar that displays the list<br />
|-<br />
<br />
|loggerid<br />
|<comma-separated list of datalogger IDs><br />
|List of IDs, to change it dynamically<br />
|-<br />
<br />
|rowspan="2"|maxvalues<br />
|true<br />
|Show maximum values, if in range mode<br />
|-<br />
|false<br />
|Hide maximum values<br />
|-<br />
<br />
|rowspan="2"|minvalues<br />
|true<br />
|Show minimum values, if in range mode<br />
|-<br />
|false<br />
|Hide minimum values<br />
|-<br />
<br />
|rowspan="4"|mode<br />
|live<br />
|Live mode<br />
|-<br />
|browser<br />
|Browser mode<br />
|-<br />
|liveonly<br />
|Locks the interface in live mode. It will hide the browser/live button on the UI.<br />
|-<br />
|browseronly<br />
|Locks the interface in browser mode. It will hide the browser/live button on the UI.<br />
|-<br />
<br />
|rowspan="2"|multichart<br />
|true<br />
|Show multiple charts on live mode<br />
|-<br />
|false<br />
|Show a single chart in live mode, based on the selected scale<br />
|-<br />
<br />
|rowspan="2"|multirange<br />
|true<br />
|For multiple datalogger ids only. Show multiple ranges for each datalogger id: each chart has multiple value axes.<br />
|-<br />
|false<br />
|Default. Single range for each datalogger<br />
|-<br />
|-<br />
<br />
|names<br />
|<comma-separated list of values><br />
|Sets the dataloggers names (relative to the list attribute or, if list is empty, the loggerid attribute), displayed in the legend, list popup and csv header<br />
|-<br />
<br />
|notchcolor<br />
|<CSS color><br />
|Color of the axis notches<br />
|-<br />
<br />
|notches<br />
|<value><br />
|Number of notches on the y-axis<br />
|-<br />
<br />
|rowspan="2"|panel<br />
|true<br />
|Show background panel<br />
|-<br />
|false<br />
|Hide background panel<br />
|-<br />
<br />
|rowspan="2"|pastperiod<br />
|true<br />
|Show past period (only available for single datalogger id)<br />
|-<br />
|false<br />
|Hide past period<br />
|-<br />
<br />
|rowspan="2"|pastvaluecolor<br />
|<CSS color><br />
|A color that applies to all past values<br />
|-<br />
|<CSS color>,<CSS color>,<CSS color><br />
|Colors that apply respectively to minimum, average and maximum past values<br />
|-<br />
<br />
|rowspan="2"|pielegendposition<br />
|top<br />
|Default value. Applies to "pie" type, shows the legend on the top of the pie chart<br />
|-<br />
|right<br />
|Applies to "pie" type, shows the legend on the right of the pie chart<br />
|-<br />
<br />
|pointsize<br />
|number of pixels<br />
|Point size (use for the points chart type)<br />
|-<br />
<br />
|rowspan="2"|presentvaluecolor<br />
|<CSS color><br />
|A color that applies to all present values<br />
|-<br />
|<CSS color>,<CSS color>,<CSS color><br />
|Colors that apply respectively to minimum, average and maximum present values<br />
|-<br />
<br />
|rangegroups<br />
|<comma-separated list of values><br />
|List of group names, one for each datalogger id (specified in list or in loggerid, if the list is empty). Dataloggers with the same group name are grouped together in a single range.<br />
|-<br />
<br />
|rowspan="4"|scale<br />
|year<br />
|Set the live scale to year<br />
|-<br />
|month<br />
|Set the live scale to month<br />
|-<br />
|day <br />
|Set the live scale to day<br />
|-<br />
|hour<br />
|Set the live scale to hour<br />
|-<br />
<br />
|refreshinterval<br />
|<number><br />
|Specifies the live refresh interval in seconds. Default is 5<br />
|-<br />
<br />
|slot<br />
|<number><br />
|Show a specific slot, from 0 to the number of slots-1<br />
|-<br />
<br />
|stroke<br />
|number of pixel<br />
|Pixel size of the stroke that applies to line and spline chart's types<br />
|-<br />
<br />
|thresholdcolor<br />
|<CSS color><br />
|Color of threshold lines. Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|thresholdcolors<br />
|<comma-separated list of CSS colors><br />
|List of colors of threshold lines, one value each line. Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|thresholds<br />
|<comma-separated list of values><br />
|List of values at which to display a line (threshold). Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|rowspan="2"|totals<br />
|true<br />
|Show totals<br />
|-<br />
|false<br />
|Hide totals<br />
|-<br />
<br />
|rowspan="5"|type<br />
|bars<br />
|Draw bars<br />
|-<br />
|points<br />
|Draws points<br />
|-<br />
|line<br />
|Draws a line connecting the values<br />
|-<br />
|spline<br />
|Draws a spline connecting the values<br />
|-<br />
|pie<br />
|Draws a pie chart, each slice representing a datalogger (if multiple dataloggers are visible), or past/present values. Percentage is shown in the legend<br />
|-<br />
<br />
|units<br />
|<comma-separated list of values><br />
|Units to display on the top left of each chart. If the datalogger has slots, one unit for each slot. If there are multiple datalogger ids, one unit for each datalogger<br />
|-<br />
<br />
|valuecolor[n]<br />
|<CSS color><br />
|Available only with multiple dataloggers. Specifies the value color of the datalogger with index n (starting from 1). Accepted color formats: rgb and hex.<br />
|-<br />
<br />
|rowspan="2"|valueclickenabled<br />
|true<br />
|Default. Clicking on a value in browser mode will show the details of the next scale, if available.<br />
|-<br />
|false<br />
|Clicking on a value to show the details is disabled<br />
|-<br />
<br />
|valuelabelcolor<br />
|<CSS color><br />
|Value label's color<br />
|-<br />
<br />
|rowspan="3"|valuelabeltype<br />
|inside<br />
|Value labels are shown inside (if "type" is bars, points or gauge) or over (if "type" is line or spline)<br />
|-<br />
|outside<br />
|Value labels are shown above or below<br />
|-<br />
|popup<br />
|Value labels are shown on mouseover, or on touch (if on a touch-enabled device)<br />
|-<br />
<br />
<br />
<br />
|}<br />
<br />
{{Note:CSS Color}}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Datalogger&diff=8910Datalogger2020-09-03T06:27:53Z<p>Gionatan: /* Datalogger attributes */</p>
<hr />
<div>{{UI Object Header}}<br />
Works in combination with the data logger function to present a collection of data using time-based statistical charts.<br />
This object automatically adapts the graphical layout and size of the charts based on the overall object's size. The default presentation can be customized using several optional attributes.<br />
A datalogger can have a browser mode (if available server-side) for consulting past data. If a datalogger in browser mode isn't visible for more than a minute, it automatically resets to live mode.<br />
<br />
[[File:UI Object datalogger.1.png]][[File:UI Object datalogger.2.png]][[File:UI Object datalogger.3.png]]<br />
<br />
== Parameters ==<br />
*'''id''': the object's ID, used by UISets. Optional<br />
*'''loggerID''': the datalogger ID (or comma-separated list of multiple IDs)<br />
*'''position''': the object's position. Use the pixels or rows and columns coordinates format<br />
*'''size''': the chart's area's width and height<br />
*'''unit''': list of values axis labels. If the datalogger has slots, one unit for each slot. If there are multiple datalogger ids, one unit for each datalogger<br />
*'''attributes''': list of UI attribute names and values defining the chart's aspect and data. Setting this parameter is the same as setting each UI attribute with a UISet<br />
<br />
== Syntax ==<br />
(datalogger[!<id>] <loggerID>; <pos>; <width>; <height>; <label>; <attributes>)<br />
E.g.<br />
(datalogger!datalogger1 edl; x80y60; 820; 500; kWh; controls=toolbar)<br />
<br />
== Types ==<br />
There are 5 different options to display data, which correspond to five possible values of the '''type''' attribute.<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''bars'''"<br />
|-<br />
| [[File:UI Object datalogger.bars.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''points'''"<br />
|-<br />
| [[File:UI Object datalogger.points.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''line'''"<br />
|-<br />
| [[File:UI Object datalogger.line.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''spline'''"<br />
|-<br />
| [[File:UI Object datalogger.spline.png]]<br />
|}<br />
<br />
{{clear}}<br />
<br />
=== Pie ===<br />
The '''pie''' type is particularly useful to compare multiple dataloggers.<br />
<br />
The optional '''pielegendposition attribute''' determines the legend position relative to the pie chart.<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''pie'''"<br />
|-<br />
| [[File:UI Object datalogger.pie.1.png]]<br />
|}<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''pie'''" (with pielegendposition="right")<br />
|-<br />
| [[File:UI Object datalogger.pie.2.png]]<br />
|}<br />
{{clear}}<br />
<br />
== HD ==<br />
In browser mode, it is possible to display a high definition version of the current resolution, which selects and displays values from the next resolution available.<br />
For example when HD is active, the "month" resolution will display all the data from the "day" resolution, so it will show 744 (31*24) values instead of 31.<br />
HD is displayed only when available (if the next resolution data is available and not consolidated).<br />
<br />
HD is controlled by the hd attribute, which can be either "true"/"false" or "toggle" which will show an icon and let the user control it.<br />
<br />
[[File:UI Object datalogger.4.png]][[File:UI Object datalogger.5.png]]<br />
<br />
== Multiple Dataloggers ==<br />
The Datalogger object can be configured to show multiple dataloggers at once.<br />
The '''loggerID''' parameter (or '''loggerid''' attribute) can contain a list of IDs of visible dataloggers.<br />
<br />
<br />
To give the user the option to select which dataloggers to show, the '''list''' attribute can be used. If a list is set, a drop down menu will appear in the top left of the toolbar (which is visible only if controls is set to toolbar). The '''names''' attribute allows to associate a name to each datalogger of the list (or each datalogger specified in loggerid, if the list is empty).<br />
<br />
[[File:UI Object datalogger.6.png]]<br />
<br />
<br />
By default, all dataloggers are merged on the same scale. The '''multirange''' attribute allows each datalogger to have its own range, with its scale shown on the left of the chart.<br />
<br />
[[File:UI Object datalogger.7.png]]<br />
<br />
<br />
The '''rangegroups''' attribute allows dataloggers to be grouped to a common range.<br />
<br />
[[File:UI Object datalogger.8.png]]<br />
<br />
<br />
The '''valuecolor[n]''' attribute (where n is an index starting from 1) changes the value color of a specific datalogger.<br />
<br />
In a datalogger with type range, the value is used for average, while colors for maximum and minimum are automatically calculated by changing the brightness.<br />
Use only colors in rgb or hex formats.<br />
<br />
<br />
{{tip| }} To avoid strange behaviors when displaying multiple dataloggers, it's better to choose dataloggers that have common properties (such as origin, range, consolidation).<br />
<br />
== Fullscreen ==<br />
The datalogger object has a fullscreen mode, that can be toggled by clicking the fullscreen icon, or by setting the value of the "fullscreen" UI Attribute.<br />
<br />
The fullscreen mode will hide any other object and scale the datalogger to cover the whole screen.<br />
<br />
If the URL query "fullwindow" is present, the datalogger will just expand inside the browser's window instead of actually going fullscreen.<br />
<br />
== UI Attributes ==<br />
{{UI Object Attributes (Common)}}<br />
=== Datalogger attributes ===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|avgvalues<br />
|true<br />
|Show average values, if in range mode<br />
|-<br />
|false<br />
|Hide average values<br />
|-<br />
<br />
|axiscolor<br />
|<CSS color><br />
|Axis color<br />
|-<br />
<br />
|browserdate<br />
|date and time, in the "yyyymmddhh" format<br />
|Set the browser date and time. These formats will also be accepted: "yyyy", "yyyymm", "yyyymmdd"<br />
|-<br />
<br />
|rowspan="5"|browserscale<br />
|10y<br />
|Set the live scale to 10 years<br />
|-<br />
|year<br />
|Set the browser scale to year<br />
|-<br />
|month<br />
|Set the browser scale to month<br />
|-<br />
|day<br />
|Set the browser scale to day<br />
|-<br />
|hour<br />
|Set the browser scale to hour<br />
|-<br />
<br />
|rowspan="2"|byday<br />
|true<br />
|Show daily data (hours)<br />
|-<br />
|false<br />
|Hide daily data<br />
|-<br />
<br />
|rowspan="2"|byhour<br />
|true<br />
|Show hourly data (minutes)<br />
|-<br />
|false<br />
|Hide hourly data<br />
|-<br />
<br />
|rowspan="2"|byminute<br />
|true<br />
|Show data by minute (seconds)<br />
|-<br />
|false<br />
|Hide data by minute<br />
|-<br />
<br />
|rowspan="2"|bymonth<br />
|true<br />
|Show monthly data (days)<br />
|-<br />
|false<br />
|Hide monthly data<br />
|-<br />
<br />
|rowspan="3"|controls<br />
|tabs<br />
|Show tabs on live mode for scale and slots<br />
|-<br />
|toolbar<br />
|Show a toolbar to control live and browser modes<br />
|-<br />
|none<br />
|Don't show any controls<br />
|- <br />
<br />
|csvseparator<br />
|<character><br />
|Specifies a character used to separate columns in the generated csv file. Rows are separated with the newline character.<br />
|-<br />
<br />
|rowspan="2"|download<br />
|true<br />
|Display a button in browser mode that downloads a CSV file with the currently displayed data<br />
|-<br />
|false<br />
|Default. No download icon<br />
|-<br />
<br />
|rowspan="2"|drawaxis<br />
|true<br />
|Default. The axes are visible (also notches and labels)<br />
|-<br />
|false<br />
|The axes are not visible (also notches and labels)<br />
|-<br />
<br />
|rowspan="2"|fullscreen<br />
|true<br />
|Enables fullscreen mode<br />
|-<br />
|false<br />
|Disables fullscreen mode<br />
|-<br />
<br />
|group<br />
|<value><br />
|Name of a group. Dataloggers with the same group are synchronized (controlling one affects the others)<br />
|-<br />
<br />
|rowspan="3"|hd<br />
|true<br />
|Enables HD<br />
|-<br />
|false<br />
|Disables HD<br />
|-<br />
|toggle<br />
|Shows an HD icon that lets the user toggle HD on and off<br />
|-<br />
<br />
|labelcolor<br />
|<CSS color><br />
|Color of the axis and bars labels<br />
|-<br />
<br />
|rowspan="3"|legend<br />
|true<br />
|Show all legends<br />
|-<br />
|false<br />
|Hide legends<br />
|-<br />
|<comma-separated list of values><br />
|List of legends (min, avg, max) to show<br />
|-<br />
<br />
|list<br />
|<comma-separated list of datalogger IDs><br />
|List of IDs of dataloggers selectable by the user. Shows an icon in the control bar that displays the list<br />
|-<br />
<br />
|loggerid<br />
|<comma-separated list of datalogger IDs><br />
|List of IDs, to change it dynamically<br />
|-<br />
<br />
|rowspan="2"|maxvalues<br />
|true<br />
|Show maximum values, if in range mode<br />
|-<br />
|false<br />
|Hide maximum values<br />
|-<br />
<br />
|rowspan="2"|minvalues<br />
|true<br />
|Show minimum values, if in range mode<br />
|-<br />
|false<br />
|Hide minimum values<br />
|-<br />
<br />
|rowspan="4"|mode<br />
|live<br />
|Live mode<br />
|-<br />
|browser<br />
|Browser mode<br />
|-<br />
|liveonly<br />
|Locks the interface in live mode. It will hide the browser/live button on the UI.<br />
|-<br />
|browseronly<br />
|Locks the interface in browser mode. It will hide the browser/live button on the UI.<br />
|-<br />
<br />
|rowspan="2"|multichart<br />
|true<br />
|Show multiple charts on live mode<br />
|-<br />
|false<br />
|Show a single chart in live mode, based on the selected scale<br />
|-<br />
<br />
|rowspan="2"|multirange<br />
|true<br />
|For multiple datalogger ids only. Show multiple ranges for each datalogger id: each chart has multiple value axes.<br />
|-<br />
|false<br />
|Default. Single range for each datalogger<br />
|-<br />
|-<br />
<br />
|names<br />
|<comma-separated list of values><br />
|Sets the dataloggers names (relative to the list attribute or, if list is empty, the loggerid attribute), displayed in the legend, list popup and csv header<br />
|-<br />
<br />
|notchcolor<br />
|<CSS color><br />
|Color of the axis notches<br />
|-<br />
<br />
|notches<br />
|<value><br />
|Number of notches on the y-axis<br />
|-<br />
<br />
|rowspan="2"|panel<br />
|true<br />
|Show background panel<br />
|-<br />
|false<br />
|Hide background panel<br />
|-<br />
<br />
|rowspan="2"|pastperiod<br />
|true<br />
|Show past period (only available for single datalogger id)<br />
|-<br />
|false<br />
|Hide past period<br />
|-<br />
<br />
|rowspan="2"|pastvaluecolor<br />
|<CSS color><br />
|A color that applies to all past values<br />
|-<br />
|<CSS color>,<CSS color>,<CSS color><br />
|Colors that apply respectively to minimum, average and maximum past values<br />
|-<br />
<br />
|rowspan="2"|pielegendposition<br />
|top<br />
|Default value. Applies to "pie" type, shows the legend on the top of the pie chart<br />
|-<br />
|right<br />
|Applies to "pie" type, shows the legend on the right of the pie chart<br />
|-<br />
<br />
|pointsize<br />
|number of pixels<br />
|Point size (use for the points chart type)<br />
|-<br />
<br />
|rowspan="2"|presentvaluecolor<br />
|<CSS color><br />
|A color that applies to all present values<br />
|-<br />
|<CSS color>,<CSS color>,<CSS color><br />
|Colors that apply respectively to minimum, average and maximum present values<br />
|-<br />
<br />
|rangegroups<br />
|<comma-separated list of values><br />
|List of group names, one for each datalogger id (specified in list or in loggerid, if the list is empty). Dataloggers with the same group name are grouped together in a single range.<br />
|-<br />
<br />
|rowspan="4"|scale<br />
|year<br />
|Set the live scale to year<br />
|-<br />
|month<br />
|Set the live scale to month<br />
|-<br />
|day <br />
|Set the live scale to day<br />
|-<br />
|hour<br />
|Set the live scale to hour<br />
|-<br />
<br />
|refreshinterval<br />
|<number><br />
|Specifies the live refresh interval in seconds. Default is 5<br />
|-<br />
<br />
|slot<br />
|<number><br />
|Show a specific slot, from 0 to the number of slots-1<br />
|-<br />
<br />
|stroke<br />
|number of pixel<br />
|Pixel size of the stroke that applies to line and spline chart's types<br />
|-<br />
<br />
|thresholdcolor<br />
|<CSS color><br />
|Color of threshold lines. Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|thresholdcolors<br />
|<comma-separated list of CSS colors><br />
|List of colors of threshold lines, one value each line. Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|thresholds<br />
|<comma-separated list of values><br />
|List of values at which to display a line (threshold). Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|rowspan="2"|totals<br />
|true<br />
|Show totals<br />
|-<br />
|false<br />
|Hide totals<br />
|-<br />
<br />
|rowspan="5"|type<br />
|bars<br />
|Draw bars<br />
|-<br />
|points<br />
|Draws points<br />
|-<br />
|line<br />
|Draws a line connecting the values<br />
|-<br />
|spline<br />
|Draws a spline connecting the values<br />
|-<br />
|pie<br />
|Draws a pie chart, each slice representing a datalogger (if multiple dataloggers are visible), or past/present values. Percentage is shown in the legend<br />
|-<br />
<br />
|units<br />
|<comma-separated list of values><br />
|Units to display on the top left of each chart. If the datalogger has slots, one unit for each slot. If there are multiple datalogger ids, one unit for each datalogger<br />
|-<br />
<br />
|valuecolor[n]<br />
|<CSS color><br />
|Available only with multiple dataloggers. Specifies the value color of the datalogger with index n (starting from 1). Accepted color formats: rgb and hex.<br />
|-<br />
<br />
|valuelabelcolor<br />
|<CSS color><br />
|Value label's color<br />
|-<br />
<br />
|rowspan="3"|valuelabeltype<br />
|inside<br />
|Value labels are shown inside (if "type" is bars, points or gauge) or over (if "type" is line or spline)<br />
|-<br />
|outside<br />
|Value labels are shown above or below<br />
|-<br />
|popup<br />
|Value labels are shown on mouseover, or on touch (if on a touch-enabled device)<br />
|-<br />
<br />
<br />
<br />
|}<br />
<br />
{{Note:CSS Color}}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Datalogger&diff=8909Datalogger2020-09-03T06:27:29Z<p>Gionatan: /* Datalogger attributes */</p>
<hr />
<div>{{UI Object Header}}<br />
Works in combination with the data logger function to present a collection of data using time-based statistical charts.<br />
This object automatically adapts the graphical layout and size of the charts based on the overall object's size. The default presentation can be customized using several optional attributes.<br />
A datalogger can have a browser mode (if available server-side) for consulting past data. If a datalogger in browser mode isn't visible for more than a minute, it automatically resets to live mode.<br />
<br />
[[File:UI Object datalogger.1.png]][[File:UI Object datalogger.2.png]][[File:UI Object datalogger.3.png]]<br />
<br />
== Parameters ==<br />
*'''id''': the object's ID, used by UISets. Optional<br />
*'''loggerID''': the datalogger ID (or comma-separated list of multiple IDs)<br />
*'''position''': the object's position. Use the pixels or rows and columns coordinates format<br />
*'''size''': the chart's area's width and height<br />
*'''unit''': list of values axis labels. If the datalogger has slots, one unit for each slot. If there are multiple datalogger ids, one unit for each datalogger<br />
*'''attributes''': list of UI attribute names and values defining the chart's aspect and data. Setting this parameter is the same as setting each UI attribute with a UISet<br />
<br />
== Syntax ==<br />
(datalogger[!<id>] <loggerID>; <pos>; <width>; <height>; <label>; <attributes>)<br />
E.g.<br />
(datalogger!datalogger1 edl; x80y60; 820; 500; kWh; controls=toolbar)<br />
<br />
== Types ==<br />
There are 5 different options to display data, which correspond to five possible values of the '''type''' attribute.<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''bars'''"<br />
|-<br />
| [[File:UI Object datalogger.bars.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''points'''"<br />
|-<br />
| [[File:UI Object datalogger.points.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''line'''"<br />
|-<br />
| [[File:UI Object datalogger.line.png]]<br />
|}<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''spline'''"<br />
|-<br />
| [[File:UI Object datalogger.spline.png]]<br />
|}<br />
<br />
{{clear}}<br />
<br />
=== Pie ===<br />
The '''pie''' type is particularly useful to compare multiple dataloggers.<br />
<br />
The optional '''pielegendposition attribute''' determines the legend position relative to the pie chart.<br />
<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''pie'''"<br />
|-<br />
| [[File:UI Object datalogger.pie.1.png]]<br />
|}<br />
{| class="wikitable" style="float:left; margin-right:5px"<br />
| type="'''pie'''" (with pielegendposition="right")<br />
|-<br />
| [[File:UI Object datalogger.pie.2.png]]<br />
|}<br />
{{clear}}<br />
<br />
== HD ==<br />
In browser mode, it is possible to display a high definition version of the current resolution, which selects and displays values from the next resolution available.<br />
For example when HD is active, the "month" resolution will display all the data from the "day" resolution, so it will show 744 (31*24) values instead of 31.<br />
HD is displayed only when available (if the next resolution data is available and not consolidated).<br />
<br />
HD is controlled by the hd attribute, which can be either "true"/"false" or "toggle" which will show an icon and let the user control it.<br />
<br />
[[File:UI Object datalogger.4.png]][[File:UI Object datalogger.5.png]]<br />
<br />
== Multiple Dataloggers ==<br />
The Datalogger object can be configured to show multiple dataloggers at once.<br />
The '''loggerID''' parameter (or '''loggerid''' attribute) can contain a list of IDs of visible dataloggers.<br />
<br />
<br />
To give the user the option to select which dataloggers to show, the '''list''' attribute can be used. If a list is set, a drop down menu will appear in the top left of the toolbar (which is visible only if controls is set to toolbar). The '''names''' attribute allows to associate a name to each datalogger of the list (or each datalogger specified in loggerid, if the list is empty).<br />
<br />
[[File:UI Object datalogger.6.png]]<br />
<br />
<br />
By default, all dataloggers are merged on the same scale. The '''multirange''' attribute allows each datalogger to have its own range, with its scale shown on the left of the chart.<br />
<br />
[[File:UI Object datalogger.7.png]]<br />
<br />
<br />
The '''rangegroups''' attribute allows dataloggers to be grouped to a common range.<br />
<br />
[[File:UI Object datalogger.8.png]]<br />
<br />
<br />
The '''valuecolor[n]''' attribute (where n is an index starting from 1) changes the value color of a specific datalogger.<br />
<br />
In a datalogger with type range, the value is used for average, while colors for maximum and minimum are automatically calculated by changing the brightness.<br />
Use only colors in rgb or hex formats.<br />
<br />
<br />
{{tip| }} To avoid strange behaviors when displaying multiple dataloggers, it's better to choose dataloggers that have common properties (such as origin, range, consolidation).<br />
<br />
== Fullscreen ==<br />
The datalogger object has a fullscreen mode, that can be toggled by clicking the fullscreen icon, or by setting the value of the "fullscreen" UI Attribute.<br />
<br />
The fullscreen mode will hide any other object and scale the datalogger to cover the whole screen.<br />
<br />
If the URL query "fullwindow" is present, the datalogger will just expand inside the browser's window instead of actually going fullscreen.<br />
<br />
== UI Attributes ==<br />
{{UI Object Attributes (Common)}}<br />
=== Datalogger attributes ===<br />
{| class="wikitable"<br />
!Name<br />
!Value<br />
!Description<br />
|-<br />
<br />
|rowspan="2"|avgvalues<br />
|true<br />
|Show average values, if in range mode<br />
|-<br />
|false<br />
|Hide average values<br />
|-<br />
<br />
|axiscolor<br />
|<CSS color><br />
|Axis color<br />
|-<br />
<br />
|browserdate<br />
|date and time, in the "yyyymmddhh" format<br />
|Set the browser date and time. These formats will also be accepted: "yyyy", "yyyymm", "yyyymmdd"<br />
|-<br />
<br />
|rowspan="5"|browserscale<br />
|10y<br />
|Set the live scale to 10 years<br />
|-<br />
|year<br />
|Set the browser scale to year<br />
|-<br />
|month<br />
|Set the browser scale to month<br />
|-<br />
|day<br />
|Set the browser scale to day<br />
|-<br />
|hour<br />
|Set the browser scale to hour<br />
|-<br />
<br />
|rowspan="2"|byday<br />
|true<br />
|Show daily data (hours)<br />
|-<br />
|false<br />
|Hide daily data<br />
|-<br />
<br />
|rowspan="2"|byhour<br />
|true<br />
|Show hourly data (minutes)<br />
|-<br />
|false<br />
|Hide hourly data<br />
|-<br />
<br />
|rowspan="2"|byminute<br />
|true<br />
|Show data by minute (seconds)<br />
|-<br />
|false<br />
|Hide data by minute<br />
|-<br />
<br />
|rowspan="2"|bymonth<br />
|true<br />
|Show monthly data (days)<br />
|-<br />
|false<br />
|Hide monthly data<br />
|-<br />
<br />
|rowspan="3"|controls<br />
|tabs<br />
|Show tabs on live mode for scale and slots<br />
|-<br />
|toolbar<br />
|Show a toolbar to control live and browser modes<br />
|-<br />
|none<br />
|Don't show any controls<br />
|- <br />
<br />
|csvseparator<br />
|<character><br />
|Specifies a character used to separate columns in the generated csv file. Rows are separated with the newline character.<br />
|-<br />
<br />
|rowspan="2"|download<br />
|true<br />
|Display a button in browser mode that downloads a CSV file with the currently displayed data<br />
|-<br />
|false<br />
|Default. No download icon<br />
|-<br />
<br />
|rowspan="2"|drawaxis<br />
|true<br />
|Default. The axes are visible (also notches and labels)<br />
|-<br />
|false<br />
|The axes are not visible (also notches and labels)<br />
|-<br />
<br />
|rowspan="2"|fullscreen<br />
|true<br />
|Enables fullscreen mode<br />
|-<br />
|false<br />
|Disables fullscreen mode<br />
|-<br />
<br />
|group<br />
|<value><br />
|Name of a group. Dataloggers with the same group are synchronized (controlling one affects the others)<br />
|-<br />
<br />
|rowspan="3"|hd<br />
|true<br />
|Enables HD<br />
|-<br />
|false<br />
|Disables HD<br />
|-<br />
|toggle<br />
|Shows an HD icon that lets the user toggle HD on and off<br />
|-<br />
<br />
|labelcolor<br />
|<CSS color><br />
|Color of the axis and bars labels<br />
|-<br />
<br />
|rowspan="3"|legend<br />
|true<br />
|Show all legends<br />
|-<br />
|false<br />
|Hide legends<br />
|-<br />
|<comma-separated list of values><br />
|List of legends (min, avg, max) to show<br />
|-<br />
<br />
|list<br />
|<comma-separated list of datalogger IDs><br />
|List of IDs of dataloggers selectable by the user. Shows an icon in the control bar that displays the list<br />
|-<br />
<br />
|loggerid<br />
|<comma-separated list of datalogger IDs><br />
|List of IDs, to change it dynamically<br />
|-<br />
<br />
|rowspan="2"|maxvalues<br />
|true<br />
|Show maximum values, if in range mode<br />
|-<br />
|false<br />
|Hide maximum values<br />
|-<br />
<br />
|rowspan="2"|minvalues<br />
|true<br />
|Show minimum values, if in range mode<br />
|-<br />
|false<br />
|Hide minimum values<br />
|-<br />
<br />
|rowspan="2"|mode<br />
|live<br />
|Live mode<br />
|-<br />
|browser<br />
|Browser mode<br />
|-<br />
|liveonly<br />
|Locks the interface in live mode. It will hide the browser/live button on the UI.<br />
|-<br />
|browseronly<br />
|Locks the interface in browser mode. It will hide the browser/live button on the UI.<br />
|-<br />
<br />
|rowspan="2"|multichart<br />
|true<br />
|Show multiple charts on live mode<br />
|-<br />
|false<br />
|Show a single chart in live mode, based on the selected scale<br />
|-<br />
<br />
|rowspan="2"|multirange<br />
|true<br />
|For multiple datalogger ids only. Show multiple ranges for each datalogger id: each chart has multiple value axes.<br />
|-<br />
|false<br />
|Default. Single range for each datalogger<br />
|-<br />
|-<br />
<br />
|names<br />
|<comma-separated list of values><br />
|Sets the dataloggers names (relative to the list attribute or, if list is empty, the loggerid attribute), displayed in the legend, list popup and csv header<br />
|-<br />
<br />
|notchcolor<br />
|<CSS color><br />
|Color of the axis notches<br />
|-<br />
<br />
|notches<br />
|<value><br />
|Number of notches on the y-axis<br />
|-<br />
<br />
|rowspan="2"|panel<br />
|true<br />
|Show background panel<br />
|-<br />
|false<br />
|Hide background panel<br />
|-<br />
<br />
|rowspan="2"|pastperiod<br />
|true<br />
|Show past period (only available for single datalogger id)<br />
|-<br />
|false<br />
|Hide past period<br />
|-<br />
<br />
|rowspan="2"|pastvaluecolor<br />
|<CSS color><br />
|A color that applies to all past values<br />
|-<br />
|<CSS color>,<CSS color>,<CSS color><br />
|Colors that apply respectively to minimum, average and maximum past values<br />
|-<br />
<br />
|rowspan="2"|pielegendposition<br />
|top<br />
|Default value. Applies to "pie" type, shows the legend on the top of the pie chart<br />
|-<br />
|right<br />
|Applies to "pie" type, shows the legend on the right of the pie chart<br />
|-<br />
<br />
|pointsize<br />
|number of pixels<br />
|Point size (use for the points chart type)<br />
|-<br />
<br />
|rowspan="2"|presentvaluecolor<br />
|<CSS color><br />
|A color that applies to all present values<br />
|-<br />
|<CSS color>,<CSS color>,<CSS color><br />
|Colors that apply respectively to minimum, average and maximum present values<br />
|-<br />
<br />
|rangegroups<br />
|<comma-separated list of values><br />
|List of group names, one for each datalogger id (specified in list or in loggerid, if the list is empty). Dataloggers with the same group name are grouped together in a single range.<br />
|-<br />
<br />
|rowspan="4"|scale<br />
|year<br />
|Set the live scale to year<br />
|-<br />
|month<br />
|Set the live scale to month<br />
|-<br />
|day <br />
|Set the live scale to day<br />
|-<br />
|hour<br />
|Set the live scale to hour<br />
|-<br />
<br />
|refreshinterval<br />
|<number><br />
|Specifies the live refresh interval in seconds. Default is 5<br />
|-<br />
<br />
|slot<br />
|<number><br />
|Show a specific slot, from 0 to the number of slots-1<br />
|-<br />
<br />
|stroke<br />
|number of pixel<br />
|Pixel size of the stroke that applies to line and spline chart's types<br />
|-<br />
<br />
|thresholdcolor<br />
|<CSS color><br />
|Color of threshold lines. Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|thresholdcolors<br />
|<comma-separated list of CSS colors><br />
|List of colors of threshold lines, one value each line. Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|thresholds<br />
|<comma-separated list of values><br />
|List of values at which to display a line (threshold). Not supported with multiple dataloggers with different scales/units.<br />
|-<br />
<br />
|rowspan="2"|totals<br />
|true<br />
|Show totals<br />
|-<br />
|false<br />
|Hide totals<br />
|-<br />
<br />
|rowspan="5"|type<br />
|bars<br />
|Draw bars<br />
|-<br />
|points<br />
|Draws points<br />
|-<br />
|line<br />
|Draws a line connecting the values<br />
|-<br />
|spline<br />
|Draws a spline connecting the values<br />
|-<br />
|pie<br />
|Draws a pie chart, each slice representing a datalogger (if multiple dataloggers are visible), or past/present values. Percentage is shown in the legend<br />
|-<br />
<br />
|units<br />
|<comma-separated list of values><br />
|Units to display on the top left of each chart. If the datalogger has slots, one unit for each slot. If there are multiple datalogger ids, one unit for each datalogger<br />
|-<br />
<br />
|valuecolor[n]<br />
|<CSS color><br />
|Available only with multiple dataloggers. Specifies the value color of the datalogger with index n (starting from 1). Accepted color formats: rgb and hex.<br />
|-<br />
<br />
|valuelabelcolor<br />
|<CSS color><br />
|Value label's color<br />
|-<br />
<br />
|rowspan="3"|valuelabeltype<br />
|inside<br />
|Value labels are shown inside (if "type" is bars, points or gauge) or over (if "type" is line or spline)<br />
|-<br />
|outside<br />
|Value labels are shown above or below<br />
|-<br />
|popup<br />
|Value labels are shown on mouseover, or on touch (if on a touch-enabled device)<br />
|-<br />
<br />
<br />
<br />
|}<br />
<br />
{{Note:CSS Color}}</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8908Java Callback Methods API2020-08-31T11:42:45Z<p>Gionatan: /* userSubmit */</p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
static void DaylightEvent(boolean day)<br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
static String getUserVersion()<br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
static void haActiveEvent(boolean active)<br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
static int PowerEvent(int power)<br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
static void programTimerEvent(String name)<br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
static void SchedulerEvent(String groupname, String schedulename)<br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
static void StartupEvent()<br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
static void SunPositionEvent(int azimuth, int elevation)<br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
static void TimeEvent(long time)<br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
static void varEvent(String name, String value)<br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
static int cameraCommandEvent(String function, String action, String camera)<br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
static void CameraMotionEvent(String eventName, long remoteTime)<br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
static void CameraViewEvent(String camera, boolean active)<br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
static void DmxEvent(int channel, int state)<br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
static int DmxFilter(int channel, int state, boolean reverse)<br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
static void DmxStartupEvent(int serverIndex)<br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
static void IREvent(boolean received, int irtransid, String event)<br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
static void IOEvent(String id, String value)<br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
static void IOStartupEvent(int serverIndex)<br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)<br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
static String httpCallEvent(String address, boolean secure, String query)<br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)<br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
static void LocationEvent(long mac, InetAddress ip, int zoneId)<br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
static void SysLogEvent(String address, String log)<br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
static boolean PBXCallEvent(String host, String caller, String called)<br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
static void SlimPowerEvent(int index, int power)<br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
static void SlimStatusEvent(int index, int status)<br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
static void SlimVolumeEvent(int index, int volume)<br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
static boolean UserTimerEvent(String name, boolean active)<br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
static void pageEvent(String address, String session, String userid, String project, String page)<br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
static void loginEvent(String address, String session, String userid)<br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
static void logoutEvent(String address, String session, String userid, boolean lock)<br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
static void uiClearEvent(String session)<br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
static String userCommand(String name, String param)<br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
static String userCommand(String session, String userid, String name, String param)<br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userSubmit ===<br />
<br />
static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)<br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)<br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8907Java Callback Methods API2020-08-31T11:42:35Z<p>Gionatan: /* userCommand - with session information */</p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
static void DaylightEvent(boolean day)<br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
static String getUserVersion()<br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
static void haActiveEvent(boolean active)<br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
static int PowerEvent(int power)<br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
static void programTimerEvent(String name)<br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
static void SchedulerEvent(String groupname, String schedulename)<br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
static void StartupEvent()<br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
static void SunPositionEvent(int azimuth, int elevation)<br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
static void TimeEvent(long time)<br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
static void varEvent(String name, String value)<br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
static int cameraCommandEvent(String function, String action, String camera)<br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
static void CameraMotionEvent(String eventName, long remoteTime)<br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
static void CameraViewEvent(String camera, boolean active)<br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
static void DmxEvent(int channel, int state)<br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
static int DmxFilter(int channel, int state, boolean reverse)<br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
static void DmxStartupEvent(int serverIndex)<br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
static void IREvent(boolean received, int irtransid, String event)<br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
static void IOEvent(String id, String value)<br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
static void IOStartupEvent(int serverIndex)<br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)<br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
static String httpCallEvent(String address, boolean secure, String query)<br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)<br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
static void LocationEvent(long mac, InetAddress ip, int zoneId)<br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
static void SysLogEvent(String address, String log)<br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
static boolean PBXCallEvent(String host, String caller, String called)<br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
static void SlimPowerEvent(int index, int power)<br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
static void SlimStatusEvent(int index, int status)<br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
static void SlimVolumeEvent(int index, int volume)<br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
static boolean UserTimerEvent(String name, boolean active)<br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
static void pageEvent(String address, String session, String userid, String project, String page)<br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
static void loginEvent(String address, String session, String userid)<br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
static void logoutEvent(String address, String session, String userid, boolean lock)<br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
static void uiClearEvent(String session)<br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
static String userCommand(String name, String param)<br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
static String userCommand(String session, String userid, String name, String param)<br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userSubmit ===<br />
<br />
static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)<br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)<br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8906Java Callback Methods API2020-08-31T11:42:19Z<p>Gionatan: /* userCommand - with session information */</p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
static void DaylightEvent(boolean day)<br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
static String getUserVersion()<br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
static void haActiveEvent(boolean active)<br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
static int PowerEvent(int power)<br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
static void programTimerEvent(String name)<br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
static void SchedulerEvent(String groupname, String schedulename)<br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
static void StartupEvent()<br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
static void SunPositionEvent(int azimuth, int elevation)<br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
static void TimeEvent(long time)<br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
static void varEvent(String name, String value)<br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
static int cameraCommandEvent(String function, String action, String camera)<br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
static void CameraMotionEvent(String eventName, long remoteTime)<br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
static void CameraViewEvent(String camera, boolean active)<br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
static void DmxEvent(int channel, int state)<br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
static int DmxFilter(int channel, int state, boolean reverse)<br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
static void DmxStartupEvent(int serverIndex)<br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
static void IREvent(boolean received, int irtransid, String event)<br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
static void IOEvent(String id, String value)<br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
static void IOStartupEvent(int serverIndex)<br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)<br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
static String httpCallEvent(String address, boolean secure, String query)<br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)<br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
static void LocationEvent(long mac, InetAddress ip, int zoneId)<br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
static void SysLogEvent(String address, String log)<br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
static boolean PBXCallEvent(String host, String caller, String called)<br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
static void SlimPowerEvent(int index, int power)<br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
static void SlimStatusEvent(int index, int status)<br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
static void SlimVolumeEvent(int index, int volume)<br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
static boolean UserTimerEvent(String name, boolean active)<br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
static void pageEvent(String address, String session, String userid, String project, String page)<br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
static void loginEvent(String address, String session, String userid)<br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
static void logoutEvent(String address, String session, String userid, boolean lock)<br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
static void uiClearEvent(String session)<br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
static String userCommand(String name, String param)<br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
static String userCommand(String session, String userid, String name, String param)<br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userSubmit ===<br />
<br />
static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)<br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)<br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Java_Callback_Methods_API&diff=8905Java Callback Methods API2020-08-31T11:41:16Z<p>Gionatan: /* userCommand */</p>
<hr />
<div>[[Category:Java]]<br />
Callback methods are called by the HSYCO events management system.<br />
<br />
By implementing these methods, you can associate your custom Java code to each event.<br />
<br />
In some cases, the return values of these methods can influence the behavior of HSYCO.<br />
<br />
Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.<br />
<br />
== System Functions ==<br />
<br />
=== DaylightEvent ===<br />
<br />
static void DaylightEvent(boolean day)<br />
<br />
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.<br />
<br />
<br />
'''Parameters:'''<br />
* day: boolean - true at sunrise, false at sunset.<br />
<br />
=== getUserVersion ===<br />
<br />
static String getUserVersion()<br />
<br />
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup.<br />
<br />
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.<br />
<br />
<br />
'''Returns:'''<br />
* String - user code version information.<br />
<br />
<br />
=== haActiveEvent ===<br />
<br />
static void haActiveEvent(boolean active)<br />
<br />
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.<br />
<br />
<br />
'''Parameters:'''<br />
* active: boolean - true if the server is active, false if not active.<br />
<br />
=== PowerEvent ===<br />
<br />
static int PowerEvent(int power)<br />
<br />
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.<br />
<br />
Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.<br />
<br />
<br />
'''Parameters:'''<br />
* power: int - the power level, in Watts.<br />
<br />
<br />
'''Returns:'''<br />
* int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.<br />
<br />
=== programTimerEvent ===<br />
<br />
static void programTimerEvent(String name)<br />
<br />
Called when a program timer is activated.<br />
<br />
Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - program timer name.<br />
<br />
=== SchedulerEvent ===<br />
<br />
static void SchedulerEvent(String groupname, String schedulename)<br />
<br />
This callback blocking method allows to call user methods at configurable intervals.<br />
<br />
Schedules are defined using a group name and a schedule name.<br />
<br />
Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.<br />
<br />
<br />
'''Parameters:'''<br />
* groupname: String - the scheduler’s group name<br />
* schedulename: String - the scheduler’s name.<br />
<br />
=== StartupEvent ===<br />
<br />
static void StartupEvent()<br />
<br />
Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.<br />
<br />
=== SunPositionEvent ===<br />
<br />
static void SunPositionEvent(int azimuth, int elevation)<br />
<br />
Called when the Sun changes its height with respect to the horizon or its angle from true north.<br />
<br />
<br />
'''Parameters:'''<br />
*azimuth: int - the current Sun angle from true north, in decimal degrees<br />
*elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.<br />
<br />
=== TimeEvent ===<br />
<br />
static void TimeEvent(long time)<br />
<br />
Called every 60 seconds.<br />
<br />
HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.<br />
<br />
{{tip|However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.}}<br />
<br />
<br />
'''Parameters:'''<br />
* time: long - the current time in milliseconds.<br />
<br />
=== varEvent ===<br />
<br />
static void varEvent(String name, String value)<br />
<br />
Triggered by the change of value of a program variable.<br />
<br />
<br />
'''Parameters:'''<br />
* name: String - the variable name. Names are case-insensitive<br />
* value: String - the value to be assigned to the program variable.<br />
<br />
== Cameras ==<br />
<br />
=== CameraCommandEvent ===<br />
<br />
static int cameraCommandEvent(String function, String action, String camera)<br />
<br />
Triggered by a camera control input from the Web interface.<br />
<br />
It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* function: String - see the table below<br />
* action: String - see the table below<br />
* camera: String - the camera name.<br />
<br />
<br />
'''Returns:'''<br />
* int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.<br />
<br />
{{ui_camerapanel_ptz_table}}<br />
<br />
=== CameraMotionEvent ===<br />
<br />
static void CameraMotionEvent(String eventName, long remoteTime)<br />
<br />
Called when HSYCO starts recording video from a camera.<br />
<br />
Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):<br />
<br />
'''<nowiki>http://192.168.0.50/x/camerarec?camera=name&zone=id</nowiki>'''<br />
<br />
Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter<br />
* remoteTime: long - the current time in milliseconds.<br />
<br />
=== CameraViewEvent ===<br />
<br />
static void CameraViewEvent(String camera, boolean active)<br />
<br />
CameraViewEvent() is called on changes of the live view status of cameras.<br />
<br />
When at least one web client is showing the live feed from a camera, the camera is marked as active.<br />
<br />
When no live feed request is received for a several consecutive seconds, the camera is marked as not active.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* camera: String - the camera name<br />
* active: boolean - true if active, false if not.<br />
<br />
== DMX ==<br />
<br />
=== DmxEvent ===<br />
<br />
static void DmxEvent(int channel, int state)<br />
<br />
Called after changes to DMX-512 channels.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the new channel value, from 0 to 255.<br />
<br />
=== DmxFilter ===<br />
<br />
static int DmxFilter(int channel, int state, boolean reverse)<br />
<br />
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.<br />
<br />
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.<br />
<br />
{{tip|This is a blocking method and is called when sending commands to the DMX gateway.}}<br />
<br />
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0<br />
* state: int - the unfiltered value of the channel, from 0 to 255<br />
* reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* int - the channel value that will be sent to the DMX gateway.<br />
<br />
{{tip|The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.}}<br />
<br />
=== DmxStartupEvent ===<br />
<br />
static void DmxStartupEvent(int serverIndex)<br />
<br />
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.<br />
<br />
It is safe, inside this method, to execute command methods for the same DMX gateway.<br />
<br />
{{tip|This is a blocking method. The DMX driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - number of the DMX bus, starting from 0.<br />
<br />
== Infrared Control ==<br />
<br />
=== IREvent ===<br />
<br />
static void IREvent(boolean received, int irtransid, String event)<br />
<br />
This method is called when an IRTrans receives or sends an IR command from its local IR database.<br />
<br />
{{tip|IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* received: boolean - true if the command has been received by the IRTrans, false if sent<br />
* irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini<br />
* event: String - the string of the command received or issued, formatted as: "remote_name,command".<br />
<br />
== I/O Servers ==<br />
<br />
=== IOEvent ===<br />
<br />
static void IOEvent(String id, String value)<br />
<br />
Triggered by the value change of any data point of an I/O server.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system<br />
* value: String - the new value. For binary inputs or outputs, the returned values are “0” or “1”.<br />
<br />
=== IOStartupEvent ===<br />
<br />
static void IOStartupEvent(int serverIndex)<br />
<br />
Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.<br />
<br />
{{tip|This is a blocking method. The I/O server driver will start after this function returns.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.<br />
<br />
== Modbus ==<br />
<br />
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]<br />
<br />
<br />
=== ModbusEvent ===<br />
<br />
static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)<br />
<br />
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.<br />
<br />
The returned byte array is used as the Modbus response PDU (function code and data).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name of the Modbus Server I/O server<br />
* addr: InetAddress - IP address of the Modbus client<br />
* unitid: int - the unit id set in the received Modbus request<br />
* pdu: byte[] - the request PDU data, in hexadecimal string format.<br />
<br />
'''Returns:'''<br />
<br />
* byte[] - the response PDU data.<br />
<br />
== Network Services ==<br />
<br />
=== httpCallEvent ===<br />
<br />
static String httpCallEvent(String address, boolean secure, String query)<br />
<br />
Called when the HSYCO HTTP server receives a GET request with the following path:<br />
/x/httpcall?query<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS}}<br />
<br />
This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).<br />
<br />
HSYCO will return a 404 Not Found response code if all of the following conditions are true:<br />
* no HTTP event matches the query in EVENTS<br />
* the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value<br />
* the httpCallEvent Java callback is not defined in user.java or in any plugins, or returns null.<br />
<br />
If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* query: String - the string following the ? in the URL path.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - the string to send as the text/plain answer to the HTTP client.<br />
<br />
=== httpRawEvent ===<br />
<br />
static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)<br />
<br />
Called when the HSYCO HTTP server receives a GET or POST request with the following path:<br />
/x/raw<br />
<br />
{{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}}<br />
<br />
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.<br />
<br />
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the HTTP client<br />
* secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server<br />
* version: String - the HTTP version, as passed in the HTTP request header<br />
* httpmethod: String - the HTTP request's method, "GET", "POST" or "HEAD"<br />
* gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")<br />
* contenttype: String - the HTTP request's content type (value of Content-Type header)<br />
* query: String - the string following the ? in the URL path, or null if not present<br />
* session: String - the authenticated session id, or null<br />
* userid: String - the user id for requests having a valid authentication cookie, null otherwise<br />
* out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response<br />
* in: BufferedInputStream - the input stream that the application code should read to retrieve the POST data, or null for GET or HEAD requests.<br />
<br />
<br />
'''Example:'''<br />
<br />
public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {<br />
Writer w = new OutputStreamWriter(out, "UTF-8");<br />
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);<br />
<br />
if (httpmethod.equals("POST")) {<br />
byte[] bb = new byte[1024];<br />
int i = 0;<br />
StringBuffer sb = new StringBuffer();<br />
while((i = in.read(bb)) != -1) {<br />
sb.append(new String(bb, 0, i, "UTF-8"));<br />
}<br />
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";<br />
w.write(version);<br />
w.write(" 200 OK\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + content.length() + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.write(content);<br />
w.flush();<br />
} else {<br />
w.write(version);<br />
w.write(" 400 Not Found\r\n");<br />
w.write("Date: " + dateFormat.format(new Date()) + "\r\n");<br />
w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");<br />
w.write("Content-length: " + 0 + "\r\n");<br />
w.write("Content-type: text/plain\r\n");<br />
w.write("Cache-Control: no-store, no-cache\r\n\r\n");<br />
w.flush();<br />
}<br />
}<br />
<br />
=== LocationEvent ===<br />
<br />
static void LocationEvent(long mac, InetAddress ip, int zoneId)<br />
<br />
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* mac: long - the MAC address of the client<br />
* ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)<br />
* zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.<br />
<br />
=== SysLogEvent ===<br />
<br />
static void SysLogEvent(String address, String log)<br />
<br />
Called when the HSYCO SYSLOG server receives a log message from a network client.<br />
<br />
Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the IP address of the SYSLOG client<br />
* log: String - SYSLOG log message.<br />
<br />
== PBX ==<br />
<br />
=== PBXCallEvent ===<br />
<br />
static boolean PBXCallEvent(String host, String caller, String called)<br />
<br />
Called when a call notification is sent to HSYCO by the PBX system.<br />
<br />
If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.<br />
<br />
The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki><br />
<br />
or:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki><br />
<br />
For example, the HTTP request:<br />
<br />
<nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki><br />
<br />
is interpreted as a call notification from internal number 21 to number 25.<br />
<br />
{{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}}<br />
<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* host: String - the IP address of the PBX server <br />
* caller: String - the caller number<br />
* called: String - the called number.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.<br />
<br />
== Squeezebox ==<br />
<br />
=== SlimPowerEvent ===<br />
<br />
static void SlimPowerEvent(int index, int power)<br />
<br />
Called when a Squeezebox player is turned on or off.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* power: int - 0: OFF, 1: ON.<br />
<br />
=== SlimStatusEvent ===<br />
<br />
static void SlimStatusEvent(int index, int status)<br />
<br />
Called when a Squeezebox player changes its playback mode.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.<br />
<br />
=== SlimVolumeEvent ===<br />
<br />
static void SlimVolumeEvent(int index, int volume)<br />
<br />
Called when a Squeezebox player changes its volume level.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini<br />
* volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.<br />
<br />
== Timers and Schedulers ==<br />
<br />
=== UserTimerEvent ===<br />
<br />
static boolean UserTimerEvent(String name, boolean active)<br />
<br />
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.<br />
<br />
It is also executed at the timer or scheduler’s rule deactivation.<br />
<br />
This method must return a true value in order to make the timer or rule actually active and the associated actions executed.<br />
<br />
Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.<br />
<br />
In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.<br />
<br />
This is a blocking method.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - timer name or scheduler’s rule name<br />
* active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* boolean - true to confirm the timer event, false to block the event.<br />
<br />
<br />
{{tip|The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.}}<br />
<br />
== User Interface ==<br />
<br />
=== pageEvent ===<br />
<br />
static void pageEvent(String address, String session, String userid, String project, String page)<br />
<br />
Called when a Web client initially loads a project and when navigating between pages.<br />
<br />
There is no guarantee that the event would be fired the exact moment the page is loaded.<br />
<br />
Network delays or errors could cause delayed triggering of this event.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* project: String - project’s id<br />
* page: String - the page id of the current page.<br />
<br />
=== loginEvent ===<br />
<br />
static void loginEvent(String address, String session, String userid)<br />
<br />
Called when a user authenticates with a valid PIN or PIN/PUK.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id.<br />
<br />
=== logoutEvent ===<br />
<br />
static void logoutEvent(String address, String session, String userid, boolean lock)<br />
<br />
Called when a user logs out or locks the user interface.<br />
<br />
Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* address: String - the client’s IP address string in textual presentation<br />
* session: String - session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* lock: boolean - false when logging out; true when the user locks the user interface.<br />
<br />
=== uiClearEvent ===<br />
<br />
static void uiClearEvent(String session)<br />
<br />
Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - session id string that uniquely identifies the client session.<br />
<br />
=== userCommand ===<br />
<br />
static String userCommand(String name, String param)<br />
<br />
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details).<br />
<br />
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
<br />
=== userCommand - with session information ===<br />
<br />
static String userCommand(String session, String userid, String name, String param)<br />
<br />
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: string - a session id string that uniquely identifies the client session<br />
* userid: string - the user id<br />
* name: String - the name field of the (user) object<br />
* param: String - the param of the (user) object.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
<br />
=== userSubmit ===<br />
<br />
static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)<br />
<br />
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java.<br />
<br />
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.<br />
<br />
userSubmit() provides a more convenient access to the values of multiple input fields in a form.<br />
<br />
This function can optionally return a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.<br />
<br />
{{userCommand return values}}<br />
<br />
{{tip|As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* session: String - a session id string that uniquely identifies the client session<br />
* userid: String - the user id<br />
* name: String - the id of the (submit!id) object<br />
* fields: HashMap<String, String> - the hash map of all input fields in the container where the (submit) object is located.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - log or go to page, see text above. If this function doesn't return a value, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.<br />
<br />
=== WebRootRequestEvent ===<br />
<br />
static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)<br />
<br />
This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.<br />
<br />
{{tip|As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.}}<br />
<br />
<br />
'''Parameters:'''<br />
<br />
* addr: InetAddress - the HTTP client’s address<br />
* secure: boolean - true if this is an HTTPS request<br />
* useragent: String - the Web browser’s user agent information.<br />
<br />
<br />
'''Returns:'''<br />
<br />
* String - optional return string containing a valid absolute or relative URL</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Template:UserCommand_return_values&diff=8904Template:UserCommand return values2020-08-31T11:39:14Z<p>Gionatan: </p>
<hr />
<div>If you want to navigate to a specific page when the button is pressed (it would be like pressing a [[Link|Link object]]), return a string starting with "page:" followed by the page name; in this case, userCommand() will be called again when that popup or page is closed, with "/close" appended to param.<br />
<br />
You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.<br />
<br />
When the interface is loaded inside the HSYCO App ([[HSYCO_App_for_iOS_Devices|iOS]] or [[HSYCO_App_for_Android_Devices|Android]]), you can send a specific command to the app by returning a string that starts with “app:“ followed by the command; the commands currently supported are “speech“, which enables the speech recognition, and “codescan“ which enables qr/bar code scanning.<br />
<br />
Use "copy:<text>" to copy a text in the clipboard.<br />
In the HSYCO App you can also use "share:<text>" to open a popup with various options. This will behave like "copy" on browser.</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=Client_JavaScript_Extension_API&diff=8903Client JavaScript Extension API2020-08-31T11:34:06Z<p>Gionatan: /* userCommand */</p>
<hr />
<div>[[Category:INCOMPLETE]]<br />
[[Category:Advanced Programming]]<br />
<div style="color:#CC0000">'''{{Note|<center>WARNING! The client-side JavaScript extensions API is experimental and subject to changes.</center>}}'''<br />
</div><br />
<br />
A project can have specific javascript code that runs on the client-side and manages various events. This code has to be written in an index.js file located inside the project's directory.<br />
<br />
== Events ==<br />
These are functions executed on specific events.<br />
<br />
=== StartupEvent ===<br />
<syntaxhighlight lang="javascript"><br />
function StartupEvent()<br />
</syntaxhighlight><br />
<br />
Executed when the interface is first loaded.<br />
It's a good place to set up the interface and set variables, for example.<br />
<br />
=== userCommand ===<br />
<syntaxhighlight lang="javascript"><br />
function userCommand(name, param)<br />
</syntaxhighlight><br />
<br />
Called by user clicks on user buttons: [[User]], [[UserMini]], [[UserMicro]], [[UserRGB]] or [[UserImage]] objects.<br />
<br />
{{userCommand return values}}<br />
<br />
'''Parameters:'''<br />
<br />
* name: string - the name field of the user object<br />
* param: string - the param of the user object<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: proceed to send the request to server as it is<br />
* "": assume the event was resolved. Don't send the request to the server<br />
* "page:page name": navigate to the specified page<br />
* "page:back": navigate to the previous page<br />
* "page:forward": navigate to the next page<br />
* "page:close": if the user button that generated the call has an open popup linked to it, close it<br />
* "error": error. Don't send the request to the server<br />
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.<br />
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.<br />
* an object, to specify new name and param values to be sent to the server<br />
<syntaxhighlight lang="javascript"><br />
{name:"new name", param:"new param"}<br />
</syntaxhighlight><br />
<br />
=== userSubmit ===<br />
<syntaxhighlight lang="javascript"><br />
function userSubmit(name, param)<br />
</syntaxhighlight><br />
Called on every submit request (from [[Submit]] objects).<br />
Parameters and return values are the same as the userCommand function.<br />
<br />
=== uiEvent ===<br />
<syntaxhighlight lang="javascript"><br />
function uiEvent(id, attr, value)<br />
</syntaxhighlight><br />
Executed on every UISet received from the server, intercepts a UISet and allows to change it, prevent its execution or execute any other custom code (e.g. set variables).<br />
<br />
'''Parameters:'''<br />
<br />
* id: string - id of the ui object<br />
* attr: string - attribute name<br />
* value: string - new value being set<br />
<br />
<br />
'''Returns:'''<br />
<br />
* null: discard the UISet<br />
* <string>: set a new value for the UISet. To keep the UISet as it is, return the initial value<br />
<br />
=== pageOpenEvent ===<br />
<syntaxhighlight lang="javascript"><br />
function pageOpenEvent(name)<br />
</syntaxhighlight><br />
<br />
Called when a page is opened.<br />
<br />
'''Parameters:'''<br />
<br />
* name: string - the page's id<br />
<br />
'''Returns:'''<br />
<br />
* false: don't open the page. A ''pageOpenEvent'' is called on the previous page, as if it was reopened.<br />
* null: proceed to open the page<br />
<br />
<syntaxhighlight lang="javascript"><br />
// page open event<br />
function pageOpenEvent(name) {<br />
console.log("opening "+name);<br />
if (name =="wconfig") {<br />
console.log("nope 1");<br />
return false;<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
=== pageCloseEvent ===<br />
<syntaxhighlight lang="javascript"><br />
function pageCloseEvent(name)<br />
</syntaxhighlight><br />
<br />
Called when a page is closed.<br />
<br />
'''Parameters:'''<br />
<br />
* name: string - the page's id<br />
<br />
'''Returns:'''<br />
<br />
* false: don't close the page<br />
* null: proceed to close the page<br />
<br />
<syntaxhighlight lang="javascript"><br />
// page close event<br />
function pageCloseEvent(name) {<br />
console.log("closing "+name);<br />
if (name =="sconfig") {<br />
console.log("nope 2");<br />
return false;<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
=== pageBackEvent ===<br />
<syntaxhighlight lang="javascript"><br />
function pageBackEvent(name)<br />
</syntaxhighlight><br />
<br />
Called when a page back is requested.<br />
<br />
'''Parameters:'''<br />
<br />
* name: string - the page's id<br />
<br />
'''Returns:'''<br />
<br />
* false: don't close the page<br />
* null: proceed to close the page<br />
<br />
<syntaxhighlight lang="javascript"><br />
// page back event<br />
function pageBackEvent(name) {<br />
console.log("backing from "+name);<br />
if (name =="sconfig") {<br />
console.log("nope 3");<br />
return false;<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
== Functions ==<br />
=== varSet ===<br />
<syntaxhighlight lang="javascript"><br />
varSet(name,value)<br />
</syntaxhighlight><br />
Sets the value of a variable. If the name begins with '''!''', the variable will be stored in the browser's cache, so that it'll available even after reloading the page or closing and reopening the browser.<br />
<br />
=== varGet ===<br />
<syntaxhighlight lang="javascript"><br />
varGet(name)<br />
</syntaxhighlight><br />
Gets the value of a variable previously set with varSet.<br />
<br />
=== uiSet ===<br />
<syntaxhighlight lang="javascript"><br />
uiSet(id,attr,value)<br />
</syntaxhighlight><br />
Sets a UI Attribute. See [[Project]], [[Page]] or [[UI Objects]] list of attributes.<br />
<br />
=== webLog ===<br />
<syntaxhighlight lang="javascript"><br />
webLog(string)<br />
</syntaxhighlight><br />
Adds a line to the daily log file, viewable from the Manager's [[Log Viewer]].<br />
<br />
== Examples ==<br />
=== Using varget and varset ===<br />
In this example we declare a persistent variable (stored in the browser's local storage) the first time any user button is pressed, we increment it each time up to 10 and then we reset it to 0. When the variable equals 3, the page "page1" is shown. When the variable equals 7, the request isn't forwarded to the server.<br />
<syntaxhighlight lang="javascript"><br />
function userCommand(name, param) {<br />
var a = varGet("!counter"); // get the variable value<br />
<br />
if (!a) // first time and when a is 0<br />
a = 1;<br />
else if (a < 10)<br />
a++;<br />
else // reset<br />
a = 0;<br />
<br />
varSet("!counter",a); // set the variable value<br />
<br />
webLog("usercommand:"+name+","+param+". Counter:"+a)<br />
if (a == 3)<br />
return "page:page1";<br />
else if (a == 7)<br />
return "";<br />
else<br />
return null;<br />
}<br />
</syntaxhighlight><br />
<br />
== User Object ==<br />
One or more User objects can be declared to send requests from the client to the server.<br />
<br />
<syntaxhighlight lang="javascript"><br />
var user = new User(); <br />
<br />
function StartupEvent() { <br />
user.setOnLoadedEvent(onUserLoaded);<br />
user.setOnErrorEvent(onUserError);<br />
// send reques<br />
user.send("myname","myparam");<br />
<br />
varSet("myvar1","myvalue");<br />
varSet("myvar2",5.3);<br />
varSet("myvar3",[1,2,3]);<br />
varSet("myvar4",{"a":1,"b":2});<br />
}<br />
</syntaxhighlight><br />
<br />
===Methods===<br />
====.send(name, param)====<br />
sends a virtualremote (name and param will be url encoded)<br />
<br />
====.setMaxWaitingTime(msec)====<br />
set max waiting time in msec. If a request exceeds this time, it will be aborted (and fire an onError event, if set).<br />
<br />
====.setMaxRetries(n)====<br />
set max number of retry attempts. If a a request fails, it will keep on retrying until it succeeds or the max number of retries is reached.<br />
Before retrying it will fire an onRetry event, if set.<br />
If n is 0, and retryOnErrorDelay is not 0, it will keep on retrying forever (it will never fire an onError event, if set).<br />
<br />
====.setRetryOnErrorDelay(msec)====<br />
set msec of delay before retrying after a request has failed.<br />
If msec is 0 it won't retry (and will fire an onError event, if set).<br />
<br />
====.setOnLoadedEvent(f)====<br />
f is a function that is called when the request is successful.<br />
To get the response text or xml, use .getResponseText() and .getResponseXML()<br />
<br />
====.setOnErrorEvent(f)====<br />
f is a function called when the request fails. f is called with an error code parameter: function(errCode)<br />
error codes are enumerated as .ERROR_GENERAL, .ERROR_CONNECTION ...<br />
<br />
====.setOnRetryEvent(f)====<br />
f is a function that is called when the last request failed, before retrying.<br />
To get the response text or xml, use .getResponseText() and .getResponseXML()<br />
<br />
====.getResponseText()====<br />
get the last response text<br />
<br />
====.getResponseXML()====<br />
get the last response XML<br />
<br />
====.free()====<br />
free the memory and reset the behaviour. It will be reinitialized if any method is called.<br />
<br />
===Error codes===<br />
*'''.ERROR_GENERAL''' : general error<br />
*'''.ERROR_CONNECTION''' : no connection<br />
*'''.ERROR_MAXWAITTIME''' : max waiting time exceeded<br />
*'''.ERROR_LOGOUT''' : client is logged out<br />
*'''.ERROR_LOCK''' : client is locked out<br />
*'''.ERROR_NOACCESS''' : request returned noaccess<br />
<br />
===Examples===<br />
====Try one time, then fire onLoaded or onError====<br />
<syntaxhighlight lang="javascript"><br />
var user = new User();<br />
<br />
function StartupEvent() {<br />
user.setOnLoadedEvent(onUserLoaded);<br />
user.setOnError(onUserError);<br />
// send request<br />
user.send("myname","myparam");<br />
}<br />
<br />
function onUserLoaded() {<br />
webLog("loaded "+user.getResponseText());<br />
// do something with the response<br />
user.free(); // won't be using it again<br />
}<br />
function onUserError(errCode) {<br />
webLog("error");<br />
user.free(); // won't be using it again<br />
}<br />
</syntaxhighlight><br />
<br />
====Retry forever, until it succeeds====<br />
<syntaxhighlight lang="javascript"><br />
var user = new User(); <br />
<br />
function StartupEvent() {<br />
user.setOnLoadedEvent(onUserLoaded);<br />
user.setRetryOnErrorDelay(1000); // wait one second before retrying on error<br />
// send request<br />
user.send("myname","myparam");<br />
}<br />
<br />
function onUserLoaded() {<br />
webLog("loaded "+user.getResponseText());<br />
// do something with the response<br />
user.free(); // won't be using it again<br />
}<br />
</syntaxhighlight><br />
<br />
====Retry 3 times, then fire onError====<br />
<br />
<syntaxhighlight lang="javascript"><br />
var user = new User(); <br />
<br />
function StartupEvent() {<br />
// init user object<br />
user.setRetryOnErrorDelay(100); // retry almost immediately on error<br />
user.setMaxRetries(3); // retry 3 times, then fire error<br />
user.setOnLoadedEvent(onUserLoaded);<br />
user.setOnError(onUserError);<br />
// send request<br />
user.send("myname","myparam");<br />
}<br />
<br />
function onUserLoaded() {<br />
webLog("loaded "+user.getResponseText());<br />
// do something with the response<br />
user.free(); // won't be using it again<br />
}<br />
<br />
function onUserError(errCode) {<br />
webLog("error, already tried 3 times");<br />
if (errCode == user.ERROR_MAXWAITTIME)<br />
webLog("the last request failed because it exceeded the waiting time");<br />
user.free(); // won't be using it again<br />
}<br />
</syntaxhighlight></div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=HSYCO_App_for_iOS_Devices&diff=8857HSYCO App for iOS Devices2020-07-02T16:38:46Z<p>Gionatan: </p>
<hr />
<div>{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Menu.png|l1=Right menu|w2=150|i2=HSYCO_iOS_FavPages.png|l2=Favorite pages}}<br />
<br />
<br />
HSYCO App is the offical HSYCO iOS application for iPhone, iPad and iPod touch that lets you easily connect to your HSYCO Server, in a more convenient way than traditional Web-based access.<br />
<br />
Its many features enrich and expand the HSYCO experience in many ways:<br />
<br />
* Multiple connections: you can easily setup connections and set your favourite ones to quickly switch between them.<br />
<br />
* Connection setup: customize your connection to your needs with kiosk mode, lock rotation, scale, speech recognition and bar scanner tool. Manage the certificate and saved pin/puk.<br />
<br />
* Export/Import connections: save and restore all your connections with a password-protected file.<br />
<br />
* Authentication: if you wish so, the app handles the PIN/PUK credentials of all your connections automatically, adding a layer of protection with a global password and integrating Touch and Face ID.<br />
<br />
* App Links: share and import connections and send custom user commands with Universal Links that can also be embedded in QR Codes and NFC Tags.<br />
<br />
* Speech Recognition: send vocal commands to the server.<br />
<br />
* QR and Bar code scanning: scan QR and bar codes from your connection, to process app links or send the data directly to the server.<br />
<br />
* Beacons: enable beacon monitoring, to gather data on the device's location.<br />
<br />
* Apple Watch: each connection with a specific Apple Watch interface will be ready for you, on your wrist.<br />
<br />
<br />
{{note|<center>HSYCO App requires iOS 9.3 or later, and HSYCO Server 3.6. The latest features are only available on iOS 13.0 and HSYCO Server 3.7</center>}}<br />
<br />
{{Clear}}<br />
To download the HSYCO App, go to your Apple App Store and enter HSYCO in the search box, or click the App Store badge below.<br />
<br />
<br />
<center>[[File:Download_on_the_App_Store_Badge_US-UK_135x40.png|135x40px|link=https://itunes.apple.com/app/hsyco/id1038105480]]</center><br />
<br />
<br />
<br />
==Connections==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connections_edit.png|l1=Connection list|w2=150|i2=HSYCO_iOS_Connections.png|l2=Editing the connection list}}<br />
<br />
The first time the app is opened, it will automatically add a new connection and show its configuration page.<br />
The connection can be edited from the Connections page, by pressing the Edit button and selecting the connection. From the edit mode it's also possible to add more connections, clicking on Add Connection or the + icon on the bottom, or change the connections' order by dragging vertically the right-most icon.<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connection_edit_1.png|l1=Connection settings|w2=150|i2=HSYCO_iOS_Connection_edit_2.png|l2=More settings}}<br />
<br />
A connection has the following fields:<br />
* '''Name''': the name that will be displayed.<br />
* '''URL''': the URL to access your project on your HSYCO server. If you have a default project on your server, and use a standard port for the HTTPS connection, you can simply enter the DNS name for your server, without the URL key and project name.<br />
* '''Remember PIN/PUK''': if on, it will store the connection's PIN and PUK the first time they're correctly entered. It will then show a "Forget PIN/PUK" option. It has to be enabled to use the Apple Watch interface.<br />
* '''Kiosk Mode''': enables the [[Project#Kiosk|Kiosk Mode]], which removes some elements in the project's interface<br />
* '''Favorite''': if enabled, it will show the connection in the left menu of the app, or in the Home Screen Quick Actions popup that appears when you long-press the app icon.<br />
* '''Lock Rotation''': lock the interface in portrait or landscape mode, ignoring the device's orientation<br />
* '''Scale''': set the interface [[Project#Scale|scale mode]].<br />
* '''[[#Speech Recognition|Speech Recognition]]''': enables speech input on the connection. A specific language has to be selected. A button will appear in the top right corner when opening the connection. Speech is recognized and sent as a command to the HSYCO server. Speech recognition is available from iOS 10.<br />
* '''Monitor Beacons''': if enabled it will monitor beacons and send data to the HSYCO server.<br />
* '''[[#QR.2FBar_code_scanning|QR/Bar Code Scanner]]''': if enabled, it will show a button in the top right corner when opening the connection. Pressing the button opens up the device's camera, to scan and process a barcode or QR code.<br />
* '''Download Certificate''': to enable HTML5 cache the certificate needs to be downloaded and installed on the device.<br />
* '''[[#App Link Tool|App Link Tool]]''': opens a tool to create and share app links <br />
* '''Delete Connection''': permanently deletes the connection<br />
{{Clear}}<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connection_scale.png|l1=Scale setting|w2=150|i2=HSYCO_iOS_Connection_certificate.png|l2=Certificate pinning}}<br />
<br />
If your server has an SSL certificate for HTTPS encryption, the first time you open the connection a prompt will be shown to allow you to accept the certificate and save it within the app. This prompt will appear again if the certificate changes, serving as a protection against “Man in the Middle” (MiTM) attacks.<br />
<br />
{{Clear}}<br />
<br />
==Settings==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_App_Settings_1.png|l1=Settings list|w2=150|i2=HSYCO_App_Settings_2.png|l2=Ask password}}<br />
<br />
These are general app settings:<br />
* '''Ask Password''': if enabled, it will password-protect the app by showing a lock screen. The following options are visible once enabled.<br />
** '''Change Password''': change the current password. If already set you need to specify the old password.<br />
** '''Lock Now''': lock the device now, booting you out immediately to the lock screen<br />
** '''Use FaceID/TouchID''': enables unlocking the app through FaceID and TouchID (it's visible only if the device supports it)<br />
** '''Lock On Exit''': lock the app when it's put in the background or the device's screen is switched off.<br />
** '''Auto-Lock''': here you can set an amount of time after which the app is automatically locked.<br />
* '''Clear Cache''': clears the cache for all the connections.<br />
* '''Reset Settings''': restores all the app's settings to default and '''deletes all connections'''.<br />
*'''Hide Status Bar in Portrait''': if enabled, the app's top status bar (displaying time, battery and signal indicators) will be hidden in portrait mode (it's always hidden in landscape mode).<br />
* '''Hide Navigation Bar in Landscape''': if enabled, hides the header in landscape mode<br />
* '''App Link Tool''': opens the [[#App Link Tool|App Link Tool]], to create App Links, Qr Codes and write NFC Tags.<br />
* If an Apple Watch is paired, two additional options will be available: <br />
** '''Reduce Button Feedback''': it disables sound and vibration when pressing buttons.<br />
** '''Reset Apple Watch''': resets the Apple Watch configuration. Once pressed, to see the connection page you need to open the connection again from the app.<br />
* '''Export/Import Configuration''': saves or restores settings and connections to a password-protected file. Importing a configuration will replace the current settings and list of connections.<br />
{{Clear}}<br />
<br />
==App Link Tool==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_App_App_Link_Tool_1.png|l1=App Link Tool|w2=150|i2=HSYCO_App_App_Link_Tool_2.png|l2=QR Code}}<br />
<br />
The HSYCO App Link generates links that can be used to quickly add a connection to the app, to send a custom user command to the HSYCO server or both. If the device doesn't have the HSYCO App installed, a website will be opened instead, with links to download the app.<br />
Links can be embedded in QR Codes or in NFC Tags.<br />
<br />
QR Codes are automatically scanned by the default iOS camera app, while NFC Tags are automatically scanned by bringing the device near to the tag when the screen is on (only available on devices that support background tag reading: iPhone XS and later).<br />
<br />
The App Link Tool has the following options:<br />
* '''Connection''': if specified, it will bind the link to a specific connection. This link will create the connection if no other connections with the same URL are already configured in the app.<br />
* '''Embed Configuration''': if enabled, it will embed the main configuration settings: name, kiosk mode, scale, lock rotation, speech and qr/bar code scanner. Pin and puk won't be embedded.<br />
* '''Send a command''': if enabled, it will automatically send a command when the connection is open. If no connection was specified in the previous options:<br />
** if a connection is currently open it will send the command immediately<br />
** if no connection is open (app is closed or on a different page) and there's only one connection in the connection list, it will open it and then send the command<br />
<br />
A description of what the link does is displayed above the following options:<br />
* '''Link''': share the link (sharing allows you to copy it, send it to your contacts, send it through email, save it to files etc.)<br />
* '''QR Code''': open up the QR Code tool to display, customize and share the code.<br />
* '''NFC Tag''': shows two options<br />
** Write: write the NFC Tag by bringing your device near the tag<br />
** Write Lock: write and lock the NFC Tag, if the tag supports locking. Once locked it, the data can't be changed anymore. This option is useful to prevent tampering.<br />
<br />
{{Clear}}<br />
<br />
==Speech Recognition==<br />
<br />
If the Speech Recognition option is enabled in the connection settings, when the connection is open and loaded, a speech icon [[File:HSYCO iOS.speech.png|18px]] will be displayed on the top right.<br />
Tapping it will open the speech recognition popup. When you stop speaking or press the OK button, the text will be sent to the HSYCO server's [[NLP#How_to_send_text_messages_to_the_NLP_engine|NLP engine]]. <br />
<br />
==QR/Bar code scanning==<br />
<br />
If the QR/Bar code scanning option is enabled in the connection settings, when the connection is open and loaded, a scan icon [[File:HSYCO iOS.code scan.png|18px]] will be displayed on the top right.<br />
Tapping on it the camera view will open up, allowing QR and bar code scanning.<br />
<br />
Just focus on a code of the supported type and it will be scanned.<br />
If the scanned code is a QR Code with an [[#App Link Tool|App Link]], it will be immediately processed.<br />
Otherwise the code will be sent to the HSYCO server as a user command with the following format:<br />
<pre><br />
name: "code:<code type>"<br />
param:"<scanned code>"<br />
</pre><br />
<br />
The currently supported code types are:<br />
qr, ean8, ean13, pdf417, dataMatrix, aztec, code128, code39, code39Mod43, code93, interleaved2of5, itf14, upce<br />
<br />
==Apple Watch==<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Watch_1.png|l1=Watch Page|w2=150|i2=HSYCO_iOS_Watch_2.png|l2=Camera example}}<br />
<br />
If one or more of your connections are associated with HSYCO projects configured with Apple Watch menus, you will automatically have them configured in the Apple Watch.<br />
<br />
If you change the Apple Watch menu in any project on HSYCO Server, simply open the corresponding connection in HSYCO Remote to load the new version. After this, next time you open HSYCO Remote on your Apple Watch, it will automatically show the updated command menu.<br />
<br />
You can create an Apple Watch page for a project:<br />
* visually, with the [[Project_Editor#Page_Types|Project Editor]], creating a page of type "watch page". For more information about it, see the [[Apple_Watch_Interface|Apple Watch Interface documentation]]<br />
* through a project's UISet to set the [[Project#HSYCO_App_Support|app_watch]] attribute<br />
<br />
==Beacons==<br />
(To be completed)</div>Gionatanhttps://wiki.hsyco.com/3.7/index.php?title=HSYCO_App_for_iOS_Devices&diff=8856HSYCO App for iOS Devices2020-07-02T12:03:42Z<p>Gionatan: /* Connections */</p>
<hr />
<div>{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Menu.png|l1=Right menu|w2=150|i2=HSYCO_iOS_FavPages.png|l2=Favorite pages}}<br />
<br />
<br />
HSYCO App is an iOS application for iPhone, iPad and iPod touch that lets you easily connect to your HSYCO Server, in a more convenient way than traditional Web-based access.<br />
<br />
Its many features enrich and expand the HSYCO experience in many ways:<br />
<br />
* Multiple connections: you can easily setup connections and set your favourite ones to quickly switch between them.<br />
<br />
* Connection setup: customize your connection to your needs with kiosk mode, lock rotation, scale, speech recognition and bar scanner tool. Manage the certificate and saved pin/puk.<br />
<br />
* Export/Import connections: save and restore all your connections with a password-protected file.<br />
<br />
* Authentication: if you wish so, the app handles the PIN/PUK credentials of all your connections automatically, adding a layer of protection with a global password and integrating Touch and Face ID.<br />
<br />
* App Links: share and import connections and send custom user commands with Universal Links that can also be embedded in QR Codes and NFC Tags.<br />
<br />
* Speech Recognition: send vocal commands to the server.<br />
<br />
* QR and Bar code scanning: scan QR and bar codes from your connection, to process app links or send the data directly to the server.<br />
<br />
* Beacons: enable beacon monitoring, to gather data on the device's location.<br />
<br />
* Apple Watch: each connection with a specific Apple Watch interface will be ready for you, on your wrist.<br />
<br />
<br />
{{note|<center>HSYCO App requires iOS 9.3 or later, and HSYCO Server 3.6. The latest features are only available on iOS 13.0 and HSYCO Server 3.7</center>}}<br />
<br />
{{Clear}}<br />
To download the HSYCO App, go to your Apple App Store and enter HSYCO in the search box, or click the App Store badge below.<br />
<br />
<br />
<center>[[File:Download_on_the_App_Store_Badge_US-UK_135x40.png|135x40px|link=https://itunes.apple.com/app/hsyco/id1038105480]]</center><br />
<br />
<br />
<br />
==Connections==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connections_edit.png|l1=Connection list|w2=150|i2=HSYCO_iOS_Connections.png|l2=Editing the connection list}}<br />
<br />
The first time the app is opened, it will automatically add a new connection and show its configuration page.<br />
The connection can be edited from the Connections page, by pressing the Edit button and selecting the connection. From the edit mode it's also possible to add more connections, clicking on Add Connection or the + icon on the bottom, or change the connections' order by dragging vertically the right-most icon.<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connection_edit_1.png|l1=Connection settings|w2=150|i2=HSYCO_iOS_Connection_edit_2.png|l2=More settings}}<br />
<br />
A connection has the following fields:<br />
* '''Name''': the name that will be displayed.<br />
* '''URL''': the URL to access your project on your HSYCO server. If you have a default project on your server, and use a standard port for the HTTPS connection, you can simply enter the DNS name for your server, without the URL key and project name.<br />
* '''Remember PIN/PUK''': if on, it will store the connection's PIN and PUK the first time they're correctly entered. It will then show a "Forget PIN/PUK" option. It has to be enabled to use the Apple Watch interface.<br />
* '''Kiosk Mode''': enables the [[Project#Kiosk|Kiosk Mode]], which removes some elements in the project's interface<br />
* '''Favorite''': if enabled, it will show the connection in the left menu of the app, or in the Home Screen Quick Actions popup that appears when you long-press the app icon.<br />
* '''Lock Rotation''': lock the interface in portrait or landscape mode, ignoring the device's orientation<br />
* '''Scale''': set the interface [[Project#Scale|scale mode]].<br />
* '''[[#Speech Recognition|Speech Recognition]]''': enables speech input on the connection. A specific language has to be selected. A button will appear in the top right corner when opening the connection. Speech is recognized and sent as a command to the HSYCO server. Speech recognition is available from iOS 10.<br />
* '''Monitor Beacons''': if enabled it will monitor beacons and send data to the HSYCO server.<br />
* '''[[#QR.2FBar_code_scanning|QR/Bar Code Scanner]]''': if enabled, it will show a button in the top right corner when opening the connection. Pressing the button opens up the device's camera, to scan and process a barcode or QR code.<br />
* '''Download Certificate''': to enable HTML5 cache the certificate needs to be downloaded and installed on the device.<br />
* '''[[#App Link Tool|App Link Tool]]''': opens a tool to create and share app links <br />
* '''Delete Connection''': permanently deletes the connection<br />
{{Clear}}<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Connection_scale.png|l1=Scale setting|w2=150|i2=HSYCO_iOS_Connection_certificate.png|l2=Certificate pinning}}<br />
<br />
If your server has an SSL certificate for HTTPS encryption, the first time you open the connection a prompt will be shown to allow you to accept the certificate and save it within the app. This prompt will appear again if the certificate changes, serving as a protection against “Man in the Middle” (MiTM) attacks.<br />
<br />
{{Clear}}<br />
<br />
==Settings==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_App_Settings_1.png|l1=Settings list|w2=150|i2=HSYCO_App_Settings_2.png|l2=Ask password}}<br />
<br />
These are general app settings:<br />
* '''Ask Password''': if enabled, it will password-protect the app by showing a lock screen. The following options are visible once enabled.<br />
** '''Change Password''': change the current password. If already set you need to specify the old password.<br />
** '''Lock Now''': lock the device now, booting you out immediately to the lock screen<br />
** '''Use FaceID/TouchID''': enables unlocking the app through FaceID and TouchID (it's visible only if the device supports it)<br />
** '''Lock On Exit''': lock the app when it's put in the background or the device's screen is switched off.<br />
** '''Auto-Lock''': here you can set an amount of time after which the app is automatically locked.<br />
* '''Clear Cache''': clears the cache for all the connections.<br />
* '''Reset Settings''': restores all the app's settings to default and '''deletes all connections'''.<br />
*'''Hide Status Bar in Portrait''': if enabled, the app's top status bar (displaying time, battery and signal indicators) will be hidden in portrait mode (it's always hidden in landscape mode).<br />
* '''Hide Navigation Bar in Landscape''': if enabled, hides the header in landscape mode<br />
* '''App Link Tool''': opens the [[#App Link Tool|App Link Tool]], to create App Links, Qr Codes and write NFC Tags.<br />
* If an Apple Watch is paired, two additional options will be available: <br />
** '''Reduce Button Feedback''': it disables sound and vibration when pressing buttons.<br />
** '''Reset Apple Watch''': resets the Apple Watch configuration. Once pressed, to see the connection page you need to open the connection again from the app.<br />
* '''Export/Import Configuration''': saves or restores settings and connections to a password-protected file. Importing a configuration will replace the current settings and list of connections.<br />
{{Clear}}<br />
<br />
==App Link Tool==<br />
<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_App_App_Link_Tool_1.png|l1=App Link Tool|w2=150|i2=HSYCO_App_App_Link_Tool_2.png|l2=QR Code}}<br />
<br />
The HSYCO App Link generates links that can be used to quickly add a connection to the app, to send a custom user command to the HSYCO server or both. If the device doesn't have the HSYCO App installed, a website will be opened instead, with links to download the app.<br />
Links can be embedded in QR Codes or in NFC Tags.<br />
<br />
QR Codes are automatically scanned by the default iOS camera app, while NFC Tags are automatically scanned by bringing the device near to the tag when the screen is on (only available on devices that support background tag reading: iPhone XS and later).<br />
<br />
The App Link Tool has the following options:<br />
* '''Connection''': if specified, it will bind the link to a specific connection. This link will create the connection if no other connections with the same URL are already configured in the app.<br />
* '''Embed Configuration''': if enabled, it will embed the main configuration settings: name, kiosk mode, scale, lock rotation, speech and qr/bar code scanner. Pin and puk won't be embedded.<br />
* '''Send a command''': if enabled, it will automatically send a command when the connection is open. If no connection was specified in the previous options:<br />
** if a connection is currently open it will send the command immediately<br />
** if no connection is open (app is closed or on a different page) and there's only one connection in the connection list, it will open it and then send the command<br />
<br />
A description of what the link does is displayed above the following options:<br />
* '''Link''': share the link (sharing allows you to copy it, send it to your contacts, send it through email, save it to files etc.)<br />
* '''QR Code''': open up the QR Code tool to display, customize and share the code.<br />
* '''NFC Tag''': shows two options<br />
** Write: write the NFC Tag by bringing your device near the tag<br />
** Write Lock: write and lock the NFC Tag, if the tag supports locking. Once locked it, the data can't be changed anymore. This option is useful to prevent tampering.<br />
<br />
{{Clear}}<br />
<br />
==Speech Recognition==<br />
<br />
If the Speech Recognition option is enabled in the connection settings, when the connection is open and loaded, a speech icon [[File:HSYCO iOS.speech.png|18px]] will be displayed on the top right.<br />
Tapping it will open the speech recognition popup. When you stop speaking or press the OK button, the text will be sent to the HSYCO server's [[NLP#How_to_send_text_messages_to_the_NLP_engine|NLP engine]]. <br />
<br />
==QR/Bar code scanning==<br />
<br />
If the QR/Bar code scanning option is enabled in the connection settings, when the connection is open and loaded, a scan icon [[File:HSYCO iOS.code scan.png|18px]] will be displayed on the top right.<br />
Tapping on it the camera view will open up, allowing QR and bar code scanning.<br />
<br />
Just focus on a code of the supported type and it will be scanned.<br />
If the scanned code is a QR Code with an [[#App Link Tool|App Link]], it will be immediately processed.<br />
Otherwise the code will be sent to the HSYCO server as a user command with the following format:<br />
<pre><br />
name: "code:<code type>"<br />
param:"<scanned code>"<br />
</pre><br />
<br />
The currently supported code types are:<br />
qr, ean8, ean13, pdf417, dataMatrix, aztec, code128, code39, code39Mod43, code93, interleaved2of5, itf14, upce<br />
<br />
==Apple Watch==<br />
{{Two Images on right|tw=340|m=5|w1=150|i1=HSYCO_iOS_Watch_1.png|l1=Watch Page|w2=150|i2=HSYCO_iOS_Watch_2.png|l2=Camera example}}<br />
<br />
If one or more of your connections are associated with HSYCO projects configured with Apple Watch menus, you will automatically have them configured in the Apple Watch.<br />
<br />
If you change the Apple Watch menu in any project on HSYCO Server, simply open the corresponding connection in HSYCO Remote to load the new version. After this, next time you open HSYCO Remote on your Apple Watch, it will automatically show the updated command menu.<br />
<br />
You can create an Apple Watch page for a project:<br />
* visually, with the [[Project_Editor#Page_Types|Project Editor]], creating a page of type "watch page". For more information about it, see the [[Apple_Watch_Interface|Apple Watch Interface documentation]]<br />
* through a project's UISet to set the [[Project#HSYCO_App_Support|app_watch]] attribute<br />
<br />
==Beacons==<br />
(To be completed)</div>Gionatan