JSON Schema for Custom Plugin Connector

JSON Schema for Custom Plugin Connector

October 9, 2020
TeamViewer IoT Documentation

An example template:

{
    "sensors": [
        {
            "name": "opcua_node_aa",
            "monitoringService": "python /usr/local/teamviewer-iot-agent/monitoring/opc-ua/opc_ua_connect.py",
            "monitoringParams": "--url opc.tcp://myopcuahost:26543 --nodeId "opcua_node_id" --frequency 2",
            "metrics": [
                {
                    "name": "opcua_node_id",
                    "key": "opcua_node_id",
                    "valueType": "double",
                    "valueAnnotation": ""
                }
            ]
        },
        ...
    ]
}

JSON Schema for Sensor Objects

FieldTypeRequiredDescription
SensorJSON Object  
nameStringYesDisplay name of the sensor.
monitoringServiceStringYesFull path of your custom monitoring script.
frequencyInteger (seconds)NoIf frequency is set, the TeamViewer IoT Agent will run the script in the interval specified (e.g. every 10 seconds). If frequency is not set, the TeamViewer IoT Agent will run the script once upon start up.  This assumes that the scheduler is organized within your custom monitoring script and new values of metrics are printed upon their change. Note that every new JSON message should be printed on a new line.
monitoringParamsStringNoAdditional arguments to pass to the script. E.g. url, host, sensorId etc. This field is useful for cases when you want to use same script to monitor several sensors of the same type.

JSON Schema for monitoringParams Objects

FieldTypeRequiredDescription
urlStringyesOPC UA server url
nodeIdStringyesId of the node specified by the given OPC UA server.
frequencyIntegernoThe frequency (in seconds) to poll for new node values.

If not set, frequency defaults to 1-time execution.

JSON Schema for Metric Objects

FieldTypeRequiredDescription
MetricsJSON Array  
nameString Display name of the metric
keyString Short name (identifier) of the metric. It should be used as a key in the JSON output of the monitoring script.
valueTypeEnum Indicates the type of the metric. Possible values are: integer / double / string.
valueAnnotationString The unit of measure which will be displayed as the name of the Y axis when displaying metric values on a chart. Commonly used annotations are: %, C, Pa, req/sec, MB, etc.

Monitoring Configuration File

After the sensor/metric is registered by the agent, the agent auto-generates the parameters sensorId and metricId and adds them as properties to the configuration file.

To avoid data loss. Before editing the configuration file, create a backup.
Avoid historical data loss. Do not change any sensorId or metricId after they are added to the configuration file.

Monitoring Frequency

Monitoring frequency can be controlled either by the agent’s Monitoring Configuration File (parameterfrequency) or by your custom script. In the JSON Sensor (see example below), the frequency is specified by the configuration property, causing the agent to run your script every 10 seconds.

{
   "sensors": [{
		"name": "temperature_humidity_sensor1",
		"monitoringService": "/usr/local/teamvieweriot/sensors/temperature_humidity/monitor.sh",
		"monitoringParams": "sensor1 sdkCredential",
                "frequency": 10,
		   "metrics": [{
		      "name": "Temperature",
		      "key": "temperature",
		      "valueType": "double",
		      "valueAnnotation": "C"
		    }, {
	              "name": "Humidity",
		      "key": "humidity",
	              "valueType": "double",
		      "valueAnnotation": ""
		    }]
		},
		...
	]
}

There may be scenarios where the frequency of the data collection should be set by your script rather than specified in the agent’s Monitoring Configuration File. In these scenarios, the parameter frequency in the configuration file should be left blank.

Use Case: You want to monitor discrete events which don’t have a defined frequency (event-based metrics

  • e.g. monitoring when a door is opened or closed
  • within your custom script, you subscribe to a message queue to get door movement events and print them to stdout.

Generic example:

var queue = new Queue();
queue.openConnection();
queue.createSubscription(callback);

function callback(value) {
     print {"key":value};
}

Use Case: You want to set up high frequency monitoring (e.g. 1 second)

Although this can be done by configuring the parameter frequency in the agent’s Monitoring Configuration File, an optimal solution may be use a loop in your script to print new metric values every second.

Generic example:

var networkObject = new NetworkObject();
networkObject.openConnection();

try {
    while (true) {
    var value = networkObject.getValue();
    print {"key":value};
    sleep(1000);
    }
}
finally
{
  connection.close()
}

Related posts

Want more? Exclusive deals, the latest news: Our Newsletter!