Nodos remotos (ESP-NOW)

Descripción general

Un nodo remoto es una pequeña placa ESP32 con sus propios módulos rbAmp. Mide donde un cable I2C desde el hub no llega: un garaje, la bomba de una piscina, un calentador de agua en el sótano, un subcuadro en una dependencia exterior. Envía sus lecturas al hub por radio, mediante ESP-NOW. El nodo no está en su red Wi-Fi y no tiene dirección propia: habla solo con su hub. Sus canales se convierten en puntos normales del hub, con valores en vivo, historial y coste como cualquier otro punto.

Esta página es la documentación completa de los nodos: la placa y los módulos, el cableado, la grabación del firmware, el emparejamiento, cómo un nodo mantiene la hora y la energía, qué muestra la aplicación, la API del hub y los temas MQTT, y qué hacer cuando algo no va bien. Los nodos remotos necesitan firmware de hub v1.1.7 o posterior y la aplicación web 1.1.7 o posterior. En un hub con firmware anterior, la aplicación no muestra ninguna sección Nodes; "Remote nodes are not available in this hub firmware." aparece solo en un hub cuya imagen de firmware no puede ejecutar nodos.

Un nodo es un emisor. No tiene pantalla, ni página web, ni historial que pueda leer, y no tiene actualización por el aire: se graba por USB. Desde el firmware 1.5 sí conserva los periodos de 15 minutos terminados en su propia memoria flash hasta que el hub los tiene: es una cola, no un registro que usted pueda abrir. El resto lo hace el hub.

Para cualquier trabajo dentro de un cuadro eléctrico, llame a un electricista cualificado.

Lo que necesita

Requisito
Placa del nodo Un módulo ESP32 original con 4 MB de flash. No hace falta PSRAM. En v1.1.7 el firmware del nodo se compila y se prueba solo para el ESP32 original: las placas ESP32-S2, S3 y C3 no están compiladas ni probadas.
Módulos rbAmp en el nodo Hasta tres módulos en el bus I2C del nodo, en las direcciones 0x50, 0x51 y 0x52 (ajuste propio del módulo); SDA es GPIO 25 y SCL es GPIO 26. El hub usa hasta cuatro canales de corriente por nodo.
Una entrada de tensión en el nodo En v1.1.7 un nodo registra energía solo cuando uno de sus módulos mide tensión. Un módulo solo de corriente en un nodo da corriente en vivo, pero no periodos de 15 minutos, así que no hay historial ni coste. Monte un juego rbAmp monofásico con entrada de tensión.
Fases En v1.1.7 un nodo mide solo puntos monofásicos. No hay agrupación de fases en un nodo ni "use as the three-phase input": eso es para un módulo en el hub. Un STD-U3I3 en un nodo no está probado.
El hub Firmware v1.1.7 o posterior, conectado a su Wi-Fi. La radio del hub para nodos funciona en el mismo canal que su router; un hub sin Wi-Fi no puede ejecutar nodos. Un hub admite hasta seis nodos.
Ranuras de historial Los puntos de nodo comparten las 12 ranuras de historial existentes del hub con los puntos propios del hub; no se suman a ellas. La sección Nodes muestra "History: used of 12 points in use" antes de emparejar.
Un ordenador con USB Para grabar el nodo, y para cada actualización posterior del firmware del nodo.
Pinzas de corriente Igual que para un módulo en el hub; el modelo de pinza se fija por canal desde el hub (véase Node settings).

Cableado del nodo

