Nós remotos (ESP-NOW)

Visão geral

Um nó remoto é uma pequena placa ESP32 com os seus próprios módulos rbAmp. Mede onde um cabo I2C a partir do hub não consegue chegar: uma garagem, uma bomba de piscina, um esquentador de água na cave, um quadro secundário num anexo. Envia as suas leituras para o hub por rádio, através do ESP-NOW. O nó não está na sua rede Wi-Fi e não tem endereço próprio: comunica apenas com o seu hub. Os seus canais tornam-se pontos comuns no hub, com valores em tempo real, histórico e custo como qualquer outro ponto.

Esta página é a documentação completa dos nós: a placa e os módulos, a ligação elétrica, a gravação do firmware, o emparelhamento, a forma como um nó mantém a hora e a energia, o que a aplicação mostra, a API do hub e os tópicos MQTT, e o que fazer quando algo não está bem. Os nós remotos requerem firmware do hub v1.1.7 ou posterior e aplicação web 1.1.7 ou posterior. Num hub com firmware mais antigo, a aplicação não mostra qualquer secção de Nodes; "Remote nodes are not available in this hub firmware." aparece apenas num hub cuja imagem de firmware não consegue executar nós.

Um nó é um emissor. Não tem ecrã, página web nem histórico que possa ler, e não tem atualização pelo ar: grava-se por USB. A partir do firmware 1.5 guarda os períodos de 15 minutos concluídos na sua própria memória flash até o hub os ter; isso é uma fila, e não um registo que possa abrir. O resto é tratado pelo hub.

Para qualquer trabalho no interior de um quadro elétrico, contacte um eletricista qualificado.

O que precisa

Requirement
Placa do nó Um módulo ESP32 original com 4 MB de flash. Não é necessária PSRAM. Na v1.1.7 o firmware do nó é compilado e testado apenas para o ESP32 original: as placas ESP32-S2, S3 e C3 não são compiladas nem testadas.
Módulos rbAmp no nó Até três módulos no barramento I2C do nó, nos endereços 0x50, 0x51 e 0x52 (definição do próprio módulo); SDA está no GPIO 25 e SCL no GPIO 26. O hub usa até quatro canais de corrente por nó.
Uma entrada de tensão no nó Na v1.1.7 um nó só regista energia quando um dos seus módulos mede tensão. Um módulo só de corrente num nó dá corrente em tempo real, mas nenhum período de 15 minutos, pelo que não há histórico nem custo. Instale um conjunto rbAmp monofásico com entrada de tensão.
Fases Na v1.1.7 um nó mede apenas pontos monofásicos. Não há agrupamento de fases num nó nem "use as the three-phase input": isso é para um módulo no hub. Um STD-U3I3 num nó não foi testado.
O hub Firmware v1.1.7 ou posterior, ligado à sua Wi-Fi. O rádio do hub para nós funciona no mesmo canal do seu router; um hub sem Wi-Fi não consegue executar nós. Um hub aceita até seis nós.
Vagas de histórico Os pontos dos nós partilham as 12 vagas de histórico existentes do hub com os pontos do próprio hub; não as aumentam. A secção Nodes mostra "History: used of 12 points in use" antes de emparelhar.
Um computador com USB Para gravar o nó, e para cada atualização posterior do firmware do nó.
Pinças de corrente Como para um módulo no hub; o modelo da pinça é definido por canal a partir do hub (ver Node settings).

Ligar o nó

