Virtuele apparaten
Een virtueel apparaat heeft geen fysieke verbinding: de server bewaart zelf de toestand. Virtuele apparaten verbinden de functies van geavanceerde installaties. Typische toepassingen:
- Punten die door Node-RED-flows worden aangestuurd (hieronder).
- Apparaatgroepen — een groep is een virtuele widget die zijn leden aanstuurt (zie ‘Apparaatgroepen’).
- Gerealiseerde logica-uitgangen — de uitgang van een functie omgezet in een echte widget (zie ‘Functies instellen en uitgangen’).
- Vlaggen en instelwaarden voor automatiseringen (‘Vakantiemodus’, ‘Verschuiving van de gewenste temperatuur’).
Maak ze in de werkruimte Apparaten aan zoals elke andere widget, met Protocol ingesteld op VIRTUAL. Per object stelt u het volgende in:
| Instelling | Betekenis |
|---|---|
| Range - Min / Range - Max | De waarden die het object accepteert. Een extern geschreven waarde (van een flow of de webhook) buiten het bereik wordt geweigerd; een nieuw object begint met 0 tot 100. |
| Persist State | Of de huidige waarde behouden blijft na een herstart van de server. Schakel dit in voor vlaggen en instelwaarden; laat het uit voor kortstondige signalen. |
Een virtueel object heeft geen instelling voor een standaardwaarde. Schakel Persist State in als de laatste waarde na een herstart moet terugkomen. De Object ID onder de titel van het objectvenster is wat een flow of de webhook gebruikt om het object te adresseren.

Node-RED
Node-RED is een optionele service op de server (inschakelen in ‘Services en protocollen’) voor aangepaste flows: MQTT-bruggen, afwijkende cloud-API’s, logica op maat die niet in de logica-engine past, of een driver voor een apparaat dat HyperVisu niet ondersteunt.
- Inschakelen: schakel Node-RED in onder Services. De regel toont Changes need a restart; klik op Restart Server in de balk Pending Changes en wacht tot de server weer beschikbaar is.
- Openen: zodra de service draait, verschijnt Node-Red in de groep APPS in de beheerzijbalk. Klik erop om de floweditor in een nieuw tabblad te openen.
- Verbinding: meld u aan met uw HyperVisu-account.
- Apparaten aansturen: de Hypervisu-nodes in het palet lezen en schrijven rechtstreeks naar HyperVisu-apparaten (zie ‘De HyperVisu-nodes’ hieronder). Virtuele apparaten zijn het natuurlijke koppelpunt: de flow rekent, het virtuele apparaat toont het resultaat en neemt deel aan scenario’s, automatiseringen en weergaven zoals elk ander apparaat.
- Webhook-API: flows en externe systemen kunnen ook de webhook-API voor apparaten gebruiken, beveiligd door verificatie van het serienummer (zie ‘Webhooks en externe API’s’). De schakelaar Webhooks op de pagina Services moet daarvoor aanstaan (zie ‘Services en protocollen’). Houd het serienummer geheim: iedereen die het heeft, kan via de webhook schrijven.
💡 Tip: gebruik bij voorkeur de logica-engine (zie ‘Logica-engine — Concepten en canvas’) voor standaardlogica in gebouwen: deze wordt bewaakt, gevalideerd en is zichtbaar voor bewoners. Gebruik Node-RED voor wat alleen met code kan.
De HyperVisu-nodes
De Node-RED van de server bevat een paletcategorie Hypervisu: één node per apparaattype, een Input Target-node, twee nodes voor globale opdrachten en een Scenario-node. Een apparaatnode vertegenwoordigt één HyperVisu-apparaat. Stuur er een bericht naartoe om het apparaat aan te sturen; wanneer het apparaat verandert, verstuurt de node de nieuwe waarde via een van zijn uitgangen.

