Broker MQTT

O hub pode publicar as suas medições em tempo real num broker MQTT da sua rede e receber comandos dele. O Home Assistant usa a mesma ligação: o hub anuncia os seus sensores através da descoberta MQTT.

O MQTT está desativado até definir um broker. O hub liga-se a ele apenas quando está na sua rede Wi-Fi doméstica, e não quando funciona apenas como o seu próprio ponto de acesso.

Ligar o hub a um broker

Na aplicação, abra Settings → Home Assistant e preencha o formulário MQTT broker: o endereço do broker, a porta (normalmente 1883), o início de sessão e a palavra-passe. Guarde e reinicie o hub quando a aplicação o pedir; as definições do broker aplicam-se após um reinício.

Através da API: POST /api/system/mqtt-config com {"broker_uri":"mqtt://user:password@host:1883"}. Ao lê-lo, a palavra-passe aparece mascarada.

Use um endereço mqtt:// simples, ou mqtts:// para uma ligação segura:

• a partir da v1.1.7, com um certificado de uma autoridade pública — uma que esteja na lista de raízes da Mozilla, como a Let's Encrypt ou a DigiCert — que corresponda ao nome de máquina do broker;
• a partir da v1.1.8, também com a sua própria autoridade de certificação: um broker doméstico com uma CA privada, ou um certificado autoassinado, o que cobre o Mosquitto dentro do Home Assistant com o seu próprio certificado. Veja Your own broker CA abaixo.

Na v1.1.7 um certificado privado ou autoassinado não podia ser usado de todo, e um broker desses precisava de um endereço mqtt:// simples numa rede em que confie.

A sua própria CA do broker

Settings → Home Assistant tem um cartão Broker CA (for mqtts). Enquanto nada estiver carregado, mostra "None uploaded: the hub trusts public certificate authorities only." Upload CA certificate aceita o ficheiro PEM da sua autoridade — o ficheiro que começa por -----BEGIN CERTIFICATE----- — e o hub responde "Certificate saved on the hub. It is used after a restart." O cartão lista então o que contém: assunto, emissor e as datas de validade.

O hub recusa um ficheiro que não esteja correto, e diz qual é o problema:

⚠️ Remover a CA corta um broker que depende dela. Remove the broker CA? avisa que "After a restart the hub connects only to brokers with a public certificate. A broker that uses this CA stops connecting." Depois disso: "Certificate removed. After a restart the hub trusts public certificate authorities only."

A CA carregada substitui o pacote público em vez de o acrescentar, e aplica-se no reinício seguinte. Através da API: POST /api/system/mqtt-ca com o PEM, GET para ver o que está guardado, DELETE para voltar ao pacote público.

Porque foi recusada uma ligação segura

A partir da v1.1.8 o hub verifica as datas do certificado, além da sua autoridade e do nome de máquina, e indica o que encontrou. O cartão mostra uma destas mensagens:

⚠️ Um hub sem relógio não abre uma ligação TLS de todo, e isso é deliberado. Um relógio não definido faz com que todos os certificados pareçam "not valid yet", por isso a partir da v1.1.8 o hub espera até ter a hora — por NTP ou definida manualmente — antes de tentar. O registo de eventos diz "mqtt: TLS broker — waiting for the clock". Um broker mqtt:// simples não é adiado. → Time

Cada recusa escreve também uma linha no registo de eventos. Através da API, o mesmo estado está em GET /api/system/mqtt-config → tls: {state, ca, ca_uploaded}, em que state é ok, expired, not_yet_valid, name_mismatch, unknown_ca, waiting_clock, connecting, tls_error ou off para uma ligação simples, e ca é custom ou bundle.

Se o hub não conseguir verificar o broker, continua a tentar, e nada mais deixa de funcionar: Settings → MQTT mostra o MQTT como não ligado, e o registo de eventos do hub indica a razão. → Events

Mantenha o broker privado. Quem puder ler e escrever no broker pode ler as definições do hub através do canal de comandos, e um token de administrador enviado com um comando fica visível a todos os clientes subscritos. Use um broker com os seus próprios utilizadores e regras de acesso (ACL), na sua própria rede: dê ao hub um utilizador próprio no broker, e limite o acesso a rbgrid/<mac>/# ao hub e aos clientes em que confia. Nunca use um broker público.

Tópicos

<mac> é o endereço MAC Wi-Fi do hub: 12 dígitos hexadecimais em minúsculas, por exemplo a0b1c2d3e4f5. O hub liga-se com o id de cliente rbgrid-<mac>.

A trama de telemetria

Cada trama é um objeto JSON. Os campos principais:

Os valores de energia (e_in, e_out, e_day_in, e_day_out) estão em Wh; os valores monetários (cost_*, rev_*) estão na moeda da tarifa. Nos módulos que contam a energia a bordo ("energy_mode": "on_device"), os totais de energia avançam uma vez por período de 15 minutos; a potência, a corrente e a tensão atualizam-se a cada 3 segundos. As tramas só são enviadas enquanto o hub estiver ligado. Se o broker estiver em baixo, as tramas em tempo real são descartadas (nada é guardado em memória intermédia nem reenviado). O histórico fica no hub e pode ser lido mais tarde por HTTP ou com o comando history.

Exemplo

