Difference between revisions of "Installation Guide"

From HSYCO
Jump to navigation Jump to search
 
(71 intermediate revisions by 5 users not shown)
Line 1: Line 1:
HSYCO SERVER ships pre-installed with the latest version of the HSYCO software, on a Linux Ubuntu 12.04 LTS Server distribution stripped of all not-essential services.
+
[[Category:HSYCO]]
 +
HSYCO SERVER ships pre-installed with the latest version of the HSYCO software, on a Linux Debian 9 (Stretch) distribution stripped of all not-essential services.
  
The Oracle Java SE Runtime Environment version 7 is also installed. No other software is required.
+
The Oracle Java SE Runtime Environment version 8 is also installed. No other software is required.
  
  
[[File:Installation Server.png|center]]
+
Legacy HSYCO SERVER units had Linux Ubuntu 12.04 LTS Server and Oracle Java SE Runtime Environment version 7 installed.
 +
 
 +
 
 +
[[File:HSYCO-Pi-Strato.png|center|600px]]
  
  
Line 11: Line 15:
 
== Initial Set-Up ==
 
== Initial Set-Up ==
  
There are two standard hardware configurations, a compact server with one Ethernet port and one Serial port, and a larger, expandable server with two Ethernet ports and four serial ports.
+
HSYCO SERVER is available with different hardware configurations. Each version presents minor differences in its software configuration.
 +
 
 +
=== HSYCO PI - SFERA LABS STRATO PI SERVER ===
 +
[[File:Installation HSYCO Pi Connections.png|center|300px]]
 +
The standard version is installed on a [https://www.sferalabs.cc/strato-pi/ Strato Pi Base Server], with Raspberry Pi 3 Model B+ 1GB RAM  or Raspberry Pi 4 Model B with 2/4/8 GB RAM with and a 4GB SLC industrial microSD card with pre-installed software. The operating system is
 +
Raspbian Stretch Lite or Raspberry Pi OS depending on the Raspberry Pi version.
 +
 
 +
HSYCO Pi is also available installed on Strato Pi UPS, Strato Pi CM or CM Duo or Iono Pi server.
 +
 
 +
Links to the HSYCO PI Servers User Guides:
 +
 
 +
https://www.sferalabs.cc/files/strato/doc/stratopi-base-user-guide.pdf
  
[[File:Installation ARK1122.png|center]]
+
https://www.sferalabs.cc/files/strato/doc/stratopi-ups-user-guide.pdf
  
 +
https://www.sferalabs.cc/files/strato/doc/stratopi-cm-user-guide.pdf
  
[[File:Installation ARK2120.png|center]]
+
https://www.sferalabs.cc/files/strato/doc/stratopi-cmduo-user-guide.pdf
  
HSYCO SERVER is configured with the following default network configuration:
+
https://www.sferalabs.cc/files/ionopi/doc/ionopi-user-guide.pdf
  
* IP address: 192.168.0.50
+
 
 +
To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.
 +
 
 +
HSYCO PI is configured with the following default network configuration:
 +
 
 +
* IP address (eth0): 192.168.1.50
 
* Net mask: 255.255.255.0
 
* Net mask: 255.255.255.0
* Default Gateway: 192.168.0.1
+
* Default Gateway: 192.168.1.1
* DNS: 192.168.0.1
+
* DNS: 192.168.1.1
 +
 
 +
The RS-232 / RS-485 port system id is /dev/ttyAMA0.
 +
You can only use either the RS-232 or the RS-485 port, not both at the same time, as they are connected to the same UART interface of the Raspberry Pi CPU.
  
 +
If you have FTDI USB to serial adapters connected to the USB ports, use the following system ids, that are based on the physical USB port used:
 +
* bottom right port: /dev/ftdi-1-1.2
 +
* top right port:    /dev/ftdi-1-1.3
 +
* bottom left port:  /dev/ftdi-1-1.1.3
 +
* top left port:    /dev/ftdi-1-1.1.2
  
The IP address 192.168.0.50 will be used from now on in all the examples as the HSYCO SERVER address.
+
=== HSYCO MINI - ARK-1123 ===
 +
[[File:Installation HSYCO Mini Connections.png|center|800px]]
 +
This version is installed on an Advantech ARK-1123L (ARK-1123L-S3A1E), with 1.33 GHz Intel Atom E3825 dual core processor, 2GB RAM and a 500GB hard-disk with pre-installed software. Alternative storage configurations are also available.
 +
The operating system is Debian 9 (Stretch).
  
On the two Ethernet ports server, the port which is usually configured is the one next to the USB ports, shown as LAN1. The Ethernet port LAN2, on the right, works but it is not configured.
 
  
== The Configuration Console ==
+
To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.
  
HSYCO Server provides a simple low-level maintenance console, used to reboot the system, reset its settings or restore the whole system to the original factory configuration.
+
HSYCO MINI is configured with the following default network configuration:
  
This console is not used for normal operations.
+
* IP address (eth0): 192.168.0.50
 +
* Net mask: 255.255.255.0
 +
* Default Gateway: 192.168.0.1
 +
* DNS: 192.168.0.1
  
The console is available using a keyboard and a monitor connected to the VGA/DVI/HDMI video out connector.
+
HSYCO MINI has two RS-232 serial ports with standard DB-9 female connectors, on both sides of the chassis.
 +
* the system id of the port (COM) next to the Ethernet (LAN) socket is /dev/ttyS1
 +
* the system id of the port (COM1) on the opposite side (power button side) is /dev/ttyS0.
  
 +
=== HSYCO PRO - ARK-2121 ===
 +
[[File:Installation HSYCO Pro Connections.png|center|800px]]
 +
This version is installed on an Advantech ARK-2121L (ARK-2121L-U0A1E), with 2.0 GHz Intel J1900 quad core processor, 4GB RAM and a 500GB hard-disk with pre-installed software. Alternative storage configurations are also available.
 +
The operating system is Debian 9 (Stretch).
  
<syntaxhighlight lang="text">
 
Server Configuration Console
 
  
1) Reboot the system
+
To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.
2) Halt the system
 
3) Stop HSYCO Server
 
4) Start HSYCO Server
 
5) Restore network configuration to factory defaults (192.168.0.50)
 
6) Delete all PINs and file server password and restore default values
 
7) Restore database to factory defaults. All data will be lost
 
8) Restore system software to factory defaults. All data will be lost
 
Type a function number and press Enter [1, 2, 3, 4, 5, 6, 7, 8]:
 
</syntaxhighlight>
 
  
 +
HSYCO PRO is configured with the following default network configuration:
  
Type the desired function number and Enter, then press Y to confirm after the beeps (the system will sound a number of beeps, corresponding to the function number; this should allow you to access the console functions using the keyboard and audio feedback only, without a monitor).
+
* IP address (eth0): 192.168.0.50
 +
* Net mask: 255.255.255.0
 +
* Default Gateway: 192.168.0.1
 +
* DNS: 192.168.0.1
  
Function 1 performs the operating system shutdown, followed by a reboot.
+
The LAN1 port (left) is eth1. This port is not configured with factory default settings.
 +
The LAN2 port (right) is eth0. This is the default LAN port. On a system with factory default settings, you should connect the Ethernet cable to LAN2.
  