| Node | Apparaattype (zie ‘Overzicht van widgettypen’) | Ingangen → uitgangen |
|---|---|---|
| Pushbutton | Drukknop | Elk bericht → 1 uitgang |
| Light Switch, Switch | Lichtschakelaar, schakelaar | 2 doelen → 2 uitgangen |
| Analog Output | Analoge uitgang | Een getal → 1 uitgang |
| Shutter / Blind | Rolluik / jaloezie | 8 doelen → 8 uitgangen |
| Temperature Controller | Temperatuur / thermostaat | 5 doelen → 5 uitgangen |
| Dimmer | Dimmer | 4 doelen → 4 uitgangen |
| RGB Dimmer | RGB-dimmer | 4 doelen → 4 uitgangen |
| Tunable White Dimmer | Dimmer voor instelbaar wit | 6 doelen → 6 uitgangen |
| Analog Input | Analoge ingang | Een getal → 1 uitgang |
| Digital Input | Digitale ingang | true / false → 1 uitgang |
| Text Input | Tekstingang | Een tekst → 1 uitgang |
| Alarm | Alarm | 7 doelen → 7 uitgangen |
| Audio | Audio | 13 doelen → 13 uitgangen |
| Ventilation | Ventilatie | 10 doelen → 10 uitgangen |
| Air Conditioning | Airconditioning | 11 doelen → 11 uitgangen |
| Door Lock | Deurslot | 2 doelen → 2 uitgangen |
| Meter | Meter | 4 doelen → 4 uitgangen |
| Charger | Laadpaal voor elektrische voertuigen | 8 doelen → 8 uitgangen |
| Global Lights, Global Shutters | Alle verlichting of rolluiken van een ruimte of categorie | Aan / uit, omhoog / omlaag — geen uitgang |
| Scenario | Een scenario | Elk bericht voert het uit — geen uitgang |
| Input Target | — | Voegt de doelnaam aan een bericht toe (zie ‘De Input Target-node’) |
Hoe de nodes de server bereiken. De Node-RED van de server bevat een Hypervisu-subflow die al in een flowtabblad staat, naast de nodes die berichten van en naar de apparaatnodes routeren (een linknode, een Widget out-node en een doorstuurnode). De subflow meldt zich met een speciaal serviceaccount bij de server aan, laadt de ruimtes, categorieën, apparaten en scenario’s en houdt de liveverbinding open. Laat deze nodes staan: zonder deze nodes hebben de apparaatnodes lege lijsten en blijven ze stil. Het palet bevat ook een Msg Forwarder-node: die maakt deel uit van deze routering en staat al op zijn plaats; voeg geen extra exemplaar aan uw flows toe.

⚠️ Waarschuwing: flows werken met volledige rechten. Een Global Lights- of Global Shutters-node werkt op alle overeenkomende apparaten van de ruimte of categorie, inclusief fysieke apparaten.
Een apparaatnode toevoegen
Benodigd: de Node-RED-service ingeschakeld (zie ‘Node-RED’ hierboven), een geactiveerde server en het apparaat aangemaakt in de werkruimte Apparaten.
- Sleep in de Node-RED-editor de node voor het apparaattype vanuit de paletcategorie Hypervisu naar de flow.
- Dubbelklik op de node. Het venster toont de ruimtes, categorieën en apparaten van de installatie.
- Kies Room, daarna Category en vervolgens Widget (het apparaat). Elke lijst beperkt de volgende. Het apparaat moet bij het nodetype passen: een Dimmer-node toont alleen dimmers.
- Controleer Description en de objectlijst eronder: deze tonen de objecten van het apparaat met hun Object IDs, zodat u zeker weet dat u het juiste apparaat hebt gekozen.
- Name to display wordt automatisch ingevuld als ‘Room - Device’. Pas dit aan als u een ander label op het canvas wilt.
- Klik op Done.
- Verbind een inject-node (of een andere node die een waarde levert) met de ingang en een debug-node met elke uitgang die u wilt volgen.
- Klik op Deploy.

