rbAmp
PT
Loja
Docs
Atualizado

04 · Medição por período e contabilidade tarifária

Para a contabilização tarifária de energia (Wh por 1 min / 15 min / 1 hora / dia / mês / ano) o rbAmp disponibiliza um mecanismo de instantâneo atómico do período: um único comando I²C congela a potência média no tempo ao longo de um período, e o mestre multiplica-a pelo seu próprio dt de relógio de parede para obter Wh.

Esta é a forma de qualidade de produção de extrair dados de energia. A alternativa — integrar o P_real em tempo real do lado do mestre em cada janela de medição (~100 ms, v1.2 e posteriores) — dá quase o mesmo resultado no BASIC (ligeiramente menos preciso devido à discretização da amostragem) e mantém o mestre continuamente ativo.

Períodos BASIC e STD. O BASIC mantém um instantâneo de período por canal: ao comando do mestre o módulo congela a média e a potência de pico e o comprimento do período (ao lado da janela ativa de 100 ms, que não é um período), e o anfitrião integra a energia. O STANDARD (STD) mantém a energia no módulo: contadores acumulados (importação/exportação, ativos e reativos) que sobrevivem à perda de alimentação, e registos com marca temporal de 15 minutos e de hora em hora (o mestre define o relógio). Os módulos STD cujo bit 8 de CAPABILITIES está ativo têm também 8 bancos de instantâneo independentes; sem ele, a energia do intervalo vem das diferenças dos contadores. O resto deste capítulo descreve o instantâneo de período do BASIC; o STD está descrito na referência técnica do STD.

Porque é necessário um instantâneo do período

Porque se usa um instantâneo de período além da janela de medição.

Uma única base de tempo, da responsabilidade do mestre

Num sistema com vários módulos a base de tempo tem de residir no mestre. Por isso o chip não integra Wh internamente. Em vez disso:

  • O circuito integrado expõe uma estatística independente do tempo — a média de P ao longo do período.
  • O mestre multiplica-o pelo seu próprio dt de relógio de parede.
  • Todos os módulos partilham a mesma referência temporal → não se acumula deriva no total de energia do sistema.

A fórmula

Text
E_Wh = avg_P_W × master_dt_seconds / 3600

Where:

  • avg_P_W — o valor de PERIOD_AVG_P_W, lido após CMD_LATCH_PERIOD.
  • master_dt_seconds — os segundos decorridos entre dois instantâneos sucessivos, medidos pelo mestre.

Período atómico — conceito

Como um único comando de instantâneo congela o instantâneo do período e abre o período seguinte.

O que o comando faz

Escrever 0x27 em REG_COMMAND = 0x01 dispara uma sequência atómica dentro do firmware (executada sob __disable_irq()):

Text
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

Estes três passos são indivisíveis — nenhuma interrupção pode intercalar-se entre eles. Isto garante:

  • Atomicidade: cada amostra de P por janela pertence a exatamente um instantâneo — o anterior ou o seguinte — nunca duplicada, nunca perdida.
  • Sem lacuna: o novo período começa no mesmo instante em que o anterior terminou — não há intervalo cego.

Onde vive o instantâneo

Após um instantâneo, os registos de instantâneo do período (0xBE..0xCD, mais 0xDC..0xDF para ch0 avg_p, mais 0xE0..0xE3 para MAX_P, mais 0xEC..0xEF para o PERIOD_LATCH_MS de diagnóstico) devolvem o período que acabou de fechar. Note que este intervalo não é contíguo — 0xD0..0xDB contém o bloco Q (tempo real, não instantâneo do período) e 0xE4..0xEB está reservado/de fábrica. Consulte o capítulo 11 §4.11–4.13 para o layout exato. O acumulador ao vivo já começa a contar o período seguinte; estes registos de instantâneo só são atualizados no instantâneo seguinte.

Uma escrita — fecha e abre

Esta é a propriedade definidora do instantâneo rbAmp. Um único comando de instantâneo faz simultaneamente:

  • Fecha o período que acabou de terminar (os seus dados → instantâneo)
  • Abre o período seguinte (em direto ← 0)

