Appareils virtuels
Un appareil virtuel n’a aucun lien physique : le serveur lui-même conserve son état. Les appareils virtuels relient les fonctions des installations avancées. Utilisations courantes :
- Points pilotés par des flux Node-RED (ci-dessous).
- Groupes d’appareils — un groupe est un widget virtuel qui pilote ses membres (voir « Groupes d’appareils »).
- Sorties logiques matérialisées — la sortie d’une fonction transformée en véritable widget (voir « Configuration des fonctions et sorties »).
- Indicateurs et consignes pour les automatisations (« Mode vacances », « Décalage de la température de consigne »).
Créez-les dans l’espace Appareils comme tout autre widget, en réglant Protocol sur VIRTUAL. Pour chaque objet, configurez :
| Paramètre | Signification |
|---|---|
| Range - Min / Range - Max | Valeurs acceptées par l’objet. Une valeur écrite depuis l’extérieur (un flux, le webhook) hors de cette plage est refusée ; un nouvel objet commence avec une plage de 0 à 100. |
| Persist State | Indique si la valeur actuelle est conservée après un redémarrage du serveur. Activez cette option pour les indicateurs et les consignes ; laissez-la désactivée pour les signaux momentanés. |
Un objet virtuel n’a pas de réglage de valeur par défaut. Activez Persist State si la dernière valeur doit être rétablie après un redémarrage. L’Object ID affiché sous le titre de la boîte de dialogue de l’objet est l’identifiant utilisé par un flux ou le webhook pour adresser cet objet.

Node-RED
Node-RED est un service optionnel du serveur (activez-le dans « Services et protocoles ») permettant de créer des flux personnalisés : ponts MQTT, API cloud particulières, logique sur mesure qui ne convient pas au moteur logique, ou pilote d’un appareil non pris en charge par HyperVisu.
- Activation : dans Services, activez Node-RED. La ligne affiche Changes need a restart ; cliquez sur Restart Server dans le bandeau Pending Changes et attendez le redémarrage du serveur.
- Ouverture : lorsque le service fonctionne, Node-Red apparaît dans le groupe APPS de la barre latérale d’administration. Cliquez dessus pour ouvrir l’éditeur de flux dans un nouvel onglet.
- Connexion : connectez-vous avec votre compte HyperVisu.
- Pilotage des appareils : les nœuds Hypervisu de la palette lisent et écrivent directement les appareils HyperVisu (voir « Les nœuds HyperVisu » ci-dessous). Les appareils virtuels constituent le point de rencontre naturel : le flux calcule, l’appareil virtuel affiche le résultat et participe aux scénarios, automatisations et vues comme tout autre appareil.
- API webhook : les flux et les systèmes tiers peuvent aussi utiliser l’API webhook des appareils, protégée par la vérification du numéro de série (voir « Webhooks et API tierces »). L’interrupteur Webhooks de la page Services doit être activé (voir « Services et protocoles »). Traitez le numéro de série comme un secret : toute personne qui le possède peut écrire via le webhook.
💡 Conseil : privilégiez le moteur logique (voir « Moteur logique — Concepts et canevas ») pour la logique domotique courante : elle est surveillée, validée et visible pour les occupants. Utilisez Node-RED pour ce qui nécessite du code.
Les nœuds HyperVisu
Le Node-RED du serveur comprend une catégorie Hypervisu dans la palette : un nœud par type d’appareil, un nœud Input Target, deux nœuds de commande globale et un nœud Scenario. Un nœud d’appareil représente un appareil HyperVisu. Envoyez-lui un message pour commander l’appareil ; lorsque l’appareil change, le nœud émet la nouvelle valeur sur l’une de ses sorties.

