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
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
E_Wh = avg_P_W × master_dt_seconds / 3600
Where:
avg_P_W— o valor dePERIOD_AVG_P_W, lido apósCMD_LATCH_PERIOD.master_dt_seconds— os segundos decorridos entre dois instantâneos sucessivos, medidos pelo mestre.
Período atómico — conceito
O que o comando faz
Escrever 0x27 em REG_COMMAND = 0x01 dispara uma sequência atómica dentro do firmware (executada sob __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
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").
— 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 |
Ciclo de consulta contínua (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.
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.
— 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 |
: 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 |
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)
#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
- O primeiro instantâneo é um primeiro ensaio — o resultado é descartado.
PERIOD_VALIDé lido ANTES de usar o instantâneo — caso contrário, dados obsoletos podem passar numa corrida.- dt é medido no mestre, não derivado de
PERIOD_LATCH_MS— o registo do chip serve apenas para diagnóstico de deriva. t_prevpassa 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.
— 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
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).
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.
// 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:
- Integração do lado do mestre — leia a
P_realRT (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.
— 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_VALIDcontinua a indicar 1 (o instantâneo é válido, apenas nulo).PERIOD_MAX_P_Wtambé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:
// 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?")
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:
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_Sdiminuiu desde o seu instantâneo anterior, ouUPTIME_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.
— 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:
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.
// 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:
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).
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 |
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_Passinala o evento. - Verificação de sanidade: se
max_Pexceder muitoavg_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. UsePERIOD_AVG_P_W. - ❌ Não deduza o sentido a partir de
I_rms— o RMS é sempre ≥ 0. O sentido está no sinal deP_real. - ❌ Não use
PERIOD_LATCH_MSpara 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:
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
- troubleshooting.md — o que fazer quando os valores parecem errados
- arduino-examples.md — Exemplo 5 (comunicação bidirecional no lado do mestre com o firmware BASIC)