Function Definition

Last Updated on : 2024-06-20 04:35:19download

This topic describes how to define functions for a TuyaLink-based product.

Concepts

Device model

The device model construct describes an abstraction of physical devices. It defines the characteristics and behaviors of a type of device that connects to the Tuya Developer Platform.

A device model defines an abstract representation of a device as a set of properties, actions, and events, which determines how a connected physical device interacts with the cloud applications.

Type Description
Property
The property type is used to define the continuous and queryable states of a device, which can represent one or several feature parameters. A property can be read-write or read-only for data update and query. When a specific feature parameter is updated, the device can update the property accordingly. For example, a light bulb might have properties like power state and brightness.
Action
The action type is used to run complex tasks. An action command is not intended to change the device property but directs the device to return a response. For example, face recognition and picture transmission.
Event
The event type is used to define live notification reported by a device, which requires external sensing and processing. Events work with message subscription or rule engines to respond as per the predefined logic. For example, overheating alerts and fault alerts.

Standard and custom function

  • Standard function: refers to a template library of standard data points (DP). It provides the definition of common features for more than 1,000 product categories.

  • Custom function: supports various feature types and data types to help you define custom features as needed.

Prerequisites

You have created at least one TuyaLink-based product.

Procedure

Step 1: Go to function definition

  1. Log in to the Tuya Developer Platform. Choose a created product and click Continue to Develop.

  2. Click the Function Definition tab.

    Function Definition

Step 2: Add standard functions

Select the desired functions and add them.

Function Definition

Function Definition

Step 3: Add custom functions

If the standard functions cannot address your needs, you can create custom functions.

Three function types are available: property, event, and action. Choose the types that suit your product features to create custom functions.

Click Add in the Custom Functions section.

Function Definition

Function Definition

Select a function type and populate the required fields to create a custom function. The required information varies depending on function types. See the following introduction to fields regarding each function type.

  • Property type
    The property type is used to define the continuous and queryable states of a device, which can represent one or several feature parameters. For example, a light bulb might have properties like power state and brightness.

    • DP Name: the name of a custom function.

    • Identifier: the unique identifier of a custom function.

    • Data Type: the data type of a property. Nine data types are available, namely value, string, date, boolean, enum, raw, struct, array, and fault.

      Function Definition

    Example for property definitions

    Data type Example
    Value Take the temperature which ranges from 1°C to 100°C as an example. If the reported data is 36.6°C, The definition is as follows:
    • Data type: Value
    • Value Range: 1 to 1,000
    • Pitch: 1.
      The pitch specifies the difference between adjacent values. For example, if the pitch is 1, the valid values will be 0, 1, 2… If the pitch is 3, the valid values will be 0, 3, 6…
    • Scale: 1
    • Unit: °C
      The scale is used to transform the data of an integer to a decimal, such as transforming 1 to 0.1. In practice, the functions on the devices control the scale. It is only for parameter definition here.
    String Take the URL of the image as an example. The definition is as follows:
    • Data type: String
    • Maximum length: 50 bytes
    Date Take the product update time as an example. The device data is reported and parsed by the timestamp. The definition is as follows:
    • Data type: Date
    • Update time: If the update time is defined as 1638853568, the time can be parsed as 2021-12-07 13:06:08.
    Bool Take the switch as an example. The switch has two statuses: on and off. The definition is as follows:
    • Data type: Bool
    • True: on
    • False: off

    Enum Take the run mode as an example. It includes sports mode, personal mode, and team mode. The definition is as follows:
    • Data Type: Enum
    • Enum values: Sport_mode/Personal_mode/Team_mode
    RAW Take the binary code as an example. It cannot be transmitted in plaintext.
    • Data type: RAW
      The platform directly transmits the data to the device without any processing.
    Struct Take geolocation as an example. It is in multiple data types.
    • Data type: struct
    • Add parameter: Add the data type as needed.
      • Longitude: Value
      • Latitude: Value
      • Height: Value
      • Coordinate system: Enum
        You can add parameters to define all components of geolocation.
    Array Take the color of lights as an example. The color depends on the data.
    • Data type: Array
    • Element type: Select the element type as needed, such as a value type
    • Maximum elements: 3
      The color is usually expressed by the RGB values. You can change the RGB values to show different colors.
    Fault Take the alert as an example. You can report the specified information according to predefined conditions.
    • Data type: Fault
    • Barrier values: a high temperature, a low temperature, and temperature alerts
  • Event type
    The event type is used to report live device alerts to the cloud. The reported data can include one or more output parameters. For example, overheating alerts and fault alerts.

    Function Definition
  • Action type
    The action type applies to complex tasks that are required to return the result to the cloud. The input and output parameters must be specified due to this request-response mechanism. For example, after a door is unlocked, the smart lock will return a message indicating the door is unlocked to the mobile app.

    Function Definition

With the three function types, you can build a cloud-based model with a complete set of features you want to apply to a physical device. This separates a physical device from the device model so that the hardware and application development can be performed in parallel for a quick development cycle.

Next step

Proceed with device development to register your devices for cloud connectivity.