| Nœud | Type d’appareil (voir « Vue d’ensemble des types de widgets ») | Entrées → sorties |
|---|---|---|
| Pushbutton | Bouton-poussoir | Tout message → 1 sortie |
| Light Switch, Switch | Interrupteur d’éclairage, interrupteur | 2 cibles → 2 sorties |
| Analog Output | Sortie analogique | Un nombre → 1 sortie |
| Shutter / Blind | Volet roulant / store | 8 cibles → 8 sorties |
| Temperature Controller | Température / thermostat | 5 cibles → 5 sorties |
| Dimmer | Variateur | 4 cibles → 4 sorties |
| RGB Dimmer | Variateur RGB | 4 cibles → 4 sorties |
| Tunable White Dimmer | Variateur de blanc ajustable | 6 cibles → 6 sorties |
| Analog Input | Entrée analogique | Un nombre → 1 sortie |
| Digital Input | Entrée numérique | true / false → 1 sortie |
| Text Input | Entrée de texte | Un texte → 1 sortie |
| Alarm | Alarme | 7 cibles → 7 sorties |
| Audio | Audio | 13 cibles → 13 sorties |
| Ventilation | Ventilation | 10 cibles → 10 sorties |
| Air Conditioning | Climatisation | 11 cibles → 11 sorties |
| Door Lock | Serrure | 2 cibles → 2 sorties |
| Meter | Compteur | 4 cibles → 4 sorties |
| Charger | Borne de recharge pour véhicule électrique | 8 cibles → 8 sorties |
| Global Lights, Global Shutters | Tous les éclairages ou volets d’une pièce ou d’une catégorie | Marche / arrêt, montée / descente — aucune sortie |
| Scenario | Un scénario | Tout message l’exécute — aucune sortie |
| Input Target | — | Ajoute le nom de la cible à un message (voir « Le nœud Input Target ») |
Comment les nœuds accèdent au serveur. Le Node-RED du serveur est fourni avec un sous-flux Hypervisu déjà placé dans un onglet de flux, à côté des nœuds qui acheminent les messages vers et depuis les nœuds d’appareil (un nœud de liaison, un nœud Widget out et un nœud de transfert). Le sous-flux se connecte au serveur avec un compte de service dédié, charge les pièces, catégories, appareils et scénarios, et maintient la connexion active. Laissez ces nœuds en place : sans eux, les listes des nœuds d’appareil sont vides et ces nœuds restent silencieux. La palette contient aussi un nœud Msg Forwarder : il fait partie de cet acheminement et est déjà placé ; n’en ajoutez pas un autre à vos flux.

⚠️ Attention : les flux disposent de tous les droits, et un nœud Global Lights ou Global Shutters agit sur tous les appareils correspondants de la pièce ou de la catégorie, y compris les appareils physiques.
Ajouter un nœud d’appareil
Prérequis : le service Node-RED activé (voir « Node-RED » ci-dessus), un serveur activé et l’appareil créé dans l’espace Appareils.
- Dans l’éditeur Node-RED, faites glisser le nœud du type d’appareil depuis la catégorie Hypervisu de la palette vers le flux.
- Double-cliquez sur le nœud. La boîte de dialogue répertorie les pièces, catégories et appareils de l’installation.
- Choisissez Room, puis Category, puis Widget (l’appareil). Chaque liste filtre la suivante. L’appareil doit correspondre au type du nœud : un nœud Dimmer ne répertorie que les variateurs.
- Vérifiez Description et la liste des objets en dessous : elles affichent les objets de l’appareil avec leurs Object IDs, pour vérifier que vous avez sélectionné le bon appareil.
- Name to display se remplit automatiquement avec « Room - Device ». Modifiez-le si vous souhaitez un autre libellé sur le canevas.
- Cliquez sur Done.
- Reliez un nœud inject (ou tout nœud produisant une valeur) à l’entrée et un nœud debug à chaque sortie à surveiller.
- Cliquez sur Deploy.

