Este site usa cookies. Ao utilizar o site você aceita o uso de cookies. Demitir Mais informações

Datasheet Historian complete

Datasheet Historian complete

All the technical data for the Tani historian including its api are documented here.

General, File formats, REST interface

Historian General Technical Data

If the historian is installed in OPC UA the configured variables will offer the history functionality.

Operation mode: File

The maximum memory used can be limited, on default the limit is using memory until 80% of the system memory. On startup of the historian or on all changes in the historian configuration the memory limits are checked.

Operation mode: Disc

The maximum disk usage is depending on the share or mount the history is written to. During the historian installation a base point will be configured.
- On Linux this is a directory. This directory can be a mount also.
- Under Windows this is a drive or network share and a directory.
Each configured history variable will use a created sub directory under the base point. The directory name is the variable name. If the multiple variabled need to be written on separate disc drives you can mount each variable directory to another drive.
The disc variables ars always in sub directories under the configured base point.

Each variables space limit can be configured separately. Thereby the global setting can be used, or the variable is using private settings. Please beware setting the security limits to small, this can damage your machine.
All default settings are save always.


Tani Historian File Description

Directory structure

The historian has a configurable data directory. All historian variables that use file storage write the data in this directory. It can be changed in <install directory>/Historian/bin/Historian.Settings, key "HistorianFilePath".

Below this directory, each historian variable has its own sub-directory (name is the variable name). Each directory contains these files:

  • Var.ini: is a copy of the variable configuration. This allows reconstructing the variable settings and file formats, even if the variable itself has been deleted from the historian.
  • Structs.ini: exists only for variables that have a structure type. It contains all required structure definitions.
  • data_*.bin: are the data files.

Var.ini contents

The Var.ini file is an ini-File with one section. The section name is "[Var.<variable name>]". In this section, the following keys can exist:

Active
Boolean; yes enables the variable in the runtime system.
AggregateAvg
Boolean; yes enables calculation of Average
AggregateCalcOffset
Number; for DataType=struct, the offset of the element that is used for aggregate calculation
AggregateCalcDataType
Enum; for DataType=struct, the data type of the element that is used for aggregate calculation; see Data Types
AggregateCount
Boolean; yes enables calculation of Count
AggregateMax
Boolean; yes enables calculation of Maximum
AggregateMin
Boolean; yes enables calculation of Minimum
AggregateStddev
Boolean; yes enables calculation of Standard Derivation
ArrayLength
Number; number of array elements to store
DataType
Enum; data type of value to store; see Data Types; for structures, a : and the structure name is appended
ElementLength
Number; for DataType=string, the maximum string length; for DataType=struct, the data length of the structure
FileResolution
Enum; The resolution for creating new data files; see Resolution
FileSave
Boolean; yes to enable file save
MaxFileCount
Number; the maximum number of live data value files to create
MaxMem
Number; number of bytes to use for live data storage of memory variable
MinimumFreeDiskSpace
Number; mimimal required free disk space; 0 uses globally defined value; values < 100 are percent; value >= 100 are bytes
OPCActive
Boolean; yes to enable automatic data acquisation of OPC data
OPCConnName
String; OPC Connection name to use
OPCGroupName
String; OPC Connection group name to use
OPCVarName
String; OPC Variable name to use
ReadResolution
Enum; The resolution of OPC data acquisation; see Resolution

Structs.ini contents

The Structs.ini is an ini-file with multiple sections. Each section describes one data structure used in the data files. The section name is equal to the structure name, some characters with special meaning are replaced by <xx> where xx is the hex-code of the character. The sequence of section entries describes the sequence of structure elements. Valid keys are:

Header
<Structure Name>,<Flags>
<Structure Name> - the structure name (repeated, for historical reasons)
<Flags> - hexadecimal encoded flag bits; internal use only; not required for decoding
Element
<Element Name>,<Data Type>,<Data Type Flags>,<Element Flags>,<Array Size>,<Original Type>
<Element Name> - the element name; some characters with special meaning are replaced by <xx> where xx is the hex-code of the character.
<Data Type> - data type of the structure element; see Data Types; for structures and enumerations, a : and the structure/enumeration name is appended; for strings, a : and the maximum string length is appended
<Data Type Flags> - hexadecimal encoded flag bits; internal use only; not required for decoding
<Element Flags> - hexadecimal encoded flag bits; valid values from the following list are OR'ed tokether:   0x0010 - PACKED - if set, no bit padding exists before this element
  0x0020 - PADDING - if set, this element is a padding element and can be ignored or hidden by user application
  0x0040 - VARIABLE_ARRAY_LENGTH - if set, the array length is given by another structure element instead of the ArrayLength field
  0x0080 - VARIABLE_STRING_LENGTH - if set, the string length is dynamic, instead of a fixed string length with padding
  0x0100 - OPTIONAL - if set, the element is optional; its presence is determined by another structure element
  all other bits are reserved for internal use only