Function 2 performs the operating system shutdown and halts the system. You should turn it off then back on to restart.
+
HSYCO PRO has four RS-232 serial ports with standard DB-9 female connectors.
 +
* the system id of COM1 is /dev/ttyS0
 +
* the system id of COM2 is /dev/ttyS1
 +
* the system id of COM3 is /dev/ttyS2
 +
* the system id of COM4 is /dev/ttyS3.
  
Function 3 and 4 are used to temporarily stop the HSYCO Server process, and to restart it.
+
=== HSYCO ENTERPRISE - ARK-2250 ===
 +
[[File:Installation HSYCO Enterprise Connections.png|center|1000px]]
 +
This version is installed on an Advantech ARK-2250L (ARK-2250L-U6A1E), with 2.6 GHz Intel i7 dual core processor, 8GB RAM and a 500GB hard-disk or SSD with pre-installed software.
 +
HSYCO ENTERPRISE can also be configured with an additional high speed mSATA SLC solid state drive. In this case the SLC drive becomes the main drive, while the hard-disk is configured to store HSYCO logs and cameras' motion recording files.
 +
The operating system is Debian 9 (Stretch).
  
  
{{note|Use functions 5 to 8 with caution. These function will delete configuration settings, user data, and security settings of the system. They could allow a local user with physical access to the server, unrestricted access to your data.}}
+
To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.
  
 +
HSYCO ENTERPRISE is configured with the following default network configuration:
  
Function 5 restores the factory default network configuration. If you make a mistake while setting the network parameters, preventing access to the server via the network connection, you can use this function to reset the configuration and regain access to the server.
+
* IP address (eth0): 192.168.0.50
 +
* Net mask: 255.255.255.0
 +
* Default Gateway: 192.168.0.1
 +
* DNS: 192.168.0.1
  
Function 6 removes all users’ PIN and PUK codes, restoring the default 00000 administrator enabled PIN. It also reset the operating system password to its default.
+
The ARK-2250 dynamically allocates the Ethernet ports. If only one port (eth0) is configured at the operating system level, then eth0 is assigned to LAN1 if this port is connected. If LAN2 is connected and LAN1 is not, then eth0 is assigned to LAN2. This dynamic setup offers an automatic failover configuration where eth0 is automatically switched from LAN1 to LAN2 in case of a physical link failure on LAN1. If both ports (eth0 and eth1) are configured at the operating system level, and both LAN1 and LAN2 are connected, eth0 is assigned to LAN1, and eth1 to LAN2. But, if LAN1 is not connected, eth0 will be assigned to LAN2, leaving eth1 down.
  
Function 7 deletes all data in the HSYCO database, including persistent variables.
+
HSYCO ENTERPRISE has four RS-232 serial ports with standard DB-9 female connectors.
 +
* the system id of COM1 is /dev/ttyS0
 +
* the system id of COM2 is /dev/ttyS1
 +
* the system id of COM3 is /dev/ttyS2
 +
* the system id of COM4 is /dev/ttyS3.
  
Function 8 performs a full factory reset, returning the system to the HSYCO version and settings as shipped, removing all custom data, configuration and programs.
+
== Access to the Manager ==
  
== The Administration Pages ==
+
HSYCO SERVER is pre-configured with a Web-based toolkit of applications, the [[Manager]], that gives you access to configuration and administration functions, including the ability to change the network settings and the operating system's password, HSYCO users management and the tools to create customized graphic user interfaces.
  
HSYCO SERVER is pre-configured with a system’s management application that gives you access to the administration functions, including the ability to change the network settings and the operating system’s password, and HSYCO users management.
+
To access the system's management application, simply called [[Manager]] from now on, enter the following URL in your Web Browser:
  
The protection of any system from unauthorized access is extremely important.
+
<nowiki>https://192.168.0.50/hsycoserver/manager</nowiki>
  
HSYCO uses several security mechanisms, and it is therefore safe to use through the Internet or inside a local network.
+
The Manager runs on most modern Web browsers, including tablets like Apple’s iPad. It even runs on small screen devices like the iPhone or iPod touch, although a larger screen size is advisable for ease of use. Microsoft’s Internet Explorer versions 8 and older are not supported, and IE9 is not guaranteed to work, although it should in most cases.
  
 
HSYCO default configuration only accepts Web requests through the HTTPS secure protocol, while access via HTTP is disabled.
 
HSYCO default configuration only accepts Web requests through the HTTPS secure protocol, while access via HTTP is disabled.
Line 87: Line 137:
  
  
{{tip|The factory default URLKey is hsycoserver.}}
+
{{note|The factory default URLKey is hsycoserver.}}
  
  
 
The URLKey is not a secret password, but only an additional protection feature.
 
The URLKey is not a secret password, but only an additional protection feature.
  
To access the system’s management application, simply called Manager from now on, enter the following URL in your Web Browser:
+
Because the SSL certificate used to secure the communication between the Web Browser and HSYCO SERVER is self-generated, you will be asked to accept the server's certificate.
 
 
<nowiki>https://192.168.0.50/hsycoserver/manager</nowiki>
 
 
 
Because the SSL certificate used to secure the communication between the Web Browser and HSYCO SERVER is self-generated, you will be asked to accept the server’s certificate.
 
  
 
On the iPod touch, iPhone or iPad press Continue, on other browsers follow the dialog boxes to permanently accept the certificate.
 
