04 · Medición por periodos y contabilidad de tarifas
Para la contabilidad tarifaria de energía (Wh por 1 min / 15 min / 1 hora / día / mes / año) rbAmp ofrece un mecanismo de instantánea de período atómica: un único comando I2C congela la potencia promediada en el tiempo durante un período, y el master la multiplica por su propio dt de reloj de pared para obtener Wh.
Esta es la forma de calidad de producción de extraer datos de energía. La alternativa, integrar P_real de RT en el lado del maestro en cada ventana de medida (~100 ms, v1.2 y posteriores), da casi el mismo resultado en BASIC (con algo menos de precisión por la discretización del muestreo) y mantiene al maestro activo de forma continua.
Periodos de BASIC y STD. BASIC mantiene una instantánea de periodo por canal: a orden del maestro, el módulo congela la potencia media y de pico y la longitud del periodo (junto a la ventana viva de 100 ms, que no es un periodo), y el host integra la energía. STANDARD (STD) mantiene la energía en el módulo: contadores acumulados (importación/exportación, activa y reactiva) que sobreviven a cortes de alimentación, más registros con marca de tiempo de 15 minutos y horarios (el maestro fija el reloj). Los módulos STD cuyo bit 8 de CAPABILITIES está activo tienen además 8 bancos de instantáneas independientes; sin él, la energía del intervalo se obtiene de las diferencias de los contadores. El resto de este capítulo describe la instantánea de periodo de BASIC; STD se describe en la referencia técnica de STD.
Por qué hace falta una instantánea de período
Una única base de tiempos, gestionada por el maestro
En un sistema de varios módulos la base de tiempos debe estar en el master. Por tanto el chip no integra Wh internamente. En su lugar:
- El chip expone un estadístico independiente del tiempo: la P media a lo largo del periodo.
- El maestro lo multiplica por su propio dt de reloj de pared.
- Todos los módulos comparten la misma referencia de tiempo → no se acumula deriva en el total de energía del sistema.
La fórmula
E_Wh = avg_P_W × master_dt_seconds / 3600
Where:
avg_P_W: el valor dePERIOD_AVG_P_W, leído trasCMD_LATCH_PERIOD.master_dt_seconds: los segundos transcurridos entre dos instantáneas consecutivas, medidos por el master.
Periodo atómico: concepto
Qué hace el comando
Escribir 0x27 en REG_COMMAND = 0x01 dispara una secuencia atómica dentro del firmware (ejecutada bajo __disable_irq()):
1. snapshot ← live (copy the live accumulator into the I2C-visible snapshot)
2. live ← 0 (reset the accumulator; start the next period)
3. period_start_ms = now
Estos tres pasos son indivisibles: ninguna interrupción puede intercalarse entre ellos. Esto garantiza que:
- Atomicidad: cada muestra de P por ventana pertenece a exactamente una instantánea, la anterior o la siguiente; nunca se duplica ni se pierde.
- Sin hueco: el nuevo periodo empieza en el mismo instante en que terminó el anterior; no hay intervalo ciego.
Dónde reside la instantánea
Tras una instantánea, los registros de instantánea de período (0xBE..0xCD, más 0xDC..0xDF para avg_p del canal 0, más 0xE0..0xE3 para MAX_P, más 0xEC..0xEF para el PERIOD_LATCH_MS de diagnóstico) devuelven el período que acaba de cerrarse. Tenga en cuenta que este rango no es contiguo: 0xD0..0xDB contiene el bloque Q (tiempo real en vivo, no instantánea de período) y 0xE4..0xEB está reservado o es de fábrica. Consulte el capítulo 11, §4.11–4.13, para el diseño exacto. El acumulador en vivo ya empieza a contar el período siguiente; esos registros de instantánea solo se actualizan con la siguiente instantánea.
Una escritura: cierra y abre
Esta es la propiedad definitoria de la instantánea de rbAmp. Un solo comando de instantánea a la vez:
- Cierra el periodo que acaba de terminar (sus datos → instantánea)
- Abre el siguiente periodo (viva ← 0)
El maestro necesita una escritura por medición, no dos (como en una implementación ingenua de «inicio → parada → lectura»).
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::latchPeriod() / RbAmp::isPeriodValid() |
envíe el comando de instantánea; compruebe el indicador de validez |
| ESP-IDF | rbamp_latch_period() / rbamp_is_period_valid() |
envíe el comando de instantánea; compruebe el indicador de validez |
| Python | dev.latch_period() / dev.is_period_valid() |
envíe el comando de instantánea; compruebe el indicador de validez |
| ESPHome | update_interval: |
cada actualización cierra el período; el comando de instantánea y la estabilización los gestiona el componente |
Ciclo de sondeo continuo (recomendado)
master chip
------ ----
accumulator running since boot...
write CMD_LATCH (0x27) ────► snapshot ← live (since-boot — DISCARD)
live ← 0, period_start = T0
t0 = master.clock() ◄──── first snapshot — primer (discard)
[wait 60 seconds]
write CMD_LATCH ────► snapshot ← live (over [T0..T1] — KEEP)
live ← 0, period_start = T1
t1 = master.clock()
read avg_p_W @ 0xDC ────► float32 LE
E1_Wh = avg_p × (t1 − t0) / 3600
[wait 60 seconds]
write CMD_LATCH ────► snapshot ← live (over [T1..T2] — KEEP)
live ← 0, period_start = T2
t2 = master.clock()
read avg_p_W
E2_Wh = avg_p × (t2 − t1) / 3600
...and so on. t1 is both the end of period 1 and the start of period 2.
La primera instantánea es un cebado (descártela)
La primera instantánea tras el arranque captura lo que el acumulador recogió desde el encendido hasta la primera llamada del master: una ventana de longitud indefinida no apta para la medición. Descarte su resultado. A partir de la segunda instantánea los datos son limpios y utilizables.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch) / RbAmp::begin() |
instantánea, asentamiento, comprobación de validez y lectura en una sola llamada; begin() descarta la primera instantánea |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_begin() |
instantánea, estabilización, comprobación de validez y lectura en una sola llamada; begin descarta la primera instantánea |
| Python | dev.read_period_snapshot(settle_ms=50, skip_latch=False) / dev.begin() |
instantánea, asentamiento, comprobación de validez y lectura en una sola llamada; begin() descarta la primera instantánea |
| ESPHome | update_interval: / latch_interval: |
cadencia de actualización del ciclo de instantáneas; cadencia de instantánea separada opcional |
Registros de instantánea del periodo
| Dirección | Nombre | Tipo | Cuándo leer | Descripción |
|---|---|---|---|---|
0x07 |
PERIOD_VALID |
u8 | lea primero | bit0 = 1 si la instantánea es reciente y válida, 0 si está obsoleta (carrera o instantánea prematura) |
0xDC..0xDF |
PERIOD_AVG_P_W[0] |
float32 LE | primario | PRODUCCIÓN: P_real media del canal I0 durante el período (W) |
0xC2..0xC5 |
PERIOD_AVG_P_W[1] |
float32 LE | UI2/UI3 | P_real media del canal I1 |
0xC6..0xC9 |
PERIOD_AVG_P_W[2] |
float32 LE | UI3 | P_real media del canal I2 |
: la misma instantánea congela también los promedios por canal; lea 0xC2 (ch1) / 0xC6 (ch2) en la misma pasada y multiplique por el mismo dt: e1_wh = avg_p1 * dt_s / 3600. | 0xE0..0xE3 | PERIOD_MAX_P_W | float32 LE | opcional | P_real máxima durante el periodo (para tarifas de demanda) | | 0xEC..0xEF | PERIOD_LATCH_MS | u32 LE | solo diagnóstico | Vista del chip del dt entre instantáneas: puede leerse corta bajo carga; use PERIOD_COMMIT_COUNT × la longitud del commit para la longitud de ventana del lado del módulo | | 0xBE..0xC1 | PERIOD_COMMIT_COUNT | u32 LE | medida de ventana | Número de commits RT en el periodo cerrado. Un commit = 0.1 s desde la v1.2; 0.2 s en imágenes anteriores: cuenta × 0.1 s (o × 0.2 s) es la medida propia del módulo de la longitud de la ventana. Véase la sección de deriva de reloj para saber cuál aplica
Acumuladores de exportación
| Dirección | Nombre | Tipo | Descripción |
|---|---|---|---|
| — | — | El mapa BASIC no tiene acumuladores de exportación (sentido negativo); en STD la energía se registra de otra forma: véase la documentación de STD |
En los módulos BASIC no hay registros de exportación; las lecturas de una dirección no asignada devuelven 0x00 (el firmware nunca responde NACK a las lecturas; vea el capítulo 11, §5.2). Un master que necesite seguimiento de exportación en BASIC recurre a la contabilidad basada en RT (vea arduino-examples.md → Ejemplo 5).
En las bibliotecas cliente: la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
potencia media y de pico del periodo cerrado |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
potencia media y de pico del periodo cerrado |
| Python | dev.read_period_avg_power(ch=0) / dev.read_period_max_power() |
potencia media y de pico del periodo cerrado |
| ESPHome | update_interval: |
el componente lee las medias de período en cada actualización |
Algoritmo en el lado del master
Ciclo básico (un módulo, periodo de 60 segundos)
#include
#define RB_ADDR 0x50
void setup() {
Serial.begin(115200);
Wire.begin();
delay(300);
// 1. Primer snapshot (discard result)
rb_write_u8(RB_ADDR, 0x01, 0x27);
}
void loop() {
static uint32_t t_prev = millis();
delay(60000); // wait 60 seconds
// 2. Final snapshot — closes [t_prev, now]
rb_write_u8(RB_ADDR, 0x01, 0x27);
uint32_t t_now = millis();
delay(50); // firmware finishes in ~5 ms; allow margin
// 3. Check PERIOD_VALID
uint8_t valid = rb_read_u8(RB_ADDR, 0x07);
if ((valid & 0x01) == 0) {
// Race or premature snapshot — retry
delay(250);
rb_write_u8(RB_ADDR, 0x01, 0x27);
t_now = millis();
delay(50);
valid = rb_read_u8(RB_ADDR, 0x07);
if ((valid & 0x01) == 0) {
Serial.println("WARN: two stale snapshots in a row");
t_prev = millis();
return;
}
}
// 4. Read the snapshot
float avg_p = rb_read_float_le(RB_ADDR, 0xDC);
float max_p = rb_read_float_le(RB_ADDR, 0xE0);
// 5. Compute energy on master clock
float dt_s = (t_now - t_prev) / 1000.0f;
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[+%5.1fs] E=%.3f Wh avg_P=%.1f W max_P=%.1f W\n",
dt_s, e_wh, avg_p, max_p);
t_prev = t_now;
}
Lo esencial de este código
- La primera instantánea es un cebado: su resultado se descarta.
- Debe leer
PERIOD_VALIDANTES de usar la instantánea; de lo contrario, datos obsoletos pueden colarse en una condición de carrera. - dt se mide en el master, no se deriva de
PERIOD_LATCH_MS: el registro del chip es solo para diagnóstico de deriva. t_prevse actualiza al t_now de una instantánea correcta, no al inicio original del periodo; así la cadena es continua, sin huecos.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) / RbAmpEnergy::reset(ch) |
total Wh en marcha guardado en el host; ponga a cero el acumulador |
| ESP-IDF | rbamp_energy_wh() / rbamp_energy_reset() |
total Wh en marcha guardado en el host; ponga a cero el acumulador |
| Python | dev.energy.wh(ch) / dev.energy.reset(ch) |
total Wh en marcha guardado en el host; ponga a cero el acumulador |
| ESPHome | energy |
sensor de energía integrado por el componente |
Contabilidad bidireccional
En un módulo BASIC los registros PERIOD_AVG_P_NEG_W no están asignados (las lecturas devuelven 0x00), y PERIOD_AVG_P_W es siempre ≥ 0 (las muestras negativas se descartan del acumulador).
Qué significa la contabilidad bidireccional
El chip integra dos acumuladores separados por período:
- Consumo: integral de
max(P, 0) × dt; solo potencia positiva. - Exportación: integral de
max(−P, 0) × dt: solo potencia negativa, en magnitud.
La suma de ambos da la energía total que ha pasado por el contador en valor absoluto; la diferencia es el consumo neto (lo que mostraría un contador mecánico de disco).
Aplicaciones
- Hogares con paneles solares: el consumo y la exportación se facturan con tarifas distintas (tarifa de inyección)
- Sistemas con almacenamiento en baterías: seguimiento de los ciclos de carga y descarga
- Aerogeneradores, cargas regenerativas, cargadores de vehículos eléctricos V2G
Dónde vive la contabilidad bidireccional
Los productos bidireccionales (consumo + exportación) pertenecen a la línea rbAmp STD, que usa un mapa de registros distinto, de 16 bits, con contadores de energía con signo en el propio dispositivo; véase la documentación de referencia de STD. En el mapa BASIC de 8 bits descrito en este capítulo no hay registros de exportación.
// BASIC-map period accounting, 60-second period (consumption only)
void loop() {
static uint32_t t_prev = millis();
delay(60000);
rb_write_u8(RB_ADDR, 0x01, 0x27);
uint32_t t_now = millis();
delay(50);
if ((rb_read_u8(RB_ADDR, 0x07) & 0x01) == 0) {
t_prev = millis();
return;
}
float avg_p_consume = rb_read_float_le(RB_ADDR, 0xDC); // ≥ 0
float dt_s = (t_now - t_prev) / 1000.0f;
float e_consume_wh = avg_p_consume * dt_s / 3600.0f;
Serial.printf("[%.1fs] consume=%.3f Wh\n", dt_s, e_consume_wh);
t_prev = t_now;
}
Lo que no está disponible en BASIC
Si tiene un módulo de nivel BASIC y necesita contabilidad bidireccional, tiene dos opciones:
- Integración en el lado del master: lea la
P_realde RT (0xA6) en cada ventana de medición (~100 ms desde v1.2; 200 ms antes) e integre por separado las muestras positivas y negativas en el lado del master. Vea el ejemplo 5 en arduino-examples.md. La precisión es ligeramente menor (por la discretización del muestreo), pero funciona con cualquier firmware.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::stdReadEnergy(out) / RbAmp::readPower(ch) |
STD: contadores de importación/exportación en el propio dispositivo; BASIC: potencia con signo, separada en el host |
| ESP-IDF | rbamp_std_read_energy() / rbamp_read_power() (con signo) |
STD: contadores de importación/exportación en el propio dispositivo; BASIC: potencia con signo, separada en el host |
| Python | dev.read_std_energy() / dev.read_power(ch) |
STD: contadores de importación/exportación en el propio dispositivo; BASIC: potencia con signo, separada en el host |
| ESPHome | bidirectional: / energy_exported |
active la energía de exportación; sensores de exportación (BASIC publica 0) |
Variantes solo I: la medición de período devuelve cero
En I1/I2/I3 (y variantes I* superiores solo de corriente) sin sensor de tensión:
PERIOD_AVG_P_W[*]es siempre 0.0f: no hay U, así que no hay nada que integrar.PERIOD_VALIDsigue indicando 1 (la instantánea es válida, solo que es cero).PERIOD_MAX_P_Wtambién es 0.
En las variantes solo de corriente, la medición por periodo en el chip no entrega una lectura de energía. El maestro debe:
- Use su propio sensor de tensión e integre
I_rms × U_master × cos(φ)_master(más complejo; requiere sincronización de fase), o - Use el módulo solo de corriente únicamente para monitorizar la presencia de corriente, y combínelo con un módulo UI* o con un medidor externo para la energía.
Sondeo dirigido por eventos frente a periódico
Periódico (tipo cron)
El maestro lee cada N segundos con un temporizador:
// Once per hour
setInterval(60 * 60 * 1000, [](){
rb_write_u8(0x50, 0x01, 0x27);
// ... read snapshot, accumulate Wh
});
Adecuado para la medición tarifaria clásica (1 min, 15 min, 1 hora).
Dirigido por eventos
El maestro emite una instantánea cuando se produce un evento externo:
- Un pulso del contador electrónico de la compañía (contraste)
- Un cambio de tarifa (punta / valle)
- Una consulta del usuario («¿cuánto he consumido hasta ahora?»)
void on_tariff_change() {
rb_write_u8(0x50, 0x01, 0x27); // close the period under the old tariff
delay(50);
if (rb_read_u8(0x50, 0x07) & 0x01) {
float avg_p = rb_read_float_le(0x50, 0xDC);
save_period_to_tariff_a_bucket(avg_p, current_dt_s);
}
// the next period accumulates into bucket B
}
Reinicio del periodo
Para descartar el acumulador en vivo y empezar de nuevo, emita una instantánea adicional e ignore su resultado:
void restart_period() {
rb_write_u8(0x50, 0x01, 0x27); // close current + start new
// do not read the snapshot — discard
}
Después, reanude un ciclo de instantánea normal desde cero.
Detección del reinicio de un módulo
Un reinicio del módulo (caída de alimentación, watchdog) reinicia en silencio el acumulador en vivo, de modo que la siguiente instantánea cubre una ventana indefinida: exactamente como la primera instantánea tras el arranque. El módulo expone:
| Dirección | Nombre | Tipo | Descripción |
|---|---|---|---|
0x46..0x49 |
UPTIME_S |
u32 LE | Contador de tiempo activo propio del módulo (en principio segundos desde el arranque). Solo detector de reinicio: en firmware hasta 1.4.21 avanza más lento que el tiempo de reloj (medido 0.58–0.80×); nunca lo use como reloj ni para cálculos de tiempo |
0x4A |
RESET_CAUSE |
u8 | Indicadores del motivo de reinicio: bit0 pin externo, bit1 encendido o caída de tensión, bit2 software, bit3/bit4 watchdogs. Solo para registro |
Compruebe en cada instantánea: el módulo se reinició dentro del período si se cumple cualquiera de estas condiciones:
UPTIME_Sha disminuido desde su instantánea anterior, oUPTIME_Ses menor que el tiempo transcurrido desde su instantánea anterior (según el reloj del master).
Como el contador puede ir lento, la segunda comprobación puede marcar a veces un reinicio que no ocurrió (poco después de un arranque real): es inocuo, porque descarta un periodo extra como cebado. Trate UPTIME_S estrictamente como discriminador de reinicio, no como fuente de tiempo.
Al detectar un reinicio, descarte la instantánea de ese período (trátela como un nuevo cebado), vuelva a confirmar el modelo de CT si usa un modelo no de fábrica con firmware anterior a 1.4.20 (bit 12 de CAPABILITY a 0) (initialization.md → Qué persiste tras un reinicio), y reinicialice cualquier configuración solo en RAM: vea el capítulo 11 (bit de evento RESET_OCCURRED). RESET_CAUSE no cambia el tratamiento: regístrelo y siga adelante.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmpPeriodSnapshot::module_restarted |
indicador de reinicio en el resultado del periodo (vía del contador STD) |
| ESP-IDF | rbamp_read_uptime_s() / module_restarted |
lea el tiempo activo del módulo; indicador de reinicio en el resultado del período |
| Python | — | no expuesto: no hay llamada dedicada para detectar reinicios en BASIC |
| ESPHome | — | no expuesto: no hay opción de detección de reinicio en YAML |
Varios módulos: instantánea simultánea
Si el maestro quiere instantáneas síncronas de todos los módulos (para un balance energético instantáneo de la vivienda), hay dos enfoques.
Enfoque 1: instantánea secuencial (sencillo)
El master toma la instantánea de cada módulo por turno:
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev[] = {0, 0, 0};
void setup() {
Wire.begin();
// Primer
for (int i = 0; i < 3; i++) {
rb_write_u8(modules[i], 0x01, 0x27);
t_prev[i] = millis();
}
}
void loop() {
delay(60000);
for (int i = 0; i < 3; i++) {
rb_write_u8(modules[i], 0x01, 0x27);
uint32_t t_now = millis();
delay(50);
if (rb_read_u8(modules[i], 0x07) & 0x01) {
float avg_p = rb_read_float_le(modules[i], 0xDC);
float dt_s = (t_now - t_prev[i]) / 1000.0f;
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[0x%02X] E=%.3f Wh\n", modules[i], e_wh);
t_prev[i] = t_now;
}
}
}
Inconveniente: los instantes de la instantánea difieren en unos pocos milisegundos. Para un período de 60 segundos el error es < 0.1 %: despreciable.
Enfoque 2: instantánea de difusión mediante llamada general (precisa, opcional)
La dirección de llamada general I²C 0x00 es un paquete que reciben simultáneamente todos los esclavos. rbAmp acepta una trama canónica de 5 bytes en la dirección de llamada general que dispara CMD_LATCH_PERIOD en cada módulo que tenga la recepción GC habilitada. GC es opcional por módulo mediante FLEET_CONFIG.bit0 (por defecto DESACTIVADA); vea initialization.md para la secuencia de habilitación y el formato de trama.
// Canonical 5-byte GC frame: A5 27 group tick_lo tick_hi.
// Returns true on ACK, false on bus-level NACK (no module has GC enabled).
bool broadcast_latch(uint16_t tick16, uint8_t group = 0) {
Wire.beginTransmission(0x00); // general call
Wire.write(0xA5); // frame magic
Wire.write(0x27); // CMD_LATCH_PERIOD opcode
Wire.write(group); // group_id (0 = all-call)
Wire.write((uint8_t)(tick16 & 0xFF)); // tick_lo
Wire.write((uint8_t)((tick16 >> 8) & 0xFF)); // tick_hi
return Wire.endTransmission() == 0;
}
El maestro mantiene un contador tick de 16 bits que se incrementa en cada difusión. Cada módulo replica el último tick aceptado en GC_TICK (0x59), de modo que el maestro puede detectar una difusión perdida en un módulo concreto.
Tras la instantánea de difusión, el maestro lee la instantánea de cada módulo por su dirección individual. Compruebe siempre el valor devuelto: ante un NACK, la trama GC no llegó (ningún módulo tiene GC activado) y el maestro debe recurrir a la instantánea secuencial módulo a módulo:
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev;
uint16_t gc_tick = 0;
void setup() {
Wire.begin();
if (!broadcast_latch(gc_tick++)) {
// Fall back: per-module sequential snapshot.
for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
}
t_prev = millis();
}
void loop() {
delay(60000);
if (!broadcast_latch(gc_tick++)) {
for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
}
uint32_t t_now = millis();
delay(50);
float dt_s = (t_now - t_prev) / 1000.0f;
for (int i = 0; i < 3; i++) {
if (rb_read_u8(modules[i], 0x07) & 0x01) {
float avg_p = rb_read_float_le(modules[i], 0xDC);
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[0x%02X] E=%.3f Wh P_avg=%.1f W\n",
modules[i], e_wh, avg_p);
}
}
t_prev = t_now;
}
Ventaja: sincronización precisa: las instantáneas se toman en el mismo instante en todos los módulos con GC habilitada, con una precisión de pocos microsegundos.
Caso de uso: crítico para el equilibrio instantáneo (por ejemplo, consumo_casa − exportación_solar en un instante dado).
por módulo mediante FLEET_CONFIG.bit0 (por defecto DESACTIVADA en un módulo nuevo). Cuando está desactivada, el esclavo responde NACK a la trama de llamada general y el master recurre automáticamente a una instantánea secuencial por módulo. Vea initialization.md, General Call (difusión en la dirección 0x00), para la secuencia de habilitación y el formato de trama.
Un acumulador, dos disparadores. La instantánea direccionada (0x27 en la dirección propia del módulo) y la instantánea de difusión reinician el mismo acumulador de periodo: solo hay uno por módulo. Elija un método por módulo para el ciclo regular; una instantánea extra con el otro método acorta el periodo en curso. Los patrones de respaldo anteriores son seguros porque solo se disparan cuando la difusión no llegó a ese módulo.
En las bibliotecas cliente: la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch=true) |
trama de instantánea de difusión a la flota; lea cada módulo tras una instantánea externa |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_read_period_snapshot(..., skip_latch=true) |
trama de instantánea de difusión a la flota; lea cada módulo tras una instantánea externa |
| Python | fleet.gc_latch(group, tick, settle_ms) / dev.read_period_snapshot(skip_latch=True) |
trama de instantánea de difusión a la flota; lea cada módulo tras una instantánea externa |
| ESPHome | fleet_gc_enable: / group_id: |
Opciones YAML para la activación de llamada general y el identificador de grupo |
Elegir la duración del período
| Aplicación | dt recomendado |
|---|---|
| Panel UI en vivo | 1 s (o lea directamente P_real de RT) |
| Gráfico de tendencia, resolución de 1 minuto | 60 s |
| Medición de demanda máxima de 15 minutos | 900 s |
| Medición horaria | 3600 s |
| Totales diarios | Acumule instantáneas horarias en el master; no deje que un solo período supere 1 hora |
Los periodos de más de 1 hora están permitidos y nada se desborda: el acumulador sigue promediando mientras no llegue ninguna instantánea. Lo que se degrada en una ventana muy larga es la precisión del promedio: en el peor caso ≈ 0.2 % a 1 hora, 1.3 % a 6 horas, 5 % a 24 horas. Por esa razón, mantenga los periodos individuales en ≤ 1 hora y acumule totales más largos en el maestro.
PERIOD_MAX_P_W: demanda máxima
El registro 0xE0 informa de la potencia máxima observada en cualquier ventana RT dentro del periodo. Usos:
- Tarifas de demanda máxima: las compañías facturan la demanda máxima de 15 minutos del mes para los cargos de capacidad.
- Detección de irrupción: los arranques de motor producen un pico de 5–10× la nominal:
max_P >> avg_Pseñala el evento. - Comprobación de coherencia: si
max_Psupera ampliamente aavg_P, la carga es a ráfagas: normal en muchos escenarios domésticos, pero merece investigarse si se espera una carga constante.
La atomicidad está garantizada
CMD_LATCH_PERIOD se ejecuta con las interrupciones desactivadas durante la copia de la instantánea (unos pocos microsegundos). El master nunca puede leer una instantánea a medio actualizar: aunque lea los bytes justo después de la escritura, el firmware termina de actualizar el bloque antes de que acabe la siguiente transacción I²C (transcurren al menos 10+ µs entre la escritura y la lectura).
La misma atomicidad vincula el reinicio del acumulador a la copia de la instantánea: cada muestra de P está en exactamente una instantánea (la del período anterior o la del siguiente), nunca en ambas ni en ninguna.
Lo que el master NO debe hacer
- ❌ No calcule
U_rms × I_rms × dt: eso es energía aparente (VAh), no Wh. La potencia aparente incluye el contenido reactivo y sobrecarga cualquier carga inductiva. UsePERIOD_AVG_P_W. - ❌ No infiera la dirección a partir de
I_rms: el RMS es siempre ≥ 0. La dirección está en el signo deP_real. - ❌ No use
PERIOD_LATCH_MSpara Wh: ese registro es de diagnóstico y puede derivar con el reloj del chip.master_dtes la referencia. - ❌ No haga instantáneas más deprisa que el ciclo de confirmación RT. El chip necesita al menos un período de red (~20 ms a 50 Hz) de acumulación más la estabilización: mínimo 50 ms entre emisiones de
CMD_LATCH_PERIOD. Hacer instantáneas más rápido produce una instantánea vacía (PERIOD_VALID = 0). 200 ms es un mínimo práctico seguro para el sondeo en régimen permanente; vea el capítulo 11, §6.0 / §6.4.
Diagnóstico de deriva del reloj
PERIOD_LATCH_MS es un registro solo de diagnóstico: la base de tiempos interna del módulo se lee corta cuando el módulo está ocupado. La comprobación cruzada debe usar un margen amplio:
uint32_t chip_dt = rb_read_u32(0x50, 0xEC);
uint32_t master_dt = t_now - t_prev;
float ratio = (float)chip_dt / (float)master_dt;
if (ratio < 0.70f || ratio > 1.05f) {
Serial.printf("WARN: chip drift outside ±30%% envelope, ratio=%.3f\n", ratio);
}
Aceptación: hasta un 30 % de recuento inferior bajo carga es normal (cociente tan bajo como ~0.70). Es por diseño; vea troubleshooting.md §13. No use un umbral estricto del 3 %–5 %: rechazaría en masa módulos sanos.
Esta deriva no afecta a la precisión de Wh (Wh usa el reloj del maestro); PERIOD_LATCH_MS sirve solo para señalar anomalías graves del lado del chip.
Cuando quiera la medida propia del módulo de la longitud de la ventana cerrada, use PERIOD_COMMIT_COUNT (registro 0xBE) multiplicado por la longitud del commit: cuenta commits RT completos y no se lee corto bajo carga como puede ocurrir con PERIOD_LATCH_MS. Un commit son 0.1 s desde la v1.2; las imágenes anteriores a la v1.2 usaban 0.2 s. No hace falta una tabla de versiones para distinguirlas: el cociente PERIOD_LATCH_MS / PERIOD_COMMIT_COUNT es cercano a 100 o cercano a 200.
Siguiente
- troubleshooting.md: qué hacer cuando los valores parecen erróneos
- arduino-examples.md: Ejemplo 5 (bidireccional con el maestro sobre firmware BASIC)