HS/FS now provides the possibility to read in files located on a server that can be reached via the LAN/Internet.
In these text files, there are data records ("switching points") consisting of group address, date and time, as well as the value. The HS/FS can retrieve these files via FTP or http protocol.
After reading in the files, the HS/FS sets the variable with the specified group addresses to the value at the set date and time. Through the simple structure, the file interface is ideally suited for connecting external management programs (e.g. schedule management) with the building system technology. Use in connection with a central management of property would be possible via this interface and a common file server. From this source, the files with switching points are retrieved cyclically and/or manually using a command.
In these text files, there are data records ("switching points") consisting of group address, date and time, as well as the value. The HS/FS can retrieve these files via FTP or http protocol.
After reading in the files, the HS/FS sets the variable with the specified group addresses to the value at the set date and time. Through the simple structure, the file interface is ideally suited for connecting external management programs (e.g. schedule management) with the building system technology. Use in connection with a central management of property would be possible via this interface and a common file server. From this source, the files with switching points are retrieved cyclically and/or manually using a command.
1.File retrieval
The following files are retrieved for each operation:
- A year file
- A month file
- n day files (depending on the value max. days) (max. value: 7 days).
All switching points from the files are read in, processed, and retentively saved in the HS/FS. But only future switching points are used. The constant Max. switching points limits the quantity to be processed per file (max. value: 1000 lines).
Note
All files are always retrieved and processed by the other party.
2.File names
The HS/FS expects file names with the following structure:
- Year file: PrefixYYYYSuffix (example: switching point2007.dat for the year 2007)
- Month file: PrefixYYYYMMSuffix (example: switching point200706.dat for June 2007)
- Day file: PrefixYYYYMMDDSuffix (example: switching point20070615.dat for 15th June 2007)
YYYY: Year number is always 4-digit
MM: Month number is always 2-digit
MM: Day is always 2-digit
Prefix and suffix are explained in a later section.
MM: Month number is always 2-digit
MM: Day is always 2-digit
Prefix and suffix are explained in a later section.
3.File structure
All file types (year/month/day) have the same file structure line by line.
A line is defined as follows:
DATE_TIME|KEY|VALUE
The character "|" is used as a separator between the individual fields Comment:You receive this character by pressing the buttons [Alt Gr] + [<] simultaneously.
The date must be in the format YYYYMMDD and have eight digits. The time, separated from the date with an underscore, must be four-digit and exist in the format ssmm. The group address of the desired communication object serves as the key. The notation of the group address, 2 or 3 digit, has to be identical to that in the settings in HS/FS Expert. The desired value is specified under value. This can also be both a numeric and alphanumeric value. The decimal separator in the case of floating-point values is the period.
Note: YYYY = Year, MM = Month, DD = Day, hh = Hour, mm = Minute
Example:
20061001_1230|100/1|1
20061001_1245|100/1|0
The file contains two switching points. The first is on October 1 2006 at 12.30 pm. At this point in time, the (internal) communication object with the group address 100/1 is set to the value 1. The second switching point is on October 1 2006 at 12:45 pm. At this point in time, the same communication object is set to 0.
A line is defined as follows:
DATE_TIME|KEY|VALUE
The character "|" is used as a separator between the individual fields Comment:You receive this character by pressing the buttons [Alt Gr] + [<] simultaneously.
The date must be in the format YYYYMMDD and have eight digits. The time, separated from the date with an underscore, must be four-digit and exist in the format ssmm. The group address of the desired communication object serves as the key. The notation of the group address, 2 or 3 digit, has to be identical to that in the settings in HS/FS Expert. The desired value is specified under value. This can also be both a numeric and alphanumeric value. The decimal separator in the case of floating-point values is the period.
Note: YYYY = Year, MM = Month, DD = Day, hh = Hour, mm = Minute
Example:
20061001_1230|100/1|1
20061001_1245|100/1|0
The file contains two switching points. The first is on October 1 2006 at 12.30 pm. At this point in time, the (internal) communication object with the group address 100/1 is set to the value 1. The second switching point is on October 1 2006 at 12:45 pm. At this point in time, the same communication object is set to 0.
4.Comments
As soon as a line cannot be identified as a data line, it is ignored by Expert without it leading to an error. You can add both empty lines and text lines without any problem. A text can only not be added BEHIND a valid data line.
5.Example of a new external switching list
Example data (call-up date 01.10.2006 12:00 pm):
Max. days: 2
max. switching points: 100
Prefix: mydata/switchingpoint
Suffix: ".dat"
In this example the following files are retrieved from the server
- mydata/switchingpoint2006.dat,
- mydata/switchingpoint200610.dat,
- mydata/swithingpoint20061001.dat and
- mydata/switchingpoint20061002.dat
. The next hundred switching points (from 01.10.2006 at 12:00 pm) are extracted from these files and processed.
Max. days: 2
max. switching points: 100
Prefix: mydata/switchingpoint
Suffix: ".dat"
In this example the following files are retrieved from the server
- mydata/switchingpoint2006.dat,
- mydata/switchingpoint200610.dat,
- mydata/swithingpoint20061001.dat and
- mydata/switchingpoint20061002.dat
. The next hundred switching points (from 01.10.2006 at 12:00 pm) are extracted from these files and processed.
6.Data
Call cycle (in min.)
The files are retrieved from the server in this cycle. The minimum value is one minute.
Max. days
Defines the maximum number of days that are retrieved from the server and processed. The minimum value is one day.
Max. switching points
Defines the maximum number of switching points which should be processed and saved. Only future switching points count in the case of a retrieval. If more switching points are contained in the retrieved files, the surplus switching points are ignored. The minimum value is one switching point.
Status (optional)
Writes the status of a retrieval in the numeric communication object specified here:
- 1 => The data was retrieved successfully.
- 2 => The data could not be retrieved. This may be, for example, because at present no connection to the server is possible, or the retrieved file structure is invalid.
The specification of a communication object is optional.
Manual query >(optional)
If the communication object specified here sends a 1, querying the switching points is started manually. The specification of a communication object is optional.
Allow access to the following communication objects
Only the communication objects specified here can be changed by the switching points. Group addresses that are missing in this list are ignored. The group address serves as the key.
Important
If internal communication objects are changed, they require a group address!
7.Server
- FTP (active) => Retrieves the data from a FTP server (in active mode).
- FTP (passive) => Retrieves the data from a FTP server (in passive mode).
- HTTP => Retrieves the data from an HTTP server.
Note
The usual port is 21 for FTP queries, 22 for SFTP queries.
User name (optional)
If access to the files should be password-protected, the corresponding user name has to be entered here.
Password (optional)
If access to the files should be password-protected, the corresponding password has to be entered here.
Path with prefix
Defines the file path with the file prefix. Example: For the file "mydata/switchingpoint2006.dat", the prefix would be "mydata/switchingpoint".
Note
You should not use any special characters or points in the prefix!
Suffix
Defines the concluding part (suffix) of the file name.
Normally that is ".dat" or ".txt". You can also use any other suffix you wish. If you wish to use a file without a suffix, just enter a period (".") under suffix in Expert.
Normally that is ".dat" or ".txt". You can also use any other suffix you wish. If you wish to use a file without a suffix, just enter a period (".") under suffix in Expert.
Note
You should not use any special characters and, apart from the first character, no periods in the suffix either!
8.Some examples
Depending on the type of server on which the lists are located, you should observe upper case and lower case.
| Path with prefix | File type | Suffix | File name | Comment |
|---|---|---|---|---|
ExtList/test | Year | .dat | test2016.dat | The file is located in the "ExtList" subdirectory |
heating | Day | .txt | heating20160916.txt | |
MyCompany | Month | . | MyCompany201609 | If a "." suffix is entered in Expert, the file has no ending! |
ExtList/special/lights | Day | mycompany | lights20161027mycompany | The file is located in the "ExtList/special" subdirectory. Although it has a suffix, it has NO file ending! |