On the iPod touch, iPhone or iPad press Continue, on other browsers follow the dialog boxes to permanently accept the certificate.
Line 114: Line 160:
  
  
{{tip|The default pre-configured PIN and PUK are the same for all HSYCO SERVERS, to let you conveniently access the user interface during the initial installation. Both the PIN and PUK should be changed immediately to different, hard to guess numbers.}}
+
{{note|The default pre-configured PIN and PUK are the same for all HSYCO SERVERS, to let you conveniently access the user interface during the initial installation. Both the PIN and PUK should be changed immediately to different, hard to guess numbers.}}
  
  
Press the Admin icon in the Manager’s main menu to access the Users, System Password, Network and Clock settings functions, described below.
+
Press the [[Admin]] icon in the [[Manager]]’s main menu to access the [[Admin#Users|Users]], [[Admin#System Password|System Password]], [[Admin#Network|Network]] and [[Admin#Clock|Clock]] settings functions.
  
  
Line 123: Line 169:
  
  
=== Users ===
+
HSYCO is now ready to be configured!
  
The users page lets you fully manage individual users from the HSYCO Web interface.
+
For further information about the Manager toolkit usage please visit the [[Settings|Configuration Guide]].
  
You can set and revoke the administrator rights, enable and disable a user, modify PIN and PUK codes, delete a user, and also define the rights of access to the subdirectories.
+
== SSH Access to the Operating System ==
  
If no pages have been specified through the Web interface, the user has no limits and can access all the existing pages.
+
The configuration of the operating system only needs one administrator user, whose login is '''hsyco'''.
  
 +
The password initially configured for the '''hsyco''' user is '''hsycoserver'''.
  
[[File:Installation Users.png|center]]
+
{{note|In order to guarantee the system safety and to prevent any unauthorized access it is essential to modify the access password of the HSYCO user before installing the system onto any not-secure LAN network.}}
  
 +
The SSH secure protocol is used to access the operating system’s console and, if needed, to manage files. The SSH protocol encrypts all traffic and can be safely used for remote management. If the network has a firewall it might be necessary to open port '''TCP 22''' and configure traffic forwarding towards the HSYCO SERVER IP address.
  
To change the predefined PIN and PUK, select user, then enter the new PIN and PUK codes in the appropriate fields, and press Save to confirm.
+
HSYCO is installed in the home directory of the '''hsyco''' user, '''/home/hsyco'''.
  
Or you can create one or more new users, at least one of them with administrator privileges, then log in again with the new administrator PIN and PUK and delete the default user.
+
In this directory, the subdirectory '''./hsyco''' contains the software, the configuration files, custom Java programs, logs and recorded images from cameras.
  
=== System Password ===
+
Several software programs are available for the SSH access on Microsoft Windows, in particular [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Putty] to access the console, and Bitvise Tunnelier [http://www.bitvise.com/download-area] and [http://winscp.net/eng/index.php WinSCP] to access files through SFTP.
  
The system password is used to access both the operating system’s console, directly or with SSH, and the HSYCO files through the files sharing network service.
+
On Apple Mac OS X the SSH access is integrated in the operating system and directly usable through Terminal, while [http://cyberduck.ch/ Cyberduck] is one of the most widespread utilities to manage files through SFTP.
  
This password is needed to access the HSYCO SERVER for maintenance and to change its configuration.
+
On Ubuntu OS the SSH access is integrated in the operating system and accessible through Terminal, while [https://filezilla-project.org/ Filezilla] is a good solution for managing file  through SFTP.
  
To change the system password you should log in with a PIN and PUK corresponding to a user with administrator privileges.
+
=== Start and Stop the HSYCO Server (HSYCO version 3.6.0 or later) ===
  
 +
HSYCO starts automatically with the operating system when the server is turned on. The execution of HSYCO is signaled by three consecutive high-pitch beeps.
  
[[File:Installation Password.png|center]]
+
HSYCO also restarts automatically with every change to the '''hsyco.ini''', '''hsyco.jar''' and '''com/hsyco/user.class''' files. In this case the restart is also signaled by three beeps.
  
 +
{{note|The following commands should be used for all HSYCO Server units shipped with HSYCO 3.6.0 pre-installed. For servers shipped with an older version, use the commands listed in the next chapter.}}
  
Click the Password button in the Admin menu and enter the new password twice, then press Save to confirm.
+
To manually stop HSYCO, access the console via SSH:
  
In order to guarantee an adequate safety the password should be composed by letters and numbers, should not contain well-known words and needs to be of at least 10-16 characters.
+
ssh hsyco@192.168.0.50
  
You should save the password in a safe place.
+
and execute the command:
  
If you forget the password, but still have access to HSYCO, you can simply go to the password page and type a new password.
+
sudo systemctl stop hsyco.service
  
The system password should be known only by the owner of the system.
+
To start HSYCO, execute:
 +
sudo systemctl start hsyco.service
  
If, for maintenance reasons, someone else needs to access HSYCO, you should change the password to a temporary new password, then revert to your secret password.
+
Finally, to verify the current state of HSYCO execute:
  
 +
sudo systemctl status hsyco.service
  
{{tip|Be aware that the system password provides unrestricted access to the operating system configuration, to the HSYCO configuration, including users administration, and to all files, like recorded images from all the cameras and log files.}}
+
If HSYCO is running, the answer to the command will be something like:
  
=== Network Settings ===
+
hsyco.service - HSYCO Server service
 +
  Loaded: loaded (/etc/systemd/system/hsyco.service; enabled)
 +
  Active: active (running) ...
  
The network settings page lets you change the network parameters of HSYCO SERVER.
+
=== Start and Stop the HSYCO Server (HSYCO version 3.5.x or older) ===
  
Be sure to know the meaning and the effects of your changes, as a mistake in these parameters may render HSYCO SERVER not accessible from the network and through the HSYCO Web interface.
+
HSYCO starts automatically with the operating system when the server is turned on. The execution of HSYCO is signaled by three consecutive high-pitch beeps.
  
 +
HSYCO also restarts automatically with every change to the '''hsyco.ini''', '''hsyco.jar''' and '''com/hsyco/user.class''' files. In this case the restart is also signaled by three beeps.
  
{{note|HSYCO implements a safety mechanism that in most cases would automatically revert, after 5 minutes from the change, the network settings to the original configuration if for any reason network access to HSYCO is lost after a change.}}
+
To manually stop HSYCO, access the console via SSH:
  
 +
ssh hsyco@192.168.0.50
  
[[File:Installation Network.png|center]]
+
and execute the command:
  
 +
sudo stop hsyco
  
To change the network settings, enter the new parameters and press Save.
+
To start HSYCO, execute:
 +
sudo start hsyco
  
After the change, you have 5 minutes to log in again to any page to confirm your changes.
+
Finally, to verify the current state of HSYCO execute:
  
The network settings page is not normally needed after the initial installation, and it is usually deleted from the menu to prevent accidental changes to the network configuration.
+
sudo status hsyco
  
=== Clock Settings ===
+
If HSYCO is running, the answer to the command will be something like:
  
The clock page sets the server’s clock and time zone, and enables the automatic update of the clock based on Internet time servers.
+
hsyco (start) running, process ...
  
 +
== SMB Access to Files ==
  
[[File:Installation Clock.png|center]]
+
{{note|Starting with HSYCO 3.6.0, SMB support is not pre-installed. If you need SMB on you HSYCO Server you can install it on Linux, or contact HSYCO for support.}}
  
  
To change the time settings, enter the new parameters and press Save.  
+
To guarantee an easy access to files, HSYCO SERVER makes the main directory available through a standard ''file server'' (network disk) service. The name of the service is ''hsyco''. To access the file server you should use the same hsyco user and password provided to access the operating system.  
  
All the other parameters are read-only from the clock page, and can be set using the Settings menu, as explained in the [[Configuration Guide]].
+
=== Access to Files on Microsoft Windows ===
  
The time zone information is used to obtain the correct local time and automatically adjust for daylight saving time.
+
In order to connect a Microsoft Windows system to the HSYCO SERVER shared network folder, select '''Tools > Map network drive''' from the Explorer menu.
  
If automatic time is set to on HSYCO automatically sets the local date and time by polling Network Time Protocol (NTP) servers.
+
Type ''\\192.168.0.50\hsyco'' in the field '''Folder''' and press '''Finish'''.
  
== The Manager ==
 
  
The Manager is the Web-based toolkit of applications that you will use to create  customized graphic user interfaces and access all system’s configuration files.
+
[[File:Access Files Windows1.png]]
{{note|The Manager runs on most modern Web browsers, including tablets like Apple’s iPad. It also runs on small screen devices like the iPhone or iPod touch, although a larger screen size is advisable for ease of use. Microsoft’s Internet Explorer versions 8 and older are not supported, and IE9 is not guaranteed to work, although it should in most cases.}}
 
  
  
To access the Manager, enter the following URL in your Web Browser:
+
Then, insert the user name (''hsyco'', as before) and password (initially ''hsycoserver'', that you can modify as already described) and press OK.
  
https://192.168.0.50/hsycoserver/manager
 
  
You need to authenticate using a PIN with administrator privileges to use the Manager.
+
[[File:Access Files Windows2.png]]
  
  
[[File:Manager menu.png|center]]
+
All the HSYCO files are available and accessible in the shared folder window, and you have full read and write permissions on them.
  
  
Touch “about” in the bottom left corner to show HSYCO’s current version information.
+
{{note|In order to guarantee the highest safety and protection of HSYCO from any unauthorized access, you should disconnect the shared folder when not in use and avoid saving<sup>[[#note8|[Note 8]]]</sup> the password for automatic access.}}
  
 +
To manually edit the content of the files directly from the shared folder, use the '''WordPad''' application, and not the '''Notepad''' application, the latter cannot correctly manage the text files format.
  
[[File:Manager About.png|center]]
+
To open the files using ''WordPad'', right click on the file, then select '''Open with...''' and ''WordPad'', if it appears in the menu, or go to ''Programs'' and choose WordPad in the list of available applications.
  
  
The Manager has several application.
+
[[File:Access Files Windows3.png]]
  
'''Admin''' for basic user and network settings, as already discussed.
 
  
The '''Project Editor''' is the visual editor you use to customize the user interface, and will be described in the Customization chapter.
+
<span id="note8">
 +
;Note 8 :  Do not select the ''Remember my password'' option in the window where the username and password are required.
 +
</span>
  
The '''File Manager''' provides access to all HSYCO’s files, just like the standard file manager you have in your personal computer, only this one is fully Web-based and works directly on HSYCO Server’s files.
+
=== Access to Files on Mac OS X ===
  
The '''Log Viewer''' is a real-time viewer of HSYCO’s logs.
+
In order to connect an Apple Mac OS X system to the HSYCO SERVER file server, select '''Go > Connect to Server''' from the '''Finder''' menu.
  
The '''Status Browser''', a real-time viewer of data points, variables and dynamic user interface attributes, will be discussed in the Programming chapter.
 
  
The '''System Monitor''' is used to monitor several key hardware and operating system parameter of the HSYCO server.
+
[[File:Access Files Mac1.png]]
  
The '''Wiring Editor''', an easy to use end-user logic and scenarios builder, will be described n the Customization chapter.
 
  
Finally, the '''Knx Utility''' and '''BACnet Utility''' applications are also available through the Manager if the respective I/O servers are enabled.
+
In the '''Server Address''' field insert ''smb://192.168.0.50'' and press '''Connect'''.
  
You can switch between applications touching the [[File:Manager Switching Applications.png]] icon on the top bar.
+
Then, insert the username (''hsyco'') and password (initially ''hsycoserver'', that you can modify as already described) and press '''Connect'''.
  
[[File:Manager Top Bar.png|center]]
 
  
 +
[[File:Access Files Mac2.png]]
  
Using a PC with a physical keyboard, you can press [Ctrl] and [Shift] at the same time for fast switching between applications. An application selection panel appears until you keep the [Ctrl] key pressed; select the application you need by repeatedly pressing [Shift], then releasing [Ctrl].
 
  
 +
{{note| In order to guarantee the highest safety and protection of HSYCO from any unauthorized access, we advise you to disconnect the shared folder when not in use and not to save the password in the Mac ''keychain''.}}
  
=== The File Manager ===
+
== Software License Key ==
  
The File Manager application offers all the conventional tools used to manage files, including a text editor to modify text files without having to download them to your computer.
+
The license.txt file contains the software license key needed to unlock HSYCO. The first time HSYCO is started, or in case this file is removed before start, HSYCO creates a new file containing the encrypted code that univocally identifies the hardware where the software runs. In order to allow the correct execution of HSYCO the file should contain the software license key, issued by HSYCO Srl specific to every single computer.  
  
 +
{{note|The hardware identification code is based on the hardware components installed on the server. For example, by replacing or adding network cards the code changes and therefore the software license key will be no longer valid for the new configuration.}}
  
[[File:Manager File Manager.png|center]]
+
If the license key is not in the file, or if it is not correct, HSYCO disables all the access functions to the field devices, keeping only the Web Server working. It will be therefore possible to access the Web pages, but not to execute any action on or interface to the systems connected to HSYCO.
  
 +
{{note|The possible error messages related to the software license are written in the daily log files.}}
  
You can download and upload individual files or ZIP directories, and create, rename and delete files and directories.
+
The content of license.txt, generated by HSYCO and containing only the hardware identification code is the following:
 +
#Generated by HSYCO CONTROLLER 3.3.0
 +
#Tue Dec 10 11:49:06 CET 2013
 +
hwid=2080334b6283f450283bd4bbc3389bf66dc03dda
  
You can download a full backup of all configuration files (excluding the logs and motion directories), using the download root backup tool. Because of its size, this function could take a considerable amount of time to generate and download the backup.zip file.
+
To unlock HSYCO features, replace the license.txt file generated by HSYCO at the time of its first execution with the license.txt version with the key provided by HSYCO Srl. The file and the key are automatically recognized within a few seconds, it is therefore not necessary to restart HSYCO.
  
 +
This is an example of the complete software license key file:
  
[[File:Manager Tools.png|center]]
+
#Generated by HSYCO LICENSE MANAGER 3.3.0
 +
#Tue Dec 10 12:20:00 CET 2013
 +
name=Company Name
 +
hwid=2080334b6283f450283bd4bbc3389bf66dc03dda
 +
key=302D021500898B20F13ABE66DF3D2577809C6A53343A23A5CD0214540FD580A1E3DA1CBEB18D11E98CAAE453D402BF
  
 +
== The Configuration Console ==
  
You can also activate a small live log view window, quite a useful tool while you are editing files and want to check the logs for debugging.
+
HSYCO Server provides a simple low-level maintenance console, used to reboot the system, reset its settings or restore the whole system to the original factory configuration.
  
 +
This console is not used for normal operations.
  
[[File:Manager Text Editor.png|center]]
+
The console is available using a keyboard and a monitor connected to the VGA/DVI/HDMI video out connector.
  
  
In the text editor, if someone modifies the file you are currently editing, you will be prompted with a warning message, asking to either reload the file with the new version, or ignoring the changes.
+
<syntaxhighlight lang="text">
 +
Server Configuration Console
  
 +
1) Reboot the system
 +
2) Halt the system
 +
3) Stop HSYCO Server
 +
4) Start HSYCO Server
 +
5) Restore network configuration to factory defaults (192.168.0.50)
 +
6) Delete all PINs and file server password and restore default values
 +
7) Restore database to factory defaults. All data will be lost
 +
8) Restore system software to factory defaults. All data will be lost
 +
Type a function number and press Enter [1, 2, 3, 4, 5, 6, 7, 8]:
 +
</syntaxhighlight>
  
[[File:Manager File Changed.png|center]]
 
  
 +
Type the desired function number and Enter, then press Y to confirm after the beeps (the system will sound a number of beeps, corresponding to the function number; this should allow you to access the console functions using the keyboard and audio feedback only, without a monitor).
  
Your changes will be lost if you accept to reload the new version of the file.
+
Function 1 performs the operating system shutdown, followed by a reboot.
  
 +
Function 2 performs the operating system shutdown and halts the system. You should turn it off then back on to restart.
  
==== Upgrading and restarting HSYCO ====
+
Function 3 and 4 are used to temporarily stop the HSYCO Server process, and to restart it.
In order to upgrade the HSYCO software version, you should simply upload a new version of the hsyco.jar file to the root directory. After the upload, the server will restart and the Manager will reload on the browser.
 
  
You can also manually force an HSYCO restart. To do so, select the hsyco.jar file and press the “restart hsyco” button in the right panel.
 
  
 +
{{note|Use functions 5 to 8 with caution. These function will delete configuration settings, user data, and security settings of the system. They could allow a local user with physical access to the server, unrestricted access to your data.}}
  
[[File:Manager Restart HSYCO.png|center]]
 
  
=== The Log Viewer ===
+
Function 5 restores the factory default network configuration. If you make a mistake while setting the network parameters, preventing access to the server via the network connection, you can use this function to reset the configuration and regain access to the server.
  
The Log Viewer application shows a scrollable live view of the last 1000 lines from the daily log file.
+
Function 6 removes all users’ PIN and PUK codes, restoring the default 00000 administrator enabled PIN. It also reset the operating system password to its default.
  
 +
Function 7 deletes all data in the HSYCO database, including persistent variables.
  
[[File:Manager Log Viewer.png|center]]
+
Function 8 performs a full factory reset, returning the system to the HSYCO version and settings as shipped, removing all custom data, configuration and programs.
 
 
 
 
The tool bar at the bottom lets you filter log lines searching for a text, or to exclude a text in order to de-clutter the log. Type multiple words to select or exclude all lines that contain at least one of the words. Touch “search” to toggle between text search and exclude mode.
 
 
 
Touch “pause” to stop updating the viewer, then press again to restart. New log lines written while paused will not appear in the viewer, but will still be saved in the log file.
 
 
 
Touch “clear” to clear the log window.
 
 
 
You can also temporarily select which log levels you want, without having to modify the hsyco.ini main configuration file.
 
 
 
Touch “verbose”, “events” or “user” to enable or disable the log levels. Changing log levels also affects what other users will see in the Log Viewer as well as what is actually written in the log file. Changes to the log levels will return to the preset configuration after you leave the Log Viewer application.
 
 
 
=== The Log Viewer ===
 
 
 
The System Monitor works in combination with the system I/O server, which must be enabled for this function to work, and monitors several key hardware and operating system parameters of the HSYCO server.
 
 
 
 
 
[[File:Manager System Monitor.png|center]]
 
 
 
 
 
If the system I/O server  is not enabled, the following message will be shown.
 
 
 
 
 
[[File:Manager System Monitor Message.png|center]]
 
 
 
 
 
See the system I/O server application note for additional information.
 
 
 
== Files Organization ==
 
 
 
The general structure of HSYCO’s main directory is shown in the following diagram.
 
 
 
 
 
[[File:Installation File Organization.png|center]]
 
 
 
 
 
=== hsyco/access.ini ===
 
This file contains the information corresponding to the users’ PIN/PUK access codes. This file can be manually modified to create or delete a PIN code, though it is usually modified through the users management pages in the HSYCO Web interface. It is also updated by HSYCO after every access, showing the time and the IP address of the last access and the number of access errors made by every user.
 
----
 
 
 
=== hsyco/acl.ini ===
 
This file is used to define server-side access control lists for Web-based user commands. The optional acl.ini file defines the rules to allow or reject commands.
 
 
 
See the Access Control List chapter in the Appendix section for additional information.
 
----
 
 
 
=== hsyco/console.log ===
 
console.log is a system log file. It contains information and error messages generated by the operating system or by the Java Virtual Machine.
 
 
 
For example, the following message:
 
 
 
Exception in thread "main" java.lang.NoClassDefFoundError: com/hsyco/OpenWebNetMonitor
 
at com.hsyco.hsyco.main(hsyco.java:4794)
 
Caused by: java.lang.ClassNotFoundException: com.hsyco.OpenWebNetMonitor
 
 
 
suggests that one of the HSYCO Java libraries is missing. This file is therefore useful in the testing stage or during the development of an additional Java component,  while it does not provide any relevant information about the normal execution of the HSYCO software.
 
----
 
 
 
=== hsyco/hsyco.ini ===
 
This is the main configuration file, containing all HSYCO configuration parameters. It is fully described in the Configuration chapter. Any change to this file causes the automatic restart of HSYCO after a few seconds.
 
----
 
 
 
=== hsyco/hsyco.jar ===
 
This file contains all the components of the HSYCO software. In order to update  HSYCO SERVER to a newer version, you replace this file with a new one, containing the whole code and the resources of the software in a compressed format. Any change to this file causes the automatic restart of HSYCO after a few seconds.
 
----
 
 
 
=== hsyco/hsyco.keys ===
 
This file contains the '''SSL''' certificate for the '''HTTPS''' web traffic cryptography. When HSYCO is started, if the file is not available, a new SSL certificate is automatically generated according to the name defined in hsyco.ini. Otherwise, HSYCO simply uses the certificate contained in this file, which could have been also generated by an official '''Certification Authority (CA)'''<sup>[[#note1|[Note 1]]]</sup>. If an official certificate is not used, this file is created and managed by HSYCO without any manual intervention.
 
 
 
<span id="note1">
 
;Note 1 :  For example Verisign or Thawte.
 
</span>
 
----
 
 
 
=== hsyco/keys.data ===
 
It is the database of the secure authentication keys between the Web Browser and HSYCO. This file is created and managed by HSYCO and must not be modified or erased.
 
----
 
 
 
=== hsyco/license.txt ===
 
This file contains the software license key needed to make HSYCO fully operational. When  HSYCO is started for the first time, or if this file is removed before start-up, HSYCO creates a new file containing an encrypted unique code that identifies the computer on which the software is running. In order to unlock HSYCO, the file needs to contain the software license key, issued by Home Systems Consulting.
 
 
 
If the license key is not available in the file or if it is not correct, HSYCO disables all the functions of access to any field device, keeping only the HTTP and HTTPS Web Server running. It will be therefore possible to access the Web pages, but not to execute any action on or interface to the systems connected to HSYCO.
 
----
 
 
 
=== hsyco/systemtopo.txt ===
 
Contains the list of all the devices of the system and names of the '''Wi-Fi''' location zones<sup>[[#note2|[Note 2]]]</sup>.
 
 
 
This file format is described in details in the Configuration chapter.
 
 
 
systemtopo.txt can be modified at any time; any change is applied within a few seconds without restarting HSYCO. Web pages are automatically reloaded after any change to systemtopo.txt.
 
 
 
<span id="note2">
 
;Note 2 : That is, the list of the different Access Point devices that constitute the local wireless network.
 
</span>
 
----
 
 
 
=== hsyco/timers.data ===
 
It is the database of the timers’ settings, such as alarms, irrigation or light timers, managed by HSYCO. This file is created and managed by HSYCO and should not be modified or erased.
 
----
 
 
 
=== hsyco/com/hsyco ===
 
This directory contains the customizable Java files. In particular, the file '''user.class''' must always exist, even just in its original version if it has not been customized. The corresponding source file '''user.java''' is not necessary for the correct execution of the software.
 
----
 
 
 
=== hsyco/www ===
 
The www directory contains all the customizable files corresponding to the Web pages of the user interface. All the required standard files can be found in the '''hsyco.jar''' package and therefore are not included in www; however it is always possible to add new customized files in appropriate locations in www; these files will have priority over the standard files contained in hsyco.jar.
 
 
 
{{note|Whenever HSYCO detects any change to the files in www and in its sub-directories, it automatically forces the refresh of the Web page on the connected browsers, so that all the changes are immediately visible.}}
 
 
 
The directories and the standard files will be described in the following paragraphs, although the directories and files structure can be customized as needed.
 
----
 
 
 
=== hsyco/www/<project>/index.hsm ===
 
The <project> directory, contains the definition of the user interface pages. Each <project> directory contains the '''index.hsm''' file, with the complete definition of the whole Web interface. This file format is described in the Personalization chapter.
 
 
 
It is not possible to use names such as img and the skins’ names, which are reserved. It is also not possible to have more than one Web interface description file in the same directory.
 
----
 
 
 
=== hsyco/www/<project>/img ===
 
Contains the files of the images associated to the automation and lighting devices defined in the systemtopo.txt file, or any other image file used by the Web interface.
 
 
 
Files in this subdirectory have priority over files in the hsyco/www/img directory.
 
----
 
 
 
=== hsyco/www/<skin> ===
 
Customized skins can be defined and saved in www subdirectories. The files of the standard skins are included in the hsyco.jar package file. Creating a directory with the same name of a standard skin is possible, but should be done carefully, as it will override the standard skin files.
 
 
 
=== hsyco/www/img ===
 
Contains the files of the images associated to the automation and lighting devices defined in the systemtopo.txt file, or any other image file used by the Web interface. Files in the img/ sub-directory under the project's main directory have priority over files in this directory.
 
 
 
=== hsyco/www/public ===
 
The HTTPServerPublicDirectory parameter defined in hsyco.ini file enables a basic Web server that serves files, without any parsing, contained in a specific directory, via HTTP and HTTPS, only to clients in the trusted range of IP addresses.
 
 
 
=== hsyco/motion ===
 
Contains the images of every single frame recorded from each camera. The motion directory contains a distinct subdirectory for each camera, named as  the cameras ids defined in hsyco.ini. In these directories the files are organized in two additional subdirectory levels. HSYCO automatically manages these directories and the individual files.
 
 
 
{{note|In order to avoid any malfunction in the reproduction and, potentially, in the recording of the events you should not partially delete the files. If needed, it is possible to delete all the files of a camera and then restart HSYCO so that the index of the images can be correctly updated.}}
 
 
 
HSYCO will automatically erase the files and their corresponding subdirectories  after the time of images storage has expired, as set in hsyco.ini for each camera.
 
 
 
Moreover, the older frames are automatically erased before their times of expiration if the space available on disc drops below a safe margin.
 
 
 
=== hsyco/logs ===
 
Contains the log files generated by HSYCO. The information details contained in the log files depend on the log level settings defined in hsyco.ini. All the relevant events detected from the field, the commands sent, the users access information and errors can be traced.
 
 
 
When starting HSYCO the information corresponding to the execution of the different HSYCO modules will be logged. Some of the most important log messages are listed in the Appendix chapter.
 
 
 
HSYCO writes a separate log file each day, in a different directory for each year, in the '''''MMGG-message.log'''' format. For example, the log file for the 12th April 2012 will be hsyco/logs/2012/0412-message.log.
 
 
 
If anti-intrusion systems are integrated with HSYCO, the file '''security.log''' will be written too, in the same directories as the daily log files. This file contains the list of all the events concerning activation, deactivation and alarms on the anti-intrusion systems.
 
 
 
The log files can be removed anytime without causing any problem. HSYCO does not provide an automatic procedure to erase the log files.
 
 
 
=== hsyco/ir ===
 
This directory can be empty or might not exist at all. It contains the files with CCF encoded IR commands, to be used when sending IR commands with IRTrans devices.
 
 
 
These files should have the extension .ccfhex and the name corresponds to the IR database name.
 
 
 
Each file contains one or more lines per command:
 
 
 
command_name = hex_ccf_data
 
 
 
The CCF data for each command is in hexadecimal format, and could be broken in multiple lines.
 
 
 
=== hsyco/dataloggers.ini ===
 
This file contains the definitions of time slots for data loggers of type counter. Each line sets some rules for a time slot of a data logger, the format to be used is the following:
 
 
 
datalogger_name; slot_id; time_range; days_of_week; date; rate
 
 
 
Whenever a counter data logger listed in this file is updated, the rules are matched from top to bottom to establish the time slot the new value belongs to and thus which rate to apply.
 
 
 
The following table describes each field of a rule line:
 

Latest revision as of 11:17, 18 August 2020

HSYCO SERVER ships pre-installed with the latest version of the HSYCO software, on a Linux Debian 9 (Stretch) distribution stripped of all not-essential services.

The Oracle Java SE Runtime Environment version 8 is also installed. No other software is required.


Legacy HSYCO SERVER units had Linux Ubuntu 12.04 LTS Server and Oracle Java SE Runtime Environment version 7 installed.


HSYCO-Pi-Strato.png


This chapter describes the access procedures for the basic management of the system and the structure of HSYCO’s installation and configuration files.

Initial Set-Up

HSYCO SERVER is available with different hardware configurations. Each version presents minor differences in its software configuration.

HSYCO PI - SFERA LABS STRATO PI SERVER

Installation HSYCO Pi Connections.png

The standard version is installed on a Strato Pi Base Server, with Raspberry Pi 3 Model B+ 1GB RAM or Raspberry Pi 4 Model B with 2/4/8 GB RAM with and a 4GB SLC industrial microSD card with pre-installed software. The operating system is Raspbian Stretch Lite or Raspberry Pi OS depending on the Raspberry Pi version.

HSYCO Pi is also available installed on Strato Pi UPS, Strato Pi CM or CM Duo or Iono Pi server.

Links to the HSYCO PI Servers User Guides:

https://www.sferalabs.cc/files/strato/doc/stratopi-base-user-guide.pdf

https://www.sferalabs.cc/files/strato/doc/stratopi-ups-user-guide.pdf

https://www.sferalabs.cc/files/strato/doc/stratopi-cm-user-guide.pdf

https://www.sferalabs.cc/files/strato/doc/stratopi-cmduo-user-guide.pdf

https://www.sferalabs.cc/files/ionopi/doc/ionopi-user-guide.pdf


To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.

HSYCO PI is configured with the following default network configuration:

  • IP address (eth0): 192.168.1.50
  • Net mask: 255.255.255.0
  • Default Gateway: 192.168.1.1
  • DNS: 192.168.1.1

The RS-232 / RS-485 port system id is /dev/ttyAMA0. You can only use either the RS-232 or the RS-485 port, not both at the same time, as they are connected to the same UART interface of the Raspberry Pi CPU.

If you have FTDI USB to serial adapters connected to the USB ports, use the following system ids, that are based on the physical USB port used:

  • bottom right port: /dev/ftdi-1-1.2
  • top right port: /dev/ftdi-1-1.3
  • bottom left port: /dev/ftdi-1-1.1.3
  • top left port: /dev/ftdi-1-1.1.2

HSYCO MINI - ARK-1123

Installation HSYCO Mini Connections.png

This version is installed on an Advantech ARK-1123L (ARK-1123L-S3A1E), with 1.33 GHz Intel Atom E3825 dual core processor, 2GB RAM and a 500GB hard-disk with pre-installed software. Alternative storage configurations are also available. The operating system is Debian 9 (Stretch).


To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.

HSYCO MINI is configured with the following default network configuration:

  • IP address (eth0): 192.168.0.50
  • Net mask: 255.255.255.0
  • Default Gateway: 192.168.0.1
  • DNS: 192.168.0.1

HSYCO MINI has two RS-232 serial ports with standard DB-9 female connectors, on both sides of the chassis.

  • the system id of the port (COM) next to the Ethernet (LAN) socket is /dev/ttyS1
  • the system id of the port (COM1) on the opposite side (power button side) is /dev/ttyS0.

HSYCO PRO - ARK-2121

Installation HSYCO Pro Connections.png

This version is installed on an Advantech ARK-2121L (ARK-2121L-U0A1E), with 2.0 GHz Intel J1900 quad core processor, 4GB RAM and a 500GB hard-disk with pre-installed software. Alternative storage configurations are also available. The operating system is Debian 9 (Stretch).


To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.

HSYCO PRO is configured with the following default network configuration:

  • IP address (eth0): 192.168.0.50
  • Net mask: 255.255.255.0
  • Default Gateway: 192.168.0.1
  • DNS: 192.168.0.1

The LAN1 port (left) is eth1. This port is not configured with factory default settings. The LAN2 port (right) is eth0. This is the default LAN port. On a system with factory default settings, you should connect the Ethernet cable to LAN2.

HSYCO PRO has four RS-232 serial ports with standard DB-9 female connectors.

  • the system id of COM1 is /dev/ttyS0
  • the system id of COM2 is /dev/ttyS1
  • the system id of COM3 is /dev/ttyS2
  • the system id of COM4 is /dev/ttyS3.

HSYCO ENTERPRISE - ARK-2250

Installation HSYCO Enterprise Connections.png

This version is installed on an Advantech ARK-2250L (ARK-2250L-U6A1E), with 2.6 GHz Intel i7 dual core processor, 8GB RAM and a 500GB hard-disk or SSD with pre-installed software. HSYCO ENTERPRISE can also be configured with an additional high speed mSATA SLC solid state drive. In this case the SLC drive becomes the main drive, while the hard-disk is configured to store HSYCO logs and cameras' motion recording files. The operating system is Debian 9 (Stretch).


To start the server simply plug the power supply. HSYCO automatically starts, the execution of HSYCO is signalled by three consecutive high-pitch beeps.

HSYCO ENTERPRISE is configured with the following default network configuration:

  • IP address (eth0): 192.168.0.50
  • Net mask: 255.255.255.0
  • Default Gateway: 192.168.0.1
  • DNS: 192.168.0.1

The ARK-2250 dynamically allocates the Ethernet ports. If only one port (eth0) is configured at the operating system level, then eth0 is assigned to LAN1 if this port is connected. If LAN2 is connected and LAN1 is not, then eth0 is assigned to LAN2. This dynamic setup offers an automatic failover configuration where eth0 is automatically switched from LAN1 to LAN2 in case of a physical link failure on LAN1. If both ports (eth0 and eth1) are configured at the operating system level, and both LAN1 and LAN2 are connected, eth0 is assigned to LAN1, and eth1 to LAN2. But, if LAN1 is not connected, eth0 will be assigned to LAN2, leaving eth1 down.

HSYCO ENTERPRISE has four RS-232 serial ports with standard DB-9 female connectors.

  • the system id of COM1 is /dev/ttyS0
  • the system id of COM2 is /dev/ttyS1
  • the system id of COM3 is /dev/ttyS2
  • the system id of COM4 is /dev/ttyS3.

Access to the Manager

HSYCO SERVER is pre-configured with a Web-based toolkit of applications, the Manager, that gives you access to configuration and administration functions, including the ability to change the network settings and the operating system's password, HSYCO users management and the tools to create customized graphic user interfaces.

To access the system's management application, simply called Manager from now on, enter the following URL in your Web Browser:

https://192.168.0.50/hsycoserver/manager

The Manager runs on most modern Web browsers, including tablets like Apple’s iPad. It even runs on small screen devices like the iPhone or iPod touch, although a larger screen size is advisable for ease of use. Microsoft’s Internet Explorer versions 8 and older are not supported, and IE9 is not guaranteed to work, although it should in most cases.

HSYCO default configuration only accepts Web requests through the HTTPS secure protocol, while access via HTTP is disabled.

Furthermore, 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, defined in the general system configuration parameters.


The factory default URLKey is hsycoserver.


The URLKey is not a secret password, but only an additional protection feature.

Because the SSL certificate used to secure the communication between the Web Browser and HSYCO SERVER is self-generated, you will be asked to accept the server's certificate.

On the iPod touch, iPhone or iPad press Continue, on other browsers follow the dialog boxes to permanently accept the certificate.


Installation Certificate.png


You will see the PIN and PUK authentication page. Enter the default PIN and PUK, and press OK:

PIN: 0000
PUK: 00000 0000 00000


Installation PIN PUK.png


The default pre-configured PIN and PUK are the same for all HSYCO SERVERS, to let you conveniently access the user interface during the initial installation. Both the PIN and PUK should be changed immediately to different, hard to guess numbers.


Press the Admin icon in the Manager’s main menu to access the Users, System Password, Network and Clock settings functions.


Installation Admin.png


HSYCO is now ready to be configured!

For further information about the Manager toolkit usage please visit the Configuration Guide.

SSH Access to the Operating System

The configuration of the operating system only needs one administrator user, whose login is hsyco.

The password initially configured for the hsyco user is hsycoserver.

In order to guarantee the system safety and to prevent any unauthorized access it is essential to modify the access password of the HSYCO user before installing the system onto any not-secure LAN network.


The SSH secure protocol is used to access the operating system’s console and, if needed, to manage files. The SSH protocol encrypts all traffic and can be safely used for remote management. If the network has a firewall it might be necessary to open port TCP 22 and configure traffic forwarding towards the HSYCO SERVER IP address.

HSYCO is installed in the home directory of the hsyco user, /home/hsyco.

In this directory, the subdirectory ./hsyco contains the software, the configuration files, custom Java programs, logs and recorded images from cameras.

Several software programs are available for the SSH access on Microsoft Windows, in particular Putty to access the console, and Bitvise Tunnelier [1] and WinSCP to access files through SFTP.

On Apple Mac OS X the SSH access is integrated in the operating system and directly usable through Terminal, while Cyberduck is one of the most widespread utilities to manage files through SFTP.

On Ubuntu OS the SSH access is integrated in the operating system and accessible through Terminal, while Filezilla is a good solution for managing file through SFTP.

Start and Stop the HSYCO Server (HSYCO version 3.6.0 or later)

HSYCO starts automatically with the operating system when the server is turned on. The execution of HSYCO is signaled by three consecutive high-pitch beeps.

HSYCO also restarts automatically with every change to the hsyco.ini, hsyco.jar and com/hsyco/user.class files. In this case the restart is also signaled by three beeps.

The following commands should be used for all HSYCO Server units shipped with HSYCO 3.6.0 pre-installed. For servers shipped with an older version, use the commands listed in the next chapter.


To manually stop HSYCO, access the console via SSH:

ssh hsyco@192.168.0.50

and execute the command:

sudo systemctl stop hsyco.service

To start HSYCO, execute:

sudo systemctl start hsyco.service

Finally, to verify the current state of HSYCO execute:

sudo systemctl status hsyco.service

If HSYCO is running, the answer to the command will be something like:

hsyco.service - HSYCO Server service
  Loaded: loaded (/etc/systemd/system/hsyco.service; enabled)
  Active: active (running) ...

Start and Stop the HSYCO Server (HSYCO version 3.5.x or older)

HSYCO starts automatically with the operating system when the server is turned on. The execution of HSYCO is signaled by three consecutive high-pitch beeps.

HSYCO also restarts automatically with every change to the hsyco.ini, hsyco.jar and com/hsyco/user.class files. In this case the restart is also signaled by three beeps.

To manually stop HSYCO, access the console via SSH:

ssh hsyco@192.168.0.50

and execute the command:

sudo stop hsyco

To start HSYCO, execute:

sudo start hsyco

Finally, to verify the current state of HSYCO execute:

sudo status hsyco

If HSYCO is running, the answer to the command will be something like:

hsyco (start) running, process ...

SMB Access to Files

Starting with HSYCO 3.6.0, SMB support is not pre-installed. If you need SMB on you HSYCO Server you can install it on Linux, or contact HSYCO for support.


To guarantee an easy access to files, HSYCO SERVER makes the main directory available through a standard file server (network disk) service. The name of the service is hsyco. To access the file server you should use the same hsyco user and password provided to access the operating system.

Access to Files on Microsoft Windows

In order to connect a Microsoft Windows system to the HSYCO SERVER shared network folder, select Tools > Map network drive from the Explorer menu.

Type \\192.168.0.50\hsyco in the field Folder and press Finish.


Access Files Windows1.png


Then, insert the user name (hsyco, as before) and password (initially hsycoserver, that you can modify as already described) and press OK.


Access Files Windows2.png


All the HSYCO files are available and accessible in the shared folder window, and you have full read and write permissions on them.


In order to guarantee the highest safety and protection of HSYCO from any unauthorized access, you should disconnect the shared folder when not in use and avoid saving[Note 8] the password for automatic access.


To manually edit the content of the files directly from the shared folder, use the WordPad application, and not the Notepad application, the latter cannot correctly manage the text files format.

To open the files using WordPad, right click on the file, then select Open with... and WordPad, if it appears in the menu, or go to Programs and choose WordPad in the list of available applications.


Access Files Windows3.png


Note 8 
Do not select the Remember my password option in the window where the username and password are required.

Access to Files on Mac OS X

In order to connect an Apple Mac OS X system to the HSYCO SERVER file server, select Go > Connect to Server from the Finder menu.


Access Files Mac1.png


In the Server Address field insert smb://192.168.0.50 and press Connect.

Then, insert the username (hsyco) and password (initially hsycoserver, that you can modify as already described) and press Connect.


Access Files Mac2.png


In order to guarantee the highest safety and protection of HSYCO from any unauthorized access, we advise you to disconnect the shared folder when not in use and not to save the password in the Mac keychain.


Software License Key

The license.txt file contains the software license key needed to unlock HSYCO. The first time HSYCO is started, or in case this file is removed before start, HSYCO creates a new file containing the encrypted code that univocally identifies the hardware where the software runs. In order to allow the correct execution of HSYCO the file should contain the software license key, issued by HSYCO Srl specific to every single computer.

The hardware identification code is based on the hardware components installed on the server. For example, by replacing or adding network cards the code changes and therefore the software license key will be no longer valid for the new configuration.


If the license key is not in the file, or if it is not correct, HSYCO disables all the access functions to the field devices, keeping only the Web Server working. It will be therefore possible to access the Web pages, but not to execute any action on or interface to the systems connected to HSYCO.

The possible error messages related to the software license are written in the daily log files.


The content of license.txt, generated by HSYCO and containing only the hardware identification code is the following:

#Generated by HSYCO CONTROLLER 3.3.0
#Tue Dec 10 11:49:06 CET 2013
hwid=2080334b6283f450283bd4bbc3389bf66dc03dda 

To unlock HSYCO features, replace the license.txt file generated by HSYCO at the time of its first execution with the license.txt version with the key provided by HSYCO Srl. The file and the key are automatically recognized within a few seconds, it is therefore not necessary to restart HSYCO.

This is an example of the complete software license key file:

#Generated by HSYCO LICENSE MANAGER 3.3.0
#Tue Dec 10 12:20:00 CET 2013
name=Company Name
hwid=2080334b6283f450283bd4bbc3389bf66dc03dda
key=302D021500898B20F13ABE66DF3D2577809C6A53343A23A5CD0214540FD580A1E3DA1CBEB18D11E98CAAE453D402BF

The Configuration Console

HSYCO Server provides a simple low-level maintenance console, used to reboot the system, reset its settings or restore the whole system to the original factory configuration.

This console is not used for normal operations.

The console is available using a keyboard and a monitor connected to the VGA/DVI/HDMI video out connector.


Server Configuration Console

1) Reboot the system
2) Halt the system
3) Stop HSYCO Server
4) Start HSYCO Server
5) Restore network configuration to factory defaults (192.168.0.50)
6) Delete all PINs and file server password and restore default values
7) Restore database to factory defaults. All data will be lost
8) Restore system software to factory defaults. All data will be lost
Type a function number and press Enter [1, 2, 3, 4, 5, 6, 7, 8]:


Type the desired function number and Enter, then press Y to confirm after the beeps (the system will sound a number of beeps, corresponding to the function number; this should allow you to access the console functions using the keyboard and audio feedback only, without a monitor).

Function 1 performs the operating system shutdown, followed by a reboot.

Function 2 performs the operating system shutdown and halts the system. You should turn it off then back on to restart.

Function 3 and 4 are used to temporarily stop the HSYCO Server process, and to restart it.


Use functions 5 to 8 with caution. These function will delete configuration settings, user data, and security settings of the system. They could allow a local user with physical access to the server, unrestricted access to your data.


Function 5 restores the factory default network configuration. If you make a mistake while setting the network parameters, preventing access to the server via the network connection, you can use this function to reset the configuration and regain access to the server.

Function 6 removes all users’ PIN and PUK codes, restoring the default 00000 administrator enabled PIN. It also reset the operating system password to its default.

Function 7 deletes all data in the HSYCO database, including persistent variables.

Function 8 performs a full factory reset, returning the system to the HSYCO version and settings as shipped, removing all custom data, configuration and programs.