Opent HyperVisu een afzonderlijke TCP-socket voor elk object?

Nee. Alle objecten op een apparaatverbinding delen één permanente TCP-socket, wat apparatuur ondersteunt die slechts één client toestaat.

Waarom ontvangt een inkomend object nooit een waarde?

De sleutel moet voorkomen in het feedbackframe en er is een match-patroon nodig om de waarde te extraheren. Controleer beide aan de hand van de commandoreferentie van het apparaat.

Hoe configureer ik een apparaat dat zijn status zelfstandig pusht?

Stel het poll-interval in op 0 en laat overbodige queries leeg. Configureer voor ongevraagde UDP-pushes de Listen port.

Waarom worden sommige commando's genegeerd?

Controleer het Frame sent-voorbeeld voor de framing, rekening houdend met het feit dat dit een voorbeeldwaarde toont en niet wat daadwerkelijk is verzonden. Verhoog Delay between commands als het apparaat direct opeenvolgende verzoeken negeert.

Wat doet de knop Test wanneer de TCP-verbinding al geopend is?

Het rapporteert de bestaande live-status in plaats van een tweede socket te openen die een apparaat met één client mogelijk weigert.

TCP/UDP-integratie

Het TCP/UDP-protocol is bedoeld voor apparaten die een eenvoudige commandotaal rechtstreeks over een netwerksocket spreken — zonder web-API en zonder registermodel: professionele audiospelers en matrices (AUDAC XMP44 en SourceCon-modules), projectoren (PJLink), displays en versterkers achter RS-232-over-IP-bridges, en eigen microcontroller-boards. U beschrijft de commando-frames die HyperVisu verstuurt wanneer een waarde verandert, de patronen die waarden extraheren uit de frames die het apparaat terugstuurt, en optionele query-frames om te pollen. Alle apparaatspecifieke logica bevindt zich in de configuratie, niets in de server.

Elke verbinding vertegenwoordigt één apparaat, via TCP (één permanente verbinding, continu opengehouden en automatisch hersteld) of UDP (datagrammen). Bij TCP deelt elk object van het apparaat die ene socket — wat noodzakelijk is voor apparaten die slechts één client accepteren (zoals de XMP44).