Un nodo se cablea como un hub pequeño: sus módulos rbAmp van en el bus I2C del nodo, y las pinzas de corriente van en los módulos.

  • I2C: cuatro hilos entre la placa ESP32 y los módulos: SDA a GPIO 25, SCL a GPIO 26, GND y 3.3 V. Las direcciones de módulo 0x50, 0x51, 0x52 se fijan en los módulos; el nodo lee los que estén presentes al arrancar, hasta tres. El bus tiene pull-ups por las resistencias de a bordo de los módulos; con hasta tres módulos en cables cortos déjelos como están. La longitud de cable y los pull-ups para otros casos están en la guía de cableado de rbAmp, igual que para los módulos en el hub.
  • Entrada de tensión: en v1.1.7 un módulo del nodo debe tener su entrada de tensión conectada a la red que mide; sin ella el nodo tiene corriente en vivo pero no registra energía (véase What you need). La entrada de tensión también da al nodo la dirección de cada corriente, importación o exportación.
  • Pinzas: una por canal de corriente, en el conductor que quiera medir, con la flecha marcada como indica la documentación de los módulos rbAmp. El modelo de pinza se fija por canal desde el hub (véase Node settings); un modelo equivocado escala mal las lecturas.
  • Alimentación: la alimentación habitual de la placa ESP32, por ejemplo su puerto USB o una fuente de 5 V en la entrada de la placa. El nodo no tiene batería ni retención: un corte de energía lo detiene, y se pierde la energía del periodo que estaba abierto.
  • Lugar: donde vaya a estar. Un nodo no tiene que estar cerca del hub para emparejarse; el enlace se comprueba donde está (véase Checking the link). Evite, donde pueda, carcasas metálicas entre el nodo y el hub.

Para cualquier trabajo dentro de un cuadro eléctrico, llame a un electricista cualificado.

Grabar el firmware del nodo

El firmware del nodo se publica con cada versión del hub en la página de Releases de RBgrid en GitHub: rbgrid-node_vX.Y.Z.bin (solo la aplicación) y rbgrid-node_vX.Y.Z_full.zip (cargador de arranque, tabla de particiones y aplicación). Use la versión que coincida con su hub, o una más reciente.

Con la placa en modo de descarga y esptool instalado (pip install esptool), grabe el juego 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

⚠️ Actualizar un nodo al firmware 1.5 graba los tres archivos, no solo la aplicación. La 1.5 añade la partición de flash donde viven los periodos conservados. Un nodo al que se le da solo la nueva aplicación ejecuta la 1.5 sin lugar donde guardarlos y recurre a ocho periodos en memoria, y la tarjeta no lo dice. Grabar los tres también es lo que quiere para cualquier actualización posterior: no cuesta nada, y un nodo emparejado con la 1.4 no necesita emparejarse otra vez.

Compilar el firmware usted mismo, y los pines que cambiar si su placa cablea I2C de otra manera, están en node/README.md del repositorio de RBgrid.

El nodo no necesita archivo de clave ni ajuste de canal. Obtiene su clave del hub cuando lo empareja, y encuentra por sí mismo el canal del hub.

Compilar el firmware del nodo usted mismo

El código fuente es la carpeta node/ del repositorio de RBgrid, bajo la misma licencia que el firmware del hub. Se compila con ESP-IDF 5.5.1 (5.4.1 también compila):

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

La biblioteca de rbAmp se descarga en el momento de compilar (dependencies.lock fija su versión). Si su placa cablea I2C a otros pines, compile con -DRBN_I2C_SDA=<n> -DRBN_I2C_SCL=<n>. No hace falta archivo de clave. Las variantes de desarrollo del código (RBN_ROLE_MASTER, RBN_FREERUN, RBN_OUTPUT_NODE) no forman parte de la versión publicada y no son compatibles.

Emparejar un nodo

Los nodos se gestionan en Management → Points, en la sección Remote nodes (ESP-NOW). El encabezado muestra "n of 6 nodes" y el estado de la radio para nodos, "radio on" o "radio off". En un hub que puede ejecutar nodos la sección aparece en la parte superior de la página, por encima de rbAmp modules, y el asistente de configuración incluye un paso opcional ESP-NOW nodes ("Step 5 of 8", después de Sensors y antes de Tariff).

  1. Coloque el nodo donde vaya a estar, con sus módulos y pinzas montados, pero sin alimentar.
  2. En la aplicación, elija el Pairing time (en minutos) y pulse Pair a node. La sección dice: "Power the node up now. It shows up below in a few seconds." y cuenta hacia atrás: "Waiting for a node… time left". Stop pairing cierra la ventana antes de tiempo.
  3. Alimente el nodo (o reinícielo). Busca el hub en los canales Wi-Fi, intercambia claves con él y aparece en la lista, marcado como new. Sus puntos se añaden al momento: "Paired in this window: n. Their points are already added; no restart needed."

