Datenfluss

Beschreibung

Der Datenfluss soll erklären, wie Daten zwischen "Device <-> Splitter <-> I/O" in IP-Symcon versendet werden und was dafür eingerichtet werden muss.

Für eine einfache Erstellung eines Moduls inklusive des Datenflusses, wird die Nutzung des Modul-Generators empfohlen.

Typischer Aufbau

Datenflussrichtung

Es gibt 2 Datenflussrichtungen.

I/O zu Device

Diese Flussrichtung ist, wie in der Abbildung sichtbar, von der übgeordneten Instanz via SendDataToChildren zu den Children. Die ankommenden Daten werden innerhalb der Children von der überschreibaren Funktion ReceiveData verarbeitet.
Zwischen I/O und Device kann optional und falls nötig ein Splitter eingepflegt werden.

Device zu I/O

Diese Flussrichtung ist, wie in der Abbildung sichtbar, von der untergeordneten Instanz via SendDataToParent zu dem Parent. Die ankommenden Daten werden innerhalb des Parents von der überschreibaren Funktion ForwardData verarbeitet.
Zwischen Device und I/O kann optional und falls nötig ein Splitter eingepflegt werden.

I/O Module

Bei selbstentwickelten Modulen sind die GUIDs für Devices und Splitter in der jeweiligen module.json Datei anzugeben.
Diese können über den GUID Generator erstellt werden.

Seitens der I/O stehen folgende Datenpakete für I/O Typen zur Verfügung.

Datenpakete

Die Datenpakete werden JSONString kodiert.
Diese beinhalten einmal die GUID des Datenpakettyps und die eigentlichen Daten.
Über die GUID als Identifikator weiß das jeweilge Modul, welche Daten in dem Datenpaket sind und deren Formatierung.

Simpel

RX GUID: {018EF6B5-AB94-40C6-AA53-46943E824ACF}
TX GUID: {79827379-F36E-4ADA-8A95-5F8D1DC92FA9}

// Beispiel für das Senden an den Parent (TX Paket) vom Typ Simpel
    public function SendData() {
        $this->SendDataToParent(json_encode([
            'DataID' => "{79827379-F36E-4ADA-8A95-5F8D1DC92FA9}",
            'Buffer' => utf8_encode("Hallo Welt String"),
        ]));
    }

    // Empfangene Daten vom Parent (RX Paket) vom Typ Simpel
    public function ReceiveData($JSONString) {
        $data = json_decode($JSONString);
        $data['Buffer'] = utf8_decode($Data['Buffer']);

        //Im Meldungsfenster zu Debug zwecken ausgeben
        IPS_LogMessage("DATA", print_r($data, true));
    }

Erweitert (Event)

RX GUID: {FD7FF32C-331E-4F6B-8BA8-F73982EF5AA7}
TX GUID: {4A550680-80C5-4465-971E-BBF83205A02B}

// Beispiel für das Senden an den Parent (TX Paket) vom Typ Erweitert (Event)
    public function SendData() {
        $this->SendDataToParent(json_encode([
            'DataID' => "{4A550680-80C5-4465-971E-BBF83205A02B}",
            'Buffer' => utf8_encode("Hallo Welt String"),
            'EventID' => 123
        ]));
    }

    // Empfangene Daten vom Parent (RX Paket) vom Typ Erweitert (Event)
    public function ReceiveData($JSONString) {
        $data = json_decode($JSONString);
        $data['Buffer'] = utf8_decode($Data['Buffer']);

        //Im Meldungsfenster zu Debug zwecken ausgeben
        IPS_LogMessage("DATA", print_r($data, true));
    }

Erweitert (Socket)

RX GUID: {7A1272A4-CBDB-46EF-BFC6-DCF4A53D2FC7}
TX GUID: {C8792760-65CF-4C53-B5C7-A30FCC84FEFE}

// Beispiel für das Senden an den Parent (TX Paket) vom Typ Erweitert (Socket) 
    public function SendData() {
        $this->SendDataToParent(json_encode([
            'DataID' => "{C8792760-65CF-4C53-B5C7-A30FCC84FEFE}",
            'Buffer' => utf8_encode("Hallo Welt String"),
            'Type' => 0,
            'ClientIP' => "192.168.0.8",
            'ClientPort' => 502
        ]));
    }

    // Empfangene Daten vom Parent (RX Paket) vom Typ Erweitert (Socket)
    public function ReceiveData($JSONString) {
        $data = json_decode($JSONString);
        $data['Buffer'] = utf8_decode($Data['Buffer']);

        //Im Meldungsfenster zu Debug zwecken ausgeben
        IPS_LogMessage("DATA", print_r($data, true));
    }

Erweitert (UDP)

RX GUID: {9082C662-7864-D5CA-863F-53999200D897}
TX GUID: {8E4D9B23-E0F2-1E05-41D8-C21EA53B8706}

// Beispiel für das Senden an den Parent (TX Paket) vom Typ Erweitert (UDP)
    public function SendData() {
        $this->SendDataToParent(json_encode([
            'DataID' => "{8E4D9B23-E0F2-1E05-41D8-C21EA53B8706}",
            'Buffer' => utf8_encode("Hallo Welt String"),
            'ClientIP' => "192.168.0.8",
            'ClientPort' => 502
            'Broadcast' => false,
        ]));
    }

    // Empfangene Daten vom Parent (RX Paket) vom Typ Erweitert (UDP)
    public function ReceiveData($JSONString) {
        $data = json_decode($JSONString);
        $data['Buffer'] = utf8_decode($Data['Buffer']);

        //Im Meldungsfenster zu Debug zwecken ausgeben
        IPS_LogMessage("DATA", print_r($data, true));
    }

