O que é um dispositivo virtual?

É um widget cujo estado é conservado no servidor sem uma ligação física de protocolo. Pode representar um indicador, um grupo, um valor calculado ou um ponto Node-RED.

Como conservar um valor virtual após um reinício?

Ative Persist State no respetivo objeto de comunicação. Um objeto virtual não tem definição de valor predefinido.

Onde abro o Node-RED?

Ative o serviço opcional Node-RED na página Services e reinicie o servidor. Quando estiver em execução, a respetiva entrada aparece em APPS na barra lateral de administração e abre o editor de fluxos num novo separador.

Quando devo utilizar o Node-RED em vez do motor de lógica?

Utilize o motor de lógica para a lógica habitual dos edifícios, com validação e monitorização. O Node-RED é adequado para integrações e fluxos personalizados que não se enquadram nesses blocos.

Porque é que um nó HyperVisu ignora a minha mensagem?

O nome do destino em msg.inputTarget está em falta, mal escrito ou com maiúsculas incorretas — por exemplo Switch ON/OFF em vez de Switch On/OFF. Defina-o com um nó Input Target. Verifique também se o nó está associado a um dispositivo: um exemplo importado mostra «(set device)» até escolher um.

Os fluxos precisam do PIN do alarme?

Não. Um fluxo arma e desarma um alarme sem PIN, mesmo que esteja protegido, tal como os cenários e as automatizações.

Dispositivos virtuais e Node-RED

Dispositivos virtuais

Um dispositivo virtual não tem qualquer ligação física — o próprio servidor conserva o seu estado. Os dispositivos virtuais interligam as funções das instalações avançadas. Utilizações típicas:

Pontos controlados por fluxos Node-RED (abaixo).
Grupos de dispositivos — um grupo é um widget virtual que controla os seus membros (ver «Grupos de dispositivos»).
Saídas de lógica materializadas — a saída de uma função transformada num widget real (ver «Configuração de funções e saídas»).
Indicadores e valores de referência para automatizações («Modo de férias», «Desvio da temperatura pretendida»).

Crie-os na área de trabalho Dispositivos como qualquer outro widget, com Protocol definido como VIRTUAL. Para cada objeto, configure:

Definição	Significado
Range - Min / Range - Max	Os valores que o objeto aceita. Um valor escrito do exterior (por um fluxo ou pelo webhook) fora do intervalo é recusado; um objeto novo começa com 0 a 100.
Persist State	Se o valor atual é conservado após reiniciar o servidor. Ative para indicadores e valores de referência; deixe desativado para sinais momentâneos.

Um objeto virtual não tem definição de valor predefinido. Ative Persist State se o último valor tiver de ser recuperado após um reinício. O Object ID apresentado sob o título da caixa de diálogo do objeto é o identificador que um fluxo ou o webhook utiliza para endereçar o objeto.

As definições de objeto de um widget virtual.

Node-RED

O Node-RED é um serviço opcional do servidor (ative-o em «Serviços e protocolos») para criar fluxos personalizados — pontes MQTT, API de cloud específicas, lógica à medida que não se enquadra no motor de lógica ou um controlador para um dispositivo que o HyperVisu não suporta.

Ativar: em Services, ative Node-RED. A linha mostra Changes need a restart; clique em Restart Server na faixa Pending Changes e aguarde que o servidor volte a estar disponível.
Abrir: quando o serviço estiver em execução, Node-Red aparece no grupo APPS da barra lateral de administração. Clique para abrir o editor de fluxos num novo separador.
Ligação: inicie sessão com a sua conta HyperVisu.
Controlar dispositivos: os nós Hypervisu da paleta leem e escrevem diretamente nos dispositivos HyperVisu (ver «Os nós HyperVisu» abaixo). Os dispositivos virtuais são o ponto de encontro natural: o fluxo calcula, o dispositivo virtual apresenta o resultado e participa em cenários, automatizações e vistas como qualquer outro dispositivo.
API webhook: os fluxos e os sistemas de terceiros também podem utilizar a API webhook de dispositivos, protegida pela verificação do número de série (ver «Webhooks e API de terceiros»). O interruptor Webhooks da página Services tem de estar ativo (ver «Serviços e protocolos»). Mantenha o número de série secreto: quem o conhecer pode escrever através do webhook.