La sección Remote nodes con una ventana de emparejamiento abierta: «Waiting for a node… 1:56 left» y «Stop pairing», encima de las dos tarjetas de nodo

⚠️ Mientras la ventana de emparejamiento está abierta, cualquier nodo RBgrid al alcance que lo pida se empareja. No hay PIN. Eso incluye un nodo de otra persona cuyo propio hub se haya quedado sin responder: un nodo emparejado que no recibe respuesta durante unos 150 segundos empieza a pedir emparejarse por sí solo. Abra la ventana solo cuando vaya a alimentar un nodo, manténgala breve y ciérrela con Stop pairing cuando su nodo esté en la lista; después compruebe que la lista contiene solo los nodos que espera.

Las claves se guardan en el nodo y en el hub. Tras un reinicio, o tras haber apagado la radio, el nodo se reconecta por sí solo; usted lo empareja una vez.

Antes de emparejar, compruebe las dos líneas de capacidad de la sección: "n of 6 nodes" (cuando el hub está lleno, el botón se sustituye por "The hub takes up to 6 nodes. Remove one to pair another.") y "History: used of 12 points in use. Points beyond 12 show live values only." (o "History: all 12 points are in use. A new node's points will show live values only."). Si la radio está apagada, la sección dice "Turn the radio for nodes on to pair one."

Cada nodo aporta hasta cuatro puntos. Se nombran según el nodo y sus canales; renómbrelos y asígneles funciones en sus propias páginas, como cualquier otro punto (véase Points). Los puntos de nodo no pueden vincularse ni desvincularse a mano: un canal desactivado en los ajustes del nodo deja de medir, y eliminar el nodo elimina sus puntos.

La tarjeta del nodo

La sección Remote nodes: la radio en el canal 6, el control de emparejamiento y dos tarjetas de nodo — una en línea con su señal, sincronización de reloj y dos canales de recepción, otra sin conexión durante 90 minutos

Cada nodo emparejado tiene una tarjeta en la sección.

En la tarjeta Qué significa
online / offline El hub ha oído al nodo en los últimos 15 segundos, o no. Un nodo desactivado (véase abajo) muestra off.
new Emparejado en la ventana de emparejamiento actual.
Last heard "now", "n s ago", "n min ago", "n h ago", o "not heard since the hub started".
Signal La potencia de la última trama del nodo, en dBm, tal como la vio la radio del hub.
Lost packets, last minute La proporción de las balizas de tiempo del hub que el nodo no recibió en el último minuto, en porcentaje. Muestra "measuring (1 min)" hasta que haya pasado un minuto completo.
Clock sync Lo de cerca que sigue el reloj del nodo al del hub: "±n µs · n ppm".
Firmware La versión del firmware del nodo, cuando el nodo la ha informado.
Period "15 min". El periodo es fijo; el diálogo Settings lo dice: "Energy records: every 15 min, fixed."
Waiting to send Donde lo informa el hub: el número de periodos de 15 minutos terminados que el nodo retiene porque el hub estaba fuera de alcance (véase How a node keeps time and energy). El firmware del hub v1.1.7 no lo informa, así que la fila no aparece allí.
Channel n Cada canal de corriente del nodo: el punto al que alimenta (su nombre, un enlace a la página del punto; "Point key" hasta que el punto tenga nombre) y su estado, "receiving", "no data" u "off (Settings)".
settings not applied yet / settings not applied Los ajustes se enviaron al nodo y aún no los ha confirmado, o los ha rechazado.
Signal, lost packets and clock sync missing Un nodo no oído desde que arrancó el hub no tiene ninguno de ellos: la tarjeta omite las tres filas y Last heard dice "not heard since the hub started". Aparecen con la primera trama del nodo.

La tarjeta tiene tres botones: Settings, Turn off / Turn on, y Delete.