Um nó é ligado como um pequeno hub: os seus módulos rbAmp ficam no barramento I2C do nó, e as pinças de corrente são colocadas nos módulos.

  • I2C: quatro fios entre a placa ESP32 e os módulos, SDA ao GPIO 25, SCL ao GPIO 26, GND e 3.3 V. Os endereços dos módulos 0x50, 0x51, 0x52 são definidos nos próprios módulos; o nó lê os que estiverem presentes ao arrancar, até três. O barramento é puxado para cima pelas resistências existentes nos módulos; com até três módulos em cabos curtos, deixe-as como estão. O comprimento do cabo e as resistências de pull-up para outros casos estão no guia de ligação rbAmp, o mesmo que para os módulos no hub.
  • Entrada de tensão: na v1.1.7 um módulo do nó tem de ter a sua entrada de tensão ligada à rede que mede; sem ela, o nó tem corrente em tempo real mas não regista energia (ver What you need). A entrada de tensão também dá ao nó o sentido de cada corrente, importação ou exportação.
  • Pinças: uma por canal de corrente, no condutor que quer medir, com a seta a indicar conforme a documentação do módulo rbAmp. O modelo da pinça é definido por canal a partir do hub (ver Node settings); um modelo errado escala mal as leituras.
  • Alimentação: a alimentação habitual da placa ESP32, por exemplo a sua porta USB ou uma fonte de 5 V na entrada da placa. O nó não tem bateria nem reserva de energia: um corte de energia para-o, e a energia do período que estava aberto perde-se.
  • Local: onde vai viver. Um nó não tem de estar perto do hub para emparelhar; a ligação é verificada onde está (ver Checking the link). Evite caixas metálicas entre o nó e o hub sempre que possível.

Para qualquer trabalho no interior de um quadro elétrico, contacte um eletricista qualificado.

Gravar o firmware do nó

O firmware do nó é publicado com cada versão do hub na página RBgrid Releases do GitHub: rbgrid-node_vX.Y.Z.bin (apenas a aplicação) e rbgrid-node_vX.Y.Z_full.zip (bootloader, tabela de partições e aplicação). Use a versão que corresponde ao seu hub, ou uma mais recente.

Com a placa em modo de download e o esptool instalado (pip install esptool), grave o conjunto completo:

python -m esptool --chip esp32 -p <PORT> -b 460800 write_flash 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 rbgrid-node_vX.Y.Z.bin

⚠️ Atualizar um nó para o firmware 1.5 grava os três ficheiros, e não apenas a aplicação. A 1.5 acrescenta a partição de flash onde ficam os períodos guardados. Um nó ao qual se dê apenas a nova aplicação executa a 1.5 sem sítio onde os guardar, e recorre a oito períodos na memória RAM, e o cartão não o indica. Gravar os três é também o que quer para qualquer atualização posterior: não custa nada, e um nó emparelhado na 1.4 não precisa de voltar a ser emparelhado.

Compilar o firmware você mesmo, e os pinos a alterar se a sua placa ligar o I2C de forma diferente, estão em node/README.md do repositório RBgrid.

O nó não precisa de ficheiro de chave nem de definição de canal. Obtém a sua chave do hub quando o emparelha, e encontra sozinho o canal do hub.

Compilar o firmware do nó você mesmo

O código-fonte é a pasta node/ do repositório RBgrid, sob a mesma licença do firmware do hub. Compila-se com o ESP-IDF 5.5.1 (a 5.4.1 também compila):

cd node
idf.py set-target esp32
idf.py build
idf.py -p <PORT> flash

A biblioteca rbAmp é obtida no momento da compilação (dependencies.lock fixa a sua versão). Se a sua placa ligar o I2C a outros pinos, compile com -DRBN_I2C_SDA=<n> -DRBN_I2C_SCL=<n>. Não é necessário ficheiro de chave. As variantes de desenvolvimento do código-fonte (RBN_ROLE_MASTER, RBN_FREERUN, RBN_OUTPUT_NODE) não fazem parte da versão e não são suportadas.

Emparelhar um nó

Os nós são geridos em Management → Points, na secção Remote nodes (ESP-NOW). O cabeçalho mostra "n of 6 nodes" e o estado do rádio para nós, "radio on" ou "radio off". Num hub que consegue executar nós, a secção fica no topo da página, acima de rbAmp modules, e o assistente de configuração recebe um passo opcional ESP-NOW nodes ("Step 5 of 8", depois de Sensors e antes de Tariff).

  1. Coloque o nó onde vai viver, com os módulos e as pinças instalados, mas sem o ligar.
  2. Na aplicação, escolha o Pairing time (em minutos) e prima Pair a node. A secção diz: "Power the node up now. It shows up below in a few seconds." e faz a contagem decrescente: "Waiting for a node… time left". Stop pairing fecha a janela mais cedo.
  3. Ligue o nó (ou reinicie-o). Ele procura o hub nos canais Wi-Fi, troca chaves com ele e aparece na lista, marcado como new. Os seus pontos são adicionados de imediato: "Paired in this window: n. Their points are already added; no restart needed."