Ontbreekt een zojuist aangemaakt apparaat in de lijsten, herstart dan de flows (menu Deploy → Restart Flows), herlaad de editorpagina en open het venster opnieuw.
Inkomende en uitgaande berichten
Een bericht naar een apparaatnode bevat twee eigenschappen:
| Eigenschap | Inhoud |
|---|---|
msg.inputTarget | Voor welk object van het apparaat de waarde bestemd is, op naam — bijvoorbeeld Switch On/OFF of Dimming setpoint. De namen per node staan hieronder in ‘Nodereferentie’. Gebruik een Input Target-node om dit in te stellen (zie ‘De Input Target-node’). |
msg.payload | De waarde: true / false, een getal, een tekst of een RGB-object {"red": 255, "green": 120, "blue": 0}. |
Een bericht dat een uitgang verlaat, bevat de waarde in msg.payload en de Object ID van het object in msg.topic. Uitgang n hoort bij doel n van de nodelijst, in dezelfde volgorde.
Een node heeft twee soorten doelen:
- Opdrachten (Switch On/OFF, Dimming setpoint, Up/Down output…) — verzenden stuurt het apparaat aan, net als een tik in de app.
- Terugmeldingen (Feedback, Status feedback, Actual setpoint, Temperature…) — de toestand die het apparaat meldt. Schrijven vanuit een flow werkt de door HyperVisu getoonde waarde bij; er wordt niets naar het apparaat gestuurd.
Wanneer de uitgangen berichten versturen:
| Uitgang van een… | Verstuurt wanneer |
|---|---|
| Opdrachtdoel | de flow dat doel verstuurt (de waarde wordt direct uitgevoerd); de app, een scenario, een automatisering of een andere flow het apparaat aanstuurt — alleen wanneer de waarde verandert. |
| Terugmeldingsdoel | het apparaat een waarde meldt — elke keer, ook als deze gelijk blijft. |
ℹ️ Opmerking: namen zijn hoofdlettergevoelig. Een bericht met een onbekende naam, of zonder
msg.inputTargetbij een node die dit nodig heeft, wordt zonder foutmelding genegeerd — bijvoorbeeldSwitch ON/OFFin plaats vanSwitch On/OFF.
Node-RED als apparaatdriver
Node-RED kan een apparaat bedienen waarvoor HyperVisu geen protocol heeft:
- Maak een virtueel apparaat van het juiste type aan (zie ‘Virtuele apparaten’ hierboven).
- Voeg de node ervan aan een flow toe. Verbind de opdrachtuitgangen met de nodes die met het echte apparaat communiceren (HTTP, MQTT, serieel…).
- Voer de antwoorden van het echte apparaat terug naar de node, via een Input Target-node die op het overeenkomstige terugmeldingsdoel staat.
Bewoners gebruiken het apparaat zoals gewoonlijk in de apps; de flow stuurt de opdrachten door en voert de toestand terug.

De Input Target-node
De Input Target-node stelt msg.inputTarget voor u in vanuit een lijst, zodat u de namen niet hoeft te typen.
- Sleep een Input Target-node tussen de waardebron en de apparaatnode.
- Dubbelklik erop.
- Kies in Widget het apparaattype (Dimmer, Shutter/Blind, Audio…).
- Kies in Input het doel. De lijst toont de doelen van dat type in de volgorde van de uitgangen van de apparaatnode.
- Vul eventueel Name in. Zonder naam toont de node de doelnaam op het canvas.
- Klik op Done en daarna op Deploy.

De node stuurt elk bericht door met msg.inputTarget toegevoegd en toont de laatste waarde eronder: een groene stip met Value: …, of een rode ring met No input target selected als Input leeg is. Voor een apparaatnode staan gewoonlijk meerdere Input Target-nodes, één per gebruikt doel.
💡 Tip: stel in een function-node zelf dezelfde eigenschap in —
msg.inputTarget = "Dimming setpoint"; msg.payload = 40; return msg;. Een functie kan vervolgens meerdere doelen na elkaar versturen metnode.send().
Nodereferentie
Elke vermelding toont de doelen in uitgangsvolgorde. C = opdracht, F = terugmelding. De voorbeelden komen uit een testflow met virtuele apparaten: inject-nodes links, Input Target-nodes in het midden, de apparaatnode en rechts één debug-node per uitgang.
Een voorbeeld importeren
Elk voorbeeld hieronder is beschikbaar als bestand dat u in uw eigen Node-RED kunt importeren. De apparaatnodes in deze bestanden zijn niet aan een apparaat gebonden: hun naam bevat ‘(set device)’.
- Download het voorbeeldbestand.
- Open in de Node-RED-editor het hoofdmenu (☰) en kies Import.
- Klik op select a file to import en kies het bestand, of plak de inhoud in het venster.
- Kies current flow of new flow, klik op Import en klik op het canvas om de groep te plaatsen.
- Dubbelklik op de apparaatnode en kies Room, Category en Widget van uw installatie (zie ‘Een apparaatnode toevoegen’). Kies voor Global Lights en Global Shutters een ruimte of categorie; voor Scenario een scenario. Klik op Done.
- Klik op Deploy.
⚠️ Waarschuwing: de inject-nodes van een voorbeeld sturen het apparaat aan zodra u erop klikt. Bind de voorbeelden eerst aan een testapparaat of virtueel apparaat en stel het apparaat in voordat u implementeert: een apparaatnode zonder apparaat registreert alleen fouten.
Drukknop
| Ingang | Uitgang |
|---|---|
Elk bericht — msg.inputTarget en msg.payload zijn niet nodig | 1 · de verstuurde waarde, telkens wanneer de knop wordt gebruikt (app, scenario of flow), zodra de server deze heeft |
Het subtype van het apparaat bepaalt de waarde: ON verstuurt true, OFF verstuurt false, Toggle verstuurt het omgekeerde van de laatste waarde.