Si un appareil que vous venez de créer ne figure pas dans les listes, redémarrez les flux (menu Deploy → Restart Flows), rechargez la page de l’éditeur et rouvrez la boîte de dialogue.
Messages entrants et sortants
Un message destiné à un nœud d’appareil comporte deux propriétés :
| Propriété | Contenu |
|---|---|
msg.inputTarget | Objet de l’appareil auquel la valeur est destinée, identifié par son nom — par exemple Switch On/OFF ou Dimming setpoint. Les noms par nœud figurent dans « Référence des nœuds » ci-dessous. Utilisez un nœud Input Target pour le définir (voir « Le nœud Input Target »). |
msg.payload | La valeur : true / false, un nombre, un texte ou un objet RGB {"red": 255, "green": 120, "blue": 0}. |
Un message émis par une sortie contient la valeur dans msg.payload et l’Object ID de l’objet dans msg.topic. La sortie n correspond à la cible n de la liste du nœud, dans le même ordre.
Les cibles d’un nœud sont de deux types :
- Commandes (Switch On/OFF, Dimming setpoint, Up/Down output…) — l’envoi commande l’appareil, exactement comme un appui dans l’application.
- Retours d’état (Feedback, Status feedback, Actual setpoint, Temperature…) — l’état signalé par l’appareil. Une écriture depuis un flux actualise la valeur affichée par HyperVisu ; rien n’est envoyé à l’appareil.
Quand les sorties émettent :
| Sortie d’une… | Émet lorsque |
|---|---|
| Cible de commande | le flux envoie cette cible (la valeur est émise immédiatement) ; l’application, un scénario, une automatisation ou un autre flux commande l’appareil — uniquement lorsque la valeur change. |
| Cible de retour d’état | l’appareil signale une valeur — à chaque fois, même si elle est identique. |
ℹ️ Remarque : les noms sont sensibles à la casse. Un message dont le nom est inconnu ou sans
msg.inputTargetsur un nœud qui l’exige est ignoré sans erreur — par exempleSwitch ON/OFFau lieu deSwitch On/OFF.
Node-RED comme pilote d’appareil
Node-RED peut prendre en charge un appareil pour lequel HyperVisu ne dispose d’aucun protocole :
- Créez un appareil virtuel du type approprié (voir « Appareils virtuels » ci-dessus).
- Ajoutez son nœud à un flux. Reliez les sorties de commande aux nœuds qui communiquent avec l’appareil réel (HTTP, MQTT, série…).
- Renvoyez les réponses de l’appareil réel vers le nœud, via un nœud Input Target réglé sur la cible de retour d’état correspondante.
Les occupants utilisent l’appareil dans les applications comme d’habitude ; le flux transmet les commandes et renvoie l’état.

Le nœud Input Target
Le nœud Input Target définit msg.inputTarget à partir d’une liste, sans devoir saisir les noms.
- Faites glisser un nœud Input Target entre la source de la valeur et le nœud d’appareil.
- Double-cliquez dessus.
- Dans Widget, choisissez le type d’appareil (Dimmer, Shutter/Blind, Audio…).
- Dans Input, choisissez la cible. La liste affiche les cibles de ce type dans l’ordre des sorties du nœud d’appareil.
- Renseignez éventuellement Name. Sinon, le nœud affiche le nom de la cible sur le canevas.
- Cliquez sur Done, puis sur Deploy.

