Custom Plugin Connector - How to easily integrate your IoT Sensors

Highlighted
Posted by TeamViewer Staff
TeamViewer Staff

Custom Plugin Connector - How to easily integrate your IoT Sensors

This article applies to all TeamViewer IoT users who want to connect and monitor their IoT sensor network.

The solution presented in this article requires TeamViewer IoT Agent v 1.1.102 (or higher).  To identify the version of your agent, run: sudo teamviewer-iot-agent info (an error, or no result, indicates an older version of the agent is installed).

The IoT world is comprised of diverse communities, some who love to write code, and some who don't.  For those who don't, this guide allows you to easily integrate your IoT Sensors with the TeamViewer IoT Agent without having to write much code.

This guide is for users who:

  1. Have a TeamViewer IoT Agent installed (version 1.1.12 or later)
  2. Want to monitor sensor metrics
  3. Don't want to interact with the TeamViewer IoT Agent API directly

Overview

This guide will allow you to integrate your own script (which retrieves sensor/metric values) with the TeamViewer IoT Agent.  The agent will allow you to easily register your sensor metrics and will call your monitoring script at defined intervals to retrieve metric values.

Step 1 - Creating your Custom Monitoring Script

Before you can integrate your sensors to the TeamViewer IoT Agent, you need to define what metrics you want to monitor and be able to write a shell script which retrieves them from your sensor.

This guide does not go into how to write a shell script but identifies the requirements of the script to integrate it with the TeamViewer IoT Agent.

Your custom script:

  • should retrieve your sensor metric's current value
  • should print to the console the metrics you want to monitor in JSON format {key:value}, where key is the metric identifier and value is the current value of the metric.
    • e.g. if you have a sensor which measures temperature and humidity, then the output of the script will be {"temperature": 23,"humidity": 34} 
  • can have input arguments
  • should be saved/located on the device running the TeamViewer IoT Agent
    • e.g. /usr/local/teamviewer-iot-agent/monitoring/temperature_humidity/your_monitoring_script.sh

The generic example below shows what a script may look like with two example input arguments (sensor ID and credentials for your SDK) - which would be executed by:

./your_monitoring_script.sh sensor123 mypassword
your_monitoring_script.sh
--------------------------------------
var sensorId = args[0]; var credentialForSDK = args[1]; var sensorSDK = new SensorSDK(credentialForSDK); var humidity = sensorSDK.getHumidity(sensorId); var temperature - sensorSDK.getTemperature(sesnorId); print {"temperature":temperature_value, "humidity":humidity_value"}

Prior to moving to the next step, run the script and ensure a valid JSON is printed to the console. You can use any free online JSON validator to ensure the output is valid JSON.

 

Step 2 - Integrating your script with the TeamViewer IoT Agent

The TeamViewer IoT Agent includes its own system monitoring configuration file.  This configuration file will be extended to include your custom script.  As you are going to maually edit a system configuration file, ensure to create a backup of the file in the case the file gets corrupted by user error.

  1. Open for editing the TeamViewer IoT Agent monitoring configuration file located at:
    • /var/lib/teamviewer-iot-agent/system_monitors.conf
    • sensors are hosted under the "sensors" node of the configuration file
  2. For each sensor you want to integrate (e.g. temperature and humidity, luminosity, pressure, etc), you must append its registration information to the configuration file
  3. Save the configuration file.
  4. Restart the agent to reload the configuration file.

    • teamviewer-iot-agent restart

  5. Log into your TeamViewer IoT dashboard and verify that the Sensors/Metrics added to the configuration file now appear on your Metrics tab.

    • Pin the metrics to your dashboard and ensure the data is being updated per the frequency specified in the config file

 

JSON Configuration File Example:

{
"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": "" }] }, ... ] }

 

JSON Schema

Field

Type

Required

Description

Sensor:

JSON Object

 

 

name

String

Yes

Display name of the sensor.

monitoringService

String

Yes

Full path of your custom monitoring script.

frequency

Integer (seconds)

No

If 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. Please note that every new JSON message should be printed on a new line.

monitoringParams

String

No

Additional 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.

 

 

 

 

Metrics

JSON Array

 

 

name

String

 

Display name of the metric

key

String

 

Short name (identifier) of the metric. It should be used as a key in the JSON output of the monitoring script.

valueType

Enum

 

Indicates the type of the metric. Possible values are:

  • integer
  • double
  • string

valueAnnotation

String

 

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
Please note that corrupting the monitoring configuration file may lead to loss of all provisioned Operating System (OS) sensor/metrics.  To be able to recover from a file corruption, ensure to make a backup copy of the configuration file prior to editing.Also, note that after the sensor/metric is registered by the agent, the agent auto generate the sensorId and metricId parameters and adds them as properties to the configuration file. Changing these ID's will cause historical data loss. 
 
Monitoring Frequency
Monitoring frequency can be controlled either by the agent configuration file (frequency parameter) or by your custom script. In the JSON Sensor example, the frequency is specified by the configuration property, causing the agent to run your script every 10 seconds.There may be scenarios where the frequency of the data collection should be set by your script rather than specified in the agent monitoring configuration file.  In these scenarios, the frequency parameter in the configuration file should be left blank.A couple of use cases are described below:
  • 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.
    • Note: Every message/event should be printed to a new line
    • Generic example for use case 1:
      • var queue = new Queue();
        queue.openConnection();
        queue.createSubscription(callback);
        
        function callback(value) {
             print {"key":value};
        }
  • You want to setup high frequency monitoring (e.g. 1 second).  Although this can be done by configuring the frequency parameter in the agent monitoring configuration file, an optimal solution may be use a loop in your script to print new metric values every second.
    • Generic example for use case 2:
      var networkObject = new NetworkObject();
      networkObject.openConnection();
      
      try {
          while (true) {
          var value = networkObject.getValue();
          print {"key":value};
          sleep(1000);
          }
      }
      finally
      {
        connection.close()
      }