O mestre precisa de uma escrita por medição, e não de duas (como numa implementação ingénua "iniciar → parar → ler").

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::latchPeriod() / RbAmp::isPeriodValid() enviar o comando de instantâneo; verificar o indicador de validade
ESP-IDF rbamp_latch_period() / rbamp_is_period_valid() enviar o comando de instantâneo; verificar o indicador de validade
Python dev.latch_period() / dev.is_period_valid() enviar o comando de instantâneo; verificar o indicador de validade
ESPHome update_interval: cada atualização fecha o período; o comando de instantâneo e a estabilização são tratados pelo componente
Text
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.

O primeiro instantâneo é um primeiro ensaio (descartar)

O primeiro instantâneo após o arranque captura o que o acumulador recolheu desde o power-on até à primeira chamada do mestre — uma janela de duração indefinida, inadequada para medição. Descarte o seu resultado. A partir do segundo instantâneo os dados estão limpos e utilizáveis.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch) / RbAmp::begin() instantâneo, estabilização, verificação de validade e leitura numa só chamada; begin() descarta o primeiro instantâneo
ESP-IDF rbamp_read_period_snapshot() / rbamp_begin() instantâneo, estabilização, verificação de validade e leitura numa só chamada; begin descarta o primeiro instantâneo
Python dev.read_period_snapshot(settle_ms=50, skip_latch=False) / dev.begin() instantâneo, estabilização, verificação de validade e leitura numa só chamada; begin() descarta o primeiro instantâneo
ESPHome update_interval: / latch_interval: cadência de atualização do ciclo de instantâneo; cadência de instantâneo separada opcional

Registos de instantâneo do período

Endereço Nome Tipo Quando ler Descrição
0x07 PERIOD_VALID u8 ler primeiro bit0 = 1 se o instantâneo estiver atualizado e válido, 0 se obsoleto (corrida ou instantâneo prematuro)
0xDC..0xDF PERIOD_AVG_P_W[0] float32 LE primário PRODUÇÃO — P_real médio do canal I0 ao longo do período (W)
0xC2..0xC5 PERIOD_AVG_P_W[1] float32 LE UI2/UI3 P_real médio do canal I1
0xC6..0xC9 PERIOD_AVG_P_W[2] float32 LE UI3 P_real médio do canal I2
Energia por canal (UI2/UI3)

: o mesmo instantâneo congela também as médias por canal — leia 0xC2 (ch1) / 0xC6 (ch2) na mesma passagem e multiplique pelo mesmo dt: e1_wh = avg_p1 * dt_s / 3600. | 0xE0..0xE3 | PERIOD_MAX_P_W | float32 LE | opcional | P_real de pico durante o período (para tarifas de potência) | | 0xEC..0xEF | PERIOD_LATCH_MS | u32 LE | apenas diagnóstico | Visão do circuito integrado sobre o dt entre instantâneos — pode ler curto sob carga; use PERIOD_COMMIT_COUNT × o comprimento da confirmação para o comprimento da janela do lado do módulo | | 0xBE..0xC1 | PERIOD_COMMIT_COUNT | u32 LE | medida da janela | Número de confirmações RT no período fechado. Uma confirmação = 0.1 s a partir da v1.2; 0.2 s nas imagens mais antigas — contagem × 0.1 s (ou × 0.2 s) é a medida própria do módulo para o comprimento da janela. Veja a secção sobre deriva de relógio para saber qual se aplica

Acumuladores de exportação

Endereço Nome Tipo Descrição
— — O mapa BASIC não tem acumuladores de exportação (sentido negativo); no STD a energia é guardada de outra forma — veja a documentação do STD
Nota

Nos módulos BASIC não existem registos de exportação; as leituras de um endereço não mapeado devolvem 0x00 (o firmware nunca responde com NACK às leituras — ver capítulo 11 §5.2). Um mestre que precise de seguir a exportação no BASIC recorre à contabilização baseada em RT (ver arduino-examples.md → Exemplo 5).