A secção Remote nodes com uma janela de emparelhamento aberta: «Waiting for a node… 1:56 left» e «Stop pairing», acima dos dois cartões de nó

⚠️ Enquanto a janela de emparelhamento estiver aberta, qualquer nó RBgrid ao alcance que o peça é emparelhado. Não há PIN. Isso inclui um nó de outra pessoa cujo hub próprio ficou sem resposta: um nó emparelhado que não recebe resposta durante cerca de 150 segundos começa a pedir para emparelhar por si. Abra a janela apenas quando for ligar um nó, mantenha-a curta, e feche-a com Stop pairing assim que o seu nó estiver na lista; depois verifique se a lista só tem os nós que espera.

As chaves ficam guardadas no nó e no hub. Após um reinício, ou depois de o rádio ter estado desligado, o nó volta a ligar-se sozinho; emparelha-o uma vez só.

Antes de emparelhar, verifique as duas linhas de capacidade na secção: "n of 6 nodes" (quando o hub está cheio, o botão é substituído por "The hub takes up to 6 nodes. Remove one to pair another.") e "History: used of 12 points in use. Points beyond 12 show live values only." (ou "History: all 12 points are in use. A new node's points will show live values only."). Se o rádio estiver desligado, a secção diz "Turn the radio for nodes on to pair one."

Cada nó traz até quatro pontos. Recebem o nome do nó e dos seus canais; renomeie-os e atribua-lhes funções nas suas próprias páginas, como qualquer outro ponto (ver Points). Os pontos de nós não podem ser associados nem desassociados manualmente: um canal desligado nas definições do nó deixa de medir, e remover o nó remove os seus pontos.

O cartão do nó

A secção Remote nodes: o rádio no canal 6, o controlo de emparelhamento e dois cartões de nó — um online com o seu sinal, clock sync e dois canais a receber, e outro offline há 90 minutos

Cada nó emparelhado tem um cartão na secção.

On the card What it means
online / offline O hub ouviu o nó nos últimos 15 segundos, ou não. Um nó desligado (ver abaixo) mostra off.
new Emparelhado na janela de emparelhamento atual.
Last heard "now", "n s ago", "n min ago", "n h ago", ou "not heard since the hub started".
Signal A força da última trama do nó, em dBm, tal como o rádio do hub a viu.
Lost packets, last minute A percentagem dos sinais de tempo (beacons) do hub que o nó perdeu no último minuto. Mostra "measuring (1 min)" até passar um minuto completo.
Clock sync O quão de perto o relógio do nó acompanha o do hub: "±n µs · n ppm".
Firmware A versão do firmware do nó, assim que o nó a tiver comunicado.
Period "15 min". O período é fixo; o diálogo Settings diz isso: "Energy records: every 15 min, fixed."
Waiting to send Onde o hub o indica: o número de períodos de 15 minutos concluídos que o nó retém porque o hub esteve fora de alcance (ver How a node keeps time and energy). O firmware do hub v1.1.7 não o indica, pelo que a linha não aparece aí.
Channel n Cada canal de corrente do nó: o ponto que alimenta (o seu nome, uma ligação para a página do ponto; "Point key" até o ponto ter um nome) e o seu estado, "receiving", "no data" ou "off (Settings)".
settings not applied yet / settings not applied As definições foram enviadas ao nó e este ainda não as confirmou, ou recusou-as.
Signal, lost packets and clock sync missing Um nó não ouvido desde que o hub arrancou não tem nenhuma destas: o cartão omite as três linhas e Last heard mostra "not heard since the hub started". Aparecem com a primeira trama do nó.

O cartão tem três botões: Settings, Turn off / Turn on, e Delete.

O cartão completo de um nó: o MAC e o seu distintivo online, Last heard, Lost packets in the last minute, Clock sync, Signal, Firmware 1.5 e o período de 15 minutos, com os dois canais do nó associados a pontos com nome

Definições do nó