💡 Sugestão: prefira o motor de lógica (ver «Motor de lógica — Conceitos e tela») para a lógica habitual dos edifícios — é monitorizada, validada e visível para os residentes. Utilize o Node-RED para o que exige código.

Os nós HyperVisu

O Node-RED do servidor inclui uma categoria Hypervisu na paleta: um nó por tipo de dispositivo, um nó Input Target, dois nós de comandos globais e um nó Scenario. Um nó de dispositivo representa um dispositivo HyperVisu. Envie-lhe uma mensagem para comandar o dispositivo; quando o dispositivo muda, o nó emite o novo valor por uma das suas saídas.

A paleta deslocada até à categoria Hypervisu.

Nó	Tipo de dispositivo (ver «Visão geral dos tipos de widgets»)	Entradas → saídas
Pushbutton	Botão de pressão	Qualquer mensagem → 1 saída
Light Switch, Switch	Interruptor de iluminação, interruptor	2 destinos → 2 saídas
Analog Output	Saída analógica	Um número → 1 saída
Shutter / Blind	Estore / persiana	8 destinos → 8 saídas
Temperature Controller	Temperatura / termóstato	5 destinos → 5 saídas
Dimmer	Regulador de luminosidade	4 destinos → 4 saídas
RGB Dimmer	Regulador de luminosidade RGB	4 destinos → 4 saídas
Tunable White Dimmer	Regulador de branco ajustável	6 destinos → 6 saídas
Analog Input	Entrada analógica	Um número → 1 saída
Digital Input	Entrada digital	true / false → 1 saída
Text Input	Entrada de texto	Um texto → 1 saída
Alarm	Alarme	7 destinos → 7 saídas
Audio	Áudio	13 destinos → 13 saídas
Ventilation	Ventilação	10 destinos → 10 saídas
Air Conditioning	Ar condicionado	11 destinos → 11 saídas
Door Lock	Fechadura de porta	2 destinos → 2 saídas
Meter	Contador	4 destinos → 4 saídas
Charger	Carregador de veículo elétrico	8 destinos → 8 saídas
Global Lights, Global Shutters	Todas as luzes ou estores de uma divisão ou categoria	Ligar / desligar, subir / descer — sem saída
Scenario	Um cenário	Qualquer mensagem o executa — sem saída
Input Target	—	Adiciona o nome do destino a uma mensagem (ver «O nó Input Target»)

Como os nós acedem ao servidor. O Node-RED do servidor inclui um subfluxo Hypervisu já colocado num separador de fluxo, junto dos nós que encaminham mensagens de e para os nós de dispositivo (um nó de ligação, um nó Widget out e um nó de reencaminhamento). O subfluxo inicia sessão no servidor com uma conta de serviço dedicada, carrega as divisões, categorias, dispositivos e cenários e mantém a ligação em tempo real aberta. Deixe estes nós no lugar: sem eles, os nós de dispositivo têm listas vazias e não emitem mensagens. A paleta também inclui um nó Msg Forwarder: faz parte deste encaminhamento e já está colocado — não adicione outro aos seus fluxos.

⚠️ Aviso: os fluxos atuam com todos os direitos e um nó Global Lights ou Global Shutters atua sobre todos os dispositivos correspondentes da divisão ou categoria, incluindo os físicos.

Adicionar um nó de dispositivo

Requisitos: serviço Node-RED ativo (ver «Node-RED» acima), servidor ativado e dispositivo criado na área de trabalho Dispositivos.

No editor Node-RED, arraste o nó do tipo de dispositivo da categoria Hypervisu da paleta para o fluxo.
Faça duplo clique no nó. A caixa de diálogo apresenta as divisões, categorias e dispositivos da instalação.
Escolha Room, depois Category e, em seguida, Widget (o dispositivo). Cada lista filtra a seguinte. O dispositivo tem de ser do tipo do nó: um nó Dimmer apresenta apenas reguladores de luminosidade.
Verifique Description e a lista de objetos por baixo: apresentam os objetos do dispositivo com os respetivos Object IDs, para confirmar que escolheu o dispositivo certo.
Name to display é preenchido automaticamente como «Room - Device». Altere-o se pretender outro rótulo na tela.
Clique em Done.
Ligue um nó inject (ou qualquer nó que produza um valor) à entrada e um nó debug a cada saída que pretenda observar.
Clique em Deploy.