Nas bibliotecas cliente — a mesma tarefa sem acesso aos registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() média e potência de pico do período fechado
ESP-IDF rbamp_read_period_avg_power() / rbamp_read_period_max_power() média e potência de pico do período fechado
Python dev.read_period_avg_power(ch=0) / dev.read_period_max_power() média e potência de pico do período fechado
ESPHome update_interval: o componente lê as médias do período em cada atualização

Algoritmo do lado do mestre

Ciclo básico (um módulo, período de 60 segundos)

C++
#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;
}

O que é essencial neste código

  1. O primeiro instantâneo é um primeiro ensaio — o resultado é descartado.
  2. PERIOD_VALID é lido ANTES de usar o instantâneo — caso contrário, dados obsoletos podem passar numa corrida.
  3. dt é medido no mestre, não derivado de PERIOD_LATCH_MS — o registo do chip serve apenas para diagnóstico de deriva.
  4. t_prev passa a ser o t_now de um instantâneo bem-sucedido, e não o início original do período — isto mantém a cadeia contínua, sem lacunas.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::energyWh(ch) / RbAmpEnergy::reset(ch) total de Wh em execução mantido no anfitrião; repor o acumulador a zero
ESP-IDF rbamp_energy_wh() / rbamp_energy_reset() total de Wh em execução mantido no anfitrião; repor o acumulador a zero
Python dev.energy.wh(ch) / dev.energy.reset(ch) total de Wh em execução mantido no anfitrião; repor o acumulador a zero
ESPHome energy sensor de energia integrado pelo componente

Contabilização bidirecional

Nota

Num módulo BASIC os registos PERIOD_AVG_P_NEG_W não são alocados (as leituras devolvem 0x00), e PERIOD_AVG_P_W é sempre ≥ 0 (as amostras negativas são descartadas do acumulador).

Como a energia é contabilizada nos módulos BASIC face aos módulos STANDARD (STD).

O que significa a contabilização bidirecional

O circuito integrado tem dois acumuladores separados por período:

  • Consumo: integral de max(P, 0) × dt — apenas potência positiva.
  • Exportação: integral de max(−P, 0) × dt — apenas potência negativa, em magnitude.

A soma das duas dá a energia total que passou pelo contador em valor absoluto; a diferença é o consumo líquido (o que mostraria um contador eletromecânico de disco).

Aplicações

  • Casas com painéis solares: o consumo e a exportação são faturados com tarifas diferentes (tarifa de injeção na rede)
  • Sistemas com armazenamento em bateria: registo de ciclos de carga/descarga
  • Aerogeradores, cargas regenerativas, carregadores V2G de veículos elétricos

Onde vive a medição bidirecional

Os produtos bidirecionais (consumo + exportação) pertencem à linha rbAmp STD, que usa um mapa de registos diferente, de 16 bits, com contadores de energia com sinal no próprio dispositivo — veja a documentação de referência do STD. Não existem registos de exportação no mapa BASIC de 8 bits descrito neste capítulo.

C++
// 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;
}

O que não está disponível no BASIC

Se tiver um módulo de nível BASIC e precisar de contabilização bidirecional, tem duas opções:

  1. Integração do lado do mestre — leia a P_real RT (0xA6) em cada janela de medição (~100 ms a partir da v1.2; 200 ms antes) e integre as amostras positivas e negativas separadamente do lado do mestre. Ver o Exemplo 5 em arduino-examples.md. A exatidão é ligeiramente inferior (devido à discretização da amostragem), mas funciona em qualquer firmware.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::stdReadEnergy(out) / RbAmp::readPower(ch) STD: contadores de importação/exportação no próprio dispositivo; BASIC: potência com sinal, separada no anfitrião
ESP-IDF rbamp_std_read_energy() / rbamp_read_power() (com sinal) STD: contadores de importação/exportação no próprio dispositivo; BASIC: potência com sinal, separada no anfitrião
Python dev.read_std_energy() / dev.read_power(ch) STD: contadores de importação/exportação no próprio dispositivo; BASIC: potência com sinal, separada no anfitrião
ESPHome bidirectional: / energy_exported ative a energia de exportação; sensores de exportação (o BASIC publica 0)