Settings abre "Node mac: settings". Para cada canal mostra Channel n measures (ligado ou desligado) e Current clamp, o modelo de pinça instalado nesse canal. "Pick the clamp actually fitted to each channel: a wrong one scales its readings wrongly. A channel turned off stops measuring." Pelo menos um canal tem de ficar ligado.

Send to the node envia as definições através do hub: "Sent. The node applies the settings on its next contact; the card shows «settings not applied yet» until it confirms." Se o nó estiver desligado, o hub guarda as definições e entrega-as quando o nó voltar ("The node is offline. It takes the settings when it's back.").

O período de energia de um nó é fixo em 15 minutos ("Energy records: every 15 min, fixed."); não pode ser alterado.

Desligar e ligar um nó

Turn off mantém o nó emparelhado, mas faz com que o hub descarte os seus dados. A aplicação pergunta primeiro: "The hub discards the node's data while it's off: that energy won't be in History or the totals, and turning it back on doesn't bring it back. To pause a node and keep its energy, leave it on." Enquanto estiver desligado, o cartão mostra off, e os seus pontos não mostram valores em tempo real. Turn on retoma.

Use-o quando um nó mede algo que não quer contabilizado durante algum tempo. Para parar um nó de vez, remova-o.

O rádio para nós

A linha Radio for nodes no cabeçalho da secção mostra um de três estados:

  • "On, channel n: the same as your Wi-Fi router's." O rádio do hub para nós está ativo. Funciona no canal Wi-Fi do hub, que o seu router escolhe; se o router mudar para outro canal, o hub e os seus nós seguem-no.
  • "Starts by itself when a node is paired (factory setting)." Ainda não está a funcionar nada; o rádio arranca com o primeiro emparelhamento ou quando já há um nó emparelhado.
  • "Off. Nodes can't send data." Foi desligado por si.

Desligá-lo pede confirmação primeiro: "The nodes stop sending live values. They keep their 15-minute energy records and send them when the radio is on again (up to 2 hours on node firmware 1.4, about 5 days on 1.5). The hub remembers this after a restart." Todos os nós ficam offline de imediato. Os valores em tempo real desse período não são guardados; os registos são, enquanto o firmware do nó os conseguir manter.

Remover um nó

Delete pergunta "Remove node mac?": "The node and its points (channels: n) are removed, with their stored history, for good. Download the history first in History (CSV) if you need it. To use the node again, pair it again."

⚠️ Remover um nó elimina os seus pontos e todo o histórico guardado. Se puder precisar dos registos, descarregue-os primeiro em History.

O hub deixa de aceitar os dados do nó de imediato e confirma: "Node removed, with its points: n." Para voltar a usar o nó, emparelhe-o novamente: abra uma janela de emparelhamento e reinicie o nó (ou espere cerca de 2½ minutos: um nó que não recebe resposta do seu hub durante 150 segundos começa a pedir para emparelhar por si).

Mudar um nó para outro hub

Um nó emparelhado continua a pedir ao seu hub; quando não recebe resposta durante 150 segundos, marca-se a si próprio como não emparelhado e pede para emparelhar de novo, e após um reinício pede de imediato. Por isso, mudar um nó para outro hub, ou pôr em serviço um nó usado, é um emparelhamento:

  1. Delete no hub antigo (se o tiver).
  2. Abra uma janela de emparelhamento no novo hub e reinicie o nó (ou espere cerca de 2½ minutos). O nó recebe a chave do novo hub.

Apagar primeiro a flash do nó (python -m esptool --chip esp32 -p <PORT> erase_flash, depois flash the firmware again) é opcional: um arranque limpo, e não um requisito.