Wat u nodig heeft: het IP-adres en de poort van het apparaat, de commandoreferentie (framesyntaxis, scheidingsteken, de commando's en de feedback die het verzendt), en of het apparaat statuswijzigingen zelfstandig pusht of moet worden opgevraagd.

Verbindingen. TCP/UDP is multi-connection: één verbinding per apparaat (zie “Verbindingen”). Velden:

Veld	Beschrijving
Device address	IP-adres of hostnaam van het apparaat.
Port	De TCP- of UDP-poort waarop het apparaat luistert (AUDAC XMP44: `5001`).
Poll Interval (seconds)	Hoe vaak het apparaat opnieuw wordt uitgelezen. `0` voor een apparaat dat zijn status zelfstandig pusht.
Transport	TCP · persistent connection of UDP · datagrams.
Frame delimiter	Wat twee frames scheidt — `\r\n` voor vrijwel elk tekstprotocol.
Payload encoding	ASCII text voor tekstprotocollen, HEX bytes voor binaire protocollen.
Listen port	Alleen UDP. Voor een apparaat dat naar een vaste poort pusht; laat dit leeg en antwoorden komen terug op de poort van waaruit de server heeft verzonden.
Heartbeat frame / Every	Alleen TCP, optioneel. Een frame dat op een inactieve verbinding wordt verzonden zodat het apparaat deze niet sluit (minstens elke 5 s); het Frame sent-voorbeeld toont dit met zichtbare stuurtekens.
Connect timeout	Hoe lang gewacht wordt tot het apparaat de verbinding accepteert (ms, standaard 5000).
Delay between commands	Veel apparaten negeren opeenvolgende commando's die te snel volgen; verhoog dit als er commando's worden genegeerd (ms, standaard 50).
Read everything on connect	Aan: HyperVisu verstuurt elke query eenmalig zodra het apparaat antwoordt, zodat de app de actuele status toont zonder te wachten op de eerste poll.

Het dialoogvenster Add connection vraagt om de Instance Name, het Device address, de Port, het Poll Interval (seconds), het Transport en de Frame delimiter (standaardwaarden 30, TCP · persistent connection en \r\n). De overige velden bevinden zich onder Framing and timing op de opgeslagen verbinding: selecteer de nieuwe verbinding, stel ze in en klik op Save connection.

Test in het dialoogvenster Add connection opent een socket naar het ingevoerde adres. Dit bewijst dat het apparaat bereikbaar is, niet dat het uw frames begrijpt. Bij een opgeslagen verbinding, terwijl de service de enige verbinding van het apparaat al vasthoudt, rapporteert Test de actuele status en het aantal getelde inkomende en uitgaande frames in plaats van een tweede socket te openen.

Een object koppelen (zie “TCP/UDP koppelen” hieronder). Per object geeft u een Key op — een korte tekst die elk antwoord met deze waarde bevat: alleen inkomende frames die de sleutel bevatten, worden getoetst aan het match-patroon van het object (voor AUDAC de naam van het feedbackcommando: OG1, FREQ2). De vergelijking is hoofdlettergevoelig en een sleutel mag geen : bevatten. Twee objecten mogen dezelfde sleutel delen, bijvoorbeeld een commando-object en het bijbehorende feedbackobject. Het beheer slaat <connection>:<key> op. De rest is de datatypereeks van het object, opgebouwd uit de velden van de editor:

Veld	Opgeslagen als	Betekenis
Payload encoding	`ASCII` / `HEX`	Eerste token van de reeks. Dit verandert niets aan wat er verzonden wordt of hoe antwoorden gelezen worden: de codering die geldt is die van de verbinding, onder Framing and timing.
Command template	`SEND=`	Verzonden wanneer de waarde verandert (Out- en In/Out-objecten). `${value}` wordt vervangen door de waarde.
Different commands for ON and OFF → Command for ON / Command for OFF	`SEND1=` / `SEND0=`	Voor binaire objecten waarvan het apparaat twee afzonderlijke commando's gebruikt (`SPPLAY1` / `SPSTOP1`) in plaats van één met een 0/1-argument. Laat OFF leeg voor een knop die slechts eenmaal schakelt.
Query template	`POLL=`	Verzonden bij elke pollcyclus en eenmalig bij het verbinden (In- en In/Out-objecten). Laat dit leeg voor een apparaat dat zelfstandig pusht.
Match pattern	`MATCH=`	Toegepast op elk inkomend frame dat de sleutel bevat; wat het afvangt, wordt de waarde. Zonder dit ontvangt een inkomend object nooit een waarde.
Scale / Offset	`SCALE=` / `OFFSET=`	Lezen: waarde = ruw × scale + offset; schrijven gebruikt het omgekeerde. Alleen voor numerieke captures.
Acknowledge pattern / Acknowledge timeout (ms)	`ACK=` / `ACKTIMEOUT=`	Optioneel. Indien ingesteld, telt het schrijven pas als geslaagd zodra een frame binnen de time-out overeenkomt met het patroon (standaard 2000 ms).

Templates gebruiken ${value}, plus ${value:d} om een geschaalde waarde af te ronden op een geheel getal (een schuifregelaar van 0–100 % op een apparaat dat gehele getallen vereist), ${value:02d} voor een geheel getal aangevuld met voorloopnullen en ${value:1f} voor een vast aantal decimalen, en in HEX-modus ${value:u8}, ${value:u16be}, ${value:u16le}, ${value:u32be}, ${value:u32le} voor bytes met een vaste breedte. \r, \n, \t en \xNN zijn byte-escapes. In ASCII-modus wordt het scheidingsteken automatisch toegevoegd aan een template als dat ontbreekt.

Match-patronen gebruiken deze tokens; al het overige wordt exact vergeleken:

Token	Vangt af / doet
`\v`	een getal
`\h`	hex, gelezen als een getal
`\a`	tekst, tot aan het volgende vaste teken in het patroon (voor tekstobjecten)
`\iText\i`	spring voorbij "Text"
`\sN`	sla N tekens over
`\d` `\w` `\.`	een cijfer / een woord / elk willekeurig teken

De editor toont Frame sent met zichtbare stuurtekens (# | D001 | hv | SOG1 | 28 | U | <CR><LF>), en de opgeslagen reeks. Frame sent is een voorbeeld, geen logboek: elke ${value…} wordt vervangen door de voorbeeldwaarde 28, zonder de waarde-opmaak of de schaling, en voor een object met afzonderlijke AAN- en UIT-commando's toont het alleen het AAN-commando. Het toont niet het scheidingsteken dat de server in ASCII-modus toevoegt. Controleer een echt commando en antwoord aan de hand van het apparaat.

TCP/UDP-objecteditor voor een audio gain-object.

Belangrijk gedrag om te weten

Richting. In-objecten matchen (en pollen, als ze een query hebben); Out-objecten verzenden; In/Out-objecten doen beide — de echo van het apparaat zelf dient als bevestiging, net als bij KNX-statusobjecten.
Eén frame, meerdere objecten. Elk inkomend frame wordt getest op alle inkomende objecten van de verbinding waarvan het de sleutel bevat, zodat één enkel statusframe meerdere objecten kan voeden. Identieke query-templates worden eenmaal per pollcyclus verzonden.
TCP. Na een storing wordt de verbinding opnieuw opgebouwd met oplopende wachttijden; bij het herverbinden worden de queries opnieuw uitgevoerd als Read everything on connect aan staat. Uitgaande frames gaan door een wachtrij met tussenpozen ingesteld door Delay between commands.
UDP. Eén datagram is één frame. Ongevraagde pushes vereisen de Listen port.
Commando's die worden verzonden terwijl het apparaat onbereikbaar is, mislukken zonder processen te blokkeren; de app toont de laatst bekende status.

Praktijkvoorbeeld — AUDAC XMP44-mediaspeler

De XMP44 luistert op TCP 5001, accepteert één client en communiceert met frames # | D001 | <bron> | <commando> | <argument> | <checksum> | <CR><LF> — het vaste teken U wordt geaccepteerd als checksum. Het instellen van de uitgangsversterking is SOG1 | <arg> met arg = 8 − dB; het apparaat antwoordt met een update-frame … | OG1 | <arg> | …, dat het ook uitzendt wanneer de versterking op het frontpaneel verandert. Afspelen en stoppen zijn twee commando's (SPPLAY1, SPSTOP1).

Maak een TCP/UDP-verbinding aan (zie “Verbindingen”): adres 192.168.1.60, poort 5001, transport TCP, scheidingsteken \r\n, poll-interval 30. Klik op Test en vervolgens op Create connection. Selecteer de nieuwe verbinding en laat onder Framing and timing de optie Read everything on connect aan staan en stel de heartbeat # | D001 | hv | GTPS | 0 | U | \r\n in op elke 120 s. Klik op Save connection.
Voeg in Devices een Audio-widget "XMP44 player" toe en selecteer deze verbinding onder Protocol.
Op het volume-object (In/Out): key OG1, commando-template # | D001 | hv | SOG1 | ${value:d} | U | \r\n, query-template # | D001 | hv | GOG1 | 0 | U | \r\n, match-patroon \i | OG1 | \i\v, scale -1, offset 8 — zodat −20 dB wordt verzonden als 28 en een ontvangen 28 wordt gelezen als −20 dB.
Op het play-object (Out, binair): key PLAY1, Different commands for ON and OFF: ON # | D001 | hv | SPPLAY1 | 0 | U | \r\n, OFF # | D001 | hv | SPSTOP1 | 0 | U | \r\n.
Op het track title-object (In, tekst): key SON1, query # | D001 | hv | GSON1 | 0 | U | \r\n, match \i | SON1 | \i\a | .
Klik op Save object bij elk object, klik vervolgens op Apply changes in de zijbalk en bevestig. Het verplaatsen van de volumeregelaar verstuurt SOG1, de OG1-echo van het apparaat bevestigt het nieuwe niveau en een verandering op het frontpaneel van het apparaat verschijnt in de app.

💡 Tip: Houd de commandoreferentie van het apparaat open tijdens het koppelen — de sleutel is de feedback-naam (OG1), die bij AUDAC afwijkt van de commandonaam (SOG1).

TCP/UDP koppelen

TCP/UDP-objecten worden geconfigureerd in het objectinstellingenvenster (zie “Object Settings, Logging & Notifications”). De secties zijn:

Frame addressing

Veld Beschrijving

Key Een tekst die elk antwoord met de waarde van dit object bevat — bijv. OG1. Alleen inkomende frames die de sleutel bevatten, worden getoetst aan het match-patroon; de vergelijking is hoofdlettergevoelig. Geen : toegestaan. De sleutel hoeft niet uniek te zijn: twee objecten mogen er één delen, bijvoorbeeld een commando-object en het bijbehorende feedbackobject. Het opgeslagen adres is <connection>:<key>.

Payload encoding ASCII text voor tekstprotocollen, HEX bytes voor binaire protocollen.

Veld	Beschrijving
Key	Een tekst die elk antwoord met de waarde van dit object bevat — bijv. `OG1`. Alleen inkomende frames die de sleutel bevatten, worden getoetst aan het match-patroon; de vergelijking is hoofdlettergevoelig. Geen `:` toegestaan. De sleutel hoeft niet uniek te zijn: twee objecten mogen er één delen, bijvoorbeeld een commando-object en het bijbehorende feedbackobject. Het opgeslagen adres is `<connection>:<key>`.
Payload encoding	ASCII text voor tekstprotocollen, HEX bytes voor binaire protocollen.

Commands sent (uitgaande objecten)

Veld	Beschrijving
Command template	Verzonden wanneer de waarde verandert. `${value}` wordt vervangen door de waarde (`${value:d}` rondt af op een geheel getal); `\r` `\n` `\xNN` zijn byte-escapes.
Different commands for ON and OFF	Binaire objecten: toont Command for ON en Command for OFF voor apparaten die twee afzonderlijke commando's gebruiken in plaats van één met een 0/1-argument. Laat OFF leeg voor een knop die slechts eenmaal schakelt.
Acknowledge pattern / Acknowledge timeout (ms)	Optioneel. Indien ingesteld, telt het schrijven pas als geslaagd zodra een frame binnen de time-out overeenkomt met dit patroon.

Values read back (inkomende objecten)

Veld	Beschrijving
Query template	Verzonden bij elke pollcyclus en eenmalig bij het verbinden. Laat dit leeg voor een apparaat dat zelfstandig pusht.
Match pattern	Toegepast op elk inkomend frame dat de sleutel bevat; wat het afvangt, wordt de waarde. Tokens: `\v` een getal · `\h` hex, gelezen als een getal · `\a` tekst, tot aan het volgende vaste teken · `\iText\i` spring voorbij "Text" · `\sN` sla N tekens over · `\d` `\w` `\.` cijfer / woord / elk willekeurig teken. Zonder een match-patroon ontvangt het object nooit een waarde.
Scale / Offset	Lezen: waarde = ruw × scale + offset; schrijven gebruikt het omgekeerde.

Onder de secties toont Frame sent het berekende uitgaande frame voor een voorbeeldwaarde met zichtbare stuurtekens (… | 28 | U | <CR><LF>), en toont Stored as de datatypereeks die wordt opgeslagen. De patroontaal, templates en een AUDAC-praktijkvoorbeeld zijn te vinden in het bovenstaande TCP/UDP-hoofdstuk.

De TCP/UDP-objectinstellingen voor een audio gain-object.

TCP/UDP-integratie