Appendix
  • 12 Jun 2024
  • 6 Minutes to read
  • PDF

Appendix

  • PDF

Article summary

WebUI Historical data interface

WebUI historical data interface is a rich HTML5 interface used for visualizing historical data. This section of N3uron allows users to configure various parameters in order to monitor the historical data of selected tags.

 

The following properties can be configured:

  • Tag list: A tree menu that shows all available historized tags. In order to visualize a tag’s historical data, drag and drop the tags in the Selected tags area.
  • Configuration: Visualization parameters available in Configuration area:
    • Date mode: Allows for different ways of specifying the start and end dates for displayed data.
      • Relative: Allows users to select the start and end date according to the current date.
      • Absolute: Allows users to select a start and end date as absolute dates.
      • Current: Allows users to select an interval between the current moment and a previous moment defined by the offset.
    • Date: Configuration for the different Date modes:
      • Relative: Start and end dates are configured using an offset in days or weeks and a time offset in milliseconds
        • Offset: Offset relative to current moment.
        • Time: Absolute offset over the relative offset.
      • Absolute: Allows dates to be specified as absolute values. 
        • Start: Absolute start date.
        • End: Absolute end date.
      • Current: Allows the date to be specified between a selected negative offset and the current moment.
        • Offset: Negative offset from current date.
        • Units: Offset units (seconds, minutes, or hours).
    • Mode: Configuration of data representations.
      • Aggregated: Allows users to aggregate data using different methods.
      • Raw: Presents data as per how it is stored in the historical database.
      • Delta: Only presents values when they have changed more than the deadband value. Includes all values after the change.
      • Filter: Only presents values when they have changed more than the deadband value. Includes all values before and after the change.
    • Mode configuration: Configuration properties for the different modes.
      • Aggregated:
        • Aggregation method: Aggregation type applied to the data. Choose between:
          • Tag configuration: Value configured within the tag.
          • Avg: Weighted-time average for the selected aggregation interval.
          • Min: Minimum value for the selected aggregation interval.
          • Max: Maximum value for the selected aggregation interval.
          • First: First value for the selected aggregation interval.
          • Last: Last value for the selected aggregation interval.
      • Aggregation interval: Interval for the aggregated data:
        • Value: Interval value.
        • Units: Value units.
      • Raw: No special configuration, raw values.
      • Delta and Filter:
        • Deadband: Defines the data change threshold.
    • User presets: Configuration properties can be saved as presets. Previously saved presets can be loaded via this parameter.

After applying the retrieval parameters in Configuration, the WebUI shows the historical data of the selected tags with the following options:

  • Autoreload: Enables a periodic reload of the data.
  • Return to configuration view.
  • Reload selected tags.
  • Download: Downloads a CSV file containing historical data.
  • Data visualization: Data can be visualized in two ways: a chart or a table with date/value representation.

 



Connecting Historian to MongoDB Atlas

The following steps will help you connect your Historian instance to an Atlas Cluster in a matter of minutes.

Prerequisites

  • An Atlas account.
  • An organization and project with an account's user who has permission to create clusters.
  • An active cluster created in this account.
  • An IP address added to your IP access list.
  • A Database user on your cluster.

Take a look at the MongoDB Documentation for more information.

NOTE:
You must have a database user set up on your cluster to access your deployment. Atlas requires clients to authenticate as database users to access clusters for security purposes.

Getting the Connection String from Atlas

You'll need to get your cluster's connection string from Atlas to connect your N3uron's Historian instance to the cluster using the Node.js driver.

  • Step 1: Click on Connect:
    • Click on Databases in the top-left corner of Atlas.
    • In the Database Deployments view, click on Connect for the database deployment to which you want to connect.

  • Step 2: Click on Connect your application:

  • Step 3: Select Node.js as the Driver and copy the connection string:


Configuring N3uron

  • Step 4: Select External as Database type and open the connection helper.
  • Step 5: Paste the connection string, replace the placeholders with the database user and password, then click Apply.


  • Step 6: Set the database name (e.g. history) and save the changes.If everything has been configured properly, once you configure some tags to store their historical values in your Atlas Cluster, you should be able to see how the data is automatically pushed from N3uron.