A caixa de diálogo aberta do nó Light Switch.

Se um dispositivo que acabou de criar não aparecer nas listas, reinicie os fluxos (menu Deploy → Restart Flows), recarregue a página do editor e abra novamente a caixa de diálogo.

Mensagens de entrada e saída

Uma mensagem para um nó de dispositivo contém duas propriedades:

Propriedade	Conteúdo
`msg.inputTarget`	O objeto do dispositivo a que se destina o valor, identificado pelo nome — por exemplo `Switch On/OFF` ou `Dimming setpoint`. Os nomes por nó constam da «Referência dos nós», abaixo. Utilize um nó Input Target para o definir (ver «O nó Input Target»).
`msg.payload`	O valor: `true` / `false`, um número, um texto ou um objeto RGB `{"red": 255, "green": 120, "blue": 0}`.

Uma mensagem emitida por uma saída contém o valor em msg.payload e o Object ID do objeto em msg.topic. A saída n corresponde ao destino n da lista do nó, pela mesma ordem.

Os destinos de um nó são de dois tipos:

Comandos (Switch On/OFF, Dimming setpoint, Up/Down output…) — o envio comanda o dispositivo, tal como um toque na aplicação.
Retornos de estado (Feedback, Status feedback, Actual setpoint, Temperature…) — o estado comunicado pelo dispositivo. Uma escrita a partir de um fluxo atualiza o valor apresentado pelo HyperVisu; nada é enviado ao dispositivo.

Quando as saídas são acionadas:

Saída de um…	É acionada quando
Destino de comando	o fluxo envia esse destino (o valor sai de imediato); a aplicação, um cenário, uma automatização ou outro fluxo comanda o dispositivo — apenas quando o valor muda.
Destino de retorno de estado	o dispositivo comunica um valor — sempre, mesmo quando se repete.

ℹ️ Nota: os nomes distinguem maiúsculas de minúsculas. Uma mensagem com nome desconhecido, ou sem msg.inputTarget num nó que o exige, é ignorada sem erro — por exemplo Switch ON/OFF em vez de Switch On/OFF.

Node-RED como controlador de dispositivo

O Node-RED pode assegurar a ligação a um dispositivo para o qual o HyperVisu não dispõe de protocolo:

Crie um dispositivo virtual do tipo adequado (ver «Dispositivos virtuais» acima).
Adicione o respetivo nó a um fluxo. Ligue as saídas de comando aos nós que comunicam com o dispositivo real (HTTP, MQTT, série…).
Ligue as respostas do dispositivo real de volta ao nó, através de um nó Input Target definido para o destino de retorno de estado correspondente.

Os residentes utilizam o dispositivo nas aplicações como habitualmente; o fluxo transmite os comandos e devolve o estado.

A barra lateral de depuração após uma injeção «ON» no nó Light Switch.

O nó Input Target

O nó Input Target define msg.inputTarget a partir de uma lista, para não ter de escrever os nomes.

Arraste um nó Input Target para entre a origem do valor e o nó de dispositivo.
Faça duplo clique nele.
Em Widget, escolha o tipo de dispositivo (Dimmer, Shutter/Blind, Audio…).
Em Input, escolha o destino. A lista apresenta os destinos desse tipo pela ordem das saídas do nó de dispositivo.
Preencha Name, se pretender. Sem nome, o nó apresenta o nome do destino na tela.
Clique em Done e depois em Deploy.

A caixa de diálogo aberta do nó Input Target.

O nó reencaminha todas as mensagens com msg.inputTarget adicionado e apresenta por baixo o último valor: um ponto verde com Value: …, ou um anel vermelho com No input target selected quando Input está vazio. Um nó de dispositivo tem geralmente vários nós Input Target antes dele, um por destino utilizado.

💡 Sugestão: num nó function, defina a mesma propriedade — msg.inputTarget = "Dimming setpoint"; msg.payload = 40; return msg;. Uma função pode depois enviar vários destinos em sequência com node.send().

Referência dos nós

Cada entrada apresenta os destinos pela ordem das saídas. C = comando, F = retorno de estado. Os exemplos provêm de um fluxo de teste com dispositivos virtuais: nós inject à esquerda, nós Input Target no meio, o nó de dispositivo e um nó debug por saída à direita.

