Konfiguration

Einführung

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 allows you to:

• 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 Device Model 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.

Der getConfiguration function is used for this basic configuration, as shown below.

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

Im obigen Beispiel sehen Sie ein getConfiguration function that changes the address field name (addressLabel), so that the end user sees it instead.

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

• config: Dieser Parameter ist vom Typ Gerätemodellkonfiguration, 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.

Wenn das Skript Folgendes nicht enthält: getConfiguration function, the default values will be used. For more information, see Gerätemodellkonfiguration.

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.

Der getEndpoints function is used to obtain the list of endpoints that should be created when creating a device of this model, as shown below.

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

Der getEndpoints 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: this parameter is of type 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: Dieser Parameter ist vom Typ endpoint collection configuration and contains the endpoint collection to which the script must add the endpoint list. This is achieved through the addEndpoint() method, as shown in the example code. For each endpoint added to the collection, you can specify the following:
• Ein Adresse, which is unique for each endpoint within the device (but can of course be repeated in other endpoints of other devices).
• Ein description.
• Ein endpoint type.
• Optionally, an endpoint subtype, if applicable (see hier for more details).

Wenn das Skript Folgendes nicht enthält: getEndpoints function, a device with no endpoints will be created.

Weitere Informationen finden Sie unter Endpoint-Konfiguration.

Device Address Validation

Sie können Folgendes einbinden: validateDeviceAddress function in the configuration script to validate device addresses used for all devices of this model. This prevents users from entering incorrect addresses and displays a clear message when they do. Below is an example implementation of the validateDeviceAddress Funktion.

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"
		};
}

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

• Adresse: this parameter is of type string and contains the address of the device that will be created. The function must verify the validity of this address.
• result: Dieser Parameter ist vom Typ Ergebnis der Geräteadressvalidierung 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 mehrsprachiges Literal, allows specifying an error message if the validation fails. If a mehrsprachiges Literal object is used, messages in different languages can be specified.

Wenn das Skript Folgendes nicht enthält: validateDeviceAddress function, any address will be considered valid.

Weitere Informationen finden Sie unter Ergebnis der Geräteadressvalidierung.

Defining Device-Level User Interface Rules

Sie können Folgendes einbinden: 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. Below is an example function:

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

Der 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:

• Gerät: Dieser Parameter ist vom Typ Gerät 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.
• Regeln: Dieser Parameter ist vom Typ Geräte-UI-Regeln und dient dazu, die Regeln festzulegen. Typischerweise ändert die Funktion folgende Eigenschaften:
• canCreateEndpoints: 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.

Wenn das Skript Folgendes nicht enthält: updateDeviceUIRules Funktion werden die Standard-UI-Regeln verwendet.

Weitere Informationen finden Sie unter Geräte-UI-Regeln.

Defining Endpoint-Level User Interface Rules

Sie können Folgendes einbinden: updateEndpointUIRules 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. Below is an example function:

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

Der updateEndpointUIRules 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: Dieser Parameter ist vom Typ 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.
• Regeln: Dieser Parameter ist vom Typ Endpoint-UI-Regeln und dient dazu, die Regeln festzulegen. Typischerweise ändert die Funktion folgende Eigenschaften:
• 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 hier.
• 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.).

Wenn das Skript Folgendes nicht enthält: updateEndpointUIRules Funktion werden die Standard-UI-Regeln verwendet.

Weitere Informationen finden Sie unter Endpoint-UI-Regeln.