Configuración

Introducción

Al crear un nuevo modelo para un dispositivo que no está soportado nativamente por la plataforma, es conveniente definir algunos scripts que mejoran la experiencia del usuario, y aportan más funcionalidad. Los scripts serán utilizados luego por todos los dispositivos de ese modelo, lo cual permite además ahorrar mucho trabajo, dado que es algo que hay que hacer por única vez.

Definir un script para la configuración inicial de un modelo de dispositivo, permite:

• Indicar la estructura del dispositivo, es decir, qué endpoints contiene, y de qué tipos y subtipos.
• Definir reglas de validación para la dirección del dispositivo (por ejemplo, verificar que la dirección tenga un formato específico).
• Definir reglas de interfaz de usuario:
  • Nombre del campo address, para utilizar un texto más apropiado para el dispositivo (por ejemplo, “DEVEUI” si se trata de un dispositivo LoRaWAN, o “MAC address” si se trata de un dispositivo Wi-Fi).
  • Indicar si el dispositivo permite el agregado manual de endpoints.
  • Indicar si el dispositivo permite la eliminación manual de endpoints.
  • Indicar si se permite editar manualmente datos de los endpoints, tales como el subtipo, etc.

Definición de información básica de un modelo de dispositivo

Es posible definir aspectos básicos del modelo de dispositivo que son útiles para mejorar la experiencia de usuario. Esta información básica, actualmente, incluye el nombre que se desea utilizar para el campo “address”. Por ejemplo, si se trata de un dispositivo LoRaWAN, será preferible utilizar el nombre “DEVEUI” en lugar de “dirección”, o utilizar “MAC address” si se trata de un dispositivo Wi-Fi.

Para esta configuración básica se utiliza la función getConfiguration, como se muestra a continuación.

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

En el ejemplo anterior se puede observar una función getConfiguration que cambia el nombre del campo dirección (addressLabel), para que el usuario final vea en su lugar 

La función getConfiguration es ejecutada automáticamente por la plataforma cuando es necesario conocer información básica del modelo de dispositivo. La función recibe un único parámetro:

• config: este parámetro es de tipo device model configuration, y el código de la función debe modificar las propiedades de este objeto como sea necesario. En caso de que no se modifique ninguna propiedad del objeto, se utilizarán los valores por defecto.

Si el script no incluye la función getConfiguration, se utilizarán los valores por defecto. Para más información, vea device model configuration.

Definición de la estructura del dispositivo

Para mejorar la experiencia de los usuarios al momento de crear un dispositivo, es posible indicar la estructura (es decir, la lista de endpoints) que deberían ser creados al crear un dispositivo de este modelo. Esto simplifica el proceso de creación de dispositivos, minimiza la posibilidad de cometer errores, y habilita una experiencia idéntica a la que puede conseguirse para cualquier modelo de dispositivo soportado nativamente por la plataforma.

Para obtener la lista de endpoints que deben crearse al crear un dispositivo de este modelo, se utiliza la función getEndpoints, como se muestra a continuación.

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

La función getEndpoints es ejecutada automáticamente por la plataforma antes de crear un dispositivo utilizando este modelo. La plataforma utilizará luego el valor del parámetro endpoints, para crear los endpoints dentro del dispositivo. La función recibe los siguientes parámetros:

• deviceAddress: este parámetro es de tipo string, y contiene la dirección del dispositivo que va a ser creado. El parámetro puede utilizarse, por ejemplo, para incluirlo en la descripción de los endpoints que se vayan a crear dentro del dispositivo.
• endpoints: este parámetro es de tipo endpoint collection configuration, y contiene la colección de endpoints en la que el script deberá agregar la lista de endpoints. Este se consigue a través del método addEndpoint(), como puede verse en el código de ejemplo. Para cada endpoint agregado a la colección, será posible indicar lo siguiente:
  • Una dirección, que es única para cada endpoint incluido en el dispositivo, pero que por supuesto puede repetirse en otros endpoints de otros dispositivos)
  • Una descripción.
  • Un tipo de endpoint.
  • Opcionalmente, un subtipo de endpoint, si aplica (ver aquí para más detalles).

Si el script no incluye la función getEndpoints, se creará un dispositivo que no contiene endpoints.

Para más información, vea endpoint configuration.

Validación de la dirección de un dispositivo

Es posible incluir la función validateDeviceAddress en el script de configuración para validar las direcciones de dispositivo que se utilizan para todos los dispositivos de este modelo. Esto permite evitar que los usuarios ingresen direcciones erróneas, así como mostrar un mensaje claro al respecto cuando lo hagan. A continuación, se muestra un ejemplo de implementación de la función validateDeviceAddress.

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

