Support Commands for Jobs

AWS IoT Core Client of ThingsPro Edge offered below 6 direct methods. You can invoke them when device is on-line.

No	Method Name	Description
1	thingspro-api-v1	An universal direct method, allow to invoke almost all Restful API of ThingsPro Edge.
2	system-reboot	A direct method to restart Moxa's device.
3	thingspro-applications-control	To control application run time on device.
4	thingspro-software-upgrade	To perform software upgrade over the air.
5	message-policy-get	To retrieve D2C message policy applied on device.
6	message-policy-put	To update D2C message policy on device.

You can create a job by the script provided below on the cloudshell page of AWS web portal.

[cloudshell-user@ip-10-0-156-5 ~]$ cat ./example-job.json 
{
  "name": "thingspro-api-v1",
  "payload": "{\"path\":\"/device/ethernets\",\"method\":\"GET\"}"
}
[cloudshell-user@ip-10-0-156-5 ~]$ cat ./test.sh 
#!/bin/sh
aws iot create-job \
    --job-id "example-job-01" \
    --targets "arn:aws:iot:ap-northeast-1:1234567890:thing/gary" \
    --document file://example-job.json \
    --description "example job test"

1. ThingsPro Universal Method

An universal direct method, to invoke almost all Restful API on ThingsPro Edge device. You can get ThingsPro Edge Restful API document at 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 which associated with API endpoint.
  3	headers	It shall always be application/json.
  4	requestBody	The post data which required by API endpoint.

• Response:

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

2. Restart Device

This command will trigger device to reboot immediately.

• Method Name:

  system-reboot

• Request Payload:

  {}

• Response:

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

3. Control Application runtime

This direct method offers you a quick way to start/stop/restart applications which running on ThingsPro Edge.

• Method Name:

  thingspro-applications-control

• Request Payload:

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

  No	Name	Description
  1	appName	The name of applications running and managed by ThingsPro Edge. You can get application list by ThingsPro Restful API.
  2	command	Support commands: - start - stop - restart

• Response:

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

4. Software Upgrade

This direct method allow you to download upgrade software over the air.

• Method Name:

  thingspro-software-upgrade

• Example to trigger download and installation at one 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 point to upgrade software location.
    2	runInstallation	value true : The installation task will auto start after download task completed.

  • Response:

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

• Example to trigger a download software only upgrade job

  • Request Payload:

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

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

  • Response:

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

• Example to trigger an installation for a upgrade job id

  • Request Payload:

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

    No	Name	Description
    1	runInstallation	Value shall always be true at this case.
    2	id	The Id returned from previous direct method.

  • Response

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

5. Get D2C Message Policy

This direct method retrieves telemetry (D2C) message policy applied on 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	Message group, you can define multiple messages by demand
  2	id	The identity of this message
  3	enable	Enable or disable this message policy
  4	format	A jq script for you to transform default payload to custom payload
  5	outputTopic	The output topic which requires by Azure IoT Edge. This helps user manage message route in Azure IoT Edge.
  6	pollingInterval	Define what interval to poll tag data back. For example: - value 10 : Every 10 second - value 0 : when the data be push into tag (almost real time)
  7	properties	Application properties of the message. This allows cloud applications to access certain messages without deserializing JSON payload.
  8	sendOutThreshold	Define conditions to send out message to Azure EdgeHub by either or on: - message size - time (value 0 : almost real time)
  9	tags	The tag data you would like to send out on message. You can retrieve all available tags defined by ThingsPro Edge Restful API.

6. Update D2C Message Policy

This direct method allow you to apply telemetry (D2C) message policy on 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 }
      }
    ]
  }

6.1 Custom Payload

D2C message policy allow you to transform default payload to your desired payload schema via jq filter. You can access jq web site (https://stedolan.github.io/jq/manual/) for detail information.

ThingsPro Edge Web GUI offered a friendly interface allow you to apply jq filter and test the transform result, here are some example screen shots :

• Default D2C message schema

  You can select tags via left hand-side tag selector, and, the default result show on right hand-side area.

  

• Custom payload after execute transform

  The custom payload will display after you enable custom payload, and input jq Filter.

  

• ThingsPro Agent offers below variables for you to print out on your payload:

  No	Variable	Description
  1	.srcName	Print source name of tag data
  2	.tagName	Print tag name
  3	.dataValue	Print tag value
  4	.ts	Print time stamp of tag value be collected
  5	.dataUnit	Print data unit of tag value, example: %
  6	.dataType	Print data type of tag value, example: int64.

  P.S. If you would like to put above variable value as key of JSON element, please use parentheses, such as:

  (.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 jq Filter, you can add "format" element into D2C Message Policy to enable 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-05-11 by Aeluin Chen (陳映攸)