La tarjeta completa de un nodo: la MAC y su insignia online, Last heard, Lost packets en el último minuto, Clock sync, Signal, Firmware 1.5 y el periodo de 15 minutos, con los dos canales del nodo vinculados a puntos con nombre

Ajustes del nodo

Settings abre "Node mac: settings". Para cada canal muestra Channel n measures (activado o desactivado) y Current clamp, el modelo de pinza montado en ese canal. "Pick the clamp actually fitted to each channel: a wrong one scales its readings wrongly. A channel turned off stops measuring." Al menos un canal debe quedar activado.

Send to the node envía los ajustes a través del hub: "Sent. The node applies the settings on its next contact; the card shows «settings not applied yet» until it confirms." Si el nodo está sin conexión, el hub guarda los ajustes y se los entrega cuando el nodo vuelve ("The node is offline. It takes the settings when it's back.").

El periodo de energía de un nodo es fijo en 15 minutos ("Energy records: every 15 min, fixed."); no se puede cambiar.

Desactivar y activar un nodo

Turn off mantiene el nodo emparejado, pero hace que el hub descarte sus datos. La aplicación pregunta primero: "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." Mientras está desactivado, la tarjeta muestra off, y sus puntos no muestran valores en vivo. Turn on lo reanuda.

Úselo cuando un nodo mide algo que no quiere contar durante un tiempo. Para detener un nodo definitivamente, elimínelo.

La radio para nodos

La línea Radio for nodes del encabezado de la sección muestra uno de tres estados:

  • "On, channel n: the same as your Wi-Fi router's." La radio del hub para nodos está activa. Funciona en el canal Wi-Fi del hub, que elige su router; si el router cambia a otro canal, el hub y sus nodos lo siguen.
  • "Starts by itself when a node is paired (factory setting)." Todavía no hay nada en marcha; la radio arranca con el primer emparejamiento o cuando ya hay un nodo emparejado.
  • "Off. Nodes can't send data." Usted la desactivó.

Desactivarla pregunta primero: "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 los nodos quedan sin conexión a la vez. Los valores en vivo de ese tiempo no se conservan; los registros sí, mientras el firmware del nodo pueda guardarlos.

Eliminar un nodo

Delete pregunta "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."

⚠️ Eliminar un nodo borra sus puntos y todo su historial guardado. Si puede necesitar los registros, descárguelos antes en History.

El hub deja de aceptar los datos del nodo al instante y confirma: "Node removed, with its points: n." Para volver a usar el nodo, emparéjelo otra vez: abra una ventana de emparejamiento y reinicie el nodo (o espere unos 2½ minutos: un nodo que no recibe respuesta de su hub durante 150 segundos empieza a pedir emparejarse por sí solo).

Trasladar un nodo a otro hub

Un nodo emparejado sigue pidiendo a su hub; cuando lleva 150 segundos sin respuesta se marca a sí mismo como no emparejado y vuelve a pedir emparejarse, y tras un reinicio lo pide al momento. Así que trasladar un nodo a otro hub, o poner en servicio un nodo de segunda mano, es un emparejamiento:

  1. Delete el nodo en el hub antiguo (si lo tiene).
  2. Abra una ventana de emparejamiento en el hub nuevo y reinicie el nodo (o espere unos 2½ minutos). El nodo toma la clave del hub nuevo.

Borrar antes la flash del nodo (python -m esptool --chip esp32 -p <PORT> erase_flash, y después grabar el firmware otra vez) es opcional: un inicio limpio, no un requisito.