<Array Size> - the array length in elememnts <Original Type> - a protocol specific "original type" for imported structs; may be safely ignored
ElementDynamic
optional; <Length Element>,<Switch Element>,<Switch Value>; this line is present only if at least one of these settings are required
<Length Element> - used if VARIABLE_ARRAY_LENGTH is set; the name of a structure element that gives the array length of this element; some characters with special meaning are replaced by <xx> where xx is the hex-code of the character.
<Switch Element> - used if OPTIONAL is set; the name of a structure element that determines if this element is present or not; some characters with special meaning are replaced by <xx> where xx is the hex-code of the character.
<Switch Value> - used if OPTIONAL is set; if the <Switch Element> has this value, then this element is present, otherwise it is absent
ElementComment
optional; the element comment; some characters with special meaning are replaced by <xx> where xx is the hex-code of the character.

Data file contents

The data files contain the stored values in a binary format.

File name rules: data_<resolution>_<timestamp>.bin. <resolution> is a number (0 to 7) that specifies the resolution of the data contained in this file; see Resolution. <timestamp> is the start time of this file. The timestamp format is "yyyymmddhhmm" (4 digits for year, 2 digits each for month, day, hour and minute).

All values are stored in the little-endian format (least significant byte first). Each file contains a number of records. The length of each record is determined by the settings in Var.ini.

Each entry has a 16-byte header with the following fields:

tv_sec
unsigned int64; Timestamp, given as seconds since 1970-01-01 00:00 UTC
tv_nsec
unsigned int32; Timestamp, nanoseconds in the second given by tv_sec
quality
unsigned int32; Quality for the stored value

After the header follow the user data. After the user data (without any padding) follows the next header.

Live data format (resolution 0)

These are the unmodified values as given by OPC or written by an application. Data length is given by the DataType entry in Var.ini, multiplied by the ArrayLength entry (1 if not present).

DataType=string: Each string has a 4-byte header (giving the really used number of bytes) followed by the data bytes (always ElementLength bytes).

DataType=struct: Each structure has a length as given in ElementLength

Structure encoding rules

Aggregate data format (resolutions 1 - 7)

These are aggregated values calculated during data recording. Data length is determined by the selected aggregate functions. The following fields may be present (in the given sequence):

FieldMinMaxCountAvgStdDevTypeDescription
MinimumX----DataType
AggregateCalcDataType if DataType=struct
The minimal value in the interval.
Maximum-X---DataType
AggregateCalcDataType if DataType=struct
The maximal value in the interval.
Count--X--always unsigned int64The number of data changes in the interval.
Sum---XXalways doubleThe weighted sum of all data in the interval.
tv_sec---XXalways unsigned int64The number of seconds of data recorded in the interval.
tv_nsec---XXalways unsigned int32The number of nanoseconds after the last second of data recorded in the interval.
SumSq----Xalways doubleThe sum of all squared weighted data values in the interval.

To calculate the average value in the interval: Avg = Sum / (tv_sec + tv_nsec / 1000000000)

To calculate the standard derivation in the interval: StdDev = sqrt(SumSq / (tv_sec + tv_nsec / 1000000000) - Avg * Avg)

Data types

NameSizeDescription
bit1 Bittruth value (false or true)
u8, u16, u32, u641-8 bytesunsigned integral types with 8-64 bit (1-8 bytes)
i8, i16, i32, i641-8 bytessigned integral types with 8-64 bit (1-8 bytes)
f32, f644 or 8 bytesIEEE-floating-point values with 32 or 64 bit (4 or 8 bytes)
stringvariablecharacter string, UTF-8 encoded
time12 byteUNIX timestamp, with resolution 1 nanosecond
structvariablestructured data type, encoded according to this rules
enum4 byteenumeration, always encoded as u32

Resolution values

The following resolutions are available for data acquisation:

Fastest
Save values as fast as the source generates them
Second
Save at most one value per second
Minute
Save at most one value per minute
Hour
Save at most one value per hour
Day
Save at most one value per day