Variantes só-I — a medição por período devolve zero

Nas I1/I2/I3 (e nas variantes só-I superiores) sem sensor de tensão:

  • PERIOD_AVG_P_W[*] é sempre 0.0f — sem U não há nada a integrar.
  • PERIOD_VALID continua a indicar 1 (o instantâneo é válido, apenas nulo).
  • PERIOD_MAX_P_W também é 0.

Nas variantes só de corrente a medição de período no circuito integrado não fornece uma leitura de energia. O mestre tem de:

  • Use um sensor de tensão próprio e integre I_rms × U_master × cos(φ)_master (mais complexo; requer sincronização de fase), ou
  • Use o módulo só de corrente apenas para monitorizar a presença de corrente, e associe-o a um módulo UI* ou a um contador externo para a energia.

Consulta orientada a eventos vs periódica

Periódico (tipo cron)

O mestre lê a cada N segundos com um temporizador:

C++
// Once per hour
setInterval(60 * 60 * 1000, [](){
  rb_write_u8(0x50, 0x01, 0x27);
  // ... read snapshot, accumulate Wh
});

Adequado à medição tarifária clássica (1 min, 15 min, 1 hora).

Orientado a eventos

O mestre emite um instantâneo quando ocorre um evento externo:

  • Um pulso do contador eletrónico da concessionária (verificação cruzada)
  • Uma mudança de tarifa (ponta / fora de ponta)
  • Uma consulta do utilizador ("quanto consumi até agora?")
C++
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
}

Reinício do período

Para descartar o acumulador ao vivo e recomeçar, emita um instantâneo extra e ignore o seu resultado:

C++
void restart_period() {
  rb_write_u8(0x50, 0x01, 0x27);    // close current + start new
  // do not read the snapshot — discard
}

Depois disto, retome um ciclo normal de instantâneo a partir do zero.

Deteção de reinício do módulo

Um reinício do módulo (queda de tensão, watchdog) põe silenciosamente a zero o acumulador em curso, pelo que o instantâneo seguinte cobre uma janela indefinida — exatamente como o primeiro instantâneo após o arranque. O módulo expõe:

Endereço Nome Tipo Descrição
0x46..0x49 UPTIME_S u32 LE Contador de tempo de funcionamento próprio do módulo (nominalmente segundos desde o arranque). Apenas detetor de reinício — no firmware até 1.4.21 corre mais devagar do que o tempo de relógio (medido 0.58–0.80×); nunca o use como relógio nem para cálculos de tempo
0x4A RESET_CAUSE u8 Indicadores de motivo de reset: bit0 pino externo, bit1 alimentação ligada/brown-out, bit2 software, bit3/bit4 watchdogs. Apenas para registo

Verifique em cada instantâneo — o módulo reiniciou dentro do período se qualquer uma das seguintes ocorrer:

  • UPTIME_S diminuiu desde o seu instantâneo anterior, ou
  • UPTIME_S é menor do que o tempo decorrido desde o seu instantâneo anterior (no relógio do mestre).

Como o contador pode funcionar lento, a segunda verificação pode ocasionalmente assinalar um reinício que não aconteceu (pouco depois de um arranque genuíno) — isso é inofensivo: descarta-se um período extra como preparação. Trate UPTIME_S estritamente como este discriminador de reinício, e não como fonte de tempo.

Ao detetar um reinício, descarte o instantâneo desse período (trate o instantâneo como um novo ensaio), volte a confirmar o modelo de TC se usar um modelo não original em firmware anterior a 1.4.20 (CAPABILITY bit 12 a zero) (initialization.md → O que persiste após um reinício), e reinicialize qualquer configuração apenas em RAM — ver o capítulo 11 (bit de evento RESET_OCCURRED). RESET_CAUSE não altera o tratamento; registe-o e avance.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmpPeriodSnapshot::module_restarted indicador de reinício no resultado do período (caminho do contador STD)
ESP-IDF rbamp_read_uptime_s() / module_restarted leia o uptime do módulo; bit de reinício no resultado do período
Python — não exposto — sem chamada dedicada para deteção de reinício no BASIC
ESPHome — não exposto — sem opção de deteção de reinício no YAML