Cómo un nodo mantiene la hora y la energía

  • Reloj. El hub es el reloj. El nodo pide la hora cada 5 segundos hasta tenerla, y después cada minuto, y mantiene su propio temporizador entre medias. El Clock sync de la tarjeta muestra lo de cerca que la sigue.
  • Los valores en vivo se envían cada segundo aproximadamente y se muestran en los puntos del nodo. No se almacenan.
  • La energía se registra en periodos de 15 minutos, que el nodo cierra según su propio reloj en los límites de 15 minutos del hub, con la energía de los contadores propios de sus módulos. Cuando cambia la zona tarifaria, el hub pide a cada nodo que cierre también su periodo en ese momento, para que el coste por zona sea exacto.
  • Un periodo llega al hub, o se conserva. El nodo envía un periodo terminado hasta que el hub confirma que lo ha registrado, así que los registros sobreviven mejor a un enlace débil que la vista en vivo. El hub reconoce un periodo que ya tiene y nunca lo cuenta dos veces.
  • Fuera de alcance. El nodo sigue cerrando periodos a tiempo y retiene los terminados hasta que el hub los confirma. Cuando el enlace vuelve, llegan juntos y se archivan y se tarifan según la hora en que se midieron, no según la hora en que llegaron. Cuánto puede retener depende del firmware del nodo, no del hub:
    • Firmware de nodo 1.5 los escribe en su propia flash: unos cinco días de periodos, y sobreviven a un corte de energía en el nodo.
  • Firmware de nodo 1.4 guarda ocho (unas dos horas) en RAM; un noveno empuja fuera al más antiguo, y un corte de energía en el nodo pierde los periodos retenidos y el abierto.

En cualquier caso, cuando la retención está llena se va el periodo más antiguo, y el nodo lo dice en su registro.

  • Un nodo que arranca sin su hub no cierra periodos hasta haber oído al hub una vez. La energía no se pierde: en v1.1.7 el primer registro tras un arranque cubre todo desde el arranque del nodo hasta el final de su primer periodo de 15 minutos completo, así que ese periodo puede salir más alto de lo que realmente fue la carga.

El firmware no tiene una marca de aprobado para la señal ni para los paquetes perdidos, y esta página tampoco la da; el nodo es fiable donde está o no lo es. La prueba honesta es de comportamiento:

  1. Empareje el nodo donde vaya a estar, con la carga realmente funcionando.
  2. Observe la tarjeta unos diez minutos: el nodo debe mantenerse online, Lost packets, last minute debe quedarse en 0 y Last heard debe quedarse en "now" o en unos pocos segundos.
  3. Si los paquetes perdidos suben por encima de cero, o el nodo alterna entre online y offline, el enlace es marginal. Mueva un poco el nodo, o el hub, y vuelva a observar.

Hay dos umbrales en el firmware, y son todos los que existen: un nodo está offline tras 15 segundos sin una trama (el hub publica node_offline y node_online en MQTT), y un nodo que no oye ninguna baliza durante 8 segundos vuelve a buscar el canal del hub (así sigue a un router que cambia de canal; no hace falta reinicio).

Un enlace débil se nota en paquetes perdidos por encima de 0 y huecos en los valores en vivo mientras los registros siguen llegando; uno peor hace que el nodo parpadee. Un nodo fuera de alcance y un nodo sin alimentación se ven igual para la aplicación y para la API. Solo el historial de la tarjeta antes de la caída los distingue: un enlace débil se degrada primero (pérdidas crecientes, señal decreciente, parpadeo), un corte de energía es limpio.

Saber después que un nodo se ha quedado callado

La retención de cinco días solo ayuda si lo nota en cinco días.

Desde el firmware v1.2.0 el hub lo anota. Un nodo que deja de responder y que vuelve son líneas en el registro del hub — espnow: node <MAC> offline y … online — así que un nodo que se quedó callado mientras usted estaba fuera deja un rastro que puede encontrar después, con su hora. → Events

En el firmware v1.1.8 nada en la aplicación viene a avisarle: un nodo que deja de informar se muestra en su tarjeta y en la lista de Nodes, y en ningún otro sitio. No hay ninguna entrada en el Journal de la aplicación y ningún elemento en Needs attention — en ese firmware el hub escribe la línea solo en su propio registro serie.

En ninguno de los dos firmwares la aplicación lanza una alarma: el registro es un historial que se consulta, no una notificación que le llegue. Para eso, use Home Assistant.

Con Home Assistant tiene una alarma de verdad y cuesta una automatización. El hub publica una entidad de conectividad Online por nodo mediante MQTT discovery, como subdispositivo del hub, y sigue el estado retenido del nodo. Automatice sobre esa entidad cuando pase a apagada y le avisarán en un minuto. La misma transición se publica como un evento node_offline en el tema de eventos del hub, si prefiere vigilar eventos.

