Skip to content

Metrics Guardrail

Assets data is crucial to operations and if extreme values are written to the asset this can have a significant impact on the reliability of the asset and production.

To ensure extreme values can not be written to the asset there are a number of guardrails that can be implemented;

A guardrail is either a method than ensures no value outside of the min/max limits can be entered.

Or it is a safety monitor that will reject and drop any Control Change requests outside of the min/max limits.

Program Level Guardrail

This guardrail is configurable for each Asset.

Within any program, all outputs that will be sent as Control Changes or Recommendations should be checked against a hard-coded min/max limits or checked against a defined Asset Property.

Asset Properties are user defined values that are created when an Asset is created on the Kelvin Platform.

They can be defined for anything deemed useful by the client such as max rpm of a motor, min/max operational temperatures or min/max setpoint limits.

The advantage of using Asset Properties is that similar Assets could have different safety operational limits defined by the manufacturer. Even though the Assets may be controlled in the same way by the same Kelvin SmartApp™ or Workload, the manufacturing specs can be linked to each Asset and referenced by the any program.

This is part of the Best Practices for Developers when writing scalable programs for Kelvin SmartApps™ or Workloads.

Kelvin UI Guardrails

This guardrail is configurable for each Kelvin SmartApp™ in the app.yaml Template.

When a Kelvin SmartApp™ is deployed, it may have a number of Asset Parameters that can be set by Operations through the Kelvin UI.

To ensure extreme values can not be accidentally entered by Operations, a min/max values limits can be set for the Asset Parameters.

This can only be set for data_type number and text.

app:
  kelvin:

    assets:
      - name: asset-1
        # Asset parameter values are defined here
        parameters:
          my-param:
            value: 5.22
            - name: asset-2
        # Asset parameter values are defined here
        parameters:
          my-param:
            value: 2.47

    inputs:
      - name: temp
        data_type: raw.int32

    outputs:
      - name: temp_setpoint
        data_type: raw.int32
        control_change: true

    parameters:
      - name: my-param
        data_type: number
        default:
          value: 2.2
        schema:
          type: number
          title: My Param
          description: This is My Param.
          minimum: 0                      <===== Guardrail Min Value
          maximum: 10                     <===== Guardrail Max Value

Connection Guardrail (Last Defense)

This guardrail is configurable for each Asset.

If for any reason an extreme value makes it into a Control Change and sent to the Connection for updating the Asset, the last line of defense to filter out extreme values is in the actual Connection handling the data between Kelvin and the Asset.

To ensure the assets never receives control changes that are outside of operational limits, a metric guardrail that limits the values that can be sent to the asset can be added to the Connection Metric to reject values outside of the operational limits.

A metric guardrail option is not available when deploying a Connection from the Kelvin UI.

Guardrails are added as max/min keys in the metrics_map section of the JSON body for the /api/v4/bridges/deploy API endpoint.

In this example the metrics is an address endpoint of an OPC-UA Connection.

This can be applied in the same manner for MQTT, Modbus and Emerson ROC Connections.

{

  .. other Connection information

  "payload": {

    ... other payload information

    "metrics_map": [
      {
        "name": "demo-metric",
        "asset_name": "demo-asset",
        "access": "RW",
        "data_type": "number",
        "configuration": {
          "node": "ns=4;i=1002",
          "polling_rate": 30,
          "scale_multiplier": null,
          "max": 150,                <====== Guardrail Max value
          "min": 75                  <====== Guardrail Min value
        }
      } 
    ]
  }
}

Guardrails are added as max/min keys in the metrics_map section of the JSON body for the payload.

In this example the metrics is an address endpoint of an OPC-UA Connection.

This can be applied in the same manner for MQTT, Modbus and Emerson ROC Connections.

from kelvin.api.client import Client

# Login
client = Client(config={"url": "https://<url.kelvin.ai>", "username": "<your_username>"})
client.login(password="<your_password>")

# Create Connection (Bridge)
response = client.bridge.deploy_bridge(data={

  ... specific Connection information

  "payload": {
    "metrics_map": [
      {
        "name": "demo-metric",
        "asset_name": "demo-asset",
        "access": "RW",
        "data_type": "number",
        "configuration": {
            "node": "ns=4;i=1002",
            "polling_rate": 30,
            "scale_multiplier": null,
            "max": 150,                <====== Guardrail Max value
            "min": 75                  <====== Guardrail Min value
        }
      }
    ]
  }
})