Importar um exemplo

Cada exemplo abaixo é disponibilizado como ficheiro que pode importar no seu Node-RED. Os nós de dispositivo destes ficheiros não estão associados a nenhum dispositivo: apresentam «(set device)» no nome.

Transfira o ficheiro de exemplo.
No editor Node-RED, abra o menu principal (☰) e escolha Import.
Clique em select a file to import e escolha o ficheiro, ou cole o seu conteúdo na caixa de diálogo.
Escolha current flow ou new flow, clique em Import e depois na tela para colocar o grupo.
Faça duplo clique no nó de dispositivo e escolha Room, Category e Widget da sua instalação (ver «Adicionar um nó de dispositivo»). Para Global Lights e Global Shutters, escolha uma divisão ou categoria; para Scenario, um cenário. Clique em Done.
Clique em Deploy.

⚠️ Aviso: os nós inject de um exemplo comandam o dispositivo assim que lhes clica. Associe primeiro os exemplos a um dispositivo de teste ou virtual e defina o dispositivo antes de implementar — um nó sem dispositivo limita-se a registar erros.

Botão de pressão

Entrada	Saída
Qualquer mensagem — `msg.inputTarget` e `msg.payload` não são necessários	1 · o valor enviado, sempre que o botão é utilizado (aplicação, cenário ou fluxo), assim que o servidor o recebe

O subtipo do dispositivo determina o valor: ON envia true, OFF envia false, Toggle envia o contrário do último valor.

Pushbutton.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Interruptor de iluminação e interruptor

#	Destino	Tipo	Valor
1	`Switch On/OFF`	C	`true` / `false`
2	`Feedback`	F	`true` / `false`

Light-Switch.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Switch.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Saída analógica

Entrada	Saída
Um número em `msg.payload`, dentro do intervalo do dispositivo; `msg.inputTarget` é opcional (`Analog Output`)	1 · Comando — o valor, sempre que o dispositivo é comandado (aplicação, cenário, automatização ou fluxo)

Analog-Output.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Estore / persiana

#	Destino	Tipo	Valor
1	`Up/Down output`	C	`false` = subir, `true` = descer
2	`Stop output`	C	`true` = parar
3	`Blind Position input`	F	posição 0–100 %
4	`Blind Position output`	C	posição 0–100 %
5	`Moving Up input`	F	`true` durante a subida
6	`Moving Down input`	F	`true` durante a descida
7	`Slat Position input`	F	ângulo das lâminas 0–100 %
8	`Slat Position output`	C	ângulo das lâminas 0–100 %

As posições seguem a regra do HyperVisu: 100 % significa totalmente fechado. Os destinos das lâminas só existem em estores com lâminas. As saídas 1 e 2 são acionadas em cada comando, mesmo quando o valor se repete.

Shutter-Blind.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Controlador de temperatura

#	Destino	Tipo	Valor
1	`Setpoint`	C	°C
2	`Temperature`	F	temperatura medida, °C
3	`Actual setpoint`	F	°C
4	`Mode Selection`	C	número do modo: `1` Conforto, `2` Espera, `3` Noite
5	`Actual mode`	F	número do modo

Temperature-Controller.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Regulador de luminosidade

#	Destino	Tipo	Valor
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 %

Dimmer.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Regulador de luminosidade RGB

#	Destino	Tipo	Valor
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	mesmo formato

RGB-Dimmer.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Regulador de branco ajustável

#	Destino	Tipo	Valor
1	`Switch On/OFF`	C	`true` / `false`
2	`Status feedback`	F	`true` / `false`
3	`Dimming setpoint`	C	luminosidade 0–100 %
4	`Dimming feedback`	F	luminosidade
5	`Temperature setpoint`	C	temperatura de cor, dentro do intervalo do objeto do dispositivo
6	`Temperature feedback`	F	temperatura de cor

Tunable-White-Dimmer.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Entrada analógica e entrada digital

Nó	Entrada	Saída
Analog Input	Um número em `msg.payload`, dentro do intervalo do dispositivo; `msg.inputTarget` opcional (`Analog Input`)	1 · o valor, sempre que o dispositivo comunica um
Digital Input	`true` / `false`; `msg.inputTarget` opcional (`Digital Input`)	1 · o estado, sempre que o dispositivo comunica um