Sin MQTT, la tarjeta es lo único que hay. Abra la sección Nodes de vez en cuando — o eche un vistazo a los puntos del nodo en History, donde un nodo silencioso deja un hueco creciente.

Qué es realmente la transición, para que pueda ajustar la paciencia de la automatización:

  • el flanco se dispara tras 15 segundos sin una trama en vivo — el mismo umbral que usa la tarjeta, y un nodo envía una trama por segundo aproximadamente;
  • no hay antirrebote: cada hueco mayor de 15 s produce un par offline/online, y los huecos más cortos no producen nada. Un enlace marginal le da un puñado de pares, no cientos;
  • el tema de estado se refresca una vez por minuto con señal y pérdidas, como estado y no como evento — así que un panel que lo lea nunca va más de un minuto atrasado.

Totales y el resto "unmetered"

El total de la casa no puede contarse dos veces: los totales del sistema se toman en el límite de la red, solo desde el punto de entrada. Los puntos de carga, en el hub o en un nodo, nunca se suman a ellos.

El resto unmetered del Overview sí puede. Es la entrada menos la suma de todos los puntos de línea, y los puntos de nodo son puntos de línea. Si mide un subcuadro en un nodo y una carga dentro de ese subcuadro en otro canal, esa carga se resta dos veces, y el resto puede salir negativo.

Desde el firmware v1.1.8 puede indicárselo al hub: marque el punto interior como medido inside del exterior, y deja de restarse una segunda vez. Esa es la respuesta correcta para un taller o una subalimentación de garaje medida en un nodo con sus cargas medidas detrás: conserva ambas cifras y el resto sigue significando algo. No cambia nada en la medición ni en el total de la casa.

El ajuste está en Management → Points → el punto → Point setup → Point settings → Measured inside, donde None: a line of its own es el valor por defecto. La lista omite la entrada, el bus de tensión, el propio punto y lo que ya esté dentro de él; una elección que el hub rechaza muestra "The hub refused that choice: the point is gone, is an input, or is already inside this one. Pick another." → Points

⚠️ Vale para un nivel. B dentro de A se cuenta una vez. Cuando una cadena es más profunda — C dentro de B dentro de A — y el punto intermedio no se muestra, algunas vistas pueden seguir contando dos veces el punto más interior.

En v1.1.7 no existía ese ajuste, y el consejo era medir o el subcuadro o las cargas que contiene, pero no ambos. El total de la casa no se ve afectado en ningún caso: los totales del sistema se toman en la entrada.

Dónde aparecen los nodos en otros sitios

  • Points: los canales de un nodo son puntos como cualquier otro, con sus propias páginas, funciones y nombres (véase Points).
  • History y Economics: por punto, como para cualquier punto; los puntos de nodo comparten las 12 ranuras de historial (véase History).
  • Events: el registro del hub guarda el emparejamiento de un nodo, los ajustes que confirma y las líneas FAIL de tramas o registros que el hub no pudo contar. Un nodo que se desconecta o vuelve no está en el registro — se publica por MQTT y se muestra en la tarjeta del nodo (véase Events).
  • MQTT: el hub publica un estado retenido por nodo en rbgrid/<mac>/node/<NODEMAC>/status (online, señal, paquetes perdidos, última vez oído), refrescado cada minuto, y los eventos de nodo en rbgrid/<mac>/event; las mismas acciones de nodo están disponibles por el canal de comandos (véase MQTT broker).
  • Home Assistant: un dispositivo por nodo, con un sensor Online y un sensor Signal, por discovery. Los puntos del nodo aparecen como los locales.
  • La API del hub: GET /api/v1/espnow lista el estado de la radio y cada nodo con su salud; POST /api/v1/espnow ejecuta las mismas acciones que la aplicación (véase abajo).

La API del hub

Todo lo que la aplicación hace con los nodos pasa por un único endpoint del hub, que puede usar usted mismo.