Uma trama real de um hub de teste, encurtada a um ponto: uma linha de cozinha que consome cerca de 400 W. Na rede, é uma única linha compacta. O total de energia ainda é pequeno porque este ponto conta a energia no módulo, e o período de 15 minutos com a carga ainda não tinha fechado.

{
  "v": 2,
  "sntp": 1793756448,
  "tq": 1,
  "time_src": "sntp",
  "seq": 707,
  "boot_id": 1158837418,
  "freq": 50,
  "system": {
    "tariff": {
      "zone": "NIGHT",
      "buy_rate": 0.2,
      "sell_rate": 0.12,
      "buy_rate_all_in": 0.27104,
      "currency": "EUR",
      "placeholder": true
    },
    "units": 3,
    "present": 2
  },
  "units": {
    "0102": {
      "point": "kitchen",
      "v": 222.85,
      "i": 1.804,
      "p_act": 402.22,
      "p_rea": 0,
      "pf": 1,
      "dir": 1,
      "present": true,
      "module": 1,
      "ch": 0,
      "ch_label": "I0",
      "energy_mode": "on_device",
      "e_in": 0.0223,
      "e_day_in": 0.0223,
      "e_out": 0,
      "e_day_out": 0,
      "load_pct": 6,
      "type": "CURRENT_LOAD",
      "role": "DEVICE_LOAD"
    }
  },
  "main_unit": "0006",
  "vbus_unit": "0007"
}

"placeholder": true aqui significa que o hub de teste ainda tinha a tarifa de exemplo de fábrica.

Descoberta do Home Assistant

A cada ligação, o hub publica mensagens de descoberta retidas, para que o Home Assistant crie os dispositivos e sensores por si. Cada sensor lê o seu valor do tópico de telemetria e a sua disponibilidade do tópico de estado (um sensor fica unavailable cerca de 30 segundos depois de o hub deixar de enviar).

• Cada ponto de medição: corrente (A), potência (W), potência reativa (var), fator de potência, energia entrada e saída (Wh, desde sempre e hoje).
• O hub: potência líquida (W) e frequência (Hz).
• O barramento de tensão: tensão (V).

Os sensores de energia (total_increasing, Wh) vão diretamente para o painel de Energia; veja Integrations.

Quando elimina (ou desassocia) um ponto, o hub limpa as suas mensagens de descoberta, e o Home Assistant remove as suas entidades. Isto só funciona enquanto o hub estiver ligado ao broker. Se eliminar um ponto com o MQTT desativado ou o broker em baixo, as suas entidades ficam no Home Assistant como unavailable: remova o dispositivo manualmente (Settings → Devices & services → MQTT, o dispositivo, Delete).

Comandos

Publique um comando JSON em rbgrid/<mac>/cmd, com um id à sua escolha. A resposta chega em rbgrid/<mac>/cmd/resp com o mesmo id. Vários clientes podem partilhar cmd/resp, por isso associe as respostas pelo id.

Ler dados:

{"cmd": "get", "section": "summary", "unit": "0x0100", "period": "day", "id": "q1"}

section pode ser system, telemetry (definições), telemetry_data (a trama em tempo real), sensors, units, tariff, schema, summary (com unit, period = hour|day|week|month|year, e from/to opcionais como tempo Unix) ou economics (com unit).

Ler o histórico:

{"cmd": "history", "unit": "0x0100", "period": "hour", "type": "energy", "offset": 0, "limit": 50, "id": "h1"}

type é electrical, energy, economics, quality ou direction; limit vai até 720. A resposta é o mesmo JSON de GET /api/v1/history.

Definir a tarifa:

{"cmd": "set", "section": "tariff", "data": { "...": "the same body as the HTTP tariff call" }, "token": "<admin token>", "id": "t1"}

O token é necessário assim que um token de administrador esteja definido no hub. Lembre-se de que fica visível a todos os subscritos de cmd.

Uma resposta bem-sucedida é o mesmo JSON do endpoint HTTP correspondente. Um erro tem este aspeto:

{"type": "cmd_ack", "data": {"cmd": "frobnicate", "result": "error", "message": "unknown cmd (use 'get' / 'set' / 'history')"}, "id": "q2"}

Identifique os hubs pelo <mac> no tópico: o device_id dentro das respostas é o mesmo em todos os hubs.

Ler dados sem token no URL

A partir da v1.1.7, as leituras MQTT exigem o token de leitura quando o hub tem tokens de leitura e de administrador definidos, tal como nas leituras HTTP: cmd get e history são recusados sem ele. Para um cliente de navegador que não deva levar um token no endereço, POST /api/v1/ws-ticket devolve um ticket de uso único válido durante 30 segundos. → Settings → Security

Resolução de problemas

Nada chega ao broker

• Verifique se o endereço, a porta, o início de sessão e a palavra-passe do broker estão corretos, e se reiniciou o hub depois de os guardar.
• O hub tem de estar na sua rede Wi-Fi doméstica; no modo apenas ponto de acesso o MQTT não arranca.
• Verifique rbgrid/<mac>/status: online significa que o hub está ligado.

O Home Assistant mostra os sensores como unavailable

• O hub não está a enviar: verifique o tópico de estado e a ligação ao broker. Os sensores voltam assim que as tramas recomeçarem a chegar.