Using Direct Methods in ThingsPro Agent

ThingsPro Agent offers the following six direct methods that can we invoked when a device is online.

No	Method Name	Description
1	thingspro-api-v1	Universal direct method that invokes all Restful APIs of ThingsPro Edge
2	system-reboot	Restarts a Moxa device
3	thingspro-applications-control	Controls run-time applications on the device
4	thingspro-software-upgrade	Performs over-the-air (OTA) software upgrades
5	message-policy-get	Retrieves the D2C message policy applied to your device
6	message-policy-put	Updates the D2C message policy applied to your device

Invoking ThingsPro APIs Using the ThingsPro Agent Universal Method

The universal direct method thingspro-api-v1 can be used to invoke all Restful APIs on the ThingsPro Edge device. A complete list of the ThingsPro Edge Restful APIs is available here.

• Method Name

  thingspro-api-v1

• Request Payload: (Example to set SSH configuration)

  {
      "path":"/system/sshserver",
      "method":"PUT",
      "headers":[],
      "requestBody": {"enable": true, "port": 22}
  }

  No	Name	Description
  1	path	ThingsPro Edge Restful API endpoint
  2	method	The method associated with the API endpoint
  3	headers	Required by the application/JSON payload
  4	requestBody	Used to post data required by the API endpoint

• Response

  {
      "status":200,
      "payload":{"data":{"enable":true,"port":22}}
  }

• Example

  

  Note: We recommend changing the following time-out parameters to prevent system exceptions.

  • Connection Timeout: Within 30 seconds
  • Method Timeout: Within 60 seconds.

Restarting a Device

The system-reboot method can be used to trigger a device to reboot immediately.

• Method Name

  system-reboot

• Request Payload

  {}

• Response

  {
      "status": 200,
      "payload": {
          "data": "rebooting"
      }
  }

Controlling Runtime Applications

The thingspro-applications-control direct method offers you a quick way to start/stop/restart applications running on ThingsPro Edge.

• Method Name

  thingspro-applications-control

• Request Payload

  {
      "appName": "modbusmaster-tcp",
      "command": "stop"
  }

  No	Name	Description
  1	appName	The name of the applications running on and managed by ThingsPro Edge. You can get the complete application list using the ThingsPro Restful API for the same.
  2	command	Supported commands: - start - stop - restart

• Response

  {
      "status": 200,
      "payload": {
          "data": ""
      }
  }

Upgrading Software

The thingspro-software-upgrade direct method allows you to download software over the air and upgrade your device remotely.

• Method Name

  thingspro-software-upgrade

• Example: Triggering download and installation for an upgrade job

  • Request Payload

    {
        "downloadURL": "http://xxx/edge/87/doc_0.1.0-87_armhf.yaml",
        "runInstallation": true
    }

    No	Name	Description
    1	downloadURL	The URL to download the software to
    2	runInstallation	true: The installation task will auto start after the download task is completed

  • Response

    {
        "status": 200,
        "payload": {
            "data": {
                "id": 1
            }
        }
    }

• Example: Triggering a software download job

  • Request Payload

    {
        "downloadURL": "http://xxx/edge/87/doc_0.1.0-87_armhf.yaml",
        "runInstallation": false
    }

    No	Name	Description
    1	downloadURL	The URL to download the software to
    2	runInstallation	false: The installation task doesn't start by default. You can invoke the next direct method to launch it.

  • Response

    {
        "status": 200,
        "payload": {
            "data": {
                "id": 2
            }
        }
    }

• Example: Triggering an installation for an upgrade job ID

  • Request Payload

    {
        "id": 2,
        "runInstallation": true
    }

    No	Name	Description
    1	runInstallation	The value shall always be true for this case.
    2	id	The ID returned by the previous direct method.

  • Response

    {
        "status": 200,
        "payload": {
            "data": {
                "id": 3
            }
        }
    }

Note:

1. ThingsPro agent will send back the upgrade progress and status via Reported Properties.

   • Report download progress

     

   • Download success

     

2. ThingsPro Edge allows only one active software upgrade job at a time.

Retrieving the Telemetry Message Policy

The message-policy-get direct method retrieves the telemetry (D2C) message policy applied to a device.