La función validateDeviceAddress es ejecutada automáticamente por la plataforma antes de crear un dispositivo utilizando este modelo. La función recibe los siguientes parámetros:

• address: este parámetro es de tipo string, y contiene la dirección del dispositivo que va a ser creado. La función debe verificar la validez de esta dirección.
• result: este parámetro es de tipo device address validation result, y se utiliza para indicar el resultado de la validación. Normalmente, la función modificará las siguientes propiedades:
  • ok: esta propiedad de tipo booleano indica si la dirección fue verificada correctamente.
  • errorMessage: esta propiedad, que puede ser de tipo string o multi language literal, permite indicar un mensaje de error, en caso de que la validación sea incorrecta. Si se utiliza un objeto multi language literal, es posible indicar mensajes en diferentes idiomas.

Si el script no incluye la función validateDeviceAddress, se considerará que cualquier dirección es válida.

Para más información, vea device address validation result.

Definir reglas de interfaz de usuario a nivel de dispositivo

Es posible incluir la función updateDeviceUIRules en el script de configuración para establecer reglas de interfaz de usuario para los dispositivos de este modelo, indicando, por ejemplo, si pueden crearse endpoints manualmente. A continuación se muestra una función de ejemplo:

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

La función updateDeviceUIRules es ejecutada automáticamente por la plataforma antes de presentar opciones en la pantalla de creación de dispositivos y endpoints. De acuerdo a los valores devueltos por esta función, se presentarán u ocultarán opciones como crear endpoints dentro del dispositivo. La función recibe los siguientes parámetros:

• device: este parámetro es de tipo device, y contiene los datos del dispositivo sobre el cual se desean conocer las reglas de interfaz de usuario. La función puede utilizar este parámetro en caso de que las reglas dependan de alguna particularidad del dispositivo.
• rules: este parámetro es de tipo device UI rules, y se utiliza para indicar las reglas. Normalmente, la función modificará las siguientes propiedades:
  • canCreateEndpoints: esta propiedad de tipo booleano indica si debe permitirse la creación manual de endpoints. Si el valor devuelto es false, la interfaz de usuario de la plataforma no permitirá la creación de endpoints adicionales dentro del dispositivo.

Si el script no incluye la función updateDeviceUIRules, se utilizarán las reglas de interfaz de usuario por defecto.

Para más información, vea device UI rules.

Definir reglas de interfaz de usuario a nivel de endpoint

Es posible incluir la función updateEndpointUIRules en el script de configuración para establecer reglas de interfaz de usuario para cada endpoint contenido en un dispositivo de este modelo, indicando, por ejemplo, si el endpoint puede eliminarse, o si es posible cambiar su subtipo. A continuación se muestra una función de ejemplo:

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

La función updateEndpointUIRules es ejecutada automáticamente por la plataforma antes de presentar opciones en la pantalla de creación de dispositivos y endpoints, así como en la pantalla de edición de endpoints. De acuerdo a los valores devueltos por esta función, se presentarán u ocultarán opciones como eliminar endpoints, o modificar su subtipo de endpoint. La función recibe los siguientes parámetros:

• endpoint: este parámetro es de tipo endpoint, y contiene los datos del endpoint sobre el cual se desean conocer las reglas de interfaz de usuario. La función puede utilizar este parámetro en caso de que las reglas dependan de alguna particularidad del endpoint.
• rules: este parámetro es de tipo endpoint UI rules, y se utiliza para indicar las reglas. Normalmente, la función modificará las siguientes propiedades:
  • canDelete: esta propiedad de tipo booleano indica si el endpoint puede eliminarse manualmente.
  • canEditSubtype: esta propiedad de tipo booleano indica si se permite cambiar el subtipo de endpoint. Esta propiedad sólo es relevante para ciertos tipos de endpoint, como puede verse aquí.
  • canEditSummationAutoReset: esta propiedad de tipo booleano indica si se permite cambiar manualmente el comportamiento de “summation auto reset” del endpoint. Esta propiedad sólo es relevante para endpoints medidores de energía y sensores de flujo.
  • canEditElectricalCircuit: esta propiedad de tipo booleano indica si se permite cambiar manualmente el circuito eléctrico asociado al endpoint. Esta propiedad sólo es relevante para endpoints relacionados con energía eléctrica (medidores de energía, voltímetros, amperímetros, etc.).

Si el script no incluye la función updateEndpointUIRules, se utilizarán las reglas de interfaz de usuario por defecto.

Para más información, vea endpoint UI rules.