Examples of Custom Device Jobs - IoT Platform - Alibaba Cloud Documentation Center

The IoT Platform provides configuration and management services for device tasks. Custom device tasks require you to define task rules and device-side implementation logic based on actual needs. This topic provides sample code to simulate device reporting custom task status by manually entering commands, introducing the process of running custom tasks.

This topic uses devices under the Enterprise Edition instance in the China (Shanghai) region as an example to simulate the custom task flow of devices.

Preparations

You need to complete the following operations:

Create a product with the Product Name as Task Management Demo Product. Use default settings for other parameters. For specific operations, see Create Product.
Add three devices to the product, named Device1, Device2, and Device3 respectively. For specific operations, see Batch Create Devices.
After adding the devices, obtain the device certificate information (ProductKey, DeviceName, and DeviceSecret) for each of the three devices.
Customize a JSON format task rule file. This topic names the rule file as Task Execution Rules.json, with the following content.
```
{
    "fileName":"jobTest",
    "fileVersion":"1",
    "fileDescription":"Used for Task Management Demo"
}
```

Create Custom Task

Log on to the IoT Platform console.
On the Instance Overview page, click the target instance name or ID.
In the left-side navigation pane, select Monitoring And Operations > Task Management.
On the Tasks page, click Create Task.

On the Create Task Wizard page, complete the following configurations and click Next.

Parameter	Description
Task Name	Enter `Task Demo`.
Task Type	Select Custom Task.
Target Devices, Products, or Groups	Select the Product named Task Management Demo.
Task Execution Rules Issued to Devices	Upload the rule file: Task Execution Rules.json.

Set Number Of Jobs Executed Per Minute (50-1000) to 50, and Timeout (minutes) to 5.
Click Finish to return to the task list, click View for the task, and then click the Job Overview tab to view the task status.

Run Custom Task

The development environment used in the sample code is as follows:

Operating system: Windows 10
JDK version: JDK8
Integrated development environment: IntelliJ IDEA Community Edition

The commands supported by the sample code are shown in the table below.

Important

There must be a single space between commands, fields, and the parameter values following the fields, but parameter values cannot contain spaces.

Command	Backing Field	Usage Instructions
get	`-h`	`get -h`: Get help information for the get command.
get	`-t`	`get -t taskId: Get task details.` taskId has three value options: ID of the job under the task: Get detailed information about the task corresponding to the job ID. $next: Get information about an executable task. $list: Get a list of executable tasks, returning a maximum of 10 by default.
update	`-t` `-s` `-p` `-d`	`update -t taskId -s status -p progress -d detail`: Update the status of the job under the task. taskId: ID of the job under the task. status: Status of the job under the task. Valid values are as follows: SUCCEEDED: The task is completed. FAILED: The task failed. IN_PROGRESS: The task is in progress. REJECTED: The task is rejected. progress: Percentage of the job execution progress under the task. detail: Detailed information reported by the device. The content is in JSON format and cannot contain spaces. Note `-d` represents the execution details of the custom task and is an optional field. You can view it on the Device Management > Tasks > Task Details page in the IoT Platform console.
update	`-h`	`update -h`: Retrieve help information for the update command.

For more information on the execution process of custom tasks and their topics, see Overview of Device Tasks.

This topic uses three devices to simulate the possible final states in device tasks: Timed Out, Failed, and Succeeded.

Access and download alibabacloud-iot-java-demo, extract the files. Then open IntelliJ IDEA and import the sample project from the Demo package lp.

In the src/main/java/com.aliyun.iotx.lp.demo.job directory, in the CustomJobSample.java file, set the device information as shown in the table below.

Parameter	Example	Description
productKey	a1f3***	The device certificate information you saved after adding the device. This example adds information for the device Device1. You can also view it on the Device Details page of the device Device1 in the console.
deviceName	Device1
deviceSecret	b5c96d***
region	cn-shanghai	The Region ID corresponding to the region where your service is located. Check the region where your service is located in the upper-left corner of the IoT Platform console. For Region ID values, see Regions and Zones.
config.channelHost	iot-******.mqtt.iothub.aliyuncs.com	MQTT endpoint. For specific instructions, see View Instance Endpoint.

Run the CustomJobSample program file.
The device connects to the IoT Platform and subscribes to device task-related topics.
Enter the following command to get the task list information of the device.
get -t $list
Enter the following command to get the details of the specified task.
get -t 1a9300c10d7b41248cb657ca7191048d
Start executing the task and report progress. Enter the following command to set the progress to 26%.
update -t 1a9300c10d7b41248cb657ca7191048d -s IN_PROGRESS -p 26
You can return to the Task Details > Job Overview tab in the IoT Platform console to view the task status and progress.
Note
If the status value is invalid when updating the task status, the task status update will fail.
Stop reporting progress, and after exceeding the timeout set for the task, the final status of the task is updated to Timed Out.
Refer to Step 2, modify the device information to that of Device2, and then follow Steps 3 to 5 to get the device task, and finally enter the following command to update the task status to Failed, with a failure message.
update -t d3858707af6548cabe4ec2d6878e8639 -s FAILED -p 10 -d {"errorCode":"500","message":"SystemException"}
Return to the Task Details > Job Overview tab in the IoT Platform console to view the task status as Failed.
Click Execution Details to view specific error messages.
Refer to Step 2, modify the device information to that of Device3, and then follow Steps 3 to 6 to get and execute the task, and finally enter the following command to update the task status to Succeeded.
update -t 3b888b9f892b4d3ead6e2e34f0ccd3c2 -s SUCCEEDED -p 100
Return to the Task Details > Job Overview tab in the IoT Platform console to view the task status as Succeeded.