Procesamiento de Datos

Introducción

Como parte de la configuración de un modelo de dispositivo, es posible crear un script para el procesamiento de los datos que se reciben de él a través de MQTT, HTTP, o LoRaWAN. Esto permite:

• Procesar cada payload recibido (uplink)
  • Actualizar la información de los endpoints asociados al dispositivo, aplicando funciones para convertir los datos en caso de que sea necesario.
  • Actualizar información del propio dispositivo, tales como niveles de RSSI, batería, etc., aplicando funciones para convertir los datos en caso de que sea necesario.
• Crear payloads específicos destinados al dispositivo (downlink)
  • Procesar comandos estándar o customizados definidos en la plataforma Gear, y generar con ellos un payload con el formato esperado por el dispositivo.

Procesamiento de payloads recibidos (uplink)

Para procesar cada payload recibido del dispositivo (sin importar si es recibido por HTTP, MQTT, o LoRaWAN), es posible crear una función parseUplink, como la que se muestra como ejemplo a continuación. Este ejemplo está escrito asumiendo un sensor de temperatura y humedad que informa la temperatura en el primer byte del payload, la humedad en el segundo byte, y el porcentaje de batería en el tercer byte.

function parseUplink(device, payload)
{
	// Payload is binary, so it's easier to handle as an array of bytes
	var bytes = payload.asBytes();
	
	// Verify payload contains exactly 3 bytes
	if (bytes.length != 3)
		return;

	// Parse and store temperature
	var temperatureSensor = device.endpoints.byType(endpointType.temperatureSensor);
	if (temperatureSensor != null)
	{
		var temperature = bytes[0] & 0x7f;
		if (bytes[0] & 0x80)  // Negative temperature?
			temperature -= 128;
		temperatureSensor.updateTemperatureSensorStatus(temperature);
	}

	// Parse and store humidity
	var humiditySensor = device.endpoints.byType(endpointType.humiditySensor);
	if (humiditySensor != null)
	{
		var humidity = bytes[1];
		humiditySensor.updateHumiditySensorStatus(humidity);
	}	  
	
	// Parse and store battery percentage
	var batteryPercentage = bytes[2];
	device.updateDeviceBattery({ percentage: batteryPercentage });

}

En el ejemplo anterior se puede observar una función parseUplink que procesa un payload de 3 bytes, y luego utiliza esa información para actualizar el estado de los endpoints del dispositivo (sensor de temperatura y sensor de humedad), así como el nivel de batería del dispositivo.

La función parseUplink es ejecutada automáticamente por la plataforma cada vez que se recibe un payload para el dispositivo. La función recibe los siguientes parámetros:

• device: este parámetro es de tipo device, y contiene toda la información del dispositivo que envió el payload, incluyendo la lista de endpoints asociados. Para más información, puede verse la referencia del objeto device.
• payload: este parámetro es de tipo data payload, y contiene el payload recibido del dispositivo. El objeto payload dispone de una serie de métodos que permiten acceder al contenido del payload con facilidad, tales como:
  • asBytes() permite leer el contenido del payload como un array de bytes, y es útil cuando el payload es binario.
  • asString() permite leer el contenido del payload como texto, y es útil cuando el payload es ASCII.
  • asJsonObject() permite leer el contenido del payload como un objeto Json, y es útil cuando el payload tiene formato Json.
  • asParsedObject() permite acceder a los datos pre-parseados por una plataforma externa. Esta opción está disponible para plataformas como Actility y The Things Stack, que permiten el parseo de datos antes del envío a la plataforma Gear Studio.

El objeto payload tiene además una propiedad port, disponible para datos recibidos desde redes LoRaWAN, que refleja el número de puerto LoRaWAN al que fueron enviados los datos. En forma similar, para datos recibidos por MQTT, existe una propiedad topic, que refleja el topic al cual fueron enviados los datos.

La función parseUplink se ejecuta atómicamente, es decir que los datos sólo se actualizan si el script se ejecuta en forma exitosa. En caso de errores en la ejecución del script, todos los cambios serán revertidos, como si el payload no se hubiera recibido. Por esta razón, es importante que el script maneje las condiciones de error correctamente.

Si el script no incluye la función parseUplink, el paquete recibido será ignorado.

Respuestas para envío de uplinks por HTTP

