IbaHD Server

Overview

The IbaHD Connector allows Seeq to connect to the IbaHD Server, a historian used in the metals and mining industries. IbaHD’s HD Stores and Channel Groups are indexed as a Seeq asset tree, with Channels as signals and Event Definitions as conditions.

Prerequisites

There are no prerequisites for connecting to IbaHD.

Configuration

This is an example configuration template that is displayed in the Additional Configuration box that appears when you click Configure for an existing datasource (or if a new datasource is being created, in the Create new datasource connection modal that appears after clicking Add Datasource) on the Datasources administration page.

JSON

"Host" : "<Insert the IbaHD Server's host address>",
"Port" : 9005,
"TlsCertificatePemFile" : "<Insert the filesystem path to the .pem file containing the IbaHD Server's TLS certificate. This certificate is generated in the IbaHD Server itself and must be valid for the Host configured above (i.e., firewalls must be accounted for).>",
"ApiKey" : "<Insert the API key configured in the IbaHD Server or a SECRETS_FILE containing it. Can be null if an API key is not configured in the IbaHD Server (i.e., user management is disabled).>",
"IndexDisabledHdStores" : false,
"IndexDiagnosticHdStores" : false,
"MaxEventDurationInDays" : 1,
"MaxRawChannelSampleCountPerMessage" : null,
"DownsampledSignals" : {
  "CreateDownsampledSignals" : true,
  "SignalNamePrefix" : "(Downsampled) ",
  "SampleCount" : 100000,
  "DownsamplingMethod" : "AVERAGE"
}

IbaHD Additional Configuration

Property Name	Default Value	Data Type	Description
`Host`	A help text that must be replaced	String	The IbaHD Server's host address.
`Port`	`9005`	Integer	The IbaHD Server's port.
`TlsCertificatePemFile`	A help text that must be replaced	String	The filesystem path to the `.pem` file containing the IbaHD Server's TLS certificate. This certificate is generated in the IbaHD Server itself and must be valid for the `Host` configured above (i.e., firewalls must be accounted for).
`IndexDisabledHdStores`	`false`	Boolean	Whether disabled HD Stores should be indexed.
`IndexDiagnosticHdStores`	`false`	Boolean	Whether diagnostic HD Stores should be indexed.
`MaxEventDurationInDays`	`1`	Integer	The maximum expected duration of IbaHD Events, in days. Events longer than this won't be displayed in Seeq.
`MaxRawChannelSampleCountPerMessage`	`null`	Integer	This is an optimization option, specifying many samples IbaHD should return in each response for raw Channel data requests. Values less than or equal to `0` or `null` mean using the IbaHD default. Care should be taken when increasing this value, see the section "Memory management" in IbaHD’s API manual for warnings about memory exhaustion.
`DownsampledSignals`	See section below	See section below	See section below

Downsampled Signals Configuration

IbaHD’s Channels of analog data can have a very high resolution, of millions of samples per hour. Since this can make trending large intervals slow, the connector uses IbaHD’s aggregated data functionality to optionally provide an additional downsampled version of each Signal.

These Downsampled Signals have the following special characteristics:

When trending, a fixed number of representative Samples is retrieved, no matter how large the interval. These Samples are calculated from the raw data by IbaHD itself, using its AGGR_ALGO_TYPE_MIN_MAX_AVG_DOWNSAMPLING algorithm.
Since the representative Samples are approximations, Downsampled Signals are always uncertain (i.e., they as displayed as dotted lines in Seeq).
The creation of Downsampled Signals, the maximum number of Samples retrieved and the downsampling method are configurable (see below).

These characteristics make Downsampled Signals a lighter weight alternative to raw Signals when high resolution and absolute precision are not required, for example when trending large intervals. Their configuration is defined by the DownsampledSignals group, with the following options:

Property Name	Default Value	Data Type	Description
`CreateDownsampledSignals`	`true`	Boolean	Whether an additional Downsampled Signal should be created for each analog Channel.
`SignalNamePrefix`	`"(Downsampled) "`	String	The beginning of the name of Downsampled Signals, to be displayed in Seeq's UI.
`SampleCount`	`100000`	Integer	The maximum number of Samples that should be requested from Downsampled Signals for any given interval, no matter how large.
`DownsamplingMethod`	`"AVERAGE"`	String	One of `"AVERAGE"`, `"MINIMUM"` or `"MAXIMUM"`, specifying how IbaHD should calculate the representative Samples when downsampling. Note that the downsampling algorithm is defined and performed by the IbaHD Server itself.

Troubleshooting

If you are running into issues with connecting to or accessing data from IbaHD, view our guide for troubleshooting datasource issues. Some particular errors are also detailed below.

RuntimeException: "TlsCertificatePemFile" was not found

Error message:

CODE

java.lang.RuntimeException: The file '(…).pem' specified in the connection configuration 
field "TlsCertificatePemFile" was not found. Please make sure it exists and is 
accessible to jvm-link.

Advice:

Make sure the file specified in TlsCertificatePemFile exists and the path is correct.
Make sure the file is accessible to jvm-link. This is especially important inside containers, which can’t access unmapped files.

UnknownHostException: No such host is known

Error message:

CODE

Caused by: java.net.UnknownHostException: No such host is known (…)

Advice:

The address configured in Host could not be reached.

Make sure the address is correct and the server is accessible. Could firewalls be interfering?

ConnectException: Connection timed out: no further information

Error message:

CODE

Caused by: java.net.ConnectException: Connection timed out: no further information

Advice:

The port configured in Port is not responding.

Make sure the IbaHD Server is available in the port specified.

CertificateException: found no certificates in input stream or IOException: Invalid lenByte

Error messages:

CODE

Caused by: java.security.cert.CertificateException: found no certificates in input stream
or
Caused by: java.io.IOException: Invalid lenByte

Advice:

These errors might indicate the file configured in TlsCertificatePemFile contains a broken TLS certificate. This might happen if the certificate was serialized to a data format like JSON and contains invalid characters.

Make sure the certificate file is downloaded directly from IbaHD to avoid such problems. Check the IbaHD API manual for details (see the “Resources” section below).

SignatureException: Signature does not match.

Error message:

CODE

Caused by: java.security.SignatureException: Signature does not match.

Advice:

This error might indicate the certificate configured in TlsCertificatePemFile is not valid for the host configured in Host.

This might happen when the certificate creation in the IbaHD Server did not account for firewalls. Check the IbaHD API manual (see the “Resources” section below) for details on certificate generation, in particular the 'DNS Alias' option.

StatusRuntimeException: UNAUTHENTICATED: Invalid authentication header

Error message:

CODE

Caused by: io.grpc.StatusRuntimeException: UNAUTHENTICATED: Invalid authentication header

Advice:

This error might indicate the API key configured in ApiKey was not accepted by the IbaHD Server.

Make sure the API key specified is correct. The key is generated by the IbaHD Server itself.

Known Issues

There are no known issues for the ibaHD-Server connector. Please report any issues you find to our support portal.

Performance considerations

View our guide on optimizing datasource performance for general guidance.