Connecting Historian to a self-managed MongoDB Replica Set

The following steps will help you connect the N3uron Historian to a self-managed MongoDB replica set deployment.

Example replica set with name rs0 (refer to this guide on deploying a replica set):

Build the MongoDB connection string

This is the standard connection URI format. Refer to the official documentation for more details.

mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]

For the example above the connection URL should be:

mongodb://username:password@mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017/n3-history?replicaSet=rs0

Configuring N3uron

  • Step 1: Go to the Historian module configuration and select External as the database type and mongodb as the protocol.

  • Step 2: Open the database connection helper, paste the connection URI created in the previous section, and click Apply.

  • Step 3: Review the module settings and click Save to load the changes.

Renaming Tags

Attention:
Before proceeding with the following procedure, it is imperative to validate the CSV file. Ensuring the accuracy and integrity of the CSV file is crucial for the proper execution of the process. 
Failure to validate the file may result in errors or unexpected outcomes. Take the necessary steps to validate the CSV file before proceeding further.

Note:
This feature is new in N3uron version 1.21.5.


Changing tag names while keeping the historical data of the time series is possible. To do this, it is necessary to follow these steps:

  • Step 1: Prepare a CSV file named tags_rename.csv with the following format: 
/oldName1,/newName1
/oldName2,/newName2
/oldName3,/newName3


  • Step 2: Stop the Historian module. (If data is received through links and Historian is configured with 'Pause links while unavailable'), remote nodes will pause sending data and will store it via S&F).
  • Step 3: Don't forget to make a backup of the module's configuration and the database.
  • Step 4: Make the corresponding changes in the data model and save them. 
  • Step 5: Save the CSV file (tags_rename.csv) to the Historian module folder inside data (On Windows: C:/Program Files/N3uron/data/Historian and on Linux: /opt/n3uron/data/Historian).
    Note:
    If the Historian instance to be renamed is different, then it should be stored in C:/Program Files/N3uron/data/<Historian module name> or /opt/n3uron/data/<Historian module name>.
  • Step 6: Restart the Historian module.


Internal Data Structure

The Historian module uses a custom structure and compact binary format to efficiently store time-series data using a MongoDB database.

The structure is as follows:

  • A collection named tags stores the tag name and its internal ID.
  • A collection is created each day with the format --> yyyy-mm-dd.samples
  • In each collection, a document is created per tag and hour, the ID of each document is composed of the numeric ID of the tag stored in the tags collection and the hour in UTC. For example, all events for a tag with ID 23 between 7:00 and 8:00 UTC are stored in the document with ID 2307.
  • Events are stored as entries inside the document, the key represents the millisecond within the hour and the value is an encoded binary object that contains the event data.
  • The binary object is encoded using the following serialization:
    • The first byte contains the quality according to the OPC standard (0 to 192).
    • The second byte contains the opcode which indicates the data type.
      • if opcode = 0: A boolean with the value false.
      • if opcode = 1: A boolean with the value true. 
      • if opcode = 2: The next 8 bytes contain a double value using big-endian ordering.
      • if opcode = 3: A null value.
      • if opcode = 4: The rest of the bytes contain a UTF8 string.
      • if opcode > 4: The value is an integer.
        • if bit 5 = 0: The value is smaller than 5 bits and is stored in the first 5 bits to the right.
        • if bit 5 = 1: The next bytes contain an integer with little-endian order.
        • if bit 6 = 0: The sign of the integer value is positive.
        • if bit 6 = 1: The sign of the integer value is negative.

Examples:

Opcode
Data type
Value
00000000
booleanfalse
00000001
booleantrue
00000010
doublenext 8 bytes as double
00000011
nullnull
00000100
stringnext bytes as UTF8 string
10001011
integer11
11010011
integer-19
10000011
integer3

Historian Full Product Details




 

 



Was this article helpful?

What's Next