Datenverarbeitung

Einführung

Als Teil einer Gerätemodell-Konfiguration können Sie ein Skript zur Verarbeitung von Daten erstellen, die vom Gerät über MQTT, HTTP oder LoRaWAN empfangen werden. Dies ermöglicht:

• Verarbeitung jeder empfangenen Nutzlast (uplink)
• Aktualisierung der Informationen von Endpunkten, die dem Gerät zugeordnet sind, wobei bei Bedarf Konvertierungsfunktionen auf die Daten angewendet werden.
• Aktualisierung von Informationen über das Gerät selbst, wie RSSI-Pegel, Batterie usw., wobei bei Bedarf Konvertierungsfunktionen auf die Daten angewendet werden.
• Erstellung spezifischer Nutzlasten, die für das Gerät bestimmt sind (downlink)
• Verarbeitung von Standard- oder benutzerdefinierten Befehlen, die in der Gear-Plattform definiert sind, und Generierung einer Nutzlast mit dem vom Gerät erwarteten Format.

Verarbeitung empfangener Nutzlasten (Uplink)

Um jede vom Gerät empfangene Nutzlast zu verarbeiten (unabhängig davon, ob sie über HTTP, MQTT oder LoRaWAN empfangen wird), können Sie eine parseUplink-Funktion erstellen, wie im folgenden Beispiel gezeigt. Dieses Beispiel wurde unter der Annahme eines Temperatur- und Feuchtigkeitssensors geschrieben, der die Temperatur im ersten Byte der Nutzlast, die Feuchtigkeit im zweiten Byte und den Batterieprozentsatz im dritten Byte meldet.

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

}

Im obigen Beispiel sehen Sie eine parseUplink-Funktion, die eine 3-Byte-Nutzlast verarbeitet und diese Informationen dann verwendet, um den Status der Endpunkte des Geräts (Temperatursensor und Feuchtigkeitssensor) sowie den Batteriestand des Geräts zu aktualisieren.

Die parseUplink-Funktion wird von der Plattform automatisch jedes Mal ausgeführt, wenn eine Nutzlast für das Gerät empfangen wird. Die Funktion erhält die folgenden Parameter:

• device: Dieser Parameter ist vom Typ device und enthält alle Informationen über das Gerät, das die Nutzlast gesendet hat, einschließlich der Liste der zugeordneten Endpunkte. Weitere Informationen finden Sie in der Referenz zum device-Objekt.
• payload: Dieser Parameter ist vom Typ data payload und enthält die vom Gerät empfangene Nutzlast. Das Nutzlast-Objekt bietet eine Reihe von Methoden, die einen einfachen Zugriff auf den Nutzlastinhalt ermöglichen, wie z. B.:
• asBytes() liest den Nutzlastinhalt als Byte-Array und ist nützlich, wenn die Nutzlast binär ist.
• asString() liest den Nutzlastinhalt als Text und ist nützlich, wenn die Nutzlast ASCII ist.
• asJsonObject() liest den Nutzlastinhalt als JSON-Objekt und ist nützlich, wenn die Nutzlast im JSON-Format vorliegt.
• asParsedObject() greift auf Daten zu, die von einer externen Plattform vorab geparst wurden. Diese Option ist für Plattformen wie Actility und The Things Stack verfügbar, die das Parsen von Daten vor dem Senden an die Gear Studio-Plattform ermöglichen.

Das Nutzlast-Objekt verfügt außerdem über eine port-Eigenschaft, die für Daten verfügbar ist, die von LoRaWAN-Netzwerken empfangen werden, und die die LoRaWAN-Portnummer widerspiegelt, an die die Daten gesendet wurden. Ebenso gibt es für Daten, die über MQTT empfangen werden, eine topic-Eigenschaft, die das Thema widerspiegelt, an das die Daten gesendet wurden.

Die parseUplink-Funktion wird atomar ausgeführt, d. h. Daten werden nur aktualisiert, wenn das Skript erfolgreich ausgeführt wird. Im Falle von Skriptausführungsfehlern werden alle Änderungen rückgängig gemacht, als ob die Nutzlast nicht empfangen worden wäre. Aus diesem Grund ist es wichtig, dass das Skript Fehlerbedingungen korrekt behandelt.