São medições: um valor escrito por um fluxo só sai pela saída depois de o servidor o armazenar, não no momento em que o fluxo o envia.

Analog-Input.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Digital-Input.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Entrada de texto

Entrada	Saída
Um texto em `msg.payload`; `msg.inputTarget` opcional (`Text`)	1 · o texto, sempre que muda no servidor

O nó só aceita textos de um fluxo para um dispositivo de texto VIRTUAL. No KNX, um texto (DPT 16) contém no máximo 14 caracteres.

Text-Input.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Alarme

#	Destino	Tipo	Valor
1	`Arm Command`	C	envia sempre `true`, independentemente do conteúdo da mensagem
2	`Partial Arm Command`	C	envia sempre `true`
3	`Disarm Command`	C	envia sempre `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` quando o alarme é acionado

Não é pedido PIN, mesmo que o alarme esteja protegido por um.

Alarm.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Áudio

#	Destino	Tipo	Valor
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` = reproduzir, `false` = parar
8	`Play/Stop feedback`	F	`true` / `false`
9	`Source selection`	C	número da fonte
10	`Source feedback`	F	número da fonte
11	`Previous/Next`	C	`false` = anterior, `true` = seguinte
12	`Track Title`	F	texto
13	`Track Artist`	F	texto

A saída 11 é acionada a cada pressão, mesmo quando o valor se repete.

Audio.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Ventilação

#	Destino	Tipo	Valor
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`

Ventilation.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Ar condicionado

#	Destino	Tipo	Valor
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	temperatura medida, °C

Air-Conditioning.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Um segundo exemplo Air Conditioning no mesmo dispositivo, com nós Input Target.

Air-Conditioning-Input-Targets.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Fechadura de porta

#	Destino	Tipo	Valor
1	`Lock/Unlock`	C	`true` = trancar, `false` = destrancar
2	`Feedback`	F	`true` / `false`

Door-Lock.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Contador

#	Destino	Tipo	Valor
1	`Power/Flow`	F	número (W, ou caudal para água e gás)
2	`Energy/Volume`	F	número (kWh, ou volume)
3	`Exported Energy`	F	número (kWh)
4	`State Of Charge`	F	número (%)

Sem msg.inputTarget, o valor é enviado para Power/Flow. Um contador só tem os objetos da sua função (ver «Visão geral dos tipos de widgets»): um contador de rede não tem estado de carga. Um valor escrito por um fluxo sai pela saída depois de o servidor o armazenar.

Meter.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Carregador

#	Destino	Tipo	Valor
1	`Start/Stop`	C	`true` = iniciar, `false` = parar
2	`Charging`	F	`true` / `false`
3	`Charging Current`	C	A
4	`Connected`	F	`true` quando um veículo está ligado
5	`Error`	F	`true` / `false`
6	`Actual Power`	F	W
7	`Last Energy`	F	kWh da última sessão
8	`Last duration`	F	duração da última sessão

Charger.json — importe-o no Node-RED, faça duplo clique no nó de dispositivo para escolher o seu dispositivo e clique em Deploy.

Global Lights, Global Shutters e Scenario

Nó	Na caixa de diálogo	Entrada	Saída
Global Lights	Room ou Category (escolher um limpa o outro)	`msg.inputTarget` = `On` ou `Off`; o conteúdo da mensagem é ignorado	—
Global Shutters	Room ou Category	`msg.inputTarget` = `Up` ou `Down`	—
Scenario	Scenario	Qualquer mensagem executa o cenário	—

Os nós globais enviam o mesmo comando que os botões globais da aplicação: todas as luzes ou todos os estores da divisão ou categoria.

Global-Commands-and-Scenario.json — importe-o no Node-RED, faça duplo clique em cada nó para escolher a divisão ou categoria (nós globais) ou o cenário e clique em Deploy.

ℹ️ Nota: ao voltar a abrir um nó Global Lights ou Global Shutters, ambas as listas apresentam um valor — a lista Category apresenta apenas a primeira entrada. O nó atua sobre a lista que alterou por último: neste caso a divisão, como indica o nome. Para mudar para uma categoria, escolha-a em Category (a divisão é então limpa).