GET /api/v1/espnow (el token de lectura, como para otras lecturas) devuelve la radio y el registro:

Campo Significado
running, enabled la radio está activa; enabled es auto (arranca sola cuando se empareja un nodo), on u off
keys, key_source true en cada imagen de hub desde v1.1.7, y de dónde procede la clave del hub (generated: creada por este hub la primera vez que arrancó la radio). Un hub sin keys no puede ejecutar nodos
max_nodes, max_channels_per_node 6 y 4
channel el canal de radio, el del router Wi-Fi
pairing_open, pairing_left_s, paired_count la ventana de emparejamiento, los segundos que le quedan y el número de nodos emparejados
beacons_sent, rt_recv, stats_recv, periods_recv, periods_injected, periods_dropped, periods_dup contadores desde que arrancó el hub: balizas de tiempo enviadas, tramas en vivo y de periodos recibidas, periodos registrados, descartados y reconocidos como repetidos
nodes[] por nodo: 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. Un nodo no oído desde que arrancó el hub no tiene last_seen_s ni sync{}

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

action Campos Qué hace
hub_on / hub_off — activa o desactiva la radio para nodos (se mantiene tras reinicios); desactivar pone todos los nodos offline al instante
pair seconds 10–600 abre la ventana de emparejamiento; 409 ESPNOW_DISABLED mientras la radio está apagada
pair_cancel — la cierra antes de tiempo
configure mac, config: { channels: [ { ch, enabled, ct_code } ] } ajustes del nodo; el hub reenvía hasta que el nodo confirma. 400 PERIOD_UNSUPPORTED para cualquier period_s distinto de 900; 400 BAD_REQUEST para un canal desconocido, un ct_code fuera de 1–7 o todos los canales desactivados
disable / enable mac desactiva o activa un nodo
remove mac elimina el nodo y sus puntos, con su historial
latch — pide a cada nodo que cierre su periodo actual ahora
add mac, channels: [ { ch, ct_code } ] registra un nodo a mano, sin emparejarlo

Los errores se devuelven como { "ok": false, "error": "BAD_REQUEST" | "ESPNOW_DISABLED" | "ESPNOW_OFF" | "ESPNOW_START_FAILED" | "REGISTRY", "message": "…" }. Los puntos de nodo son puntos normales en cualquier otro endpoint (src: "espnow" en la trama en vivo), y GET /api/system/provisioning informa de nodes_paired.

Por MQTT lo mismo funciona en el canal de comandos: {"cmd":"get","section":"espnow"} devuelve el GET de arriba, y {"cmd":"set","section":"espnow","token":"<admin>","data":{"action":"pair","seconds":60}} ejecuta una acción y responde con la respuesta del hub. El hub publica un estado retenido por nodo en rbgrid/<mac>/node/<NODEMAC>/status ({ "online", "rssi_dbm", "loss_pct", "last_seen_s" }, refrescado cada minuto) y los eventos de nodo en rbgrid/<mac>/event (paired, removed, node_online, node_offline). En Home Assistant cada nodo es un dispositivo con un sensor Online y otro Signal (dBm); un nodo no oído desde que arrancó el hub aparece como "no data".

Mensajes

Mensaje Qué significa
Remote nodes are not available in this hub firmware. La imagen de firmware de este hub no puede ejecutar nodos. (Un hub anterior a v1.1.7 no muestra ninguna sección Nodes.)
Turn the radio for nodes on to pair one. La radio está desactivada; actívela primero.
The hub takes up to 6 nodes. Remove one to pair another. Las seis ranuras de nodo están usadas.
The radio for nodes is off. Turn it on first. Una acción necesita la radio y está apagada.
The hub couldn't start the radio for nodes. Try again; if it keeps failing, restart the hub. La radio no arrancó.
The hub couldn't change its node list (full, or the node isn't known). El registro de nodos rechazó el cambio.
The hub didn't accept the request. El hub respondió que la petición estaba mal formada. Recargue la página e inténtelo de nuevo.
The hub refused: message El motivo propio del hub.
The hub didn't answer. Check the connection and try again. Sin respuesta del hub.
The hub doesn't know this node any more. Reload the page. El nodo se eliminó, quizá desde otro navegador.
The hub takes only the 15-minute period. Para un nodo solo se acepta el periodo de 15 minutos.