Como um nó mantém a hora e a energia

  • Relógio. O relógio é o do hub. O nó pede a hora a cada 5 segundos até a ter, depois a cada minuto, e mantém o seu próprio temporizador entre pedidos. O Clock sync do cartão mostra o quão de perto o acompanha.
  • Os valores em tempo real são enviados cerca de uma vez por segundo e mostrados nos pontos do nó. Não são guardados.
  • A energia é registada em períodos de 15 minutos, que o nó fecha pelo seu próprio relógio nos limites de 15 minutos do hub, com a energia dos contadores dos próprios módulos. Quando a sua zona tarifária muda, o hub pede a todos os nós que fechem o período também nesse momento, para que o custo por zona seja exato.
  • Um período chega ao hub, ou é retido. O nó envia um período concluído até o hub confirmar que o registou, pelo que os registos sobrevivem melhor a uma ligação fraca do que a vista em tempo real. O hub reconhece um período que já tem e nunca o conta duas vezes.
  • Fora de alcance. O nó continua a fechar os períodos na hora certa e retém os concluídos até o hub os confirmar. Quando a ligação volta, chegam todos juntos e são registados e tarifados pela hora em que foram medidos, e não pela hora de chegada. Quanto consegue reter depende do firmware do nó, e não do hub:
    • Firmware do nó 1.5 grava-os na sua própria flash: cerca de cinco dias de períodos, e sobrevivem a um corte de energia no nó.
  • Firmware do nó 1.4 guarda oito deles (cerca de duas horas) na RAM; um nono empurra o mais antigo para fora, e um corte de energia no nó perde os períodos retidos e o aberto.

Em qualquer caso, quando a retenção fica cheia, o período mais antigo sai, e o nó regista-o no seu registo.

  • Um nó que arranca sem o seu hub não fecha períodos até ter ouvido o hub uma vez. A energia não se perde: na v1.1.7 o primeiro registo após um arranque cobre tudo desde o arranque do nó até ao fim do seu primeiro período completo de 15 minutos, pelo que esse período pode mostrar um valor mais alto do que a carga realmente foi.

O firmware não tem qualquer valor de referência para o sinal ou para os pacotes perdidos, e esta página também não dá nenhum; o nó é fiável onde está ou não é. O teste honesto é comportamental:

  1. Emparelhe o nó onde vai viver, com a carga realmente em funcionamento.
  2. Observe o cartão durante cerca de dez minutos: o nó deve manter-se online, Lost packets, last minute deve manter-se em 0 e Last heard deve manter-se em "now" ou em alguns segundos.
  3. Se os pacotes perdidos subirem acima de zero, ou o nó alternar entre online e offline, a ligação é marginal. Mude um pouco o nó, ou o hub, e observe de novo.

Existem dois limiares no firmware, e são só esses: um nó fica offline após 15 segundos sem uma trama (o hub publica node_offline e node_online no MQTT), e um nó que não ouve nenhum beacon durante 8 segundos começa a procurar de novo o canal do hub (é assim que acompanha um router que muda de canal; não é preciso reiniciar).

Uma ligação fraca nota-se por pacotes perdidos acima de 0 e por falhas nos valores em tempo real enquanto os registos continuam a chegar; uma pior faz o nó oscilar. Um nó fora de alcance e um nó sem energia parecem iguais para a aplicação e para a API. Só o histórico do cartão antes da queda os distingue: uma ligação fraca degrada-se primeiro (perdas a subir, sinal a descer, oscilação), um corte de energia é limpo.

Saber mais tarde que um nó ficou em silêncio

A retenção de cinco dias só ajuda se notar dentro de cinco dias.

A partir do firmware v1.2.0 o hub regista-o. Um nó que deixa de responder e um que regressa são linhas no registo do hub — espnow: node <MAC> offline e … online — pelo que um nó que ficou em silêncio enquanto esteve ausente deixa um rasto que pode encontrar depois, com a respetiva hora. → Events

No firmware v1.1.8 nada na aplicação vai à sua procura: um nó que deixa de comunicar é mostrado no seu cartão e na lista de Nodes, e em mais lado nenhum. Não há entrada no Journal da aplicação e não há item em Needs attention — nesse firmware o hub escreve a linha apenas no seu próprio registo série.

Em nenhum dos firmwares a aplicação dispara um alarme: o registo é um histórico para consultar, e não uma notificação que chega até si. Para isso, use o Home Assistant.

Com o Home Assistant, tem um alarme a sério e custa uma automação. O hub publica, por descoberta MQTT, uma entidade de conectividade Online por nó, como sub-dispositivo do hub, que acompanha o estado retido do nó. Crie uma automação sobre essa entidade a passar a desligada e será avisado em menos de um minuto. A mesma transição é publicada como um evento node_offline no tópico de eventos do hub, se preferir acompanhar eventos.