Vários módulos — instantâneo simultâneo

Se o mestre quiser instantâneos síncronos de todos os módulos (para um balanço instantâneo da energia da casa), existem duas abordagens.

Abordagem 1 — instantâneo sequencial (simples)

O mestre tira o instantâneo de cada módulo por sua vez:

C++
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;
    }
  }
}

Desvantagem: os instantes de instantâneo diferem em alguns milissegundos. Para um período de 60 segundos isto dá um erro < 0.1 % — negligenciável.

Abordagem 2 — instantâneo de difusão por chamada geral (preciso, opt-in)

O endereço de chamada geral I²C 0x00 é uma trama que todos os escravos recebem em simultâneo. O rbAmp aceita uma trama canónica de 5 bytes no endereço de chamada geral que dispara CMD_LATCH_PERIOD em cada módulo que tenha a receção GC ativada. A GC é opt-in por módulo via FLEET_CONFIG.bit0 (predefinido OFF) — ver initialization.md para a sequência de ativação e o formato da trama.

Um instantâneo de difusão que chega a todos os módulos ao mesmo tempo através do endereço de chamada geral.

C++
// 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;
}

O mestre mantém um contador tick de 16 bits que incrementa em cada broadcast. Cada módulo espelha o último tick aceite em GC_TICK (0x59), para que o mestre possa detetar um broadcast perdido num módulo específico.

Após o instantâneo em broadcast, o mestre lê o instantâneo de cada módulo pelo seu endereço individual. Verifique sempre o valor de retorno — num NACK a trama GC não chegou (nenhum módulo tem o GC ativo), e o mestre tem de recorrer ao instantâneo sequencial por módulo:

C++
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;
}

Vantagem: sincronização precisa — os instantâneos são tirados ao mesmo instante em todos os módulos com GC ativa, com precisão de poucos microssegundos.

Caso de uso: crítico para o equilíbrio instantâneo (por exemplo, consumo_casa − exportação_solar num dado momento).

O instantâneo de difusão é opt-in

por módulo via FLEET_CONFIG.bit0 (predefinido OFF num módulo novo). Quando OFF, o escravo responde com NACK à trama de chamada geral e o mestre recorre automaticamente a instantâneo sequencial por módulo. Ver initialization.md — Chamada Geral (difusão no endereço 0x00) — para a sequência de ativação e o formato da trama.

Um acumulador, dois disparadores. O instantâneo endereçado (0x27 no endereço próprio do módulo) e o instantâneo broadcast repõem o mesmo acumulador de período — há apenas um por módulo. Escolha um método por módulo para o ciclo regular; um instantâneo extra pelo outro método encurta o período em curso. Os padrões de recurso acima são seguros porque só disparam quando o broadcast não chegou a esse módulo.

Nas bibliotecas cliente — a mesma tarefa sem acesso aos registos:

Biblioteca Chamada O que faz
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch=true) trama de instantâneo de difusão para a frota; leia cada módulo após um instantâneo externo
ESP-IDF rbamp_fleet_gclatch() / rbamp_read_period_snapshot(..., skip_latch=true) trama de instantâneo de difusão para a frota; leia cada módulo após um instantâneo externo
Python fleet.gc_latch(group, tick, settle_ms) / dev.read_period_snapshot(skip_latch=True) trama de instantâneo de difusão para a frota; leia cada módulo após um instantâneo externo
ESPHome fleet_gc_enable: / group_id: Opções YAML para adesão ao General Call e ID de grupo

Escolher a duração do período

Aplicação dt recomendado
Painel UI em tempo real 1 s (ou leia diretamente a P_real RT)
Gráfico de tendência, resolução de 1 minuto 60 s
Medição de pico de procura de 15 minutos 900 s
Medição horária 3600 s
Totais diários Acumule instantâneos horários no mestre; não deixe um único período exceder 1 hora
Nota

