What can we improve?

Documentation

(Edit)

Data flow

Description

The data flow should explain how data is sent between "Device <-> Splitter <-> I / O" in IP-Symcon and what has to be set up for it.

For a simple creation of a module including the data flow, the use of the module generator is recommended.

Typical structure

Data flow

Direction of Data flow

There are 2 directions of data flow.

I/O to Device

As can be seen in the figure, this flow direction is from the parent instance via SendDataToChildren to the children. The incoming data is processed within the children by the overwritable function ReceiveData. Optionally and if necessary, a splitter can be inserted between I/O and device.

Device to I/O

As can be seen in the figure, this flow direction is from the children instance via SendDataToParent to the parent. The incoming data is processed within the parent by the overwritable function ForwardData. Optionally and if necessary, a splitter can be inserted between the device and I/O.

I/O Modules

In the case of self-developed modules, the GUIDs for devices and splitters must be specified in the respective module.json file. These can be created using the GUID Generator.

On the I/O side, the following data packages are available for I/O types:

I/O module Module GUID Supported data packages
Client Socket {3CFF0FD9-E306-41DB-9B5A-9D06D38576C3} Simple
HID {E6D7692A-7F4C-441D-827B-64062CFE1C02} Extended (event)
HTTP Client {4CB91589-CE01-4700-906F-26320EFCF6C4} Extended (HTTP Request)
Multicast Socket {BAB408E0-0A0F-48C3-B14E-9FB2FA81F66A} Simple
Extended (Socket)
Serial Port {6DC3D946-0D31-450F-A8C6-C42DB8D7D4F1} Simple
Server Sent Event Client {2FADB4B7-FDAB-3C64-3E2C-068A4809849A} Extended (SSE)
Server Socket {8062CF2B-600E-41D6-AD4B-1BA66C32D6ED} Simple
Extended (Socket)
UDP Socket {82347F20-F541-41E1-AC5B-A636FD3AE2D8} Simple
Extended (Socket)
Erweitert (UDP)
Virtual I/O {6179ED6A-FC31-413C-BB8E-1204150CF376} Simple
Extended (Socket)
WebSocket Client {D68FD31F-0E90-7019-F16C-1949BD3079EF} Simple

Data Packages

The data packets are encoded in JSONString. These contain the GUID of the data packet type and the actual data. Using the GUID as an identifier, the respective module knows what data is in the data packet and how it is formatted.

Simple

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

Parameter Data type Description
Buffer String Any data content
// Example for sending to the parent (TX packet) of the simple type
public function SendData() {
    $this->SendDataToParent(json_encode([
        'DataID' => "{79827379-F36E-4ADA-8A95-5F8D1DC92FA9}",
        'Buffer' => utf8_encode("Hello World String"),
    ]));
}
 
// Received data from the parent (RX packet) of the simple type
public function ReceiveData($JSONString) {
    $data = json_decode($JSONString);
    $data['Buffer'] = utf8_decode($Data['Buffer']);
 
    // Output in the message window for debug purposes
    IPS_LogMessage("DATA", print_r($data, true));
}

Extended (Event)

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

Parameter Data type Description
Buffer String Any data content
EventID Integer ID for the event
// Example for sending to the parent (TX packet) of the type Extended (Event)
public function SendData() {
    $this->SendDataToParent(json_encode([
        'DataID' => "{4A550680-80C5-4465-971E-BBF83205A02B}",
        'Buffer' => utf8_encode("Hello World String"),
        'EventID' => 123
    ]));
}
 
// Received data from the parent (RX packet) of the type Extended (Event)
public function ReceiveData($JSONString) {
    $data = json_decode($JSONString);
    $data['Buffer'] = utf8_decode($Data['Buffer']);
 
    // Output in the message window for debug purposes
    IPS_LogMessage("DATA", print_r($data, true));
}

Extended (Socket)

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

Parameter Data type description
Buffer String Any data content
Type Integer Type of connection (0 = Data, 1 = Connect, 2 = Disconnect)
ClientIP String Connection IP address
ClientPort Integer Connection port
// Example for sending to the parent (TX packet) of the extended type (socket)
public function SendData() {
    $this->SendDataToParent(json_encode([
        'DataID' => "{C8792760-65CF-4C53-B5C7-A30FCC84FEFE}",
        'Buffer' => utf8_encode("Hello World String"),
        'Type' => 0,
        'ClientIP' => "192.168.0.8",
        'ClientPort' => 502
    ]));
}
 
// Received data from the parent (RX packet) of the type extended (socket)
public function ReceiveData($JSONString) {
    $data = json_decode($JSONString);
    $data['Buffer'] = utf8_decode($Data['Buffer']);
 
    // Output in the message window for debug purposes
    IPS_LogMessage("DATA", print_r($data, true));
}