The following resolutions are available for file rotation:

Hour
Start a new file at the beginning of each hour (UTC time): 2000-01-01 00:00, 2000-01-01 01:00, 2000-01-01 02:00, ...
Day
Start a new file at midnight (UTC time) of each day: 2000-01-01 00:00, 2000-01-02 00:00, 2000-01-03 00:00
Week
Start a new file at midnight (UTC time) of each monday: 2000-01-03 00:00, 2000-01-10 00:00, 2000-01-17 00:00, 00
Month
Start a new file at midnight (UTC time) of the first day of each month: 2000-01-01 00:00, 2000-02-01 00:00, 2000-03-01 00:00, ...
Year
Start a new file at midnight (UTC time) of january 1st: 2000-01-01 00:00, 2001-01-01 00:00, 2002-01-01 00:00, ...

Historian REST interface

The HistorianAPI is a Websocket Interface that transfers JSON data. By default it is listening on port 8081. This can be changed by editing ConfigServer.Settings.

All API requests expect an UTF-8 encoded JSON object. The following properties are used for all requests:

More properties may exist, depending on the function to execute. Any unknown properties are silently ignored. For future compatibility avoid sending undocumented properties.

All API answers are returned as an UTF-8 encoded JSON object. The following properties always exist:

More properties may exist, depending on the function to execute. For future compatibility, the client should ignore any properties it does not recognize.

Function "Historian/Read"

Reads historical values.

Additional request properties:

Notes:

Additional response properties:

example request:

{
 "function": "Historian/Read",
 "id": 12345,
 "variable": "New Variable",
 "valuecount": 100,
 "start": "2021-04-20T11:30:00Z",
 "stop": "2021-04-20T11:30:10Z",
 "resolution": "second",
 "aggregate": "avg"
}

example response:

{
 "function": "Historian/Read",
  "id": 12345,
  "status": 0,
  "variable": "New Variable",
  "values": [
   { "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 },
   { "quality": 0, "time": "2021-04-20T11:30:02Z", "value": 11 },
   { "quality": 0, "time": "2021-04-20T11:30:04Z", "value": 12 },
   { "quality": 0, "time": "2021-04-20T11:30:06Z", "value": 13 },
   { "quality": 0, "time": "2021-04-20T11:30:08Z", "value": 14 },
   { "quality": 0, "time": "2021-04-20T11:30:10Z", "value": 15 },
  ],
 "blocked": false
}

Function "Historian/Write"

Writes historical values. The Historian only supports adding values in sequential order. Values that are passed out of sequence are silently ignored.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/Write",
 "id": 12345,
 "variable": "New Variable",
 "values": [
  { "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 },
  { "quality": 0, "time": "2021-04-20T11:30:02Z", "value": 11 },
  { "quality": 0, "time": "2021-04-20T11:30:04Z", "value": 12 },
  { "quality": 0, "time": "2021-04-20T11:30:06Z", "value": 13 },
  { "quality": 0, "time": "2021-04-20T11:30:08Z", "value": 14 },
  { "quality": 0, "time": "2021-04-20T11:30:10Z", "value": 15 },
 ]
}

example response:/

{
 "function": "Historian/Write",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/AddVariable"

Adds a new variable to the Historian. Variables are identified by a unique name. Calling this function with a name that already exists allows changing some properties. When trying to change properties that are not changeable (especially anything that affects file storage format), an error occurs.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/AddVariable",
 "id": 12345,
 "variable":
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
}

example response:

{
 "function": "Historian/AddVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/DeleteVariable"

Deletes a variable from the Historian. In case of file logging, the data files are not removed.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/DeleteVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/DeleteVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/ReadVariable"

Reads a variable configuration from the Historian.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ReadVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/ReadVariable",
 "id": 12345,
 "status": 0,
 "variable":
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
}

Function "Historian/ListVariables"

Reads the list of variable configurations from the Historian.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ListVariables",
 "id": 12345,
 "startoffset": 0,
 "variablecount": 100
}

example response:

{
 "function": "Historian/ListVariables",
 "id": 12345,
 "status": 0,
 "variables": [
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
 ],
 "blocked": false
}

Function "Historian/ReadGlobalSettings"

Reads the global settings object of the historian

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ReadGlobalSettings",
 "id": 12345
}

example response:

{
 "function": "Historian/ReadGlobalSettings",
 "id": 12345,
 "status": 0,
 "mindiskspace": 1000
}

