System Architecture

Jump to navigation Jump to search

The HSYCO framework is composed of three main layers, the drivers, the core services engine and API, and the user interface. This section discusses these layers, and also other general architecture information about HSYCO, including its file structure.

System architecture model.png

The Manager Toolkit

The Manager's application popup

HSYCO 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 Manager, enter the following URL in your Web Browser:

The Manager section covers the details of each one of these tools.

The Drivers Layer

The drivers layer is used to create a consistent interface to all external systems that HSYCO is capable of controlling.

I/O Servers

Most input/output field systems are interfaced through what we call I/O servers. An I/O server is the logical representation of a field system integrated in HSYCO.

The I/O servers general concepts and specific implementations for each field system are discussed in the Introduction to I/O Servers section.


Video cameras are another very typical device used with HSYCO, usually in combination with other systems, for live view and recording.

The Video Cameras section describes the detailed requirements to interface a camera with HSYCO.

The Core

HSYCO offers a rich set of core services.

These services are used by HSYCO to provide pre-built features, and are also available to developers, through APIs in JavaScript, Java and the proprietary EVENTS language.

The State Data Engine is the most important component of the core. It stores the real-time status of all field systems, application data and user interface dynamic attributes. The Events Engine triggers all relevant API asynchronous calls whenever any status change occurs.


Network services implement some useful APIs like TCP/IP ping, HTTP get and post requests, Wake-On-Lan services and WiFi-based location services.

See the Wi-Fi Client Location Services section for additional information.


HSYCO supports both local and networked serial ports. The Communication Ports settings in Manager cover the details of serial interfaces.

Timers and Schedulers

Timers and schedulers allow users to trigger actions on field systems, or any other function that HSYCO can execute, at predefined time periods.

A timer is a simple function that allows you to set a time interval and days of week, and is used for simple alarms and repetitive tasks.

The scheduler is a powerful function that allows you to define a set of calendar entries to schedule actions at the beginning and end of each time interval.

Timers and schedulers have dedicated user interface objects, and a core engine that takes care of triggering the events that should have appropriate associated actions.

Clock and Sun Position

The clock is used to provide time information to all HSYCO services and generate time events for custom applications.

It can be configured to automatically update from network time servers and to set the local time based on standard time zones.

The Sun position service constantly computes the current azimuth and elevation position of the Sun, based on given latitude and longitude information.

It also triggers day and night events based on astronomical sunrise and sunset.

High Availability

The high availability (HA) service coordinates two redundant HSYCO servers so that one stand-by server can take over in case the main server fails or is disconnected due to network failures. This service can also mirror files and the database from the master server to the slave, as well as sync persistent variables.

It is also possible to define an IP address that the active server, master or slave, will assign as an IP alias to its main Ethernet port. 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.

HSYCO Remote

The HSYCO remote service is used in combination with the Remote I/O Server, 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.

Using the HSYCO Remote I/O Server you can build a multi-level architecture with one or more HSYCO servers acting as concentrators for data points managed by other HSYCO servers.

System Monitor

The System monitor service is used by the System Monitor I/O Server to monitor several key hardware and operating system parameters of an HSYCO server.

It is also used internally to check internal resources, for example to prevent filling the internal storage with recorded video frames from cameras.


HSYCO has a centralized log facility, where system messages and error are written to daily log files.

JavaScript, Java and EVENTS APIs also allow applications to write custom logs.

See the Log Files section for the details.

Data Logger

Data loggers allow to gather, process and visualize statistical data on the variations of a data set.

They can be used to automatically generate time charts of its trend and/or to log data as CSV files.

The Data Loggers chapter describes all key features, with examples. See the Data Loggers section in the Manager Settings tool for the full list of configuration parameters.

Leak Detector

The leak detector service is used to generate warning for potential water or other quantities leaks by analyzing any generic flow counter.

See the JavaScript Leak Detector API documentation, or the equivalent Java API, for the details.

Public Announcement

HSYCO can play audio for public announcement, as pre-recorded files or using a text-to-speech engine that converts text to audio.

Audio can be sent to the Web browser, the server’s audio line out connector, the internal speaker or audio out line of Axis cameras, SNOM's phones or PA devices, and I/O servers with audio playback capabilities, like the Sonos players.

See the Audio and Public Announcement documentation, and the JavaScript, Java and EVENTS API for additional information.

User Interface

HSYCO enables the local and remote control of every automation subsystem through a user-friendly fully customizable web interface.

The control interface is designed for any device running a modern web browser, from traditional Windows, Mac and Linux PCs to Android smartphones and the iPhone, iPod touch and iPad from Apple. HSYCO remote access is easy, fast and secure. Remote and local access have the same look and feel and identical user experience.