Períodos superiores a 1 hora são permitidos e nada transborda — o acumulador continua a calcular a média enquanto não chegar nenhum instantâneo. O que se degrada numa janela muito longa é a precisão da média: no pior caso ≈ 0.2 % a 1 hora, 1.3 % a 6 horas, 5 % a 24 horas. Por esse motivo mantenha os períodos individuais em ≤ 1 hora e acumule totais mais longos no mestre.

PERIOD_MAX_P_W — procura de pico

O registo 0xE0 indica a potência máxima observada em qualquer janela RT dentro do período. Utilizações:

  • Tarifas de procura de pico: as distribuidoras faturam a procura mais alta de 15 minutos do mês para os encargos de potência contratada.
  • Deteção de corrente de arranque: os arranques de motores produzem um pico de 5–10× o nominal — max_P >> avg_P assinala o evento.
  • Verificação de sanidade: se max_P exceder muito avg_P, a carga é em rajadas — normal em muitos cenários domésticos, mas um sinal a investigar se a carga for esperada como estável.

A atomicidade está garantida

CMD_LATCH_PERIOD corre com as interrupções desativadas durante a cópia do instantâneo (alguns microssegundos). O mestre nunca pode ler um instantâneo a meio da atualização — mesmo que leia os bytes imediatamente após a escrita, o firmware termina a atualização do bloco antes de a transação I²C seguinte concluir (decorrem pelo menos 10+ µs entre a escrita e a leitura).

A mesma atomicidade liga a reposição do acumulador à cópia do instantâneo — cada amostra de P está exatamente num instantâneo (o período anterior ou o seguinte), nunca em ambos, nunca em nenhum.

O que o mestre NÃO deve fazer

  • ❌ Não calcule U_rms × I_rms × dt — isso é energia aparente (VAh), e não Wh. A potência aparente inclui conteúdo reativo e sobrecarrega qualquer carga indutiva. Use PERIOD_AVG_P_W.
  • ❌ Não deduza o sentido a partir de I_rms — o RMS é sempre ≥ 0. O sentido está no sinal de P_real.
  • ❌ Não use PERIOD_LATCH_MS para Wh — esse registo é de diagnóstico e pode derivar com o relógio do chip. master_dt é a referência.
  • ❌ Não tire instantâneos mais depressa do que o ciclo de commit RT. O chip precisa de pelo menos um período da rede (~20 ms a 50 Hz) de acumulação mais a estabilização — mínimo de 50 ms entre emissões de CMD_LATCH_PERIOD. Tirar instantâneos mais depressa produz um instantâneo vazio (PERIOD_VALID = 0). 200 ms é um limite prático seguro para consulta em regime estável; ver capítulo 11 §6.0 / §6.4.

Diagnóstico de deriva do relógio

PERIOD_LATCH_MS é um registo apenas de diagnóstico — a base de tempo interna do módulo lê baixo quando o módulo está ocupado. A verificação cruzada deve usar um envelope largo:

C++
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);
}

Aceitação: uma subcontagem de até 30 % sob carga é normal (rácio até ~0.70). Isto é por desenho — ver troubleshooting.md §13. Não use um limiar apertado de 3 %–5 %; rejeitará em massa módulos saudáveis.

Esta deriva não afeta a precisão do Wh (o Wh usa o relógio do mestre); PERIOD_LATCH_MS serve apenas para revelar anomalias graves do lado do circuito integrado.

Quando quer a medida do próprio módulo para o comprimento da janela fechada, use PERIOD_COMMIT_COUNT (registo 0xBE) multiplicado pelo comprimento da confirmação: conta confirmações RT completas e não lê curto sob carga como pode acontecer com PERIOD_LATCH_MS. Uma confirmação são 0.1 s a partir da v1.2; as imagens anteriores à v1.2 usavam 0.2 s. Não é preciso uma tabela de versões para os distinguir: o rácio PERIOD_LATCH_MS / PERIOD_COMMIT_COUNT fica perto de 100 ou perto de 200.

Seguinte