Sem MQTT, o cartão é tudo o que existe. Abra de tempos a tempos a secção Nodes — ou olhe para os pontos do nó no History, onde um nó silencioso deixa uma falha a crescer.

O que a transição é, na prática, para poder definir a paciência da automação:

  • o disparo acontece após 15 segundos sem uma trama em tempo real — o mesmo limiar que o cartão usa, e um nó envia cerca de uma trama por segundo;
  • não há debounce: cada falha superior a 15 s produz um par offline/online, e falhas mais curtas não produzem nada. Uma ligação marginal dá-lhe um punhado de pares, e não centenas;
  • o tópico de estado é atualizado uma vez por minuto com sinal e perdas, como estado e não como evento — por isso um painel que o leia nunca está mais de um minuto desatualizado.

Totais e o restante «não medido»

O total da casa não pode ser contado em duplicado: os totais do sistema são obtidos na fronteira da rede, apenas a partir do ponto de entrada. Os pontos de carga, no hub ou num nó, nunca se somam a eles.

O restante unmetered na Overview pode ser contado em duplicado. É a entrada menos a soma de todos os pontos de linha, e os pontos de nós são pontos de linha. Se medir um quadro secundário num nó e uma carga dentro desse quadro num outro canal, essa carga é subtraída duas vezes, e o restante pode ficar negativo.

A partir do firmware v1.1.8 pode indicar isso ao hub: marque o ponto interior como medido dentro do exterior, e deixa de ser subtraído uma segunda vez. Essa é a resposta certa para uma alimentação secundária de oficina ou garagem medida num nó, com as suas cargas medidas por trás — mantém as duas figuras e o restante continua a ter significado. Não altera a medição nem o total da casa.

A definição está em Management → Points → o ponto → Point setup → Point settings → Measured inside, onde None: a line of its own é o valor predefinido. A lista omite a entrada, o barramento de tensão, o próprio ponto e tudo o que já esteja dentro dele; uma escolha que o hub recuse mostra "The hub refused that choice: the point is gone, is an input, or is already inside this one. Pick another." → Points

⚠️ Vale para um nível. B dentro de A é contado uma vez. Quando uma cadeia vai mais fundo — C dentro de B dentro de A — e o ponto do meio não é mostrado, algumas vistas ainda podem contar o ponto mais interior duas vezes.

Na v1.1.7 não existia essa definição, e o conselho era medir ou o quadro secundário ou as cargas dentro dele, e não ambos. O total da casa não é afetado de qualquer forma: os totais do sistema são obtidos na entrada.

Onde os nós aparecem noutros sítios

  • Points: os canais de um nó são pontos como quaisquer outros, com as suas próprias páginas, funções e nomes (ver Points).
  • History e Economics: por ponto, como para qualquer ponto; os pontos dos nós partilham as 12 vagas de histórico (ver History).
  • Events: o registo do hub regista o emparelhamento de um nó, as definições que confirma e as linhas FAIL de tramas ou registos que o hub não conseguiu contar. Um nó que fica offline ou regressa não está no registo — é publicado no MQTT e mostrado no cartão do nó (ver Events).
  • MQTT: o hub publica um estado retido por nó em rbgrid/<mac>/node/<NODEMAC>/status (online, sinal, pacotes perdidos, última receção), atualizado a cada minuto, e os eventos de nós em rbgrid/<mac>/event; as mesmas ações de nó estão disponíveis através do canal de comandos (ver MQTT broker).
  • Home Assistant: um dispositivo por nó, com um sensor Online e um sensor Signal, por descoberta. Os pontos do nó aparecem como os locais.
  • A API do hub: GET /api/v1/espnow lista o estado do rádio e cada nó com a sua saúde; POST /api/v1/espnow executa as mesmas ações da aplicação (ver abaixo).

A API do hub

Tudo o que a aplicação faz com os nós passa por um endpoint do hub, que pode usar você mesmo.

GET /api/v1/espnow (o token de leitura, como para outras leituras) devolve o rádio e o registo:

Field Meaning
running, enabled o rádio está ativo; enabled é auto (arranca sozinho quando um nó é emparelhado), on ou off
keys, key_source true em toda a imagem de hub a partir da v1.1.7, e de onde veio a chave do hub (generated: criada por este hub na primeira vez que o rádio arrancou). Um hub sem keys não consegue executar nós
max_nodes, max_channels_per_node 6 e 4
channel o canal do rádio, o do router Wi-Fi
pairing_open, pairing_left_s, paired_count a janela de emparelhamento, os segundos que lhe restam, o número de nós emparelhados
beacons_sent, rt_recv, stats_recv, periods_recv, periods_injected, periods_dropped, periods_dup contadores desde que o hub arrancou: sinais de tempo enviados, tramas em tempo real e de período recebidas, períodos registados, descartados e reconhecidos como repetições
nodes[] por nó: mac, online, disabled, last_seen_s, rssi_dbm, sync{ resid_sd_us, skew_ppm, fits, loss_pct }, channels[{ ch, ct_code, unit_id, present }], config_state (none, pending, applied, failed), config[], period_s, fw. Um nó não ouvido desde que o hub arrancou não tem last_seen_s nem sync{}

POST /api/v1/espnow (o token de administrador) com { "action": … }:

action Fields What it does
hub_on / hub_off — liga ou desliga o rádio para nós (mantido após reinícios); desligar marca todos os nós como offline de imediato
pair seconds 10–600 abre a janela de emparelhamento; 409 ESPNOW_DISABLED enquanto o rádio estiver desligado
pair_cancel — fecha-a mais cedo
configure mac, config: { channels: [ { ch, enabled, ct_code } ] } definições do nó; o hub reenvia até o nó confirmar. 400 PERIOD_UNSUPPORTED para qualquer period_s diferente de 900; 400 BAD_REQUEST para um canal desconhecido, um ct_code fora de 1–7 ou todos os canais desligados
disable / enable mac desliga ou liga um nó
remove mac remove o nó e os seus pontos, com o respetivo histórico
latch — pede a todos os nós que fechem já o seu período atual
add mac, channels: [ { ch, ct_code } ] regista um nó manualmente, sem emparelhar

Os erros são devolvidos como { "ok": false, "error": "BAD_REQUEST" | "ESPNOW_DISABLED" | "ESPNOW_OFF" | "ESPNOW_START_FAILED" | "REGISTRY", "message": "…" }. Os pontos de nós são pontos normais em todos os outros endpoints (src: "espnow" na trama em tempo real), e GET /api/system/provisioning indica nodes_paired.

Através do MQTT o mesmo funciona no canal de comandos: {"cmd":"get","section":"espnow"} devolve o GET acima, e {"cmd":"set","section":"espnow","token":"<admin>","data":{"action":"pair","seconds":60}} executa uma ação e responde com a resposta do hub. O hub publica um estado retido por nó em rbgrid/<mac>/node/<NODEMAC>/status ({ "online", "rssi_dbm", "loss_pct", "last_seen_s" }, atualizado a cada minuto) e eventos de nós em rbgrid/<mac>/event (paired, removed, node_online, node_offline). No Home Assistant cada nó é um dispositivo com um sensor Online e um sensor Signal (dBm); um nó não ouvido desde que o hub arrancou mostra "no data".

Mensagens

Message What it means
Remote nodes are not available in this hub firmware. A imagem de firmware deste hub não consegue executar nós. (Um hub anterior à v1.1.7 não mostra qualquer secção Nodes.)
Turn the radio for nodes on to pair one. O rádio está desligado; ligue-o primeiro.
The hub takes up to 6 nodes. Remove one to pair another. Todas as seis vagas de nós estão ocupadas.
The radio for nodes is off. Turn it on first. Uma ação precisa do rádio e ele está desligado.
The hub couldn't start the radio for nodes. Try again; if it keeps failing, restart the hub. O rádio não arrancou.
The hub couldn't change its node list (full, or the node isn't known). O registo de nós recusou a alteração.
The hub didn't accept the request. O hub respondeu que o pedido estava mal formado. Recarregue a página e tente de novo.
The hub refused: message O motivo do próprio hub.
The hub didn't answer. Check the connection and try again. Sem resposta do hub.
The hub doesn't know this node any more. Reload the page. O nó foi removido, talvez a partir de outro navegador.
The hub takes only the 15-minute period. Para um nó só é aceite o período de 15 minutos.