Le nœud transmet chaque message en y ajoutant msg.inputTarget et affiche la dernière valeur sous lui : un point vert avec Value: …, ou un anneau rouge avec No input target selected lorsque Input est vide. Un nœud d’appareil est généralement précédé de plusieurs nœuds Input Target, un par cible utilisée.
💡 Conseil : dans un nœud function, définissez vous-même la même propriété —
msg.inputTarget = "Dimming setpoint"; msg.payload = 40; return msg;. Une fonction peut ensuite envoyer plusieurs cibles à la suite avecnode.send().
Référence des nœuds
Chaque entrée répertorie les cibles dans l’ordre des sorties. C = commande, F = retour d’état. Les exemples proviennent d’un flux de test sur des appareils virtuels : nœuds inject à gauche, nœuds Input Target au milieu, nœud d’appareil, puis un nœud debug par sortie à droite.
Importer un exemple
Chaque exemple ci-dessous est fourni sous forme de fichier à importer dans votre propre Node-RED. Les nœuds d’appareil de ces fichiers ne sont liés à aucun appareil : leur nom affiche « (set device) ».
- Téléchargez le fichier d’exemple.
- Dans l’éditeur Node-RED, ouvrez le menu principal (☰) et choisissez Import.
- Cliquez sur select a file to import et choisissez le fichier, ou collez son contenu dans la boîte de dialogue.
- Choisissez current flow ou new flow, cliquez sur Import, puis sur le canevas pour placer le groupe.
- Double-cliquez sur le nœud d’appareil et choisissez Room, Category et Widget de votre installation (voir « Ajouter un nœud d’appareil »). Pour Global Lights et Global Shutters, choisissez une pièce ou une catégorie ; pour Scenario, un scénario. Cliquez sur Done.
- Cliquez sur Deploy.
⚠️ Attention : les nœuds inject d’un exemple commandent l’appareil dès que vous cliquez dessus. Liez d’abord les exemples à un appareil de test ou virtuel, et définissez l’appareil avant de déployer : un nœud sans appareil ne fait qu’enregistrer des erreurs.
Bouton-poussoir
| Entrée | Sortie |
|---|---|
Tout message — msg.inputTarget et msg.payload ne sont pas nécessaires | 1 · la valeur envoyée, chaque fois que le bouton est utilisé (application, scénario ou flux), une fois reçue par le serveur |
Le sous-type de l’appareil détermine la valeur : ON envoie true, OFF envoie false, Toggle envoie l’inverse de la dernière valeur.

Interrupteur d’éclairage et interrupteur
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Feedback | F | true / false |


Sortie analogique
| Entrée | Sortie |
|---|---|
Un nombre dans msg.payload, dans la plage de l’appareil ; msg.inputTarget est facultatif (Analog Output) | 1 · Commande — la valeur, chaque fois que l’appareil est commandé (application, scénario, automatisation ou flux) |

Volet roulant / store
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Up/Down output | C | false = montée, true = descente |
| 2 | Stop output | C | true = arrêt |
| 3 | Blind Position input | F | position 0–100 % |
| 4 | Blind Position output | C | position 0–100 % |
| 5 | Moving Up input | F | true pendant la montée |
| 6 | Moving Down input | F | true pendant la descente |
| 7 | Slat Position input | F | angle des lamelles 0–100 % |
| 8 | Slat Position output | C | angle des lamelles 0–100 % |
Les positions suivent la règle HyperVisu : 100 % correspond à la fermeture complète. Les cibles des lamelles n’existent que sur les volets avec lamelles. Les sorties 1 et 2 émettent à chaque commande, même si la valeur est identique.

Régulateur de température
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Setpoint | C | °C |
| 2 | Temperature | F | température mesurée, °C |
| 3 | Actual setpoint | F | °C |
| 4 | Mode Selection | C | numéro du mode : 1 Confort, 2 Veille, 3 Nuit |
| 5 | Actual mode | F | numéro du mode |

Variateur
| # | Cible | Type | Valeur |
|---|---|---|---|
| 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 % |

Variateur RGB
| # | Cible | Type | Valeur |
|---|---|---|---|
| 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 | même format |

Variateur de blanc ajustable
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Switch On/OFF | C | true / false |
| 2 | Status feedback | F | true / false |
| 3 | Dimming setpoint | C | luminosité 0–100 % |
| 4 | Dimming feedback | F | luminosité |
| 5 | Temperature setpoint | C | température de couleur, dans la plage de l’objet de l’appareil |
| 6 | Temperature feedback | F | température de couleur |