HSYCO is much more than the traditional web browsing experience. The user interface is based on the HTML5 standard and pure JavaScript language, with no plug-in or proprietary component. HSYCO employs advanced solutions to enhance response time and minimize the effect of poor network performance.

There is no predefined, ready to use user interface, but a rich set of tools to create a dynamic, unique user interface for each specific application. Pages navigation can be designed with the highest flexibility so to make the use of the graphical interface easy for every one.

The user interface supports screen rotation, resizing the interface when the screen orientation changes.

The HSYCO standard graphical format, also called skin, is optimized to work homogeneously and efficiently on many different devices

HSYCO offers full support for multi-language pages, including UTF-8 alphabets like simplified Chinese.

The User Interface chapter describes all the details of user interface design.

User Authentication

The PIN popup
The PUK popup
The logout popup

The HSYCO web interface is based on user authenticated access. Public, anonymous access is not available by default, and can only be implemented with a customized configuration.

HSYCO is not designed to serve as a general-purpose web server.

Each user has an internal name (lower or uppercase letters and digits only), that is only used for logging and programming, and two numeric keys to grant access to the system.

The Personal Identification Number (PIN) is a five digit number that uniquely identifies the user. The Personal Unlock Key (PUK) is a fourteen digit number that is used to create the initial peering between the web client and the server. If the clipboard contains a text with a 5 digit number or 5 digit plus 14 digit numbers, pasting into the authentication page will extract these numbers and fill the PIN and PUK automatically.

For security reasons, the PIN and PUK codes are stored in a not-readable format, and it is not easy to retrieve the codes associated to a user. It is therefore recommended to write down these codes in a safe place. In case a user’s PIN/PUK codes are forgotten or lost, it will be then necessary to reset the codes, deleting the user and creating a new one.

When access to HSYCO is requested on a browser that is not currently peered with the server, the user is required to enter the PIN and PUK.

If the PIN and PUK are correct, a valid peering is created, and access granted to the user interface project associated to the URL address.

The peering token is generated by the HSYCO server on a matching PIN/PUK entry using a secure random generator. The token is stored as a cookie on the browser, and also on the HSYCO server in an encrypted format.

The peering token will remain valid until:

  • the user executes a logout with lock
  • a different PIN is entered on the browser after a simple logout or authentication timeout
  • the user id is deleted from the server
  • the global peering file on the server is deleted.

Note that, while the peering itself doesn’t have a predefined lifetime, all authenticated users will see their authentication expire after a configurable amount of time, also based on where the client is located on the network. The access control parameters can be changed using the Settings tool in the Manager, in the System > Access Control tab.

When the authentication expires, if the peering is valid, the user will be required to re-type the PIN, but not the PUK, to regain access to the user interface.

The user can manually logout at anytime after being authenticated. A normal logout will expire the authentication, but retain the peering token. A “Lock” logout will force a complete exit and erase the peering token from the browser and server, therefore for the following accesses both the PIN and PUK codes will be required.

It is advisable to always use the “Lock” function to quit the application when HSYCO is used on a non-secure client, or a client not used exclusively and always under direct control of the same user.

Importing the Self-Generated Certificate on your Client

With some browsers and operating systems, like Safari on iOS, permanently importing the self-generated certificate in the local keystore could improve HSYCO's gui usability.

If the certificate is stored in the local keystone, the browser will always accept the HTTPS connection to HSYCO without asking for confirmation. On iOS, and in combination with the HTML5 persistent cache, saving the certificate locally will also significantly improve the gui initialization time.

To download the server certificate's public key in PEM format, simply click the link in the logout panel, then follow the browser or operating system's instructions to save the certificate.

Access Control List

HSYCO supports server-side access control lists for Web-based user commands.

This mechanism is complementary, and also more secure, than the simple approach of restricting users to specific projects having only the appropriate set of functions.

Server-side access control prevents even a legitimate, authenticated user, from directly forging client commands. In fact the server would block unauthorized commands.

See the Access Control List section for detailed configuration information.

Web Traffic Security

The HSYCO web-based user interface communicates with the HSYCO server using the HTTPS protocol, with SSL high-grade cryptography.

Only when the HTTPServerLowSecurityEnabled configuration parameter is enabled, the HTTP protocol, without encryption, is allowed for the user interface.

The SSL Certificates for Cryptography chapter contains detailed information on the cryptography configuration and SSL certificates.

Files Organization

The files structure

HSYCO’s configuration, custom user interface, applications and run-time data are all stored in plain files.

Most of these files are human readable and, although there are tools that you normally use to manage them under the hood, can be modified using any text editor.

An expert user will certainly find this extremely convenient, and it also makes it very easy to manage full back-ups of the HSYCO configuration.

The Files Organization section describes the general file structure and all configuration and run-time data files.