CIASIBSystem
CIAS IB-System IP is the supervision software of the CIAS perimeter intrusion detection systems, managing up to 1280 sensors organized in up to 640 input groups.
The integration with HSYCO is accomplished via the IB-System IP Web API, over HTTPS. This I/O Server was developed following the CIAS documentation "Communication protocol technical specification IB-System IP WebAPI", Rel. 1.0.2, and tested with IB-System IP 3.2.5.
Communication
The computer running IB-System IP must be reachable from HSYCO on the network. The Web API is configured in the WEB-API tab of the IB-System IP options: port (default 443), user and password (default "user" and "cias"), and the certificate and private key files for HTTPS. IB-System IP accepts up to 10 simultaneous Web API clients. Please refer to the IB-System IP manual for detailed instructions.
The Web API only accepts TLS 1.2 or higher connections. IB-System IP uses a self-signed certificate by default, and the certificate can be replaced in the IB-System IP options. The I/O Server does not verify the certificate against a certification authority, neither the default nor a custom one. To make sure that HSYCO is talking to the right server before sending the user and password, set the fingerprint option: the I/O Server then only accepts a certificate with that SHA-256 fingerprint. The fingerprint of the server certificate is written in the log at the first connection, and can be copied from there.
The Web API does not notify status changes: the I/O Server reads the status of all the sensors at every polling cycle, with a single request. IB-System IP must be polled at least once per second not to miss events lasting less than two seconds. The configuration, with the labels of the sensors and of the input groups, is read at start-up and then every refreshinterval seconds. The list of sensors in the status, numbers and labels, is compared at every polling cycle: when a sensor is added, removed or renamed the change is reported at once and the configuration is read again in the same cycle.
The I/O Server authenticates with the user and password of its configuration, and receives a token that expires after 24 hours. The token is renewed automatically, and immediately whenever IB-System IP refuses it. When the user or password is refused, the next attempt is made after 60 seconds.
IB-System IP 3.2.5 keeps only one valid token for each user: a new authentication invalidates the previous token. This behaviour was observed on IB-System IP 3.2.5 and is not stated in the Web API specification. HSYCO must therefore use a dedicated Web API user, not shared with other systems or with other HSYCO servers, otherwise the clients would invalidate each other's token at every request.
HSYCO Configuration
Add a CIASIBSystem I/O Server in the I/O Servers section of the Settings and set its parameters:
Communication
- Address: host name or IP address of the computer running IB-System IP
- Port: TCP/IP port of the Web API (default 443)
Authentication
- User: Web API user name
- Password: Web API password
High Availability
- Shutdown when inactive: defaults to true.
Options
| ID | Default | Values | Description |
|---|---|---|---|
| gui | true | true | enable support for UISET actions |
| false | disable UISET actions | ||
| startupevents | true | true | generate IO events also during the driver’s start-up phase |
| false | start generating events only after HSYCO is aligned with the current status of the system | ||
| pollinterval | 1000 | 200 ... 10000 | time interval in milliseconds between the start of two reads of the sensors status. IB-System IP must be polled at least once per second not to miss short events, so values above 1000 are not recommended |
| refreshinterval | 120 | 60 ... 86400 | time interval in seconds between two reads of the configuration. A sensor added, removed or renamed is detected at every polling cycle regardless of this value |
| timeout | 5000 | 1000 ... 5000 | timeout in milliseconds of each Web API request. It applies separately to the connection and to the response, so a single request can last up to twice this value |
| fingerprint | <hex> | SHA-256 fingerprint of the IB-System IP certificate, 64 hexadecimal digits, colons and spaces allowed (e.g. 3C:BC:91:…:D8:C7). When set, the I/O Server refuses a server with a different certificate. When empty, the certificate is not verified |
Datapoints
In the following table, <n> is the sensor number (1 ... 1280) and <g> the input group number (1 ... 640).
Sensor and group datapoints are only generated for the elements reported by IB-System IP.
| ID | Value | R/W | Description |
|---|---|---|---|
| connection | online | R | connection established |
| offline | R | HSYCO can't connect to IB-System IP, or the authentication failed | |
| version | <text> | R | IB-System IP and Web API versions, e.g. "IB-System IP 3.2.5, WebApi 1.0.0". Read again after every reconnection |
| newconfig | 1 | R | the IB-System IP configuration changed. Set back to 0 after 5 seconds. A sensor added, removed or renamed is reported within one polling cycle; a change of the input groups, or of the type or version of a sensor, is reported at the next configuration read, up to refreshinterval seconds later |
| 0 | R | set 5 seconds after a configuration change. The datapoint is not defined until the first change | |
| prealarm | 0 / 1 | R | at least one sensor in prealarm |
| alarm | 0 / 1 | R | at least one sensor in alarm |
| tamper | 0 / 1 | R | at least one sensor in tamper |
| fault | 0 / 1 | R | at least one sensor faulty |
| noanswer | 0 / 1 | R | at least one sensor not answering |
| group.<g>.label | <text> | R | input group label |
| group.<g>.address | <ip:port> | R | input group IP address and port |
| group.<g>.sensors | <count> | R | number of sensors in the input group |
| sensor.<n>.label | <text> | R | sensor label |
| sensor.<n>.group | <g> | R | input group of the sensor |
| sensor.<n>.type | <text> | R | sensor type, e.g. Ermo482X Pro RX |
| sensor.<n>.version | <text> | R | sensor firmware version |
| sensor.<n>.prealarm | 0 | R | sensor not in prealarm |
| 1 | R | sensor in prealarm | |
| sensor.<n>.alarm | 0 | R | sensor not in alarm |
| 1 | R | sensor in alarm | |
| sensor.<n>.tamper | 0 | R | sensor not in tamper |
| 1 | R | sensor in tamper | |
| sensor.<n>.fault | 0 | R | sensor not faulty |
| 1 | R | sensor faulty | |
| sensor.<n>.noanswer | 0 | R | sensor answering |
| 1 | R | sensor not answering | |
| sensor.<n>.pinpoint | <value> | R | distance of the intrusion point from the start of the SIOUX zone, in meters. Only for the sensors whose type is SIOUX, known after the first configuration read |
| sensor.<n>.standby | 0 / 1 | R | last standby command accepted by IB-System IP |
| 1 | W | put the sensor in standby | |
| 0 | W | remove the sensor from standby | |
| sensor.<n>.test | 0 / 1 | R | last test command accepted by IB-System IP |
| 1 | W | put the sensor in test | |
| 0 | W | remove the sensor from test |
The Web API does not report the standby and test status of the sensors. The sensor.<n>.standby and sensor.<n>.test datapoints are set to the value of the last command accepted by IB-System IP, and are not defined until a command is sent.
- Commands sent while IB-System IP is offline, or while the I/O Server is waiting to repeat a refused authentication, are not executed and are not repeated later.
- When a sensor is no longer reported by IB-System IP, its prealarm, alarm, tamper, fault and noanswer datapoints are set to 0. Its label, group, type and version keep the last value.
- A configuration change made while IB-System IP is offline is reported by
newconfigwhen IB-System IP answers again, but not if the I/O Server is restarted in the meantime (watch-dog after a long outage, I/O Server or HSYCO restart): after a restart, the first read is taken as the reference. For the same reason, a sensor removed in that period keeps its last status.
User Interface
UISET Actions
| ID | Attribute | Value | Set to |
|---|---|---|---|
| connection | visible | true | when datapoint connection = offline |
| false | when datapoint connection = online | ||
| <datapoint_id>.1 | visible | true | when datapoint with ID <datapoint_id> has value '1'. Applies to the sensor.* datapoints with values 0 and 1 |
| false | when datapoint with ID <datapoint_id> has value '0' | ||
| <datapoint_id>.0 | visible | true | when datapoint with ID <datapoint_id> has value '0'. Applies to the sensor.* datapoints with values 0 and 1 |
| false | when datapoint with ID <datapoint_id> has value '1' |
Release Notes
4.1.0
- initial release
CIAS and IB-System IP are trademarks of CIAS Elettronica S.r.l.