• Method Name

  message-policy-get

• Request Payload

  {}

• Response

  {
    "status": 200,
    "payload": {
      "data": {
        "groups": [
          {
            "id": 1,
            "enable": false,          
            "format": "",
            "outputTopic": "sample",
            "pollingInterval": 2,
            "properties": [
              { "key": "messageType", "value": "deviceMonitor" }
            ],
            "sendOutThreshold": { "size": 4096, "time": 5 },
            "tags": { 
                "system": { "status": ["cpuUsage", "memoryUsage"] }
            }
          }
        ]
      }
    }
  }

  No	Name	Description
  1	groups	The message group; you can define multiple messages by demand
  2	id	The message ID
  3	enable	Enable or disable this message policy
  4	format	A jq script to transform a default payload to a custom payload
  5	outputTopic	The output topic required by Azure IoT Edge; helps manage the message route in Azure IoT Edge
  6	pollingInterval	The interval at which to poll tag data. For example, - value 10 : Every 10 second - value 0 : when the data is pushed into the tag (almost real time)
  7	properties	Application properties of the message. This allows cloud applications to access certain messages without deserializing the JSON payload.
  8	sendOutThreshold	Define conditions to send out messages to Azure Edge Hub based on: - message size - time (value 0 : almost real time)
  9	tags	The tag data to send in the message. You can retrieve all available tags defined by ThingsPro Edge RESTful API.

Updating the D2C Message Policy

This direct method message-policy-put allows you to apply a telemetry (D2C) message policy to a device.

• Method Name

  message-policy-put

• Request Payload

  {
    "groups": [
      {
        "enable": true,
        "outputTopic": "sample",
        "format": "",
        "properties": [
          { "key": "messageType", "value": "deviceMonitor" }
        ],
        "tags": { 
            "system": { "status": ["cpuUsage", "memoryUsage"] }
        },
        "pollingInterval": 2,
        "sendOutThreshold": { "size": 4096, "time": 5 }
      }
    ]
  }

Transforming a Default Payload to a Custom Payload

The D2C message policy allows you to transform a default payload to your desired payload schema via a jq filter. For additional details, visit the jq website (https://stedolan.github.io/jq/manual/).

ThingsPro Edge Web GUI offers a easy way to apply the jq filter and test the transformed result as shown in the following examples.

• Default D2C message schema

  Select the tags that you want using the tag-selector panel on the left. The default result for the selected tags will show in the right panel.

  

• Custom payload after transforming the default payload

  Enable custom payload and and input the jq Filter to display the custom payload for your selection.

  

• ThingsPro Agent offers the following variables to print information to your payload:

  No	Variable	Description
  1	.srcName	Prints the source of the tag data
  2	.tagName	Prints the tag name
  3	.dataValue	Prints the tag value
  4	.ts	Prints the timestamp of tag value be collected
  5	.dataUnit	Prints data unit of tag value (e.g.: %)
  6	.dataType	Prints data type of tag value (e.g.: int64)

  NOTE: If you would like to include the above variables as the key of a JSON element, use parentheses as shown here.

  (.tagName): .dataValue

• Custom payload: Example 1

  jq Filter:

  {device:(.srcName),timestamp:(now|todateiso8601),(.tagName):.dataValue}

  

• Custom payload: Example 2

  jq Filter :

  {device:(.srcName),timestamp:(now|todateiso8601),tag: [{TagName:(.tagName), Value:.dataValue}]}

  

• After confirmed the jq Filter, you can include the "format" element into the D2C message policy to enable a custom payload.

  {
    "groups": [
      {
        "enable": true,
        "outputTopic": "sample",
        "format": "",
        "properties": [
          { "key": "messageType", "value": "deviceMonitor" }
        ],
        "tags": {
          "system": {
            "status": ["cpuUsage", "memoryUsage"]
          }
        },
        "pollingInterval": 2,
        "sendOutThreshold": { "size": 4096, "time": 5 },
        "format": "{device:(.srcName),timestamp:(now|todateiso8601),TagName:(.tagName), Value:.dataValue}"
      }
    ]
  }

Last updated on 2022-07-22 by Cecilia Fernandes