Resolução de problemas

Premi Pair a node, mas nada aparece

  • Ligue o nó, ou reinicie-o, enquanto a janela estiver aberta.
  • Verifique se o rádio para nós não está desligado, e se o hub está ligado à sua Wi-Fi.
  • Um nó que foi emparelhado com outro hub volta a pedir quando esse hub não lhe responde durante 150 segundos, ou de imediato após um reinício (ver Moving a node to another hub).
  • Verifique a alimentação do nó, e se a gravação da flash terminou sem erros.

O nó está offline, ou oscila entre online e offline

  • Não se ouve nada dele há 15 segundos. Verifique primeiro a alimentação; depois o local. Ver Checking the link.
  • O rádio para nós do hub pode estar desligado: nesse caso, todos os nós estão offline.

O sinal, os pacotes perdidos e o clock sync estão em falta no cartão

  • O nó não foi ouvido desde que o hub arrancou ("Last heard: not heard since the hub started"). As linhas aparecem com a primeira trama do nó.

Os pontos do nó mostram valores em tempo real mas não histórico

  • As 12 vagas de histórico do hub já estavam ocupadas quando o nó foi emparelhado: "Points beyond 12 show live values only." Remova um ponto de que não precise e emparelhe o nó de novo, ou aceite pontos apenas em tempo real.
  • Um nó só regista energia com um módulo que meça tensão. Um módulo só de corrente dá corrente em tempo real e uma potência em tempo real estimada (a sua tensão nominal × corrente, 230 V se nenhuma estiver definida) — mas nenhum período, nenhum histórico e nenhum custo. A partir da v1.1.8 o hub não contabiliza energia alguma para essa entrada, em vez de a inventar a partir da tensão nominal.

Todos os nós aparecem offline apesar de estarem ligados e emparelhados

  • GET /api/v1/espnow → inject_age_ms com -1 significa que a tarefa do hub que regista os dados dos nós não está em execução. Até à v1.1.7 o hub podia não conseguir iniciá-la em silêncio quando a RAM interna estava escassa no arranque, e nada o indicava; a v1.1.8 reserva essa memória no momento da compilação. Atualize o hub.

A partir da v1.2.0 não precisa de andar à procura: a secção Remote nodes mostra um aviso quando a tarefa parou, com um botão Restart now ao lado.

A secção Remote nodes com um aviso de que o hub não está a registar dados de nós, e um botão «Restart now»

Reiniciar limpa a condição num hub que tenha memória; se voltar a acontecer após o reinício, o hub está num firmware anterior à v1.1.8 e a solução é atualizar, e não reiniciar outra vez.

A sincronização do relógio continua a perder-se

  • Outro hub RBgrid está no mesmo canal Wi-Fi, e um nó com firmware 1.4 aceitou os sinais de tempo de ambos os hubs. Atualize o nó para 1.5: passa então a seguir apenas o hub ao qual está emparelhado, e não precisa de ser emparelhado novamente.

A energia está em falta durante algum tempo

  • O nó esteve fora de alcance por mais tempo do que consegue reter períodos, ou perdeu energia. No firmware 1.5 isso são cerca de cinco dias, e um corte de energia não perde o que retém; na 1.4 são oito períodos, cerca de duas horas, e um corte de energia perde esses e o período que estava aberto.
  • O nó esteve desligado (Turn off) nesse tempo: o hub descarta os dados de um nó enquanto ele está desligado.
  • O nó arrancou enquanto o hub estava inacessível: na v1.1.7 a energia desde o seu arranque entra no seu primeiro período completo de 15 minutos, pelo que um período anterior parece vazio e esse parece alto. Nada se perde.

O meu router mudou o canal Wi-Fi

  • Não há nada a fazer. O rádio do hub para nós segue o router, e um nó que não ouve nada durante 8 segundos volta a procurar o hub.