En el caso de que el envío de uplinks se haga por HTTP, la plataforma normalmente devolverá un status code 200, y un cuerpo vacío. Sin embargo, es posible cambiar este comportamiento devolviendo un objeto HttpResponse, indicando en él la información a retornar, incluyendo:

• Status code
• Content type
• Contenido

A continuación se muestra un ejemplo de esto.

function parseUplink(device, payload)
{
	[...]
	[ More code ]
	[...]

	var httpResponse = new HttpReponse();
	httpResponse.statusCode = 200;
	httpResponse.contentType = "application/json";
	httpResponse.content.setAsJson({ textField: "some text", aNumber: 25 });
	return httpResponse;
}

Para más información, consultar la referencia del objeto HttpResponse.

Construcción de payloads para el dispositivo (downlink)

Para enviar datos hacia el dispositivo (típicamente comandos), es posible crear una función buildDownlink, como la que se muestra como ejemplo a continuación. Este ejemplo está escrito asumiendo un dispositivo que contiene un único endpoint, de tipo appliance, que puede encenderse, apagarse, y alternarse (toggle). Se asume que recibe en el payload debe enviarse un único byte, que indica el tipo de operación.

function buildDownlink(device, endpoint, command, payload)
{
	payload.port = 25;		// This device receives commands on LoRaWAN port 25
	payload.buildResult = downlinkBuildResult.ok;

	switch (command.type) {
		case commandType.onOff:
			switch (command.onOff.type) {
				case onOffCommandType.turnOn:
					payload.setAsBytes([30]);		// Command ID 30 is "turn on"
					break;
				case onOffCommandType.turnOff:
					payload.setAsBytes([31]);		// Command ID 31 is "turn off"
					break;
				case onOffCommandType.toggle:
					payload.setAsBytes([32]);		// Command ID 32 is "toggle"
					break;
				default:
					payload.buildResult = downlinkBuildResult.unsupported;
					break;
			}
			break;
		default:
			payload.buildResult = downlinkBuildResult.unsupported;
			break;
	}
	
}

En el ejemplo anterior se puede observar una función buildDownlink que procesa un comando de la plataforma, y crea con él un payload de 1 byte. El script sólo soporta comandos para endpoints de tipo on/off, y por lo tanto muestra un error si se intenta enviar comandos de cualquier otro tipo.

La función buildDownlink es ejecutada automáticamente por la plataforma cada vez que se intenta enviar cualquier comando al dispositivo, independientemente de si el comando se envía desde una app, una acción programada, etc. La función recibe los siguientes parámetros:

• device: este parámetro es de tipo device, y contiene toda la información del dispositivo al que se va a enviar el comando, incluyendo la lista de endpoints asociados. Para más información, puede verse la referencia del objeto device.
• endpoint: este parámetro es de tipo endpoint, y contiene los datos del endpoint al que se va a enviar el comando. Este campo puede tener valor null si el comando se está enviando al dispositivo, y no a un endpoint en particular. Por ejemplo, si se intenta enviar un comando de “reboot”, este comando será enviado al dispositivo, pues no tiene sentido reiniciar un endpoint individual.
• command: este parámetro es de tipo command, y contiene el comando que la plataforma va a enviar. El código de la función normalmente utiliza la información en este objeto para construir el payload que se debe enviar al dispositivo. Para más información sobre la información contenida en el comando, revisar esta sección.
• payload: este parámetro es de tipo data payload, y sirve para crear el payload que se enviará finalmente al dispositivo. El objeto payload dispone de una serie de métodos que permiten modificar su contenido, tales como:
  • setAsBytes() permite escribir el contenido del payload utilizando un array de bytes.
  • setAsString() permite escribir el contenido del payload como texto, y es útil cuando el payload es ASCII.
  • setAsJsonObject() permite escribir el contenido del payload como un objeto Json, y es útil cuando el payload tiene formato Json.

El objeto payload tiene además una propiedad port, disponible para dispositivos con conectividad LoRaWAN, que refleja el número de puerto LoRaWAN al que serán enviados los datos. En forma similar, para dispositivos con comunicación MQTT, existe una propiedad topic, que permite indicar el topic al cual serán enviados los datos.

Si el script no incluye la función buildDownlink, el comando será rechazado indicando que no está soportado.