Difference between revisions of "About HSYCO"

From HSYCO
Jump to navigation Jump to search
Line 3: Line 3:
 
Compared to legacy building automation solutions, it offers a state-of-the-art architecture that is fully based on key modern standards, like HTML5, CSS3, JavaScript and Java.
 
Compared to legacy building automation solutions, it offers a state-of-the-art architecture that is fully based on key modern standards, like HTML5, CSS3, JavaScript and Java.
  
 +
* [[Files Organization]]
 
* [[User Interface]]
 
* [[User Interface]]
 
* [[Manager]]
 
* [[Manager]]
 
 
 
== 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 System Settings 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:
 
 
{| class="wikitable"
 
!Field
 
!Format
 
!Description
 
|-
 
 
|datalogger_name
 
|string
 
|specifies which data logger this slot is applied to
 
|-
 
 
|slot_id
 
|positive integer
 
|identifier for the slot. More lines can refer to the same slot identifier
 
|-
 
 
|time_range
 
|hh:mm-hh:mm
 
|specifies the time range in which the slot applies. An asterisk (*) in this field will always result in a match
 
|-
 
 
|days_of_week
 
|list of week days
 
|specifies the week days matched by this rule. The days are identified by a number from 1 (Monday) to 7 (Sunday). For instance, writing “135” into this field will result in a match on Mondays (1), Wednesdays (3), and Fridays (5). An asterisk in this field will always result in a match
 
|-
 
 
|date
 
|yyyy/mm/dd
 
or
 
yyyy/mm/dd-yyyy/mm/dd
 
|specifies the date or the date range in which the slot applies. In case of date ranges (yyyy/mm/dd-yyyy/mm/dd) the starting date or the ending date can be replaced by an asterisk indicating that this rule will apply respectively until or from the specified date. For instance the date range “*-2000/12/31” will match all the dates preceding and including December 31st 2000. If the exact date format is used (yyyy/mm/dd) then each field can be replaced by an asterisk which will match every year, month, or day. For instance “*/12/25” will match December 25th of every year. An asterisk in this field will always result in a match
 
|-
 
 
|rate
 
|positive float number
 
|specifies the rate (i.e. the multiplicative factor) to be applied for this time slot.
 
|-
 
|}
 
----
 
=== hsyco/data ===
 
HSYCO has an integrated SQL database engine (HSQLDB - HyperSQL DataBase) you can use in your applications via the standard JDBC API.
 
 
The database that HSYCO uses is called “hsyco” and its files are saved in the data/ directory under the base directory. We consider the data/ directory a reserved HSYCO path and discourage the use of it for storing user’s databases or in general for any customized purpose.
 
----
 
=== hsyco/Scripts ===
 
This directory can be empty or might not exist at all. It contains a copy of operating system specific scripts needed for the automatic execution of HSYCO when the server is started<sup>[[#note3|[Note 3]]]</sup>.
 
 
In this directory it is also possible to write additional scripts called by the customized code in user.java.
 
 
<span id="note3">
 
;Note 3 :  HSYCO SERVER is based on a Linux Ubuntu 12.04 LTS Server distribution. This version uses the Upstart system for the task and services management of the operating system. The configuration file is hsyco.conf. It can be found in the /etc/init directory and allows Upstart to correctly manage the execution of HSYCO.
 
</span>
 
----
 
 
=== hsyco/drivers ===
 
HSYCO offers a development framework to easily build your own I/O server, written in Java, so you can interface with external systems that are not part of the built-in library of supported systems.
 
 
Each driver has a dedicated sub-directory under the “drivers” directory in HSYCO’s root directory.
 
 
See the Custom I/O Drivers Development chapter for additional information.
 
----
 
 
=== hsyco/plugins ===
 
HSYCO allows you to bundle both the user interface design and the application code in one package that is easier to distribute and install.
 
 
Each plugin has a dedicated sub-directory under the “plugins” directory in HSYCO’s root directory.
 
 
See the Plugins Applications Development chapter for additional information.
 
  
 
[[Category:INCOMPLETE]]
 
[[Category:INCOMPLETE]]

Revision as of 10:56, 27 February 2014

HSYCO is an innovative Java-based software framework for home and building automation applications. It is highly scalable, portable, secure, reliable and customizable. 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. Compared to legacy building automation solutions, it offers a state-of-the-art architecture that is fully based on key modern standards, like HTML5, CSS3, JavaScript and Java.