配置

简介

When creating a new model for a device that is not natively supported by the platform, it is advisable to define some scripts that improve the user experience and add more functionality. The scripts will then be used by all devices of that model, which also saves considerable work since it only needs to be done once.

Defining a script for the initial configuration of a device model 允许您:

• Specify the device structure, i.e., which endpoints it contains and their types and subtypes.
• Define validation rules for the device address (for example, verifying that the address has a specific format).
• Define user interface rules:
• Address field name, to use more appropriate text for the device (for example, "DEVEUI" for a LoRaWAN device, or "MAC address" for a Wi-Fi device).
• Indicate whether the device allows manual endpoint creation.
• Indicate whether the device allows manual endpoint deletion.
• Indicate whether manually editing endpoint data, such as the subtype, is allowed.

Defining Basic 设备模型 Information

You can define basic aspects of the device model that are useful for improving the user experience. This basic information currently includes the name you want to use for the "address" field. For example, for a LoRaWAN device, it is preferable to use the name "DEVEUI" instead of "address", or use "MAC address" for a Wi-Fi device.

The get配置 function is used for this basic configuration, as shown 下方.

function getConfiguration(config)
{
	config.addressLabel = {en: "DevEUI", es: "DevEUI"};
}

In the example 上方, you can see a get配置 function that changes the address field name (addressLabel), so that the end user sees it instead.

The get配置 function is automatically executed by the platform when it needs to retrieve basic device model information. The function receives a single parameter:

• config:此参数的类型为 设备模型配置, and the function code must modify the properties of this object as needed. If no properties of the object are modified, the default values will be used.

如果脚本未包含 get配置 function, the default values will be used. 更多信息, see 设备模型配置.

Defining the Device Structure

To improve the user experience when creating a device, you can specify the structure (i.e., the list of endpoints) that should be created when creating a device of this model. This simplifies the device creation process, minimizes the possibility of errors, and enables an experience identical to what can be achieved with any natively supported device model.

The get端点 function is used to obtain the list of endpoints that should be created when creating a device of this model, as shown 下方.

function getEndpoints(deviceAddress, endpoints)
{
	endpoints.addEndpoint("1", "Temperature sensor", endpointType.TemperatureSensor);
	endpoints.addEndpoint("2", "CO2 sensor", endpointType.PpmConcentrationSensor, ppmConcentrationSensorSubType.CarbonDioxide);
}

The get端点 function is automatically executed by the platform before creating a device using this model. The platform will then use the value of the endpoints parameter to create the endpoints within the device. The function receives the following parameters:

• deviceAddress:此参数的类型为 string and contains the address of the device that will be created. The parameter can be used, for example, to include it in the description of the endpoints that will be created within the device.
• endpoints:此参数的类型为 endpoint collection configuration and contains the endpoint collection to which the script must add the endpoint list. This is achieved through the add端点() method, as shown in the example code. For each endpoint added to the collection, you can specify the following:
• An address, which is unique for each endpoint within the device (but can of course be repeated in other endpoints of other devices).
• A description.
• An endpoint type.
• Optionally, an endpoint subtype, if applicable (see 此处 for more details).

如果脚本未包含 get端点 function, a device with no endpoints will be created.

更多信息, see endpoint configuration.

Device Address Validation

You can include the validateDeviceAddress function in the configuration script to validate device addresses used for all devices of this model. This prevents users from 输入ing incorrect addresses and displays a clear message when they do. 下面是一个示例 implementation of the validateDeviceAddress function.

function validateDeviceAddress(address, result)
{
	address = address.toLowerCase();
	result.ok = true;
	if (address.length == 12) {
		var validchars = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', '', 'c', 'd', 'e', 'f'];
		for (var i = 0; i < address.length; i++) {
			if (!validchars.includes(address.charAt(i))) {
				result.ok = false;
				break;
			}
		}
	}
	else {
		result.ok = false;
	}
	if (!result.ok)
		result.errorMessage = {
			en: "The address must be 12 characters long and only have hexadecimal characters",
			es: "La dirección debe tener 12 caracteres y tener sólo caracteres hexadecimales"
		};
}

The validateDeviceAddress function is automatically executed by the platform before creating a device using this model. The function receives the following parameters:

• address:此参数的类型为 string and contains the address of the device that will be created. The function must verify the validity of this address.
• result:此参数的类型为 device address validation result and is used to indicate the validation result. Typically, the function will modify the following properties:
• ok: this boolean property indicates whether the address was verified correctly.
• errorMessage: this property, which can be of type string or multi language literal, allows specifying an error message if the validation fails. If a multi language literal object is used, messages in different languages can be specified.

如果脚本未包含 validateDeviceAddress function, any address will be considered valid.

更多信息, see device address validation result.

Defining Device-Level 用户 Interface Rules

You can include the updateDeviceUIRules function in the configuration script to set user interface rules for devices of this model, specifying, for example, whether endpoints can be created manually. 下面是一个示例 function:

function updateDeviceUIRules(device, rules)
{
	rules.canCreateEndpoints = true;
}

The updateDeviceUIRules function is automatically executed by the platform before presenting options on the device and endpoint creation screen. Based on the values returned by this function, options such as creating endpoints within the device will be shown or hidden. The function receives the following parameters:

• device:此参数的类型为 device and contains the data of the device for which the user interface rules are needed. The function can use this parameter if the rules depend on some specific characteristic of the device.
• rules:此参数的类型为 device UI rules and is used to specify the rules. Typically, the function will modify the following properties:
• canCreate端点: this boolean property indicates whether manual endpoint creation should be allowed. If the returned value is false, the platform's user interface will not allow creating additional endpoints within the device.

如果脚本未包含 updateDeviceUIRules function, the default user interface rules will be used.

更多信息, see device UI rules.

Defining 端点-Level 用户 Interface Rules

You can include the update端点UIRules function in the configuration script to set user interface rules for each endpoint contained in a device of this model, specifying, for example, whether the endpoint can be deleted or whether its subtype can be changed. 下面是一个示例 function:

function updateEndpointUIRules(endpoint, rules)
{
	rules.canDelete = false;
	rules.canEditSubtype = (endpoint.address == "2");
}

The update端点UIRules function is automatically executed by the platform before presenting options on the device and endpoint creation screen, as well as on the endpoint editing screen. Based on the values returned by this function, options such as deleting endpoints or modifying their endpoint subtype will be shown or hidden. The function receives the following parameters:

• endpoint:此参数的类型为 endpoint and contains the data of the endpoint for which the user interface rules are needed. The function can use this parameter if the rules depend on some specific characteristic of the endpoint.
• rules:此参数的类型为 endpoint UI rules and is used to specify the rules. Typically, the function will modify the following properties:
• canDelete: this boolean property indicates whether the endpoint can be manually deleted.
• canEditSubtype: this boolean property indicates whether changing the endpoint subtype is allowed. This property is only relevant for certain endpoint types, as can be seen 此处.
• canEditSummationAutoReset: this boolean property indicates whether manually changing the "summation auto reset" behavior of the endpoint is allowed. This property is only relevant for energy meter and flow sensor endpoints.
• canEditElectricalCircuit: this boolean property indicates whether manually changing the electrical circuit associated with the endpoint is allowed. This property is only relevant for electrical energy-related endpoints (energy meters, voltmeters, ammeters, etc.).

如果脚本未包含 update端点UIRules function, the default user interface rules will be used.

更多信息, see endpoint UI rules.