Entrée analogique et entrée numérique
| Nœud | Entrée | Sortie |
|---|---|---|
| Analog Input | Un nombre dans msg.payload, dans la plage de l’appareil ; msg.inputTarget facultatif (Analog Input) | 1 · la valeur, chaque fois que l’appareil en signale une |
| Digital Input | true / false ; msg.inputTarget facultatif (Digital Input) | 1 · l’état, chaque fois que l’appareil en signale un |
Il s’agit de mesures : une valeur écrite par un flux n’est émise en sortie qu’une fois enregistrée par le serveur, pas au moment où le flux l’envoie.


Entrée de texte
| Entrée | Sortie |
|---|---|
Un texte dans msg.payload ; msg.inputTarget facultatif (Text) | 1 · le texte, chaque fois qu’il change sur le serveur |
Le nœud accepte les textes d’un flux uniquement pour un appareil de texte VIRTUAL. Sur KNX, un texte (DPT 16) contient au maximum 14 caractères.

Alarme
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Arm Command | C | envoie toujours true, quelle que soit la charge utile |
| 2 | Partial Arm Command | C | envoie toujours true |
| 3 | Disarm Command | C | envoie toujours 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 lorsque l’alarme est déclenchée |
Aucun PIN n’est demandé, même si l’alarme est protégée par un PIN.

Audio
| # | Cible | Type | Valeur |
|---|---|---|---|
| 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 = lecture, false = arrêt |
| 8 | Play/Stop feedback | F | true / false |
| 9 | Source selection | C | numéro de source |
| 10 | Source feedback | F | numéro de source |
| 11 | Previous/Next | C | false = précédent, true = suivant |
| 12 | Track Title | F | texte |
| 13 | Track Artist | F | texte |
La sortie 11 émet à chaque appui, même si la valeur est identique.

Ventilation
| # | Cible | Type | Valeur |
|---|---|---|---|
| 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 |

Climatisation
| # | Cible | Type | Valeur |
|---|---|---|---|
| 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 | température mesurée, °C |


Serrure
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Lock/Unlock | C | true = verrouiller, false = déverrouiller |
| 2 | Feedback | F | true / false |

Compteur
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Power/Flow | F | nombre (W, ou débit pour l’eau et le gaz) |
| 2 | Energy/Volume | F | nombre (kWh, ou volume) |
| 3 | Exported Energy | F | nombre (kWh) |
| 4 | State Of Charge | F | nombre (%) |
Sans msg.inputTarget, la valeur est envoyée à Power/Flow. Un compteur ne possède que les objets de son rôle (voir « Vue d’ensemble des types de widgets ») : un compteur réseau n’a pas d’état de charge. Une valeur écrite par un flux est émise en sortie une fois enregistrée par le serveur.

Borne de recharge
| # | Cible | Type | Valeur |
|---|---|---|---|
| 1 | Start/Stop | C | true = démarrer, false = arrêter |
| 2 | Charging | F | true / false |
| 3 | Charging Current | C | A |
| 4 | Connected | F | true lorsqu’un véhicule est branché |
| 5 | Error | F | true / false |
| 6 | Actual Power | F | W |
| 7 | Last Energy | F | kWh de la dernière session |
| 8 | Last duration | F | durée de la dernière session |

Global Lights, Global Shutters et Scenario
| Nœud | Dans la boîte de dialogue | Entrée | Sortie |
|---|---|---|---|
| Global Lights | Room ou Category (sélectionner l’un efface l’autre) | msg.inputTarget = On ou Off ; la charge utile est ignorée | — |
| Global Shutters | Room ou Category | msg.inputTarget = Up ou Down | — |
| Scenario | Scenario | Tout message exécute le scénario | — |
Les nœuds globaux envoient la même commande que les boutons globaux de l’application : tous les éclairages ou tous les volets de la pièce ou de la catégorie.


ℹ️ Remarque : lorsque vous rouvrez un nœud Global Lights ou Global Shutters, les deux listes affichent une valeur : la liste Category affiche simplement sa première entrée. Le nœud agit sur la liste modifiée en dernier : ici la pièce, comme l’indique son nom. Pour passer à une catégorie, sélectionnez-la dans Category (la pièce est alors effacée).