O broker MQTT integrado
O HyperVisu pode executar o seu próprio broker MQTT no servidor. Os dispositivos ligam-se diretamente ao HyperVisu em vez de a uma máquina broker separada que seja necessário instalar, proteger e manter atualizada, associando os respetivos tópicos exatamente como em qualquer outro broker (consulte "Integração MQTT"). O mesmo broker também pode transmitir os valores da própria instalação para o exterior, permitindo que um painel, um sistema de gestão de energia ou outro controlador leia o estado do edifício.
Utilize-o quando tiver dispositivos MQTT e ainda não dispuser de um broker. Se já utiliza um broker — o integrado numa instalação Zigbee2MQTT, um Mosquitto num servidor ou um EMQX — mantenha-o: o HyperVisu funciona perfeitamente como cliente e o broker integrado pode permanecer desativado.
O que é necessário: o protocolo MQTT ativado (consulte "Serviços e Protocolos") para que os dispositivos possam ser associados, e uma conta para cada dispositivo que se irá ligar.
Como ativar. O broker é um serviço opcional, pelo que requer um reinício para ficar disponível, sendo configurado em seguida:
- Aceda a Serviços e ative o Broker MQTT na lista de serviços opcionais.
- Clique em Reiniciar Servidor e aguarde que a página restabeleça a ligação.
- Novamente em Serviços, clique em Configurar na linha do Broker MQTT. A página Broker MQTT abre-se.
ℹ️ Nota: O interruptor na página Serviços inicia e para o broker; todas as opções na página Broker MQTT definem o seu comportamento. Uma alteração na página Serviços requer o reinício do servidor; uma alteração na página Broker MQTT apenas reinicia o próprio broker.
Guardar alterações. As edições são acumuladas até serem aplicadas: surge uma barra no fundo da página com as opções Aplicar e Rejeitar. Aplicar grava as configurações e reinicia o broker — os dispositivos ligados restabelecem a ligação autonomamente em poucos segundos. Reaplicar, no topo do painel Estado, regrava e reinicia mesmo sem alterações; utilize esta opção se o broker tiver sido parado manualmente ou se a página indicar que os ficheiros em disco diferem das definições guardadas.
Estado — funcionamento e acesso dos dispositivos
O painel Estado é o primeiro ponto de análise.
- Um cartão por listener — MQTT e WebSockets — apresentando o respetivo endereço e se está a Escutar, Sem resposta ou Desligado.
- Endereço a introduzir no dispositivo — o endereço a configurar num Shelly, num Tasmota ou numa configuração Zigbee2MQTT, acompanhado de um botão Copiar. Trata-se do endereço do próprio servidor e do porto do listener simples.
- Ligação do próprio HyperVisu — a conta e a ligação que o próprio HyperVisu utiliza para comunicar com o broker. É criada automaticamente na primeira utilização do broker; Reparar recria-a se a ligação tiver sido editada ou eliminada.
Se o broker nunca tiver sido iniciado, o painel indica que o serviço não está em execução e remete para a página Serviços.
Listeners — portos de resposta do broker
Um listener é um porto no qual o broker aceita ligações. Estão disponíveis dois, cada um com um Porto e um Endereço de associação:
| Listener | Predefinição | Finalidade |
|---|---|---|
| MQTT | porto 1883, ligado | O listener normalmente utilizado pelos dispositivos. A autenticação mantém-se — este listener não é cifrado, mas não é aberto. |
| WebSockets | porto 9001, desligado | Para clientes MQTT em browsers e para painéis que comunicam via MQTT sobre websockets. |
O Endereço de associação define quem pode aceder ao listener: 0.0.0.0 aceita ligações da rede, 127.0.0.1 restringe o acesso ao próprio servidor.
Pelo menos um listener tem de permanecer ativo — sem nenhum, nenhuma ligação seria possível e a página recusa a gravação. Dois listeners não podem partilhar o mesmo porto, e portos já em utilização no servidor (interface web, base de dados de histórico, painéis, Node-RED, transmissão de câmaras, Home Assistant, API do HyperVisu) são rejeitados nominalmente.
⚠️ Aviso: Nenhum dos listeners cifra os dados transmitidos, pelo que deve manter o broker na rede local. Associe-o a
127.0.0.1se apenas o próprio servidor necessitar de acesso e nunca faça o reencaminhamento do respetivo porto a partir da Internet.
Contas e acessos — permissões de ligação
⚠️ Aviso: Um broker sem restrições representa um ponto de entrada na instalação. Atribua uma conta própria a cada dispositivo e mantenha o acesso anónimo desativado.
Contas. Cada dispositivo que estabelece ligação necessita de um nome de utilizador e de uma palavra-passe. Clique em Adicionar conta, introduza um Nome de utilizador (letras, dígitos e . _ @ -) e uma Palavra-passe, aplicando em seguida. A palavra-passe é processada por hash no momento da gravação e nunca mais pode ser lida — apenas substituída através do botão Palavra-passe na linha da respetiva conta. O HyperVisu dispõe de uma conta própria, identificada como tal; é gerida automaticamente e não pode ser removida.
A página recusa gravar configurações com o acesso anónimo desativado caso não exista qualquer conta criada — nada conseguiria ligar-se, nem mesmo o HyperVisu.
Ligações anónimas. A opção Permitir ligações anónimas autoriza a ligação de qualquer cliente sem nome de utilizador. Encontra-se desativada por predefinição. Se a ativar enquanto um listener estiver acessível pela rede, a página emite um aviso — Este broker ficaria acessível a toda a rede — e recusa a gravação até que confirme Compreendo e pretendo permitir. Caso contrário, qualquer utilizador na rede poderia ler e controlar os dados da instalação.
Restrições de tópicos. Sem regras definidas, qualquer conta autenticada pode publicar e subscrever todos os tópicos. Ative a opção Restringir tópicos por conta e clique em Adicionar regra. Cada regra é composta por uma Conta (introduza o nome de utilizador; se ficar vazio, aplica-se a clientes anónimos), uma Permissão (read, write, readwrite ou deny) e um Filtro de tópico, onde + corresponde a um nível e # aos restantes.
Exemplo típico: o gateway Zigbee obtém permissão readwrite em zigbee2mqtt/#, um painel obtém read em hypervisu/# e todo o restante tráfego é bloqueado.
ℹ️ Nota: As regras constituem uma lista estrita — uma conta sem regra correspondente a determinado tópico é rejeitada no mesmo. A conta do próprio HyperVisu é a exceção: mantém sempre acesso total, pelo que a ativação de restrições nunca corta o acesso do servidor aos tópicos dos dispositivos associados. Qualquer regra que mencione essa conta é ignorada.
Armazenamento e limites
Estas definições protegem o servidor contra comportamentos anómalos de dispositivos e definem o que é preservado após um reinício.
| Definição | Predefinição | Efeito |
|---|---|---|
| Manter mensagens retidas entre reinícios | ligado | Grava o estado do broker no disco, mantendo os tópicos retidos após um reinício. Sem esta opção, todos os valores retidos perdem-se ao parar o broker e os widgets aguardam pela próxima publicação do dispositivo. |
| Intervalo de gravação (s) | 1800 | Frequência de gravação do estado. Um valor mais elevado reduz o número de escritas no cartão de memória do servidor. |
| Ligações máximas | 200 | Número máximo de clientes ligados em simultâneo. -1 para ilimitado. |
| Tamanho máximo do pacote (bytes) | 0 | Tamanho máximo da mensagem aceite pelo broker. 0 significa ilimitado. |
| Permitir mensagens retidas | ligado | Permite que os dispositivos solicitem ao broker a retenção do seu último valor para novos subscritores. Ao desativar, cada widget terá de aguardar por uma nova publicação após restabelecer a ligação. |
💡 Sugestão: Mantenha as mensagens retidas ativadas. É esta funcionalidade que permite à aplicação apresentar valores reais no arranque do servidor, evitando widgets vazios.
Publicação de estados dos widgets via MQTT
O HyperVisu pode publicar os valores dos seus próprios dispositivos no broker, permitindo que outros sistemas leiam a instalação sem interagir diretamente com o HyperVisu: painéis Grafana, gestores de energia, controladores de terceiros ou outros sistemas do edifício.
Esta função está desativada por predefinição e, enquanto permanecer inativa, nada é publicado. Ative a opção Publicar estados dos widgets via MQTT para aceder às configurações:
| Definição | Predefinição | Efeito |
|---|---|---|
| Prefixo do tópico | hypervisu | Primeiro segmento de cada tópico. Apenas segmentos de texto simples — sem + ou #. |
| Incluir o número de série do aparelho no tópico | ligado | Adiciona o número de série do servidor após o prefixo, permitindo partilhar um broker entre duas instalações sem sobreposição. |
| Estilo do tópico | Identificadores | Identificadores (estável) utiliza a numeração interna dos dispositivos; Nomes (legível) utiliza os nomes das divisões e dos dispositivos. Nomes são mais legíveis, mas renomear uma divisão altera todos os tópicos associados e invalida as subscrições existentes. |
| Payload | Apenas valor | Apenas valor publica o valor simples; JSON com contexto publica o valor com o nome e a divisão do dispositivo, a respetiva unidade, identidade e timestamp — permitindo identificar o conteúdo sem necessidade de conhecer a referência widget/42/1. |
| Intervalo mínimo (ms) | 1000 | Limite de frequência por objeto. O valor mais recente é sempre entregue; 0 publica todas as alterações. |
| Reter o último valor | ligado | Clientes que estabeleçam ligação posteriormente recebem o estado atual de imediato, sem aguardar pela alteração seguinte. |
| Publicar tópico de disponibilidade | ligado | Publica online / offline, de forma retida, em <prefixo>/<série>/status, informando se os dados lidos correspondem ao estado atual ou ao último registo antes de uma perda de ligação. Desativar a publicação remove o tópico. |
| Apenas estes widgets | desligado | Desligado publica todos os dispositivos. Ligado permite selecionar pontualmente quais publicar. |
| Aceitar comandos via MQTT | desligado | Permite a um subscritor enviar valores de escrita. Consulte o aviso abaixo. |
A página apresenta a pré-visualização Aspeto do tópico em tempo real conforme as alterações efetuadas. Com as predefinições, o valor de um dispositivo é enviado para:
hypervisu/<série>/widget/42/1/state
e com a opção Nomes (legível):
hypervisu/<série>/living-room/ceiling-lamp/1/state
O último segmento antes de state corresponde ao número de objeto do dispositivo — um tópico por objeto de comunicação, não por dispositivo.
Com a opção JSON com contexto, a própria mensagem inclui a respetiva identificação:
{"value":21.5,"unit":"°C","name":"Hall thermostat","room":"Bathroom","widget":46,"object":2,"type":"FLOAT","ts":"2026-09-09T07:51:22.436Z"}
O nome e a divisão são lidos no momento da publicação; assim, renomear um dispositivo altera apenas a mensagem seguinte sem alterar a estrutura do tópico. Esta é a diferença face a Nomes (legível): tópicos legíveis mudam de endereço ao renomear, enquanto um payload com contexto mantém o endereço inalterado.
Aceitar comandos. Com a opção Aceitar comandos via MQTT ativa, a publicação de um valor no tópico correspondente …/set atua sobre o dispositivo, exatamente como através da aplicação.
⚠️ Aviso: Isto permite que qualquer entidade com capacidade de publicação no broker controle o edifício. Ative esta opção exclusivamente com o acesso anónimo desativado e restrições de tópicos configuradas — a página recusa liminarmente a combinação de comandos com acesso anónimo.
Os comandos são recusados, e contabilizados como tal, se o tópico pertencer a um objeto de apenas leitura ou se o payload for incompatível com o tipo de dados do objeto. O painel contabiliza o número de mensagens publicadas e rejeitadas, apresentando também o total de objetos publicados.
ℹ️ Nota: A publicação requer o protocolo MQTT ativo e uma ligação estabelecida a um broker. Se ativada sem ligação, o painel indica essa condição em vez de simular a publicação.
Consulta de tópicos no broker
A secção Tópicos no broker, no fundo da página, apresenta a atividade em tempo real no broker — o método mais rápido para validar se um dispositivo recém-configurado está a comunicar.
- Opcionalmente, preencha Limitar a uma subárvore para filtrar o varrimento (
zigbee2mqttanalisa apenaszigbee2mqtt/#). - Escolha o tempo de Escuta — 3, 4, 10 ou 30 segundos.
- Clique em Varrer.
O resultado é estruturado em árvore, respeitando a hierarquia / dos próprios tópicos, mantendo a navegação clara mesmo com centenas de registos. Clique numa ramificação para a expandir — a linha indica o número de subtópicos existentes — e clique num tópico para ver o respetivo último payload. Em payloads JSON, os campos são listados com a tipologia correspondente; em payloads simples, é apresentado o tipo identificado. O botão de cópia na linha aberta copia o tópico completo. As opções Expandir tudo e Recolher tudo encontram-se no topo da árvore, e varrimentos de pequena dimensão abrem totalmente expandidos.
Um nível com apenas um ramo dependente é agregado ao nível superior (118/1/state numa única linha em vez de três), simplificando a navegação em prefixos longos. Os tópicos retidos surgem em primeiro lugar em cada nível.
Os tópicos publicados pelo próprio HyperVisu são identificados nominalmente sempre que possível: um tópico como hypervisu/<série>/widget/42/1/state apresenta o dispositivo correspondente ao lado, dispensando a consulta manual do identificador.
Os tópicos retidos são transmitidos pelo broker assim que a subscrição do varrimento é iniciada, pelo que mesmo uma análise curta revela toda a estrutura retida. Caso o varrimento não devolva resultados, tal significa que não existem dispositivos ligados ou que estes apenas publicam por alteração de estado — tente um intervalo de escuta maior.
ℹ️ Nota: O varrimento reflete o estado de execução atual do broker; alterações não gravadas na página não são consideradas no relatório. O painel assinala a existência de alterações pendentes.
O varrimento é apenas de leitura: analisa os dados presentes sem realizar publicações. Para associar um destes tópicos a um dispositivo, abra o objeto do dispositivo e selecione o tópico no editor de objetos (consulte "Integração MQTT") — a mesma ferramenta de varrimento está disponível nesse editor, preenchendo automaticamente o tipo de dados, o caminho JSON e os valores ON/OFF.
Exemplo prático — tomada Shelly no broker integrado
Integração de uma tomada Shelly Plus no HyperVisu, sem recurso a outro broker na rede.
- Serviços → ative o Broker MQTT → Reiniciar Servidor. Confirme que o protocolo MQTT também se encontra ativo.
- Serviços → Configurar na linha do Broker MQTT. Em Contas e acessos, clique em Adicionar conta: utilizador
shelly, defina uma palavra-passe e clique em Aplicar. - Registe o Endereço a introduzir no dispositivo indicado no painel Estado — por exemplo
192.168.1.60:1883. - Na interface web do Shelly, ative o MQTT, introduza esse endereço, o utilizador
shellye a respetiva palavra-passe, e guarde. A tomada reinicia e estabelece ligação. - Aceda a Ligações. O painel sugere Utilizar o broker local; clique nessa opção para que o HyperVisu crie a sua própria ligação ao broker. Se este passo já tiver sido realizado anteriormente, a ligação estará presente — o navegador de tópicos necessita dela, pelo que deve garantir este passo antes do varrimento.
- De volta à página Broker MQTT, aceda a Tópicos no broker e clique em Varrer. Os tópicos da tomada são apresentados —
shellyplus1pm-a8032ab1/status/switch:0entre outros — com os respetivos últimos payloads. - Em Dispositivos, adicione o widget Interruptor de iluminação com o nome "Tomada Cozinha", selecione o protocolo MQTT nessa ligação e associe os seus objetos aos tópicos da tomada através da opção Varrer broker no editor de objetos.
- Acione a tomada através da aplicação. O comando é transmitido através do broker integrado e confirmado pelo tópico de estado da própria tomada.