Lichtschakelaar en schakelaar
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Feedback | F | true / false |


Analoge uitgang
| Ingang | Uitgang |
|---|---|
Een getal in msg.payload, binnen het bereik van het apparaat; msg.inputTarget is optioneel (Analog Output) | 1 · Opdracht — de waarde, telkens wanneer het apparaat wordt aangestuurd (app, scenario, automatisering of flow) |

Rolluik / jaloezie
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Up/Down output | C | false = omhoog, true = omlaag |
| 2 | Stop output | C | true = stoppen |
| 3 | Blind Position input | F | positie 0–100 % |
| 4 | Blind Position output | C | positie 0–100 % |
| 5 | Moving Up input | F | true tijdens omhoog bewegen |
| 6 | Moving Down input | F | true tijdens omlaag bewegen |
| 7 | Slat Position input | F | lamellenhoek 0–100 % |
| 8 | Slat Position output | C | lamellenhoek 0–100 % |
Posities volgen de regel van HyperVisu: 100 % is volledig gesloten. Lameldoelen bestaan alleen op rolluiken met lamellen. Uitgangen 1 en 2 versturen bij elke opdracht, ook als de waarde gelijk blijft.

Temperatuurregelaar
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Setpoint | C | °C |
| 2 | Temperature | F | gemeten temperatuur, °C |
| 3 | Actual setpoint | F | °C |
| 4 | Mode Selection | C | modusnummer: 1 Comfort, 2 Stand-by, 3 Nacht |
| 5 | Actual mode | F | modusnummer |

Dimmer
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | Dimming setpoint | C | 0–100 % |
| 4 | Dimming feedback | F | 0–100 % |

RGB-dimmer
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | RGB setpoint | C | {"red": 0–255, "green": 0–255, "blue": 0–255} |
| 4 | RGB feedback | F | hetzelfde formaat |

Dimmer voor instelbaar wit
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | Dimming setpoint | C | helderheid 0–100 % |
| 4 | Dimming feedback | F | helderheid |
| 5 | Temperature setpoint | C | kleurtemperatuur, binnen het bereik van het apparaatobject |
| 6 | Temperature feedback | F | kleurtemperatuur |

Analoge ingang en digitale ingang
| Node | Ingang | Uitgang |
|---|---|---|
| Analog Input | Een getal in msg.payload, binnen het bereik van het apparaat; msg.inputTarget optioneel (Analog Input) | 1 · de waarde, telkens wanneer het apparaat er een meldt |
| Digital Input | true / false; msg.inputTarget optioneel (Digital Input) | 1 · de toestand, telkens wanneer het apparaat er een meldt |
Dit zijn metingen: een door een flow geschreven waarde verlaat de uitgang pas nadat de server deze heeft opgeslagen, niet op het moment dat de flow deze verstuurt.


Tekstingang
| Ingang | Uitgang |
|---|---|
Een tekst in msg.payload; msg.inputTarget optioneel (Text) | 1 · de tekst, telkens wanneer deze op de server verandert |
De node accepteert tekst uit een flow alleen voor een VIRTUAL-tekstapparaat. Op KNX bevat een tekst (DPT 16) maximaal 14 tekens.

