If standard functions cannot meet your needs, you can define custom functions for your business. This topic describes how to add, modify, and delete custom functions.
Prerequisites
A product has been created. For more information, see Create a product.
Background information
- Custom functions can be used only with proprietary brands and the Cloud Intelligence system. They cannot be used in the Tmall Genie ecosystem.
- If a product is published, you cannot delete any of its custom functions.
- After a device is flashed, avoid editing its custom functions.
- Log on to the IoT Living Platform.
- On the project homepage, under Product Management, select a product and click Continue to Develop to open the page.
- Click Add Function in the Custom Function
- Configure the custom function parameters.
Custom properties: In the Add Custom Feature dialog box, select Property as the feature type. After you set the parameters, click Confirm.
The following table describes the property parameters.
Parameter
Description
Feature Name
The name of the property, such as electricity consumption. The feature name must be unique within a product.
Supports Chinese characters, letters, Japanese characters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). The name must start with a Chinese character, letter, Japanese character, or digit, and be up to 30 characters in length.
When you enter a feature name, matching standard features from the standard feature library are filtered for your selection. You can refer to the standard features for configuration.
NoteWhen the gateway protocol is Modbus, standard properties are not supported. Only custom properties are supported.
Identifier
The unique identifier of the property. It must be unique within the product. This is the value of the identifier parameter in the Alink JSON format. It serves as the key for the property data reported by the device. The cloud uses this identifier to validate and accept the data. Supports letters, digits, and underscores (_). The identifier can be up to 50 characters in length, such as PowerConsumption.
NoteThe following system-reserved parameters cannot be used as an identifier: set, get, post, property, event, time, and value.
Data Type
int32: A 32-bit integer. You must define a value range, step size, and unit symbol.
float: A single-precision floating-point number. You must define a value range, step size, and unit symbol.
double: A double-precision floating-point number. You must define a value range, step size, and unit symbol.
enum: An enumeration. Define the parameter value and description for each enum value, such as 1 for heating mode and 2 for refrigeration mode.
bool: A Boolean value. Use 0 or 1 to define the Boolean value, such as 0 for off and 1 for on.
text: A string. You must define the data length of the string. The maximum length is 10,240 bytes.
date: A timestamp. The format is a String type UTC timestamp in milliseconds.
struct: A JSON object. Define a JSON struct and add JSON parameter items. For example, define the color of a light as a struct composed of Red, Green, and Blue parameters. Nested structs are not supported.
array: An array. You must declare the element type and the number of elements in the array. The element type can be int32, float, double, text, or struct. Ensure that all elements in an array are of the same type. The number of elements is limited to 1 to 512.
NoteWhen the device protocol is Modbus, you do not need to set this parameter.
Value Range
If the data type is int32, float, or double, you can set the value range for the property.
Step Size
The minimum granularity of change for the property value. If the data type is int32, float, or double, you can set the step size as needed.
For example, when defining a temperature property for a thermometer product, set the data type to int32, the step size to 2, the unit to °C, and the value range to 0-100. This means the device reports the temperature value every time it changes by two degrees, such as 0°C, 2°C, 4°C, 6°C, 8°C, and so on.
Unit
You can select None for the unit or choose a unit based on your requirements.
Read/Write Type
Read and Write: The supported request methods are GET (retrieve) and SET (configure).
Read-only: The only supported request method is GET (retrieve).
NoteWhen the gateway protocol is Modbus, you do not need to set this parameter.
Description
Enter a description or note for this feature. The description can be up to 100 characters in length.
Extended Description
The extended description defines the mapping from the device communication protocol to the standard TSL model. It corresponds to the extended configuration in the TSL model.
This parameter is displayed and required only when you add a property to a TSL model for a product where Node Type is Gateway Sub-device and Gateway Protocol is Custom, OPC UA, or Modbus.
If Gateway Protocol is Custom, enter the custom configuration information in JSON format. The length is limited to 1,024 characters.
If Gateway Protocol is OPC UA, set the node name. The node name must be unique within the property dimension.
If Gateway Protocol is Modbus, set the following parameters:
Operation Type:
Discrete Input (read-only, 0x02)
Coil (read-only, 0x01)
Coil (read/write, read uses 0x01, write uses 0x05)
Coil (read/write, read uses 0x01, write uses 0x0F)
Coil (write-only, 0x05)
Coil (write-only, 0x0F)
Holding Register (read-only, 0x03)
Holding Register (read/write, read uses 0x03, write uses 0x06)
Holding Register (read/write, read uses 0x03, write uses 0x10)
Holding Register (write-only, 0x06)
Holding Register (write-only, 0x10)
Input Register (read-only, 0x04)
Register Address: Hexadecimal format. Must start with
0xand be in the range of0x0to 0xFFFF, such as0xFE.Raw Data Type: Supports int16, uint16, int32, uint32, int64, uint64, float, double, string, bool, and bits.
Bit Position: This parameter is available when the raw data type is bits. Select the position of the data.
Value Range: This is the value range of the raw data after it is processed by the scaling factor. Data outside this range is discarded. IoT Platform has set default value ranges for each operation type:
Coil type: 0 to 1
Discrete Input type: 0 to 1
Holding Register type: -2147483648 to 2147483647
Input Register type: -2147483648 to 2147483647
Swap high and low bytes within a register: Specifies whether to swap the first 8 bits and the last 8 bits of the 16-bit data in the register (byte1byte2 -> byte2byte1).
true: Swap.
false: Do not swap.
Swap register order: Specifies whether to swap the first 16 bits and the last 16 bits of the 32-bit raw data (byte1byte2byte3byte4 -> byte3byte4byte1byte2).
true: Swap.
false: Do not swap.
Scaling Factor: An integer or a floating-point number. The default value is 1. It cannot be 0 or a negative number.
Data Reporting Method: Options are Report on Schedule and Report on Change.
Custom services: In the Add Custom Feature dialog box, select Service as the feature type. After you set the parameters, click Confirm.
NoteIf the gateway protocol is Modbus, you cannot define any services.
The following table describes the service parameters.
Parameter
Description
Feature Name
The service name. Supports Chinese characters, letters, Japanese characters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). The name must start with a Chinese character, letter, Japanese character, or digit, and be up to 30 characters in length.
When you enter a feature name, matching standard features from the standard feature library are filtered for your selection. You can refer to the standard features for configuration.
Identifier
The unique identifier of the service. It must be unique within the product. This is the value of the identifier parameter for the service in the Alink JSON format. Supports letters, digits, and underscores (_). The identifier can be up to 50 characters in length.
NoteThe following system-reserved parameters cannot be used as an identifier: set, get, post, property, event, time, and value.
Invocation Method
Asynchronous: For an asynchronous invocation, the cloud returns the result immediately after the call is executed, without waiting for a response message from the device.
Synchronous: For a synchronous invocation, the cloud waits for a response from the device. If the device does not respond, the call times out.
Input Parameters
Set the input parameters for the service. This is optional.
Click Add Parameter to add input parameters for the service in the dialog box that appears.
If the gateway protocol is OPC UA, you must set the parameter index to mark the order of the parameters.
NoteThe following system-reserved parameters cannot be used as an identifier for an input parameter: set, get, post, property, event, time, and value.
You can use a property as an input parameter or define a custom parameter. For example, when defining an automatic irrigation service, you can use the defined properties irrigation time and irrigation amount as input parameters. When this service is called, these parameters are passed, and the irrigation device performs precise irrigation according to the set time and amount.
A service can have a maximum of 20 input parameters.
Output Parameters
Set the output parameters for the service. This is optional.
Click Add Parameter to add output parameters for the service in the dialog box that appears.
If the gateway protocol is OPC UA, you must set the parameter index to mark the order of the parameters.
NoteThe following system-reserved parameters cannot be used as an identifier for an output parameter: set, get, post, property, event, time, and value.
You can use a property as an output parameter or define a custom parameter. For example, you can use the defined property soil humidity as an output parameter. When the cloud calls the automatic irrigation service, the current soil humidity data is returned.
A service can have a maximum of 20 output parameters.
Extended Description
The extended description defines the mapping from the device communication protocol to the standard TSL model. It corresponds to the extended configuration in the TSL model.
This parameter is displayed and required only when you add a TSL model for a product where Node Type is Gateway Sub-device and Gateway Protocol is Custom or OPC UA.
If Gateway Protocol is Custom, you must pass the custom configuration in JSON format. The length cannot exceed 1,024 characters.
If Gateway Protocol is OPC UA, set the node name. The node name must be unique within the service dimension.
Description
Enter a description or note for this service feature. The description can be up to 100 characters in length.
Custom events: In the Add Custom Feature dialog box, select Event as the feature type. After you set the parameters, click Confirm.
NoteIf the gateway protocol is Modbus, you cannot define any events.
The following describes the event parameters.
Parameter
Description
Feature Name
The name of the event. Supports Chinese characters, letters, Japanese characters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). The name must start with a Chinese character, letter, Japanese character, or digit, and be up to 30 characters in length.
When you enter a feature name, matching standard features from the standard feature library are filtered for your selection. You can refer to the standard features for configuration.
Identifier
The unique identifier of the event. It must be unique within the product. This is the value of the identifier parameter for the event in the Alink JSON format. It serves as the key for the event data reported by the device, such as ErrorCode. Supports letters, digits, and underscores (_). The identifier can be up to 50 characters in length.
NoteThe following system-reserved parameters cannot be used as an identifier: set, get, post, property, event, time, and value.
Event Type
You can handle business logic and perform statistical analysis for different event types.
Information: Refers to general notifications reported by the device, such as the completion of a task.
Alert: Refers to sudden or abnormal situations reported by the device during operation. Alert information has a high priority.
Fault: Refers to sudden or abnormal situations reported by the device during operation. Fault information has a high priority.
Output Parameters
The output parameters for this event. Click Add Parameter to add an output parameter for the service in the dialog box that appears. You can use a property as an output parameter or define a custom parameter. For example, you can use the defined property voltage as an output parameter. When the device reports this fault event, it will carry the current voltage value of the device, which can be used to further determine the cause of the fault.
If the gateway protocol is OPC UA, you must set the parameter index to mark the order of the parameters.
NoteThe following system-reserved parameters cannot be used as an identifier for an output parameter: set, get, post, property, event, time, and value.
An event can have a maximum of 50 output parameters.
Extended Description
The extended description defines the mapping from the device communication protocol to the standard TSL model. It corresponds to the extended configuration in the TSL model.
This parameter is displayed and required only when you add a TSL model for a product where Node Type is Gateway Sub-device and Gateway Protocol is Custom or OPC UA.
If Gateway Protocol is Custom, you must pass the custom configuration in JSON format. The length cannot exceed 1,024 characters.
If Gateway Protocol is OPC UA, set the node name. The node name must be unique within the event dimension.
Description
Enter a description or note for this event feature. The description can be up to 100 characters in length.
- (Optional) If a custom function's settings are incorrect, you can modify the function.
- Click Edit for the desired function in the Custom Function
- Modify the parameters and click OK.
Note Some parameters, such as Function Type, cannot be modified in the Edit panel. These parameters are grayed out. For more information, see the parameter descriptions in step 4.
- (Optional) If a custom function is no longer needed, delete it.
- Click Delete for the desired function in the Custom Function
- In the dialog box that appears, click OK.