4.19Network I/O gateway

The Network I/O Gateway reads values from other devices and web services over the network (virtual inputs) and sends commands to them (network outputs). This page lists every field of its dialogs and what the gateway does with it.

#What it does

• Virtual inputs get a value from an HTTP address on a schedule, or from TCP or UDP messages that another device sends to the gateway. They pick one value out of the reply and make it available as a reusable value that pages and Logic Studio can use. Optionally the gateway also writes that value to a KNX group address.
• Network outputs send a command (HTTP, SOAP, TCP, UDP, UDP multicast or Wake-on-LAN) with a target and a payload. An output runs when you press an Action Button, when a Logic Studio block asks for it, when a KNX group is written, or on a repeat timer.

#Before you enable it

• The service is Disabled by default. Turn Enabled on and deploy the project (see Deploying to a gateway).
• The gateway must be able to reach the address you poll.
• A value shows on a page through its Reusable value ID, see "Using the value" below. Use KNX gateway and a group address are only needed when you also want the value on the KNX bus.
• A TCP or UDP listener opens a port on the gateway. Make sure nothing else on the gateway uses that port and that the sender can reach it.

#Settings

Every output is listed under the buttons with its command type and a delete button. Click a name to select it, then use Edit Outputs. The delete button removes the output at once, without asking.

#Virtual Inputs Editor

The list on the left has Add, Clone, Remove, Up and Down. Add creates an input with the defaults below. Cancel and Save Changes only close the dialog; edits are already in the project.

With On new value reception the gateway writes to KNX and informs the apps only when the value differs from the previous one. With On every reception it does so after every reply or message. The gateway also answers a KNX read request on that group address with the latest value.

#Data Format Editor

Choose how to find the value in the reply.

Test environment opens the Data Format Test dialog: paste a reply under Insert raw JSON/XML/Text received from external service, or use Local test, then Simulate. The result appears under Elaborated data from response. Local test sends the request from the computer running the Configurator, not from the gateway. A successful test also saves the result as the input's preview value.

#Network Output dialog

How each command type sends:

#How it works on the gateway

• Once a second the gateway checks every enabled HTTP request input that has a Refresh Rate above 0 and is not set to Manual refresh only. When the interval has passed it calls the address and reads the value. A call that fails is tried again as many times as Retry times; a failure is logged at most once a minute.
• A TCP or UDP listener input is opened as soon as the project is deployed and the service is enabled. It is closed again when you remove the input, change its port or protocol, or turn the service off.
• Every value that arrives, from a call or from a message, is made available as the Reusable value ID, shown on pages that use it and, if Use KNX gateway is on, written to the group address. A value that cannot be read (path not found, text that is not a number) is logged and the last good value stays.
• Outputs run in these cases: an Action Button with Run Configured Network Output, an automation or Logic Studio Network Output block, a write on the Trigger group address, or the Refresh timer. The result of every run is written to the gateway log.
• The commands that need no output (Send HTTP Request, Send TCP Command, Send UDP Command, Wake-on-LAN) send straight from the gateway.

#Using the value

An Analog Value, State Action or Energy Flow Line object with Protocol System Object lists each virtual input under Network I/O. The object follows the input live. If the gateway has not received a value yet, it shows the preview value saved by the last test. In Logic Studio the System Value block reads the same value.

#Example

Show the outdoor temperature from a web service:

1. Add a virtual input: Virtual Input Outdoor temperature, Reusable value ID network:outdoor_temp, Input mode HTTP request, Base URL https://example.com/api/weather, HTTP Request Type GET, Refresh Rate 600.
2. In the Data Format Editor, add the request parameter Name city, Value Dubai. Set Select Response Format Type JSON, Response Path main.temp, Cast the value to Decimal number.
3. Add an Analog Value object with Protocol System Object and pick Outdoor temperature under Network I/O.
4. Optional: turn Use KNX gateway on, KNX group address 5/1/1, KNX data type DPT 9 - 2 byte float to also put the value on the KNX bus.

#Tips and common problems

• The value never updates: the Refresh Rate is 0, or the input is set to Manual refresh only, or the Enabled switch is off. For a listener input, check that the sender uses the same port and protocol and ends each message with the separator.
• The path is not found: run Local test and check the reply. Paths are case sensitive.
• A button that should call a device does nothing: open the gateway log. The gateway writes why an output failed (a refused connection, a timeout, an HTTP error status).
• A TCP device wants a line ending: end the payload with \r\n (or \n).
• A device answers only to a hexadecimal command: use the hexadecimal type and write the bytes as pairs of digits, for example 02 41 03.
• Wake-on-LAN does not wake the PC: the PC and the gateway must be on the same network, and Wake-on-LAN must be on in the PC's BIOS and network card.

#See also

• Logic Studio
• Rule gateway
• Action Button
• Analog Value
• KNX engine