Configuration

Introduction

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.

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

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

In the example above, you can see a getConfiguration function that changes the address field name (addressLabel), so that the end user sees it instead.

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

• config: this parameter is of type device model configuration, 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.

If the script does not include the getConfiguration function, the default values will be used. For more information, see device model configuration.

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

The 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: this parameter is of type 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:
  • 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 here for more details).

If the script does not include the getEndpoints function, a device with no endpoints will be created.

For more information, 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 entering incorrect addresses and displays a clear message when they do. Below is an example 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: 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: this parameter is of type 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.

If the script does not include the validateDeviceAddress function, any address will be considered valid.

For more information, see device address validation result.

Defining Device-Level User 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. Below is an example 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: this parameter is of type 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: this parameter is of type device UI rules and is used to specify the rules. Typically, the function will modify the following properties:
  • 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.

If the script does not include the updateDeviceUIRules function, the default user interface rules will be used.

For more information, see device UI rules.

Defining Endpoint-Level User Interface Rules

You can include the 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");
}

The 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: this parameter is of type 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: this parameter is of type 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 here.
  • 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.).

If the script does not include the updateEndpointUIRules function, the default user interface rules will be used.

For more information, see endpoint UI rules.