Erweitert (SSE)

RX GUID: {5A709184-B602-D394-227F-207611A33BDF}

TX GUID: {79827379-F36E-4ADA-8A95-5F8D1DC92FA9}
TX wird nicht ausgewertet muss aber gesetzt sein

// Empfangene Daten vom Parent (RX Paket) vom Typ Erweitert (SSE)
    public function ReceiveData($JSONString) {
        $data = json_decode($JSONString);

        //Im Meldungsfenster zu Debug zwecken ausgeben
        IPS_LogMessage("DATA", print_r($data, true));
    }

Weitere Informationen gibt es unter w3.org/TR/eventsource

Erweitert (HTTP Request)

RX GUID: {018EF6B5-AB94-40C6-AA53-46943E824ACF}

TX GUID: {D4C1D08F-CD3B-494B-BE18-B36EF73B8F43}

// Beispiel für das Senden an den Parent (TX Paket) vom Typ Erweitert (HTTP Request)
    public function SendData() {
        $this->SendDataToParent(json_encode([
            'DataID' => "{D4C1D08F-CD3B-494B-BE18-B36EF73B8F43}",
            'RequestMethod' => utf8_encode("POST"),
            'RequestURL' => utf8_encode("https://reqbin.com/echo/post/form"),
            'RequestData' => utf8_encode("dummy-post-data"),
            'Timeout' => 10000
        ]));
    }

    // Empfangene Daten vom Parent (RX Paket) vom Typ Simpel
    public function ReceiveData($JSONString) {
        $data = json_decode($JSONString);
        $data['Buffer'] = utf8_decode($Data['Buffer']);

        //Im Meldungsfenster zu Debug zwecken ausgeben
        IPS_LogMessage("DATA", print_r($data, true));
    }

Voraussetzung und Einrichtung

Die GUIDs für die verwendeten Datenpakettypen werden in der module.json definiert.
Damit ein Datenfluss zwischen 2 Instanzen etabliert werden kann, muss der Sendende bei dem passenden Requirement die genutzte Kommunikationsart eintragen.
Der Empfänger trägt seinerseits unter Implemented die GUID der Kommunikationsart ein.
Wenn mehrere GUIDs verschiedener Datenpakettypen in die module.json eingetragen werden, kann ein Modul auch mehrere Datenpakettypen interpretieren und verarbeiten.

Ebenfalls muss von jedem Child der jeweilige Parent via ConnectParent, RequireParent oder ForceParent eingerichtet sein.

Beispiel

Kommunikation zwischen I/O, Splitter und Device.
Das Device hat den Splitter als Parent und der Splitter hat das I/O als Parent.

Auszug aus den jeweiligen module.json

Beispiel GUIDs der Datenpakettypen:
IO_TX: {65465465-6546-6546-6546-65465465}
IO_RX: {AE3AE3A-AE3A-AE3A-AE3A-AE3AE3AE}
Device_TX: {78978978-7897-7897-7897-78978978}
Device_RX: {12312312-1231-1231-1231-12312312}

// Innerhalb des I/Os (Parent vom Splitter)
    // I/Os haben normalerweise keine weitere Parents. Somit sollte die Liste normalerweise leer sein.
    "parentRequirements": [],
    // GUID des Datenpakettyps, welches via SendDataToChildren genutzt wird
    "childRequirements": ["{AE3AE3A-AE3A-AE3A-AE3A-AE3AE3AE}"],
    // Liste GUIDs der Datenpakettypen auf die gehorcht wird.
    // Diese wird von der Funktion ForwardData (Daten kommen vom Child) verarbeitet.
    "implemented": ["{65465465-6546-6546-6546-65465465}"],

    // Innerhalb des Splitters (Parent vom Device, Child vom I/O)
    // GUID des Datenpakettyps, welches via SendDataToParent genutzt wird
    "parentRequirements": ["{65465465-6546-6546-6546-65465465}"],
    // GUID des Datenpakettyps, welches via SendDataToChildren genutzt wird
    "childRequirements": ["{12312312-1231-1231-1231-12312312}"],
    // Liste GUIDs der Datenpakettypen auf die gehorcht wird.
    // Diese wird in wird entweder von der Funktion ForwardData (Daten kommen vom Child) oder ReceiveData (Daten kommen vom Parent) verarbeitet.
    "implemented": ["{AE3AE3A-AE3A-AE3A-AE3A-AE3AE3AE}", "{78978978-7897-7897-7897-78978978}"],

    // Innerhalb des Device (Child vom Splitter)
    // GUID des Datenpakettyps, welches via SendDataToParent genutzt wird
    "parentRequirements": ["{78978978-7897-7897-7897-78978978}"],
    // Devices haben normalerweise keine weitere Children. Somit sollte die Liste normalerweise leer sein.
    "childRequirements": [],
    // Liste GUIDs der Datenpakettypen auf die gehorcht wird.
    // Diese wird von der Funktion ReceiveData (Daten kommen vom Parent) verarbeitet.
    "implemented": ["{12312312-1231-1231-1231-12312312}"],