Alarm
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Arm Command | C | verstuurt altijd true, ongeacht de payload |
| 2 | Partial Arm Command | C | verstuurt altijd true |
| 3 | Disarm Command | C | verstuurt altijd true |
| 4 | Armed Status | F | true / false |
| 5 | Partial Armed Status | F | true / false |
| 6 | Disarmed Status | F | true / false |
| 7 | Alarm Status | F | true wanneer het alarm wordt geactiveerd |
Er wordt geen PIN gevraagd, ook niet als het alarm met een PIN is beveiligd.

Audio
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Volume setpoint | C | 0–100 |
| 2 | Volume feedback | F | 0–100 |
| 3 | Zone On/Off | C | true / false |
| 4 | Zone feedback | F | true / false |
| 5 | Mute On/Off | C | true / false |
| 6 | Mute feedback | F | true / false |
| 7 | Play/Stop | C | true = afspelen, false = stoppen |
| 8 | Play/Stop feedback | F | true / false |
| 9 | Source selection | C | bronnummer |
| 10 | Source feedback | F | bronnummer |
| 11 | Previous/Next | C | false = vorige, true = volgende |
| 12 | Track Title | F | tekst |
| 13 | Track Artist | F | tekst |
Uitgang 11 verstuurt bij elke druk, ook als de waarde gelijk blijft.

Ventilatie
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Auto On/Off | C | true / false |
| 2 | Auto feedback | F | true / false |
| 3 | Slow On/Off | C | true / false |
| 4 | Slow feedback | F | true / false |
| 5 | Medium On/Off | C | true / false |
| 6 | Medium feedback | F | true / false |
| 7 | High On/Off | C | true / false |
| 8 | High feedback | F | true / false |
| 9 | Boost | C | true / false |
| 10 | Boost feedback | F | true / false |

Airconditioning
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | On/Off | C | true / false |
| 2 | On/Off feedback | F | true / false |
| 3 | Heating Mode | C | true |
| 4 | Heating feedback | F | true / false |
| 5 | Cooling Mode | C | true |
| 6 | Cooling feedback | F | true / false |
| 7 | Auto Mode | C | true |
| 8 | Auto feedback | F | true / false |
| 9 | Setpoint | C | °C |
| 10 | Actual setpoint | F | °C |
| 11 | Temperature | F | gemeten temperatuur, °C |


Deurslot
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Lock/Unlock | C | true = vergrendelen, false = ontgrendelen |
| 2 | Feedback | F | true / false |

Meter
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Power/Flow | F | getal (W, of een debiet voor water en gas) |
| 2 | Energy/Volume | F | getal (kWh, of een volume) |
| 3 | Exported Energy | F | getal (kWh) |
| 4 | State Of Charge | F | getal (%) |
Zonder msg.inputTarget gaat de waarde naar Power/Flow. Een meter heeft alleen de objecten die bij zijn rol horen (zie ‘Overzicht van widgettypen’): een netmeter heeft geen laadstatus. Een door een flow geschreven waarde verlaat de uitgang nadat de server deze heeft opgeslagen.

Laadpaal
| # | Doel | Soort | Waarde |
|---|---|---|---|
| 1 | Start/Stop | C | true = starten, false = stoppen |
| 2 | Charging | F | true / false |
| 3 | Charging Current | C | A |
| 4 | Connected | F | true wanneer een voertuig is aangesloten |
| 5 | Error | F | true / false |
| 6 | Actual Power | F | W |
| 7 | Last Energy | F | kWh van de laatste sessie |
| 8 | Last duration | F | duur van de laatste sessie |

Global Lights, Global Shutters en Scenario
| Node | In het venster | Ingang | Uitgang |
|---|---|---|---|
| Global Lights | Room of Category (kiezen van de ene wist de andere) | msg.inputTarget = On of Off; de payload wordt genegeerd | — |
| Global Shutters | Room of Category | msg.inputTarget = Up of Down | — |
| Scenario | Scenario | Elk bericht voert het scenario uit | — |
De globale nodes versturen dezelfde opdracht als de globale knoppen in de app: alle verlichting of alle rolluiken van de ruimte of categorie.


ℹ️ Opmerking: wanneer u een Global Lights- of Global Shutters-node opnieuw opent, tonen beide lijsten een waarde: de Category-lijst toont simpelweg de eerste vermelding. De node werkt op de lijst die u het laatst hebt gewijzigd: hier de ruimte, zoals de naam aangeeft. Kies een categorie in Category om over te schakelen (de ruimte wordt dan gewist).