TCP/UDP Integration

TCP/UDP integration

The TCP/UDP protocol is for devices that speak a simple command language straight over a network socket — no web API, no register model: professional audio players and matrices (AUDAC XMP44 and SourceCon modules), projectors (PJLink), displays and amplifiers behind RS-232-over-IP bridges, and custom microcontroller boards. You describe the command frames HyperVisu sends when a value changes, the patterns that extract values from the frames the device sends back, and optional query frames to poll. All the device-specific knowledge lives in the configuration, none in the server.

Each connection is one device, over TCP (one persistent connection, kept open and reconnected automatically) or UDP (datagrams). Over TCP, every object of the device shares that single socket — which is what devices that accept only one client (the XMP44 does) require.

What you need: the device's IP address and port, its command reference (frame syntax, delimiter, the commands and the feedback it sends), and whether it pushes state changes on its own or must be asked.

Connections. TCP/UDP is multi-connection: one connection per device (see “Connections”). Fields:

The Add connection dialog asks for the Instance Name, the Device address, the Port, the Poll Interval (seconds), the Transport and the Frame delimiter (defaults 30, TCP · persistent connection and \r\n). The other fields are under Framing and timing on the saved connection: select the new connection, set them and click Save connection.

Test in the Add connection dialog opens a socket to the address you typed. This proves the device is reachable, not that it understands your frames. On a saved connection, while the service already holds the device's single connection, Test reports the live state and the frames counted in and out instead of opening a second socket.

Binding an object (see “Binding TCP/UDP” below). Per object you give a Key — a short text that every reply carrying this value contains: only incoming frames that contain the key are tried against the object's match pattern (for AUDAC, the feedback command name: OG1, FREQ2). The comparison is case-sensitive, and a key cannot contain :. Two objects may share a key, for example a command object and its feedback object. The admin stores <connection>:<key>. The rest is the object's data type string, built from the editor's fields:

Templates use ${value}, plus ${value:d} to round a scaled value to a whole number (a 0–100 % slider on a device that wants integer arguments), ${value:02d} for a whole number padded with zeros and ${value:1f} for a fixed number of decimals, and in HEX mode ${value:u8}, ${value:u16be}, ${value:u16le}, ${value:u32be}, ${value:u32le} for fixed-width bytes. \r, \n, \t and \xNN are byte escapes. In ASCII mode, a template that forgets the delimiter has it appended automatically.

Match patterns use these tokens; everything else is matched literally:

The editor shows Frame sent with control characters made visible (# | D001 | hv | SOG1 | 28 | U | <CR><LF>), and the stored string. Frame sent is a preview, not a log: every ${value…} is replaced by the sample value 28, without the value format or the scaling, and for an object with separate ON and OFF commands it shows only the ON command. It does not show the delimiter the server appends in ASCII mode. Verify a real command and reply against the device.

Behavior worth knowing

• Direction. In objects match (and poll, if they have a query); Out objects send; In/Out objects do both — the device's own echo is the confirmation, as with KNX status objects.
• One frame, many objects. Every incoming frame is tested against all incoming objects of the connection whose key it contains, so a single status frame can feed several objects. Identical query templates are sent once per poll cycle.
• TCP. The connection is reconnected with increasing delays after a failure; on reconnect the queries run again when Read everything on connect is on. Outgoing frames go through a queue spaced by Delay between commands.
• UDP. One datagram is one frame. Unsolicited pushes need the Listen port.
• Commands sent while the device is unreachable fail without blocking anything; the app shows the last known state.

Worked example — AUDAC XMP44 media player

The XMP44 listens on TCP 5001, accepts one client, and speaks frames # | D001 | <source> | <command> | <argument> | <checksum> | <CR><LF> — the literal U is accepted as checksum. Setting the output gain is SOG1 | <arg> with arg = 8 − dB; the device answers with an update frame … | OG1 | <arg> | …, which it also broadcasts when the gain changes at the front panel. Play and stop are two commands (SPPLAY1, SPSTOP1).

1. Create a TCP/UDP connection (see “Connections”): address 192.168.1.60, port 5001, transport TCP, delimiter \r\n, poll interval 30. Click Test, then Create connection. Select the new connection and, under Framing and timing, leave Read everything on connect on and set the heartbeat # | D001 | hv | GTPS | 0 | U | \r\n every 120 s. Click Save connection.

2. In Devices, add an Audio widget "XMP44 player" and select this connection under Protocol.

3. On the volume object (In/Out): key OG1, command template # | D001 | hv | SOG1 | ${value:d} | U | \r\n, query template # | D001 | hv | GOG1 | 0 | U | \r\n, match pattern \i | OG1 | \i\v, scale -1, offset 8 — so −20 dB is sent as 28 and a received 28 reads as −20 dB.

4. On the play object (Out, boolean): key PLAY1, Different commands for ON and OFF: ON # | D001 | hv | SPPLAY1 | 0 | U | \r\n, OFF # | D001 | hv | SPSTOP1 | 0 | U | \r\n.

5. On the track title object (In, text): key SON1, query # | D001 | hv | GSON1 | 0 | U | \r\n, match \i | SON1 | \i\a | .

6. Click Save object on each object, then click Apply changes in the sidebar and confirm. Moving the volume slider sends SOG1, the device's OG1 echo confirms the new level, and a change at the device's front panel appears in the app.

💡 Tip: Keep the device's command reference open while binding — the key is the feedback name (OG1), which on AUDAC differs from the command name (SOG1).

Binding TCP/UDP

TCP/UDP objects are configured in the object settings dialog (see “Object Settings, Logging & Notifications”). The cards are:

Frame addressing

Commands sent (outgoing objects)

Values read back (incoming objects)

Below the cards, Frame sent shows the resolved outgoing frame for a sample value with control characters visible (… | 28 | U | <CR><LF>), and Stored as shows the data type string that will be saved. The pattern language, templates and an AUDAC worked example are in the TCP/UDP chapter above.