How to develop a local countdown feature-Link Living-阿里云帮助中心

This topic provides a development example for a local countdown feature on a smart socket. You can use this topic as a reference to implement a local countdown feature for any device.

Background information

A local countdown starts after an app sends a "start countdown" task to a device. The device then uses its local clock to execute the countdown task.

To implement a local countdown, the device and the app must be configured as described in this topic.

Device: Create, delete, and modify countdown tasks using the platform's standard data format.
App: Use the countdown feature directly in a smart life app or in the device interfaces that the platform provides for custom apps, such as lights and switches.

Unlike a single-channel countdown, a multi-channel countdown can simultaneously set local countdown tasks for Boolean values on multiple devices, such as on a multi-outlet power strip.

Procedure

In the console, go to Human-Computer Interaction > Automation and Timing and select the local timer feature. In Function Parameters, set the maximum number of local timers. This number depends on the device's storage and performance, with a maximum of 13.

Note

The platform automatically inserts a standard feature for on-device timers (DeviceTimer) into the feature definition. This feature supports multiple scheduled tasks.

When you develop with the device software development kit (SDK), check the status of the following macro switch in the Products/example/smart_outlet/smart_outlet.mk file.

GLOBAL_CFLAGS += -DENABLE_COUNTDOWN_LIST     // Macro for the old version of local countdown. Disabled by default.

The data structure is as follows:

Feature name: Countdown List
Identifier: CountDownList
Type: JSON

CountDownList: {
Target: "PowerSwitch"(string, the identifier of the Boolean value specified in the current set operation),
Contents: "PowerSwitch-1-1-123-1535644800000,LightSwitch-0-1-456-1535644800000"(string, a string of all countdown tasks for the device. The format is described below),
XXX1:0(bool, an existing standard Boolean property of the product),
XXX2:0(bool, an existing standard Boolean property of the product)
}

CountDownList is an optional standard property. Target and Contents are required properties of CountDownList. Both are strings with a maximum length of 2048 bytes.

XXX1 and XXX2 are existing standard Boolean properties for the current product. Developers can add or delete them as needed. The default value is 0.

Note

If a feature definition includes CountDownList, the CountDownList object must contain other Boolean properties in addition to Target and Contents. Otherwise, a runtime error occurs.

Parameter Name	Type	Property Name	Required	Length	Description
Target	string	Target object	Yes	2048	A standard Boolean property that specifies the location of the countdown for the current operation.
Contents	string	Countdown command	Yes	2048	Stores all countdown tasks for the device when you set tasks for multiple Boolean properties simultaneously and an array type is not available.

Design the feature.
- Design the countdown feature:
  - If the current product's feature definition has the CountDownList property, use the new countdown list logic. The current component displays the countdown list interface.
  - If the product's feature definition does not have the CountDownList property but has the CountDown property, use the old countdown plugin logic.
- To revoke a countdown task:
  - The app deletes the task corresponding to the identifier from the Contents field. It then sets Target to this identifier, reports it to the cloud, and sends it to the device.
  - The device receives the new CountDownList property. If the Target identifier is not in Contents, the device deletes the corresponding running countdown task. Other countdown tasks are not affected.
The following is an example scenario:

Note
When the plugin and the device report data to the cloud, the Boolean properties in CountDownList, such as XXX1 and XXX2, can be set to any valid Boolean value.
1. Click the countdown button.
2. Check the TSL and find the additional properties XXX1 and XXX2 in CountDownList.
3. The countdown list pop-up layer displays a list of names for XXX1 and XXX2.
4. Select a property, such as PowerSwitch. The interface to set the time and action appears. Set the time (1000 s) and action (Turn On).
5. Set Target: "PowerSwitch" and Contents: "PowerSwitch-1-1-1000-1535644800000", and send them to the cloud.
6. After the device receives the CountDownList data, it parses the Contents and Target values and sets the scheduled task.
7. Set a second property, XXX2. Contents is now PowerSwitch-1-1-1000-1535644800000,XXX2-0-1-2000-1535644800000, and Target is XXX2.
After 1000 s, the first countdown task for PowerSwitch ends. The device deletes the PowerSwitch task from Contents and sets Target to PowerSwitch. The device then reports the entire CountDownList property to the cloud. The plugin queries the CountDownList property and finds that Contents no longer contains the Boolean property specified by Target. This indicates that the PowerSwitch countdown task has finished, and the plugin displays a notification that the task is complete.