Predix Edge Deadband Application

Introduction

The Deadband App provides the ability to manage Edge sites to have the deadband enabled for the respective tags to filter the amount of data pushed and realize savings for the data and its cost associated with Predix Time Series.

Protocol Benchmarking

The Predix Edge Deadband App sits between the protocol adapter and the cloud gateway (data travels from a protocol adapter to the Predix Edge MQTT Broker to the Deadband App to Cloud Gateway to Time Series). The throughput is highly dependent on the protocol adapter acting as the source. Throughput details for each adapter are available in the adapter's corresponding section.

The effect of the Deadband app on throughput was calculated by adding the Deadband app and configuring the tags in such a way that all data is passes by the Deadband app and nothing is filtered. The tags configured in the Deadband app are the same as the maximum throughput of each adapter without the Deadband app. In such a case, a maximum of 25% degradation is observed in the throughput. However, this should be offset by a decrease in the number of tags sent due to deadband application in any real application.

Where Do I Get It-->

The Predix Edge Deadband App and sample configuration in the table below are stored in Artifactory. Use the following information to ensure you can access the files.

For GE Employees

To access Artifactory downloads, those using a GE email address must first be logged into Artifactory.

Note: If you attempt to download from Artifactory without first logging into Artifactory, you will be asked to Sign in, which will not work.

Go to Artifactory.
Click the Log In button.
Click the SAML SSO icon.
Use your SSO to log in.
You can then return to the documentation link to access Artifactory.

For Predix Users

To access Artifactory links in the Predix Edge documentation, you must first create an account on predix.io. Your predix.io account sign in credentials will be used to access Artifactory.

When you click an Artifactory link, enter your predix.io username (email address) and password in Artifactory's Sign In dialog.


Application	Config
Predix Edge Deadband App	Sample Config

Overview of Capabilities

Currently supported capabilities:

Absolute and Percent value deadband
Deadband timeout
Configurable subscribe and publish topics on Predix Edge MQTT broker

Details of Capabilities

The Deadband app is mainly used for filtering data. It subscribes to the value of the listenTopic key and applies deadband on the data as per the configuration. It then sends the data after the deadband has been applied to the publishTopic. The deadband configuration is on a per tag basis. The deadband type can be specified as either absolute or percent. The value can be any numeric value in the case of absolute deadband and should be less than 100 in the case of percent deadband. The timeout is specified in milliseconds.

For every tag received, the following deadband logic is applied.

Absolute Deadband

If the absolute difference between the current value of the tag and the last sent value of the tag is greater than the deadband value, the current value of the tag is sent. The current value and current time are stored as last sent value and last sent time respectively for use in the next comparison cycle. If the absolute difference is less than the deadband value, the current time is compared against the last sent time and if the difference is greater than the timeout, the current value of the tag is sent. Otherwise it is filtered.

Percent Deadband

If the absolute difference between the current value of the tag and the last sent value of the tag is greater than the deadband value percentage of last sent value, the current value of the tag is sent. The current value and current time are stored as last sent value and last sent time respectively for use in the next comparison cycle. If the absolute difference is less than the deadband value percentage of last sent value, the current time is compared against the last sent time and if the difference is greater than the timeout, the current value of the tag is sent. Otherwise it is filtered.

Configuration Details

The parameters in the configuration file are shown below:

Table 1.
Field	Type	Required	Default
listenTopic	String	Yes
publishTopic	String	Yes
tags	Object	Yes
log_level	String	No	off
clientid	String	Yes
qos	Integer	No

`listenTopic`

The listenTopic field determines the MQTT topic on which this app listens for incoming data.

`publishTopic`

The publishTopic field determines the MQTT topic on which this app publishes the filtered data.

`tags`

The tags field defines the variables on which deadband is to be applied. The tags is an object of the following structure.

Table 2.
Field	Type	Required
<variable name 1>	String	Yes
<variable name 2>	String	No
...	String	No

The fields <variable name 1>, <variable name 2>, etc. represent individual variable names for which the values are objects that have the deadband details below.

Table 3.
Field	Type	Required
type	String	Yes
value	Any numeric	Yes
timeoutInMS	Integer	Yes

type determines the type of deadband; possible values are absolute and percent

value is the deadband value to be used
timeoutInMS is the timeout value (in milliseconds) to be used during deadband calculation

`log_level`

For details about the log_level and log_name fields, see the Generic CDP Blocks section of the Protocol Adapters documentation page.

`clientid`

The clientid is used to specify the name of the client in the MQTT client options. It can be any unique string.

`qos`

The qos field is used to specify the qos (quality of service) to the MQTT client during publishing.

Sample Files

docker-compose.yml

version: "3.1"

services:
  edge-app:
    image: "predix-edge-deadband-app:amd64-latest"
    environment:
      config: "/config/config-deadband.json"
    networks:
      - predix-edge-broker_net
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 5
        window: 30s

networks:
  predix-edge-broker_net:
    external: true

config.json

{
	"tags": {
		"variable name 1": {"type": "absolute", "value": 2.5, "timeoutInMS": 100000 },
		"variable name 2": {"type": "percent", "value": 10, "timeoutInMS": 500000 }
	},
	"listenTopic":"timeseries_data",
	"publishTopic":"timeseries_data_deadband",
	"clientid":"predix-edge-deadbanding",
	"qos":1,
	"log_level": "warn"
}