Test Telemetry

Experiment with sending Telemetry to the Agent REST API (Windows).

The maiLink Agent contains a REST API interface to which you can send Telemetry messages. Those messages are in the form of JSON data packets that must be formatted according to the maiLink Agent REST API Specification.

Getting Started

  1. Install the maiLink Agent on your computer using these instructions. It’s important that 1) the Agent is installed on the machine that will generate the telemetry, and 2) the Agent is up and running. You can check that everything is OK using the Windows Services tool (press Windows+R and type services.msc then press Enter) and scroll down to verify that maiLink Agent status is running.

  1. Open a PowerShell window, running it as administrator.
  2. Give yourself permission to run PowerShell scripts by entering the following command:
> Set-ExecutionPolicy unrestricted
  1. Create a working directory such as C:\Users\<your_name>\telemetry.
> cd ~
> md telemetry
> cd telemetry

■ Example: Sending Individual Metrics

The first PowerShell script accepts two command line parameters, creates a JSON data object, and pushes it to the Agent REST API.

  1. Open a new text file.
> notepad.exe sendMetric.ps1
  1. Copy and paste the following code into the editor, then save it.
# sendMetric.ps1 -- a simple Metric sender
#
# Usage: sendMetric [label] [value]

param(
    $label,
    $value
)

$json = "{""type"":""metric"",""label"":""" + $label + """,""value"":" + $value + "}"
$returnvalue = Invoke-RestMethod -Method Post -Uri "http://localhost:5465/mailink/v1/telemetry" -ContentType 'application/json' -Body $json
  1. Run the script a number of times, slightly changing the value while keeping the label gateTemp__C the same. This will start to build up data in the maiLink Telemetry Metrics database.
> .\sendMetric gateTemp__C 39.2
> .\sendMetric gateTemp__C 39.3
> .\sendMetric gateTemp__C 39.5
> .\sendMetric gateTemp__C 39.2
> .\sendMetric gateTemp__C 39.1
> .\sendMetric gateTemp__C 39.0
> .\sendMetric gateTemp__C 22.0
> .\sendMetric gateTemp__C 44.0

If your repeat this command a number of times, slightly changing the value while keeping the label gateTemp__C the same, you will start to build up data in the maiLink Telemetry Metrics database. Note that the time when you run the script defines the times associated with each data point – the Agent creates the timestamps for you.

JSON Data Object

The JSON data object for one of the single telemetry messages is simple:

{
    "type": "metric",
    "label": "<label>",
    "value": <value>
}

■ Example: Sending Batch Metrics

  1. Open a new text file.
> notepad.exe generateBatchMetrics.ps1
  1. Copy and paste the following code into generateMetrics.ps1 and save it.
# generateBatchMetrics.ps1 -- a maiLink Telemetry data generator
#
# Use this script to generate a number of geometric waveforms that are sent to the cloud, with a batch
# sent for each time point. The waveforms are:
#
#    Waveform  Description
#    --------  ---------
#    cos       Cosine
#    coshalf   Half-wave cosine
#    sin       Sine
#    sinhalf   Half-wave sine
#    tan       Tangent (clipped to +/- 100)


# Put all the functions requested into an array.
$functions = $("cos", "coshalf", "sin", "sinhalf", "tan")

$pi = [math]::PI
$delta = $pi / 72.   # For 10 cycles per hour (1 cycle every 360 seconds) need 72 samples at 5 second rate).
For ($t=0.0; $t -lt 10*$pi; $t+=$delta) {

    $json = "{""items"":["
    For ($l=0; $l -lt $functions.Length; $l++) {
        $label = $functions[$l]
        switch ($label) {
            "cos" {$value = [math]::cos($t)}
            "coshalf" {$value = [math]::abs([math]::cos($t))}
            "sin" {$value = [math]::sin($t)}
            "sinhalf" {$value = [math]::abs([math]::sin($t))}
            "tan" {$value = [math]::min([math]::max([math]::tan($t),-100.),100.)}
        }
        
        # Here is the content from sendMetric.ps1
        $json += "{""type"":""metric"",""label"":""" + $label + """,""value"":" + $value + "},"
    }
    $json = $json.Substring(0,$json.Length-1)
    $json += "]}"
    $returnvalue = Invoke-RestMethod -Method Post -Uri "http://localhost:5465/mailink/v1/telemetry/batch" -ContentType 'application/json' -Body $json

    Write-Host "." -NoNewline 
    Start-Sleep -Seconds 5.0
}
  1. Run the script. It generates a series of batch JSON data objects and sends one to the Cloud every 5 seconds. You only have to run it once … it will continue running for about an hour.
> .\sendBatchMetrics

You can visualize as many as four of the metrics at once. Just change the Query strings to any of these:

Metric Query String
cos cos{device=“device.id”}
coshalf coshalf{device=“device.id”}
sin sin{device=“device.id”}
sinhalf sinhalf{device=“device.id”}
tan tan{device=“device.id”}

JSON Data Object

The JSON data object for one of the batch telemetry messages looks like:

{
    "items": [
        {
            "type": "metric",
            "label": "cos",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "coshalf",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "sin",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "sinhalf",
            "value": <value>
        },
        {
            "type": "metric",
            "label": "tan",
            "value": <value>
        }
    ]
}

Cleaning Up

At present there is no way to delete experimental telemetry data that you may have sent to the Cloud using the instructions above. Be aware that after 90 days all telemetry data ages out of the Cloud database and is thus lost. This includes both variable names and data points (if a variable name has not been transmitted to the Cloud with telemetry data in the last 90 days, it too is removed).