Extended (UDP)

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

Parameter Data type Description
Buffer String Any data content
ClientIP String IP address of the connection, if empty then the host address set in the UDP socket is used. (Will be ignored if broadcast is active)
ClientPort Integer Connection port, if set to 0, the port set in the UDP socket is used
Broadcast Boolean Broadcast deactivated/activated (False = deactivated, True = activated)
// Example for sending to the parent (TX packet) of the extended type (UDP)
public function SendData() {
    $this->SendDataToParent(json_encode([
        'DataID' => "{8E4D9B23-E0F2-1E05-41D8-C21EA53B8706}",
        'Buffer' => utf8_encode("Hello World String"),
        'ClientIP' => "192.168.0.8",
        'ClientPort' => 502
        'Broadcast' => false,
    ]));
}
 
// Received data from the parent (RX packet) of the extended type (UDP)
public function ReceiveData($JSONString) {
    $data = json_decode($JSONString);
    $data['Buffer'] = utf8_decode($Data['Buffer']);
 
    // Output in the message window for debug purposes
    IPS_LogMessage("DATA", print_r($data, true));
}

Extended (SSE)

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

Parameter Data type Description
Event String Any type of event
Data String Any data content
Retry String In milliseconds before another attempt to send
ID String ID for the event

TX GUID: {79827379-F36E-4ADA-8A95-5F8D1DC92FA9}
TX is not evaluated but has to be set

// Received data from the parent (RX packet) of the extended type (SSE)
public function ReceiveData($JSONString) {
    $data = json_decode($JSONString);
 
    // Output in the message window for debug purposes
    IPS_LogMessage("DATA", print_r($data, true));
}

Further information is available at https://www.w3.org/TR/eventsource/

Extended (HTTP Request)

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

Parameter RX Data type Description
Buffer String Any data content

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

Parameter TX Data type Description
RequestMethod String GET or POST
RequestURL String URL of the website to be requested
RequestData String Which data value should be requested
Timeout Integer Milliseconds until a timeout occurs
// Example for sending to the parent (TX packet) of the extended type (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
    ]));
}
 
// Received data from the parent (RX packet) of the simple type
public function ReceiveData($JSONString) {
    $data = json_decode($JSONString);
    $data['Buffer'] = utf8_decode($Data['Buffer']);
 
    // Output in the message window for debug purposes
    IPS_LogMessage("DATA", print_r($data, true));
}

Requirements and Setup

The GUIDs for the data packet types used are defined in the module.json. So that a data flow can be established between two entities, the sender must enter the type of communication used for the appropriate requirement. The recipient enters the GUID of the communication type under Implemented. If several GUIDs of different data packet types are entered in the module.json, a module can also interpret and process several data packet types.

The respective parent of each child must also be set up via ConnectParent, RequireParent or ForceParent.

Example

Communication between I/O, splitter and device. The device has the splitter as a parent and the splitter has the I/O as a parent.

Excerpt from the respective module.json

Example GUIDs of the data packet types:
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}

// Inside the I/O (parent of the splitter)
// I/Os usually have no other parents. So the list should normally be empty.
"parentRequirements": [],
// GUID of the data packet type that is used via SendDataToChildren
"childRequirements": ["{AE3AE3A-AE3A-AE3A-AE3A-AE3AE3AE}"],
// List of GUIDs of the data packet types that are obeyed.
// This is processed by the ForwardData function (data come from the child).
"implemented": ["{65465465-6546-6546-6546-65465465}"],
 
// Within the splitter (parent of the device, child of the I/O)
// GUID of the data packet type which is used via SendDataToParent
"parentRequirements": ["{65465465-6546-6546-6546-65465465}"],
// GUID of the data packet type that is used via SendDataToChildren
"childRequirements": ["{12312312-1231-1231-1231-12312312}"],
// List of GUIDs of the data packet types that are obeyed.
// This is processed either by the ForwardData function (data come from the child) or ReceiveData (data come from the parent).
"implemented": ["{AE3AE3A-AE3A-AE3A-AE3A-AE3AE3AE}", "{78978978-7897-7897-7897-78978978}"],
 
// Inside the device (child of the splitter)
// GUID of the data packet type which is used via SendDataToParent
"parentRequirements": ["{78978978-7897-7897-7897-78978978}"],
// Devices usually have no other children. So the list should normally be empty.
"childRequirements": [],
// List of GUIDs of the data packet types that are obeyed.
// This is processed by the ReceiveData function (data come from the parent).
"implemented": ["{12312312-1231-1231-1231-12312312}"],
Deutsche Webseite verfügbar
Go to cart
Any questions?