Solución de problemas

Pulsé Pair a node, pero no aparece nada

  • Alimente el nodo, o reinícielo, mientras la ventana está abierta.
  • Compruebe que la radio para nodos no está apagada, y que el hub está conectado a su Wi-Fi.
  • Un nodo que estaba emparejado con otro hub vuelve a pedir emparejarse cuando ese hub lleva 150 segundos sin responderle, o al momento tras un reinicio (véase Moving a node to another hub).
  • Compruebe la alimentación del nodo, y que su flash terminó sin errores.

El nodo está offline, o alterna entre online y offline

  • No se ha oído nada de él durante 15 segundos. Compruebe primero su alimentación; después su lugar. Véase Checking the link.
  • La radio para nodos del hub puede estar apagada: entonces todos los nodos están offline.

Faltan Signal, lost packets y clock sync en la tarjeta

  • El nodo no se ha oído desde que arrancó el hub ("Last heard: not heard since the hub started"). Las filas aparecen con su primera trama.

Los puntos del nodo muestran valores en vivo pero no historial

  • Las 12 ranuras de historial del hub ya estaban en uso cuando se emparejó el nodo: "Points beyond 12 show live values only." Elimine un punto que no necesite y vuelva a emparejar el nodo, o acepte puntos solo en vivo.
  • Un nodo registra energía solo con un módulo que mida tensión. Un módulo solo de corriente da corriente en vivo y una potencia en vivo estimada (su tensión nominal × corriente, 230 V si no hay ninguna configurada) — pero no periodos, ni historial, ni coste. Desde v1.1.8 el hub no contabiliza energía alguna para esa entrada, en lugar de inventarla a partir de la tensión nominal.

Todos los nodos aparecen offline aunque tienen alimentación y están emparejados

  • GET /api/v1/espnow → inject_age_ms de -1 significa que la tarea del hub que registra los datos del nodo no se está ejecutando. Hasta v1.1.7 el hub podía no arrancarla en silencio cuando la RAM interna era escasa al arrancar, y nada lo decía; v1.1.8 reserva esa memoria al compilar. Actualice el hub.

Desde v1.2.0 no tiene que buscarlo: la sección Remote nodes muestra un aviso cuando la tarea se ha detenido, con un botón Restart now al lado.

La sección Remote nodes con un aviso de que el hub no registra datos de nodo, y un botón «Restart now»

Reiniciar limpia la situación en un hub que tiene la memoria; si vuelve tras el reinicio, el hub tiene un firmware anterior a v1.1.8 y la solución es actualizar, no volver a reiniciar.

La sincronización de reloj sigue perdiéndose

  • Otro hub RBgrid está en el mismo canal Wi-Fi, y un nodo con firmware 1.4 aceptó las balizas de tiempo de ambos hubs. Actualice el nodo a 1.5: entonces solo sigue al hub al que está emparejado, y no necesita volver a emparejarse.

Falta energía durante un tiempo

  • El nodo estuvo fuera de alcance más tiempo del que puede retener periodos, o perdió la alimentación. En el firmware de nodo 1.5 eso son unos cinco días, y un corte de energía no pierde lo que retiene; en el 1.4 son ocho periodos, unas dos horas, y un corte de energía pierde esos y el periodo abierto.
  • El nodo estuvo desactivado (Turn off) durante ese tiempo: el hub descarta los datos de un nodo mientras está desactivado.
  • El nodo arrancó mientras el hub no era accesible: en v1.1.7 la energía desde su arranque cae en su primer periodo completo de 15 minutos, así que un periodo anterior parece vacío y ese parece alto. No se pierde nada.

Mi router cambió de canal Wi-Fi

  • No hay nada que hacer. La radio del hub para nodos sigue al router, y un nodo que no oye nada durante 8 segundos vuelve a buscar el hub.