Function "Historian/WriteGlobalSettings"

Writes the global settings object of the historian

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/WriteGlobalSettings",
 "id": 12345,
 "mindiskspace": 1000
}

example response:

{
 "function": "Historian/WriteGlobalSettings",
 "id": 12345,
 "status": 0
}

Function "Historian/ReadChangeTimestamp"

Reads the timestamp of the last historian variable change (addition, modification or deletion).

Additional request properties:

Additional response properties:

example request: {
 "function": "Historian/ReadChangeTimestamp",
 "id": 12345
}
example response: {
 "function": "Historian/ReadChangeTimestamp",
 "id": 12345,
 "status": 0,
 "time": "2021-04-20T11:30:00Z"
}

Function "Historian/DiagVariable"

Reads diagnostic information for a historian variable.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/DiagVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/DiagVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable",
 "starttime": "2021-04-20T11:30:00Z",
 "currenttime": "2021-04-20T11:30:10Z",
 "currentquality": 0
}

Function "Historian/ReadStruct"

Reads structure information for a historian variable. Can be used to decode structured data.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ReadStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

example response:

{
 "function": "Historian/ReadStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure",
 "structcomment": "commment text ...",
 "structdata": [
  {
   "name": "element 1",
   "type": "uint8",
   "arraylength": 10
  },
  {
   "name": "element 2",
   "type": "uint32"
  }
 ]
}

Function "Historian/WriteStruct"

Writes structure information for a historian variable. The Historian doesn't use this, but it can be read back via "Historian/ReadStruct".

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/WriteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure",
 "structcomment": "commment text ...",
 "structdata": [
  {
   "name": "element 1",
   "type": "uint8",
   "arraylength": 10
  },
  {
   "name": "element 2",
   "type": "uint32"
  }
 ]
}

example response:

{
 "function": "Historian/WriteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

Historian/ListStructs

Lists structure information for a historian variable.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ListStructs",
 "id": 12345,
 "variable": "New Variable",
 "startoffset": 0
}

example response:

{
 "function": "Historian/ListStructs",
 "id": 12345,
 "variable": "New Variable",
 "structs": [
  {
   "structname": "New Structure",
   "structcomment": "commment text ...",
   "structdata": [
    {
     "name": "element 1",
     "type": "uint8",
     "arraylength": 10
    },
    {
     "name": "element 2",
     "type": "uint32"
    }
   ]
  }
 ]
}

Function "Historian/DeleteStruct"

Deletes structure information for a historian variable.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/DeleteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

example response:

{
 "function": "Historian/DeleteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

value objects

properties:

example:

{ "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 }

variable object

general properties:

  • "enabled": boolean, optional, true if variable is enabled (uses memory and license), false if variable is disabled (doesn't work, does not use memory or license, can be reenabled if needed); default false
  • properties for OPC data acquisation:

    properties for data storage:

    example:

    {
     "name": "New Variable",
     "type": "uint16",
     "enabled": true,
     "opc_enabled": true,
     "opc_conn": "S7-1500",
     "opc_variable": "Datablocks.OPC_DB.Temperature",
     "opc_resolution": "second",
     "file_save": false,
     "mem_size": 100
    }

    structure element object

    properties:

    structure layout rules:

    resolution values

    aggregate values

    ISO-8601 time format

    note: this is only a subset of ISO-8601

    2021-04-20T11:30:10.123+00:00
    ^    ^  ^  ^  ^  ^  ^  ^------- optional Timezone offset, allowed are "Z" (UTC)
    |    |  |  |  |  |  |           or a zone difference in hours (and optionally
    |    |  |  |  |  |  |           minutes), positive is east, UTC if not given
    |    |  |  |  |  |  +---------- optional second fractions, up to 9 digits are
    |    |  |  |  |  |              supported
    |    |  |  |  |  +------------- second, always 2 digits
    |    |  |  |  +---------------- minute, always 2 digits
    |    |  |  +------------------- hour, always 2 digits, 24-hour format
    |    |  +---------------------- day, always 2 digits
    |    +------------------------- month, always 2 digits
    +------------------------------ year, always 4 digits

    Other ISO-8601 formats (e.g. week numbers, day-of-year, ...) are not supported. All returned timestamp values are in UTC.

    Data types

    Status codes

    Other numbers signal an unspecified or undocumented error. Please contact TANI support in such cases.

    Quality codes

    Other numbers signal an unspecified or undocumented error. Please contact TANI support in such cases.