Wenn das Skript die parseUplink-Funktion nicht enthält, wird das empfangene Paket ignoriert.

Antworten für HTTP-Uplink-Übermittlungen

Wenn Uplinks über HTTP gesendet werden, gibt die Plattform normalerweise einen Statuscode 200 und einen leeren Body zurück. Dieses Verhalten kann jedoch geändert werden, indem ein HttpResponse-Objekt zurückgegeben wird, das die zurückzugebenden Informationen spezifiziert, einschließlich:

• Statuscode
• Inhaltstyp
• Inhalt

Nachfolgend finden Sie ein Beispiel hierfür.

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

Weitere Informationen finden Sie in der Referenz zum HttpResponse-Objekt.

Erstellen von Nutzlasten für das Gerät (Downlink)

Um Daten an das Gerät zu senden (typischerweise Befehle), können Sie eine buildDownlink-Funktion erstellen, wie im folgenden Beispiel gezeigt. Dieses Beispiel wurde unter der Annahme eines Geräts geschrieben, das einen einzelnen Endpunkt vom Typ Appliance enthält, der ein- und ausgeschaltet sowie umgeschaltet werden kann. Es wird angenommen, dass ein einzelnes Byte in der Nutzlast gesendet werden muss, das den Operationstyp angibt.

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

}

Im obigen Beispiel sehen Sie eine buildDownlink-Funktion, die einen Plattformbefehl verarbeitet und daraus eine 1-Byte-Nutzlast erstellt. Das Skript unterstützt nur Befehle für Endpunkte vom Typ Ein/Aus und zeigt daher einen Fehler an, wenn ein anderer Befehlstyp versucht wird.

Die buildDownlink-Funktion wird von der Plattform automatisch jedes Mal ausgeführt, wenn ein Befehl an das Gerät gesendet wird, unabhängig davon, ob der Befehl von einer App, einer geplanten Aktion usw. gesendet wird. Die Funktion erhält die folgenden Parameter:

• device: Dieser Parameter ist vom Typ device und enthält alle Informationen über das Gerät, an das der Befehl gesendet wird, einschließlich der Liste der zugeordneten Endpunkte. Weitere Informationen finden Sie in der Referenz zum device-Objekt.
• endpoint: Dieser Parameter ist vom Typ endpoint und enthält die Daten des Endpunkts, an den der Befehl gesendet wird. Dieses Feld kann null sein, wenn der Befehl an das Gerät und nicht an einen bestimmten Endpunkt gesendet wird. Beispielsweise wird beim Senden eines "Neustart"-Befehls der Befehl an das Gerät gesendet, da ein Neustart eines einzelnen Endpunkts keinen Sinn ergibt.
• command: Dieser Parameter ist vom Typ command und enthält den Befehl, den die Plattform senden wird. Der Funktionscode verwendet normalerweise die Informationen in diesem Objekt, um die Nutzlast zu erstellen, die an das Gerät gesendet werden muss. Weitere Informationen zum Befehlsinhalt finden Sie in diesem Abschnitt.
• payload: Dieser Parameter ist vom Typ data payload und wird verwendet, um die Nutzlast zu erstellen, die letztendlich an das Gerät gesendet wird. Das Nutzlast-Objekt bietet eine Reihe von Methoden, die das Ändern seines Inhalts ermöglichen, wie z. B.:
• setAsBytes() schreibt den Nutzlastinhalt unter Verwendung eines Byte-Arrays.
• setAsString() schreibt den Nutzlastinhalt als Text und ist nützlich, wenn die Nutzlast ASCII ist.
• setAsJsonObject() schreibt den Nutzlastinhalt als JSON-Objekt und ist nützlich, wenn die Nutzlast im JSON-Format vorliegt.

Das Nutzlast-Objekt verfügt außerdem über eine port-Eigenschaft, die für Geräte mit LoRaWAN-Konnektivität verfügbar ist und die LoRaWAN-Portnummer widerspiegelt, an die die Daten gesendet werden. Ebenso gibt es für Geräte mit MQTT-Kommunikation eine topic-Eigenschaft, die es ermöglicht, das Thema anzugeben, an das die Daten gesendet werden.

Wenn das Skript die buildDownlink-Funktion nicht enthält, wird der Befehl mit dem Hinweis abgelehnt, dass er nicht unterstützt wird.