rbAmp
PT
Loja
Docs
Atualizado

Referência do protocolo Wire rbAmp (v1.3)

rbAmp é um módulo compacto para medição de parâmetros da rede CA através de uma interface I²C. O módulo comporta-se como um escravo I²C padrão com um mapa de registos fixo (página 0, 0x00..0xFF). Este documento descreve o protocolo de fios ao nível de registos, comandos e sequências.

Público-alvo

: integradores terceiros e avançados que escrevem os seus próprios drivers I²C para o módulo rbAmp sem usar bibliotecas cliente (Arduino / ESP-IDF / Python / ESPHome).

Âmbito: protocolo de fios canónico do módulo rbAmp na versão v1.3 — mapa de registos, sequências de protocolo, garantias de comportamento. Esta é a documentação de referência completa ao nível do contrato de fios.

Versão: "v1.3" é a versão do protocolo de fios (o registo VERSION 0x03 lê 0x04), não a versão deste documento. É o protocolo de todos os firmwares atuais dos módulos BASIC (1.4.x); os módulos STANDARD (STD) usam um mapa de registos diferente — ver a referência técnica STD.

FORA do âmbito: integração com qualquer biblioteca / SO / framework específico — consulte a documentação da biblioteca para isso.


1 · Introdução

1.1 Gama de SKU

As variantes de módulo (SCT-UI1 … SCT-I3, com os seus canais de tensão e de corrente) estão listadas em overview.md → Variantes de módulo.

As variantes I (I1/I2/I3) não têm hardware de tensão — os registos U_RMS, U_PEAK e P devolvem 0.0. A frequência (AC_FREQ) está disponível em todas as variantes (com origem em ZC).

A calibração é de fábrica. O mestre do consumidor NÃO configura o limiar de ruído (NF), o ganho, a compensação de fase nem quaisquer outros parâmetros de fábrica — tudo isto é calibração de fábrica gravada no módulo (veja §4.0 gamas reservadas). Nos módulos da série BASIC SCT (usados com sensores SCT-013) o consumidor escreve apenas SENSOR_CLASS + CT_MODEL (veja §6.2) — o módulo aplica tudo o resto automaticamente a partir da tabela de predefinições. Os módulos da série BASIC CT e STANDARD (STD) são fornecidos em par com os seus sensores, pré-configurados e calibrados de fábrica: não se escreve nada.

1.2 Versionamento

Campo Valor
protocol_version 1.3
schema_version 2
registo VERSION (0x03) 0x04 para v1.3
Contrato da página 0 congelado na versão v1.3

2 · Noções básicas do protocolo de barramento

2.0 Potência e alimentação

Parâmetro Valor
VCC nominal +5 V
Gama de VCC 4.5..5.5 V
Consumo de corrente típico ~15 mA
Consumo de pico de corrente (instantâneo + escrita na flash) ~25 mA
Corrente de arranque ≤ 50 mA @ 5 ms
Sequenciação VCC pode ser aplicado em simultâneo com o I²C; os pull-ups (3.3 V) são permitidos antes de se aplicar VCC
Isolamento o módulo é todo de baixa tensão: a pinça acopla magneticamente, e a derivação de tensão UI é isolada galvanicamente
Nota

Quatro fios são obrigatórios no lado de baixa tensão: VCC, GND, SDA, SCL. DRDY (dreno aberto) é opcional. Veja §2.3 para orientações sobre pull-ups e vários módulos.

2.1 Parâmetros I²C

  • Endereço predefinido: 0x50 (7 bits).
  • Intervalo de endereços permitido: 0x08..0x77 (limites reservados I²C padrão).
  • Níveis lógicos: 3.3 V (tolerante a 5 V nos pull-ups para 3.3 V).
  • Pull-ups incorporadas: 4.7 kΩ em SDA/SCL para 3.3 V (módulo).
  • Estiramento do relógio: o módulo NÃO usa o estiramento do SCL como mecanismo rotineiro de controlo de fluxo. Entre transações o mestre tem de respeitar um intervalo entre transações ≥ 100 µs (tBUF). Transações encadeadas sem intervalo (START repetido sem tBUF) são permitidas mas desaconselhadas — algumas pilhas de anfitrião (ESP-IDF i2c_master) apresentam uma taxa de NACK elevada. Ver a secção §5 de aceitação / EMI em separado.

2.2 Velocidade do barramento

Velocidade Aplicabilidade Nota
50 kHz recomendado em mestres ESP32 e ESP8266 O driver I²C do ESP-IDF mostra uma taxa de NACK de ~20 % a 100 kHz — uma limitação do driver do anfitrião, e não do módulo; 50 kHz + 3× de repetição dá uma taxa de erro < 0.8 %.
100 kHz recomendado noutros mestres também viável em ESP32/ESP8266 com repetição 3× ao nível da aplicação.
400 kHz não recomendado a velocidade é escolha do utilizador.

2.3 Barramento com vários módulos

Vários módulos rbAmp podem partilhar um barramento:

  • Até ~16 módulos (limitado pela capacidade total do barramento ≤ 400 pF a 100 kHz).
  • Pull-ups: com 2–3 módulos num barramento até 15 cm, não mexa nas pull-ups da placa; com quatro ou mais, ou num barramento mais longo, as pull-ups de 4.7 kΩ em paralelo sobrecarregam o sumidouro. Corte as pull-ups da placa em todos os módulos exceto um (ou use um buffer I²C PCA9515/9615).
  • Comprimento: até 0.15 m simples → 100 kHz; 0.15–1 m par entrançado (SDA+GND e SCL+GND em pares separados) → 100 kHz; > 1 m — buffer I²C; > 3 m — barramento diferencial (PCA9615 / LTC4332).

2.4 Orçamento de consulta do barramento

A 50 kHz, uma única transação de leitura de registo demora ≈ 200–400 µs. O bloco RT completo de um canal (U + I + P + PF, 4 floats = 16 bytes em rajada) demora ≈ 5–8 ms por canal.

Configuração Ciclo de barramento Taxa máxima de consulta
1× UI1, bloco RT ~5 ms 100+ Hz (mas o módulo atualiza a 10 Hz)
5× UI1, bloco RT ~25 ms 10 Hz
16× I3, RT + período ~400 ms não consegue acompanhar — lê a cada 4.ª janela de 100 ms

Regra prática: a 50 kHz os limites confortáveis são 8–10× I3 ou 15–16× UI1 ao fazer polling em janelas alternadas (5 Hz); divida por dois o número de módulos para fazer polling em todas as janelas (10 Hz).


3 · Modelo de variantes

3.1 HW_VARIANT (registo 0x55, u8, só leitura)

Byte de SKU de referência:

Valor SKU N_I HW de tensão
0x01 UI1 1 sim
0x02 UI2 2 sim
0x03 UI3 3 sim
0x04 I1 1 não
0x05 I2 2 não
0x06 I3 3 não
0x07 UI5 5 sim
0x08 UI7 7 sim

Qualquer outro valor → o dispositivo não é identificado como rbAmp.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readVariant() ler a variante de hardware (SKU)
ESP-IDF rbamp_read_variant() ler a variante de hardware (SKU)
Python dev.read_variant() ler a variante de hardware (SKU)
ESPHome get_variant_str() ler a variante de hardware (SKU)

3.2 CAPABILITY (registos 0x57/0x58, u16 LE, só leitura)

Mapa de deteção de funcionalidades. Esta é a forma canónica de detetar as funcionalidades suportadas — sem comparação numérica de versões.

bit Indicador Significado
0 EXT_ADDRESSING endereçamento estendido de 16 bits (prefixo 0xFF)
1 GC_LATCH O instantâneo General-Call é suportado
2 GC_GROUP_FILTER o filtro GROUP_ID está ativo
3 DIGEST o bloco de resumo (0x70..0x85) está exposto
4 EVENTS EVENT_FLAGS é suportado
5 UID_ARBITRATION Arbitragem de endereços baseada em UID (sem comandos públicos)
6 SEAL reservado — não implementado
7 TWO_PHASE_ADDR alteração de endereço em duas fases (commit em duas fases)
8 ZC_PHASE_OFFSET = tensão-HW o módulo tem um canal U
9 SAVE_USER_CONFIG CMD_SAVE_USER_CONFIG disponível
10 CLEAR_ERROR CMD_CLEAR_ERROR disponível
11 IAP programação em aplicação (apenas níveis F4)
12 SCT_RATING_SELF fw 1.4.20+: uma troca de modelo SCT mantém a calibração da unidade e sobrevive a um reinício; as bibliotecas saltam a sua própria correção de potência nominal

3.2.1 Deteção de funcionalidades

Detete cada funcionalidade pelo seu bit individual — nunca compare o registo inteiro com uma constante esperada: o mapa de bits cresce com o firmware (por exemplo, o bit 12 apareceu no fw 1.4.20), por isso a comparação do valor completo falha em módulos mais recentes.

3.2.2 Layout de bytes do CAPABILITY u16 LE

CAPABILITY tem 2 bytes nos endereços 0x57 (byte baixo) e 0x58 (byte alto), little-endian:

Text
register layout (byte-addressed):

  0x57   0x58
  ┌──────┬──────┐
  │ LO   │ HI   │
  └──────┴──────┘
   bits   bits
   0-7    8-15

  full u16 = (read_u8(0x58) << 8) | read_u8(0x57)

Mapeamento de bits:

  • byte 0x57 (LO) contém os bits 0..7: EXT_ADDRESSING, GC_LATCH, GC_GROUP_FILTER, DIGEST, EVENTS, UID_ARBITRATION, SEAL, TWO_PHASE_ADDR.
  • o byte 0x58 (HI) contém os bits 8..15: ZC_PHASE_OFFSET (= HW de tensão), SAVE_USER_CONFIG, CLEAR_ERROR, IAP, SCT_RATING_SELF (bit 12, fw 1.4.20+), bits 13-15 reservados.

3.2.3 Receita canónica de has_voltage

Python
cap_hi = read_u8(0x58)             # high byte holds bits 8..15
has_voltage = bool(cap_hi & 0x01)  # bit 8 of the u16 = bit 0 of byte 0x58
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readCapability(out) / RbAmp::hasVoltageHw() ler o mapa de funcionalidades de 16 bits; verificar se existe um canal de tensão
ESP-IDF rbamp_read_capability() / rbamp_has_voltage() ler o mapa de funcionalidades de 16 bits; verificar se existe um canal de tensão
Python dev.read_capability() / dev.has_voltage() ler o mapa de funcionalidades de 16 bits; verificar se existe um canal de tensão
ESPHome get_capability_hex() ler o mapa de capacidades

3.3 Tabela de perfis de variante — invariante

SKU HW_VARIANT (0x55) N_I tensão-HW Bit 8 de CAPABILITY (tensão-HW)
UI1 1 1 sim bit 8 a 1
UI2 2 2 sim bit 8 a 1
UI3 3 3 sim bit 8 a 1
I1 4 1 não bit 8 a zero
I2 5 2 não bit 8 a zero
I3 6 3 não bit 8 a zero
UI5 7 5 sim bit 8 a 1
UI7 8 7 sim bit 8 a 1

Coerência HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 e 7..8 (UI) → bit 8 ativo; HW_VARIANT 4..6 (I) → bit 8 a zero. Uma discrepância indica uma anomalia de hardware ou firmware (dispositivo avariado ou gravação incorreta).

3.4 SENSOR_CLASS ≠ discriminador de variante

⚠ SENSOR_CLASS (0x25) NÃO é um discriminador de variante. É um registo de configuração do utilizador (seletor da classe do sensor de CT: Unset/Sct013/WiredCT/BuiltinCT) e não reflete a variante de hardware. Para deteção de variante use apenas HW_VARIANT (0x55) + CAPABILITY (0x57/0x58).

3.5 PRODUCT_ID (0x54, u8, só leitura)

Discriminador de família de produto:

Valor Família
0x01 sensor rbAmp (este documento)
0x02 rbDimmer (mapa de registos próprio; não coberto por este documento)

O mestre TEM de ler o PRODUCT_ID antes de interpretar qualquer registo específico da família.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readProductId() ler o byte de identificação da família
ESP-IDF rbamp_read_product_id() ler o byte de identificação da família
Python dev.read_product_id() ler o byte de identificação da família
ESPHome — não exposto

3.6 Algoritmo de deteção canónico

Python
if not i2c_addr_acks(addr):
    return NO_DEVICE
product = read_u8(addr, 0x54)
if product != 0x01:
    return NOT_RBAMP_SENSOR
hw = read_u8(addr, 0x55)
if 1 <= hw <= 8:
    cap_hi = read_u8(addr, 0x58)
    has_voltage = bool(cap_hi & 0x01)
    return {sku: SKU[hw], N_I: N_I_TABLE[hw], has_voltage: has_voltage}
return UNKNOWN_DEVICE
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::begin() / RbAmp::readVariant() sonde o módulo e detete a sua linha; leia a variante
ESP-IDF rbamp_begin() / rbamp_read_variant() sonde o módulo e detete a sua linha; leia a variante
Python dev.begin() / dev.read_variant() sonde o módulo e detete a sua linha; leia a variante
ESPHome rbamp: address: / get_variant_str() endereço do módulo definido no YAML; a variante como texto

4 · Mapa de registos (produção v1.3)

Filtro aplicado: build: production(registos de build de calibração excluídos). Os registos de calibração de fábrica (NF, GAIN, PHASE) sãonão documentado— pertencem à bancada de fábrica, não à superfície do consumidor.

Visão geral do mapa de registos do rbAmp e dos seus blocos de endereços.

4.0 Gamas reservadas (internas)

Os intervalos seguintes estão reservados para uso interno/de fábrica e não estão descritos neste documento. As leituras devolvem dados sem relevância para a lógica do consumidor ou 0x00 para endereços inexistentes (ver §5.2). As escritas nestes endereços são descartadas silenciosamente ou respondidas com ERR_PARAM:

  • 0x04 — indicador de modo interno (controlado pela fábrica, não configurável pelo consumidor).
  • 0x06, 0x26 — parâmetros internos de calibração (bancada de fábrica).
  • 0x08..0x0F — vista de depuração da LUT (diagnóstico de fábrica).
  • 0x1B..0x1F — página 0 reservada (0x18..0x1A são diagnóstico de produção, ver §4.2).
  • 0x36..0x3B, 0x40..0x45 — página 0 reservada (0x32 + 0x3C..0x3F são a janela de acesso aos canais, veja §4.14).
  • 0x4F, 0x50 — reservados (pré-reserva do bloco de identidade).
  • 0xE4..0xEB, 0xF0..0xFF — calibração de fábrica (NF, GAIN); escritas restritas à fábrica.
Nota

Nota sobre 0xD0..0xE3: na versão de produção esta gama está ocupada pelo bloco V03 Q (veja §4.12). No firmware de calibração separado (não distribuído ao consumidor) a mesma gama é sobreposta pelo bloco de calibração (build:cal). O mestre do consumidor vê apenas a sobreposição de produção — o bloco Q.

Integradores de 3.ª parte devem ignorar estes intervalos.

4.1 Bloco de controlo (0x00..0x07)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x00 STATUS 1 u8 r ram bit0=READY, bit1=ERROR (espelho de REG_ERROR != 0), bit2=EVENTS_PENDING (espelho de EVENT_FLAGS != 0)
0x01 COMMAND 1 u8 w ram Escreva um opcode CMD_* (ver §5.2)
0x02 ERROR 1 u8 r ram resultado da última escrita; 0x00 = OK; 0xFA..0xFF classes de erro. Limpar com CMD_CLEAR_ERROR. Veja §5.3
0x03 VERSION 1 u8 r rom Versão do protocolo. 0x04 = v1.3
0x05 CT_MODEL 1 u8 rw user_config Código SKU do SCT-013 (preparação pura v1.3 — veja §6.2)
0x07 V03_PERIOD_VALID 1 u8 r ram Definido por CMD_LATCH_PERIOD: 1 = recente, 0 = vazio/desatualizado. NÃO é limpo na leitura. Veja §6.3.3 (testemunha) + §7.5 (preservação de instantâneo falhado)
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::waitReady(timeout_ms) / RbAmp::readLastError() aguardar o indicador de pronto; ler o código de erro do dispositivo
ESP-IDF rbamp_wait_ready() / rbamp_read_last_error() aguardar o indicador de pronto; ler o código de erro do dispositivo
Python dev.wait_ready(timeout_ms=1000) / dev.read_last_error() aguardar o sinalizador de pronto (gera erro em timeout); ler o código de erro do dispositivo
ESPHome verificação de prontidão de update() / get_last_error_str() as leituras são publicadas quando o módulo indica que está pronto; o código de erro em texto

4.2 Diagnóstico — médias das entradas brutas e janela de captura (0x10..0x1C)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x10 ADC_MEAN_U 2 u16 LE r ram Média da entrada bruta, canal U (~2048 centrado)
0x12 ADC_MEAN_I0 2 u16 LE r ram Média da entrada bruta, I0
0x14 ADC_MEAN_I1 2 u16 LE r ram Média da entrada bruta, I1 (UI2/I2/I3/UI3)
0x16 ADC_MEAN_I2 2 u16 LE r ram Média da entrada bruta, I2 (UI3/I3)
0x18 CAPTURE_STATUS 1 u8 r ram Captura de amostras brutas: bit0=pronto
0x19 CAPTURE_PAGE 1 u8 rw ram Página 0..15 → 16 amostras I0 brutas em CAPTURE_WINDOW
0x1A CAPTURE_WINDOW 32 bytes r ram 16×u16 LE códigos I0 pré-LUT. Leitura em rajada de 32 bytes.

4.3 Sistema (0x20..0x25)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x20 AC_FREQ 1 u8 r ram Com origem em ZC. 50 ou 60 Hz, inteiro. O ZC está ativo em todas as variantes (incluindo I*)
0x21 AC_PERIOD 2 u16 LE r ram Meio período da rede, µs
0x23 CALIBRATION 1 u8 r ram Byte de estado de calibração legado
0x24 TOPOLOGY 1 u8 r rom Número de canais de corrente (= V03_N_I): 1, 2 ou 3; 5 = UI5, 7 = UI7
0x25 SENSOR_CLASS 1 u8 rw user_config 0 = UNSET, 1 = SCT_013, 2 = WIRED_CT (série de pinças CT, modelos 1..13: 1..5 legado; emparelhadas de fábrica nos SKU CT- — no firmware 1.4.22 e posteriores o módulo recusa escritas de classe e modelo em funcionamento normal com ERR_PARAM (0xFE); as bibliotecas cliente recusam-nas em todos os firmwares), 3 = BUILTIN_CT (calibração própria de fábrica por unidade, código de modelo não usado). Uma alteração de classe repõe CT_MODEL = 0. Não é um discriminador de variante (veja §3.4)
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::setSensorClass(cls) / RbAmp::readSensorClass(out) definir a classe do sensor; ler de volta
ESP-IDF rbamp_set_sensor_class() / rbamp_read_sensor_class() definir a classe do sensor; ler de volta
Python dev.set_sensor_class(cls) / dev.read_sensor_class() definir a classe do sensor; ler de volta
ESPHome sensor_class: Opção YAML que fixa a classe do sensor

4.4 Configuração da frota (0x27..0x2F)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x27 FLEET_CONFIG 1 u8 rw user_config bit0 = GC_ENABLE (receção de instantâneos General-Call; efetivo após reinício). bits 1-7 reservados
0x28 GROUP_ID 1 u8 rw user_config Filtro de grupo do instantâneo GC. 0 = responde a todas as chamadas. O byte de grupo da trama GC tem de coincidir ou ser 0x00
0x29 DIGEST_CONFIG 1 u8 rw ram Máscara de composição da janela de digest (ver §4.9); escrever um bit não suportado → ERR_PARAM. Predefinido em 0x00 (digest desativado) após reset; reescreva em cada inicialização
0x2A EVENT_FLAGS 1 u8 w1c ram Bits de evento persistentes (ver §5.3 modelo de erros). Predefinido em 0x00 após reset (mas o bit5 RESET_OCCURRED fica ativo no arranque)
0x2B EVENT_MASK 1 u8 rw ram Quais os bits de EVENT_FLAGS que mantêm DRDY a LOW de forma fixa
0x2C THRESH_I_HI 2 u16 LE rw ram Limiar de corrente → EVENT_FLAGS.THRESH_I. Unidades: 0.01 A. 0xFFFF = desativado
0x2E THRESH_P_HI 2 u16 LE rw ram Limiar de potência → EVENT_FLAGS.THRESH_P. Unidades: W. 0xFFFF = desativado
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::enableGc(enable) / RbAmp::setEventThresholds(i_amps, p_watts) ativar o General Call num módulo; definir os limiares de corrente e de potência
ESP-IDF rbamp_enable_gc() / rbamp_set_event_thresholds() ativar o General Call num módulo; definir os limiares de corrente e de potência
Python dev.enable_gc(enable=True) / dev.read_event_flags() ative a Chamada Geral num módulo; leia os sinalizadores de evento (sem setter de limiar do dispositivo)
ESPHome fleet_gc_enable: / group_id: Opções YAML para adesão ao General Call e ID de grupo

4.5 Endereço (0x30..0x31)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x30 I2C_ADDRESS 1 u8 rw user_config Confirmação em duas fases: escreva o candidato 0x08..0x77 → registo de preparação em RAM; arme ADDR_COMMIT_MAGIC; depois CMD_COMMIT_ADDR; é aplicado após reinício. No arranque lê-se de volta o endereço ativo (v1.3 Correção 4)
0x31 ADDR_COMMIT_MAGIC 1 u8 w ram Escreva 0xA5 para armar CMD_COMMIT_ADDR. Consumido (limpo) na tentativa de confirmação. As leituras devolvem 0x00

Veja §6.1 para a sequência.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::prepareAddressChange(new_addr) / RbAmp::readActiveAddress(out) preparar e armar o novo endereço; ler o endereço ativo
ESP-IDF rbamp_prepare_address_change() / rbamp_read_active_address() preparar e armar o novo endereço; ler o endereço ativo
Python dev.prepare_address_change(new_addr) / dev.commit_address_change() defina e arme o novo endereço, depois confirme-o
ESPHome new_address: alteração de endereço única no arranque; remova a opção depois

4.6 Saúde / diagnóstico (0x46..0x4F)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x46 UPTIME_S 4 u32 LE r ram Contador de uptime próprio do módulo (nominalmente segundos desde o arranque) — apenas detetor de reinício: nos firmwares até 1.4.21 corre mais devagar do que o relógio de parede (medido 0.58–0.80×), por isso nunca o use como relógio. Deteção de reinício para um mestre: o valor diminuiu, ou é menor do que o tempo decorrido desde o instantâneo anterior do mestre
0x4A RESET_CAUSE 1 u8 r ram Indicadores de motivo de reset (bit0=PIN, bit1=POR/BOR, bit2=SW, bit3=IWDG, bit4=WWDG, bit5=LPWR). Apenas para registo — o tratamento do reinício é o mesmo qualquer que seja a causa
0x4B I2C_ERR_COUNT 2 u16 LE r ram Erros de barramento (BERR+OVR) desde o arranque, com saturação
0x4D I2C_REINIT_COUNT 1 u8 r ram Contagem de recuperações de BUSY do periférico I²C, com saturação
0x4E ZC_OFFSET 2 u16 LE r ram µs desde a última aresta STOP do instantâneo GC até ao próximo cruzamento por zero de tensão — usado para a compensação de fase U/I no cálculo de potência. Forçado pelo firmware a 0xFFFF nas variantes só de corrente (sem front-end de tensão → sem ZC de tensão). Isto não é a fonte de ZC da frequência da rede — AC_FREQ (0x20) deriva de um pino dedicado de ZC da rede e está disponível em todas as variantes.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino — Registos de saúde do BASIC não expostos (apenas a linha STD)
ESP-IDF rbamp_read_uptime_s() ler o tempo de funcionamento do módulo em segundos
Python — Registos de saúde do BASIC não expostos (apenas a linha STD)
ESPHome — sem entidade de tempo de funcionamento ou de estado

4.7 Espelhos de verificação do modelo de CT (0x51..0x53)

Espelhos só de leitura da predefinição de modelo de CT aplicada por canal. O protocolo de escrita mantém-se inalterado (veja §6.2) — trata-se apenas de uma leitura de retorno para verificação.

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x51 CT_MODEL_CH0 1 u8 r user_config Predefinição do modelo de CT aplicado no ch0 (espelho de verificação)
0x52 CT_MODEL_CH1 1 u8 r user_config Predefinição do modelo de CT aplicado no ch1
0x53 CT_MODEL_CH2 1 u8 r user_config Predefinição de modelo de TC aplicada no ch2
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readCTModelCh(channel, out) leia o modelo de TC efetivamente aplicado num canal
ESP-IDF rbamp_read_ct_model_ch() leia o modelo de TC efetivamente aplicado num canal
Python dev.read_ct_model_ch(ch) leia o modelo de TC efetivamente aplicado num canal
ESPHome registo de arranque ct_model[0]: matches linhas de registo a confirmar que a classe do sensor e o modelo foram aplicados

4.8 Identidade (0x54..0x6F)

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x54 PRODUCT_ID 1 u8 r rom Família: 0x01 = sensor rbAmp. O mestre lê isto antes de qualquer registo específico da família
0x55 HW_VARIANT 1 u8 r rom Ver §3.1
0x56 FW_TIER 1 u8 r rom bits 0-1: 0=BASIC, 1=STANDARD (2 = não implementado); bit 2=bidirecional; bit 3=calibrado por LUT
0x57 CAPABILITY 2 u16 LE r rom Ver §3.2
0x59 GC_TICK 2 u16 LE r ram Marca de tempo do mestre da última trama GC aceite; 0xFFFF = nunca recebida
0x5C UID 12 bytes r rom UID de chip de 96 bits. Uma leitura em rajada.
0x68 LABEL 8 bytes rw user_config Etiqueta de localização do utilizador (ASCII, preenchida com zeros à direita). Vazio = não definido. Escreva byte a byte (veja §5.1)
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readProductId() / RbAmp::readUid(uid) ler o id da família; ler o UID de 96 bits
ESP-IDF rbamp_read_product_id() / rbamp_read_uid() ler o id da família; ler o UID de 96 bits
Python dev.read_product_id() / dev.read_uid() ler o id da família; ler o UID de 96 bits
ESPHome get_uid_hex() / get_variant_str() o UID em hexadecimal; a variante como texto

4.9 Janela de resumo (0x70..0x85)

DIGEST é uma janela de consulta compacta, servida por uma única leitura em rajada. A sua composição é selecionada por DIGEST_CONFIG (0x29); uma escrita que ative um bit não suportado é rejeitada com ERR_PARAM:

bit de DIGEST_CONFIG Conteúdo Formato
bit 0 I_RMS[N] u16 por canal, 0.01 A
bit 1 U_RMS u16, 0.1 V (apenas HW de tensão)
bit 2 P_REAL[N] i16 por canal, 1 W (apenas has_power)
bit 3 PF[N] u8 por canal, 0..100 (apenas has_power)
Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x70 DIGEST 22 bytes r ram Layout: [STATUS_MIRROR u8][SEQ u8] + campos ativados por máscara. A carga máxima (máscara completa do UI3) é 19 B + 2 B de cabeçalho = 21 B usados; 1 B de cauda não usado (lê 0x00). SEQ incrementa por confirmação RT, dando a volta de 255→0. Atómico através de read-freeze (veja §5.4).

O layout é dinâmico conforme DIGEST_CONFIG — cada bit ativo acrescenta os seus campos numa ordem fixa: I_RMS[N] → U_RMS → P[N] → PF[N]. Os bits desativados não deixam espaço — os campos avançam. O mestre tem de analisar com a mesma máscara que escreveu em DIGEST_CONFIG. Uma leitura em rajada de 22 bytes é segura (a cauda é 0x00 sempre que a carga total seja < 22 bytes). O byte de cauda é sempre 0x00 (reservado).

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino — janela de resumo não exposta
ESP-IDF rbamp_set_digest_fields() / rbamp_read_digest() escolha os campos de digest; leia-os numa única transação (BASIC)
Python — janela de resumo não exposta
ESPHome — janela de resumo não exposta

4.10 Bloco de tempo real V03 (0x86..0xBD)

Todos float32 LE (IEEE 754 precisão simples, ordem de bytes little-endian padrão). O layout byte a byte está congelado desde a v1.2. Cada registo é acesso r, persistência ram, grupo v03_rt. Atómico via congelamento de leitura (ver §5.4): uma leitura em rajada de 56 bytes (0x86..0xBD) é garantidamente contígua (sem instantâneo partido).

Endereço Nome Tamanho Tipo Acesso Persistência Unidades Notas
0x86 V03_U_RMS 4 float32 LE r ram V 0.0 nas variantes I
0x8A V03_U_PEAK 4 float32 LE r ram V
0x8E V03_I0_RMS 4 float32 LE r ram A
0x92 V03_I1_RMS 4 float32 LE r ram A 0.0 se a variante não tiver ch1
0x96 V03_I2_RMS 4 float32 LE r ram A 0.0 se a variante não tiver ch2
⛔ PARAR — o RMS plano por canal termina no canal 2. A linha seguinte (0x9A) é V03_I0_PEAK, NÃO V03_I3_RMS. NÃO extrapole o padrão do passo 4 para além do canal 2 — obterá números plausíveis mas silenciosamente errados (pico, não RMS; ch0, não ch3). Os canais 3+ (UI5/UI7) são acedidos apenas através da janela de acesso aos canais — veja §4.14.
0x9A V03_I0_PEAK 4 float32 LE r ram A
0x9E V03_I1_PEAK 4 float32 LE r ram A
0xA2 V03_I2_PEAK 4 float32 LE r ram A
0xA6 V03_P0_REAL 4 float32 LE r ram W 0.0 nas variantes I (sem cálculo de potência)
0xAA V03_P1_REAL 4 float32 LE r ram W
0xAE V03_P2_REAL 4 float32 LE r ram W
0xB2 V03_PF0 4 float32 LE r ram – intervalo −1..+1
0xB6 V03_PF1 4 float32 LE r ram –
0xBA V03_PF2 4 float32 LE r ram –
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readAll(snapshot) / RbAmp::channels() leia o bloco de tempo real completo; número de canais de corrente
ESP-IDF rbamp_read_all() / rbamp_channels() leia o bloco de tempo real completo; número de canais de corrente
Python dev.read_all() / dev.channels leia o bloco de tempo real completo; número de canais de corrente
ESPHome voltage / power Sensores YAML para os valores em tempo real

4.11 Bloco de período V03 (0xBE..0xCF)

Instantâneo de período tirado em CMD_LATCH_PERIOD. Layout irregular (legado histórico da v1.2, congelado na v1.3): o avg_p de ch1/ch2 está aqui, enquanto o avg_p de ch0 está na §4.12 no endereço 0xDC (a primitiva de energia legada não foi realocada, para não quebrar a API dos integradores existentes). Logicamente, estes três valores pertencem ao mesmo grupo.

Endereço Nome Tamanho Tipo Acesso Persistência Unidades Notas
0xBE V03_PERIOD_COMMIT_CNT 4 u32 LE r ram – Confirmações RT no período fechado. Uma confirmação = 0.1 s a partir da v1.2 (0.2 s antes) — contagem × o comprimento da confirmação é a medida, do lado do módulo, do comprimento da janela (veja §7.4)
0xC2 V03_PERIOD_AVG_P_CH1 4 float32 LE r ram W Média instantânea de P, canal 1 (UI2, UI3)
0xC6 V03_PERIOD_AVG_P_CH2 4 float32 LE r ram W Média instantânea de P, canal 2 (UI3)
0xCA V03_PERIOD_MS 4 u32 LE r ram ms Duração do período atual
0xCE V03_STATUS 1 u8 r ram – bit 0 = válido (resultado do commit RT). NÃO é limpo ao ler. O mestre consulta STATUS (0x00) para aguardar o estado pronto. O alias DATA_VALID é por vezes usado para este registo nos capítulos de tutorial — mesmo endereço, mesma semântica.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodSnapshot() leia a potência média do período; tire e leia um instantâneo de período completo
ESP-IDF rbamp_read_period_avg_power() / rbamp_read_period_snapshot() leia a potência média do período; tire e leia um instantâneo de período completo
Python dev.read_period_avg_power(ch) / dev.read_period_snapshot() leia a potência média do período; tire e leia um instantâneo de período completo
ESPHome update_interval: / latch_interval: Opções YAML para o período e a cadência do instantâneo

4.12 V03 Q + período ch0 (0xD0..0xE3, versão de produção)

Endereço Nome Tamanho Tipo Acesso Persistência Unidades Notas
0xD0 V03_Q0_REAC 4 float32 LE r ram VAr Potência reativa ch0 = √(S² − P²), S = U_rms × I_rms — sem sinal (≥ 0), inclui a potência de distorção; 0 nas variantes só-I; ruidosa perto de FP ≈ 1. Exatidão não especificada
0xD4 V03_Q1_REAC 4 float32 LE r ram VAr
0xD8 V03_Q2_REAC 4 float32 LE r ram VAr
0xDC V03_PERIOD_AVG_P 4 float32 LE r ram W Primitivo de energia de PRODUÇÃO: instantâneo de P média ch0, ≥ 0 (pinça unidirecional BASIC). Agrupado logicamente com V03_PERIOD_AVG_P_CH1/CH2 (§4.11); o layout legado é mantido por compatibilidade
0xE0 V03_PERIOD_MAX_P 4 float32 LE r ram W Pico de P ch0 máximo neste período
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() ler a média e o máximo de potência do período
ESP-IDF rbamp_read_period_avg_power() / rbamp_read_period_max_power() ler a média e o máximo de potência do período
Python dev.read_period_avg_power(ch) / dev.read_period_max_power() ler a média e o máximo de potência do período
ESPHome reactive_power / update_interval: sensor de potência reativa; cada atualização fecha o período e lê as médias

4.13 dt de diagnóstico do lado do circuito integrado (0xEC)

Endereço Nome Tamanho Tipo Acesso Persistência Unidades Notas
0xEC V03_PERIOD_LATCH_MS 4 u32 LE r ram ms dt do lado do circuito integrado entre os dois instantâneos mais recentes. Temporizador de diagnóstico do módulo — pode ler curto sob carga; use o relógio do mestre para a energia. Veja §7.4
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodLatchMs() ler o comprimento do período do lado do módulo (apenas diagnóstico)
ESP-IDF rbamp_read_period_latch_ms() ler o comprimento do período do lado do módulo (apenas diagnóstico)
Python dev.read_period_latch_ms() ler o comprimento do período do lado do módulo (apenas diagnóstico)
ESPHome — não exposto

4.14 Janela de acesso a canais (0x32 + 0x3C..0x3F)

Aplica-se aos módulos UI5 (5 canais) e UI7 (7 canais). Nos UI1/UI2/UI3 e I1/I2/I3 também está disponível — um caminho unificado se preferir a §4.10 de registos planos.

Os canais 3..6 não têm registos planos por canal (havia espaço para 8 bytes no espaço de endereços de 8 bits, e um layout plano precisaria de ~88). Em vez disso é exposta uma janela de seleção e leitura:

Endereço Nome Tamanho Tipo Acesso Persistência Notas
0x32 REG_CHANNEL_SELECT 1 u8 rw ram Este é um endereço de registo, NÃO o opcode de comando CMD_SAVE_USER_CONFIG — colidem numericamente. Cite sempre 0x32 indicando o espaço de registo ou de comando a que se refere. Codificado como (field << 4) \| channel. O nibble channel tem a gama 0..15 (reservado para até 16 canais); o máximo físico por SKU é channels() (7 no UI7). Um seletor cujo índice de canal seja >= channels() é aceite sem ERR_PARAM; a janela de dados lê então 0 e as escritas para ela são ignoradas. field conforme a tabela abaixo. Escrever o seletor copia o valor pedido para REG_CHANNEL_DATA.
0x3C..0x3F REG_CHANNEL_DATA 4 float32 LE r ram Buffer de dados para a seleção. float32 LE para todos os campos públicos.

Códigos de campo (nibble alto em 0x32):

Código Campo Tipo Acesso Significado
0 CHFIELD_I_RMS float32 LE r Corrente RMS em tempo real do canal selecionado (unidade A)
1 CHFIELD_I_PEAK float32 LE r Corrente de pico em tempo real (unidades A)
2 CHFIELD_P_REAL float32 LE r Potência real em tempo real (unidade W)
3 CHFIELD_PF float32 LE r Fator de potência em tempo real (−1..+1)
4..12 (reserved) – – Não documentado para código do utilizador; não dependa de valores ou códigos.
13 CHFIELD_PERIOD_AVG_P float32 LE r Potência real média do período (W) do instantâneo. Para os canais 3+ este é o ÚNICO campo de período/energia — os registos planos V03_PERIOD_AVG_P* (§4.11/§4.12) cobrem apenas ch0..ch2.
14 (reserved) – – Reservado para firmware futuro; não dependa dele.
15 CHFIELD_CT_MODEL u8 em 0x3C (os bytes 0x3D..0x3F são lidos como preenchimento a zero) rw Firmware ≥ 1.4.18. Código do modelo de CT por canal para o canal selecionado (0..N-1). A leitura devolve o modelo aplicado no canal. A escrita é apenas em RAM e aplica-se de imediato: a escala do canal passa para a predefinição do modelo selecionado na mesma transação; não há comando de confirmação separado nem é preciso CMD_SET_CT_MODEL_CH*. As escritas são feitas byte a byte, conforme a regra do protocolo (§5.1). Um par (SENSOR_CLASS, code) desconhecido devolve ERR_PARAM (0xFE) e o canal mantém o modelo anterior — sem estado parcial. Os canais das referências superiores (ch3+) JÁ NÃO herdam o modelo global — cada canal tem de ser configurado explicitamente através do campo 15. Persistência: CMD_SAVE_USER_CONFIG (opcode 0x32 em REG_COMMAND, sem restrição) grava os modelos de todos os canais na página flash de configuração do utilizador num único comando. Uma escrita sem um CMD_SAVE_USER_CONFIG posterior reverte no reinício. O conjunto de pares (class, code) aceites é definido pela tabela de modelos da versão de firmware; o módulo confirma de forma autoritativa um código — escreva-o, leia-o de volta e verifique REG_ERROR. Nos módulos com firmware v1.4.0, escrever este campo devolve ERR_PARAM; use os comandos por canal + o registo de preparação plano REG_CT_MODEL.

As quatro armadilhas — leia isto antes de escrever código

  1. ⛔ O RMS plano por canal termina no canal 2. As linhas V03_I0_RMS (0x8E) → V03_I1_RMS (0x92) → V03_I2_RMS (0x96) têm passo 4, e 0x9A continua o passo — mas 0x9A é V03_I0_PEAK, não V03_I3_RMS. Extrapolar o padrão devolve silenciosamente o pico do ch0 em vez do RMS do ch3. O firmware não consegue detetar o erro; o valor parece plausível. Os canais 3+ existem apenas na janela de acesso a canais.
  2. Volte a selecionar antes de cada leitura. REG_CHANNEL_DATA é um instantâneo tirado no momento da escrita do seletor, e não uma vista em tempo real. Fazer polling de 0x3C..0x3F num ciclo sem voltar a escrever 0x32 devolve um valor congelado para sempre. Cada leitura nova exige uma nova escrita em 0x32.
  3. 0x32 endereço de registo ≠ 0x32 opcode de comando. CMD_SAVE_USER_CONFIG usa o opcode 0x32 escrito em REG_COMMAND (0x01) — que é um espaço de endereços diferente de REG_CHANNEL_SELECT (que está no endereço de registo 0x32). Nunca cite 0x32 sem dizer a que espaço se refere.
  4. Para os canais 3+ o período/energia vem apenas do campo 13 (CHFIELD_PERIOD_AVG_P). Os registos V03_PERIOD_AVG_P* (0xC2/0xC6/0xDC) cobrem apenas ch0/ch1/ch2. Não existe um V03_PERIOD_AVG_P_CH3 plano — leia o campo 13 através da janela.

Exemplo ao nível do fio — ler a corrente RMS do canal 3

Text
# select field=0 (I_RMS), channel=3  →  (0 << 4) | 3  =  0x03
write_u8(REG_CHANNEL_SELECT=0x32, 0x03)

# read 4 bytes at REG_CHANNEL_DATA — float32 LE
bytes = read(0x3C, 4)
i3_rms = unpack_float32_le(bytes)   # amperes

Para a corrente de pico do canal 4: seletor = (1 << 4) | 4 = 0x14, depois leia 0x3C..0x3F. Para a potência média do período do canal 5: seletor = (13 << 4) | 5 = 0xD5, depois leia 0x3C..0x3F.

Exemplo ao nível do fio — ler a corrente RMS em TODOS os canais de um módulo UI7

Combina os dois caminhos num só ciclo: bloco RT plano para os canais 0..2, janela de acesso aos canais para os canais 3..6.

Text
# --- Discover physical channel count -----------------------------
N = read_u8(TOPOLOGY=0x24)      # 5 on UI5, 7 on UI7

# --- ch 0..2 via flat block (single 12-byte burst) ---------------
bytes = read(V03_I0_RMS=0x8E, 12)
i0 = unpack_float32_le(bytes[0:4])
i1 = unpack_float32_le(bytes[4:8])
i2 = unpack_float32_le(bytes[8:12])

# --- ch 3..N-1 via channel access window (re-select per read) ----
i_rms = [i0, i1, i2]
for ch in range(3, N):
    write_u8(REG_CHANNEL_SELECT=0x32, (0 << 4) | ch)   # field 0 = I_RMS
    i_rms.append(unpack_float32_le(read(REG_CHANNEL_DATA=0x3C, 4)))

# i_rms is now length-N: RMS current for every physical channel of the module.

O mesmo padrão estende-se a I_PEAK (campo 1), P_REAL (campo 2), PF (campo 3) e ao instantâneo PERIOD_AVG_P (campo 13) — bloco plano para ch0..ch2, janela para ch3+. O campo 13 é a ÚNICA fonte de período/energia para ch3+ — o bloco plano não tem V03_PERIOD_AVG_P_CH3..6.

Para a configuração do modelo de TC por canal em qualquer canal (0..N-1), use o campo de janela 15 (CHFIELD_CT_MODEL): escreva (15 << 4) | ch em 0x32, depois escreva o código do modelo como um byte em 0x3C. Persista os modelos de todos os canais com um único CMD_SAVE_USER_CONFIG (opcode 0x32 em REG_COMMAND (0x01) — sem restrição).

Recomendação para novas integrações

A janela cobre os canais 0..6 — pode usá-la como um caminho unificado para todos os canais, em vez de ramificar entre registos planos (ch0..ch2) e a janela (ch3..ch6). Para frotas que misturam SKUs júnior (UI1/UI2/UI3) e sénior (UI5/UI7), isto elimina a divisão de código. A latência é uma pequena escrita extra por leitura (comparada com uma leitura em rajada direta do bloco plano).

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readCurrent(ch) / RbAmp::channels() ler qualquer canal por índice; número de canais
ESP-IDF rbamp_read_channel() / rbamp_read_all_channels() ler um canal por índice, incluindo os canais 3 e superiores; ler todos os canais
Python dev.current[ch] / dev.channels índice sobre os canais válidos; número de canais
ESPHome current_N: slots de sensor por canal para até sete canais de corrente

5 · Protocolo de fios

5.1 Assimetria de LEITURA / ESCRITA

As leituras em rajada incrementam automaticamente, enquanto as escritas de vários bytes são feitas um byte de cada vez.

Comportamento canónico por desenho:

Direção Auto-incremento Padrão
LEITURA (leitura em rajada de N bytes) ✅ SIM read(addr, N) devolve N bytes consecutivos a partir de addr.
ESCRITA (registos de vários bytes) ❌ NÃO Um registo multi-byte é escrito byte a byte — uma transação separada de um único byte por endereço. Uma escrita em rajada perde os bytes 1..N-1 e aceita apenas o primeiro.

Registos graváveis multi-byte afetados (escrever byte a byte)

  • LABEL (0x68-0x6F, 8 bytes)
  • THRESH_I_HI (0x2C, 2 bytes u16 LE)
  • THRESH_P_HI (0x2E, 2 bytes u16 LE)

Ordem dos bytes em escritas de vários bytes: o byte no endereço mais baixo é o byte menos significativo (LE). Por exemplo, para escrever THRESH_I_HI = 0x1234 (4660 em decimal):

Text
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34)   # LO byte
write(addr=0x2D, value=0x12)   # HI byte

Exemplo ERRADO / CORRETO (pseudocódigo)

Text
# WRONG — only 'M' (first byte) is accepted, the rest are dropped
write(addr=0x50, reg=0x68, data=b"MyMeter1")   # 8-byte burst

# CORRECT — byte-at-a-time loop
label = b"MyMeter1"
for i, byte in enumerate(label):
    write(addr=0x50, reg=0x68 + i, data=byte)

Exceção — trama de difusão GC

A trama de broadcast GC (endereço general-call 0x00 + payload de 5 bytes) é um caminho de protocolo de fios separado, não uma escrita de registo. A assimetria leitura/escrita de §5.1 não se aplica ao GC. Veja §6.3.

5.2 Comportamento de registos não mapeados

Qualquer leitura de um endereço não mapeado devolve 0x00. O firmware nunca responde com NACK às leituras de registos. Isto é intencional (correção de bloqueio).

Implicação para a deteção: a deteção de um dispositivo em falta tem de passar pelo ACK da trama de endereço I²C, não por sondagens de registos.

5.3 Modelo de erros

Canónico v1.3:

  • REG_ERROR (0x02) é o resultado da última escrita, NÃO persistente. Em cada escrita de registo o firmware põe reg_error = ERR_OK; qualquer escrita não relacionada seguinte limpa o erro anterior.
  • EVENT_FLAGS (0x2A) bit 3 é o sinal durável (W1C persistente), ativado em qualquer escrita ou comando rejeitado.

Códigos de erro

Código Nome Gravidade
0x00 OK –
0xF9 CLONE reservado — não é levantado
0xFA LUT_BAD erro
0xFB FLASH_PARAMS_BAD erro (ver §6.5 gravação nova)
0xFC NOT_READY erro
0xFD SENSOR_OVERFLOW erro
0xFE PARAM erro (escrita rejeitada — argumento inválido / opcode desconhecido / enum fora de gama; ativa EVENT.bit3. Imagens muito antigas, 1.2–1.4.3, ignoravam opcodes desconhecidos em silêncio)
0xFF UNHANDLED erro

Layout de EVENT_FLAGS (0x2A) (persistente W1C)

bit Nome Notas
0 PERIOD_READY instantâneo de período disponível
1 THRESH_I I_rms ultrapassou THRESH_I_HI
2 THRESH_P A soma P ultrapassou THRESH_P_HI
3 ERROR REG_ERROR != 0 (sinal de erro durável)
4 CONFIG_CHANGED classe/modelo/endereço/etiqueta alterados
5 RESET_OCCURRED módulo reiniciado (definido no arranque até W1C). O mestre tem de voltar a inicializar a configuração em RAM.

Padrões de erro canónicos

Padrão 1 — captura pontual após a operação (resultado exatamente dessa operação):

Text
write target_reg(...)
err = read_u8(0x02)   # IMMEDIATELY after the operation, before the next write

Padrão 2 — monitorização durável (canónico para um mestre de funcionamento prolongado):

Text
event_flags = read_u8(0x2A)
if event_flags & (1 << 3):    # ERROR bit
    last_err = read_u8(0x02)
    # handle
    write_u8(0x2A, 1 << 3)    # W1C clear bit 3
    # or CMD_CLEAR_ERROR

⚠ ressalva sobre o bit 3 assíncrono

Uma rejeição de escrita ativa EVENT_FLAGS.bit3 de forma assíncrona, dentro de uma janela de medição (~100 ms a partir da v1.2; 200 ms nas imagens anteriores à v1.2) após a operação, e não de imediato. Não faça polling do bit 3 logo após uma escrita — ou espere ≥ 200 ms (cobre todas as imagens), ou use o Padrão 1 (captura imediata de REG_ERROR) para o resultado de uma operação específica, reservando o polling do bit 3 para monitorização de longa duração.

Sentinela anti-clone

DEV_ERR_CLONE (0xF9) é reservado — nunca é ativado. O código é mantido por compatibilidade futura.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readLastError() / RbAmp::hasError(out) ler o código de erro da última escrita; ler o indicador de erro durável
ESP-IDF rbamp_read_last_error() / rbamp_has_error() ler o código de erro da última escrita; ler o indicador de erro durável
Python dev.read_last_error() / dev.has_error() ler o código de erro da última escrita; ler o indicador de erro durável
ESPHome get_last_error_str() / get_event_flags() o código de erro como texto; os sinalizadores de evento

5.4 Semântica de atomicidade / congelamento de leitura

5.4.1 Congelamento de leitura presente (atómico — NÃO partido)

Estes blocos são protegidos pelo read-freeze do firmware. Uma leitura em rajada é atómica em relação à confirmação RT:

  • Bloco RMS / P / PF V03 (0x86..0xBD) — o bloco completo em float.
  • Bloco de resumo (0x70..0x85).

As leituras em rajada destes intervalos são seguras — não há amostra partida entre dois commits consecutivos.

Estes registos são atualizados de forma assíncrona, sem congelamento durante a leitura. As leituras de um byte são tolerantes, mas o valor pode mudar entre transações:

  • GC_TICK (0x59) — contador de ticks da GC.
  • I2C_ADDRESS (0x30) — espelho do registo de preparação em RAM.
  • CT_MODEL_CH0/1/2 (0x51..0x53) — espelhos de verificação.

Padrão para leituras fiáveis:

Text
val1 = read_u8(addr)
val2 = read_u8(addr)
if val1 == val2:
    return val1   # stable
else:
    retry          # value changed between reads

5.4.3 Semântica da pinça NF

I_RMS = 0x00000000 significa "sinal abaixo do limiar de ruído" (o firmware calcula rms_corr² = max(0, raw² − nf²)), NÃO "sem dados" / "erro". É uma medição válida para cenários sem carga ou com carga muito baixa.

O código do mestre não deve interpretar I_RMS = 0.0 como erro ou dados em falta.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readAll(snapshot) ler todo o bloco em tempo real numa só chamada
ESP-IDF rbamp_read_all() ler todo o bloco em tempo real numa só chamada
Python dev.read_all() ler todo o bloco em tempo real numa só chamada
ESPHome leitura em rajada do bloco instantâneo o componente lê o bloco instantâneo numa rajada por atualização

6 · Sequências de protocolo

6.0 Cronologia do arranque a frio

Após POR (reinício na ligação) ou reinício físico, o módulo passa pelas seguintes fases:

Tempo desde POR Estado
0 ms POR — todos os registos em estado de reinício, SCL/SDA em alta impedância
~10 ms Responde ao barramento (o módulo faz ACK ao seu endereço)
~50 ms Primeiro commit RT (o bloco RT a partir de 0x86 tem dados válidos; STATUS.bit0 = 1)
~60-80 ms Primeiro V03_STATUS.bit0 válido (o pipeline RT percorreu um período completo da rede)
~100 ms A primeira CMD_LATCH_PERIOD pode devolver V03_PERIOD_VALID = 1 (o instantâneo exige ≥ 1 período da rede de acumulação; ~200 ms nas imagens anteriores à v1.2)
~250 ms Todas as medições estáveis (típico)
Nota

Arranque a frio completo até à primeira medição válida ≈ 250 ms (típico). Após um CMD_RESET suave a cronologia é idêntica (corre a máquina de estados de reset completa).

Sequência de inicialização do mestre:

Text
1. wait ~50 ms after VCC stable
2. probe slave address (read PRODUCT_ID = 0x54); retry up to 300 ms on NACK
3. read identity (HW_VARIANT 0x55, CAPABILITY 0x57/0x58); validate
4. check REG_ERROR (0x02):
   - 0x00 — normal boot
   - 0xFB — fresh flash, provisioning required (§6.5)
   - other — see §6.7 error-state recovery
5. configure (SENSOR_CLASS, CT_MODEL, FLEET_CONFIG, etc.)
6. poll STATUS (0x00) until bit0 = 1 (READY) — usually immediate after step 5
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::begin() / RbAmp::waitReady(timeout_ms) sondar o módulo, depois aguardar o sinalizador de pronto
ESP-IDF rbamp_begin() / rbamp_wait_ready() sondar o módulo, depois aguardar o sinalizador de pronto
Python dev.begin() / dev.wait_ready(timeout_ms=1000) sondar o módulo, depois aguardar o sinalizador de pronto
ESPHome rbamp: address: endereço do módulo definido no YAML; o componente sonda o módulo na configuração

6.1 Alteração de endereço — confirmação em duas fases (compatível com produção)

Protocolo de barramento (v1.3 canónico):

Text
1. write candidate_addr (1 byte) → REG_I2C_ADDRESS (0x30)   # RAM staging, not persisted
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31)                # arm commit
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)        # persists into flash
4. wait ~700 ms (flash write completion; see §6.6 settle)
5. issue CMD_RESET (opcode 0x01)                             # module resets
6. wait ~300 ms boot-to-responsive
7. verify: bus-probe the new address (ACK = success)
Nota

: CMD_COMMIT_ADDR NÃO reinicia automaticamente o módulo — é necessário um CMD_RESET explícito no passo 5. Se o mestre omitir o reinício explícito, o novo endereço fica guardado na flash, mas o endereço antigo continua ativo até ao próximo reinício externo (corte de alimentação, pino de reinício físico, IWDG).

Guarantees:

  • A alteração de endereço funciona em modo de produção (não está restrita à fábrica).
  • REG_I2C_ADDRESS (0x30) no arranque lê o endereço ativo (canónico v1.3). Até reiniciar após a preparação, ecoa o candidato.
  • O endereço é excluído do espaço de nomes de CMD_SAVE_GAINS / CMD_SAVE_USER_CONFIG — só é persistido através de CMD_COMMIT_ADDR.

Temporização da janela de arranque para a verificação:

  • Mínimo de 300 ms entre o arranque e a resposta.
  • Janela de repetição no novo endereço: ~1 s no total (se um NACK persistir após 1–2 repetições, pode ser necessário um atraso de arranque adicional).
  • Quando o novo endereço responder com ACK, opcionalmente verifique lendo 0x30 (que já reflete o novo endereço ativo) para confirmação.

Modos de falha:

  • ADDR_COMMIT_MAGIC não armado → CMD_COMMIT_ADDR → REG_ERROR = ERR_PARAM (0xFE).
  • Candidato fora do intervalo (< 0x08 ou > 0x77) → ERR_PARAM.
  • Timeout de 5 s sem commit → o magic é limpo; o passo prepare tem de ser repetido.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() defina e arme o novo endereço, depois confirme-o
ESP-IDF rbamp_prepare_address_change() / rbamp_commit_address_change() defina e arme o novo endereço, depois confirme-o
Python dev.prepare_address_change(new_addr) / dev.commit_address_change() defina e arme o novo endereço, depois confirme-o
ESPHome new_address: alteração de endereço única no arranque; remova a opção depois

6.2 Associação do modelo de CT — preparação pura + CMD por canal

Nota

Em imagens anteriores ao fw 1.4.20 (CAPABILITY bit 12 a zero) a escala aplicada por modelo volta à predefinição de fábrica após um reinício do módulo — prepare e confirme de novo CT_MODEL em cada canal após cada reinício detetado, ou a energia ficará errada.

Staging puro canónico da v1.3: escrever REG_CT_MODEL (0x05) já não aplica automaticamente a predefinição em ch0. A vinculação acontece apenas através de CMD_SET_CT_MODEL_CHn.

Protocolo canónico por canal (independente da ordem na v1.3):

Text
1. write REG_SENSOR_CLASS (0x25) = sct013    # if not already set
2. write REG_CT_MODEL (0x05) = model_code     # stages, applies nothing
3. issue CMD_SET_CT_MODEL_CHn (opcode 0x28/0x29/0x2A for ch0/1/2)
   # VALIDATES (class, model) + binds to channel n
4. wait 5 ms settle
5. (optional) issue CMD_SAVE_USER_CONFIG (opcode 0x32) for persistence

Independente da ordem: na v1.3 os canais podem ser configurados em qualquer ordem — ch0 primeiro, por último, o que for mais conveniente. A solução "ligar ch0 por último" da v1.2 já não é necessária.

Verificação por leitura de retorno: após a associação, leia CT_MODEL_CH0/1/2 (0x51..0x53) — estes refletem o estado aplicado por canal.

Modos de falha (a validação de (classe, modelo) acontece no passo de vinculação CMD_SET_CT_MODEL_CHn, não na escrita de staging puro em 0x05):

  • SENSOR_CLASS = 0 (NÃO DEFINIDO) quando CMD_SET_CT_MODEL_CHn é emitido → REG_ERROR = ERR_PARAM.
  • CT_MODEL fora de 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) em CMD_SET → ERR_PARAM.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) definir a classe do sensor e o modelo de CT por canal
ESP-IDF rbamp_set_sensor_class() / rbamp_set_ct_model_ch() definir a classe do sensor e o modelo de CT por canal
Python dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) definir a classe do sensor e o modelo de CT por canal
ESPHome sensor_class: / ct_model: Opções YAML para a classe do sensor e o modelo de CT

6.3 Instantâneo por broadcast GC — sincronização de frota por adesão

Ativação por módulo através de REG_FLEET_CONFIG.bit0 (GC_ENABLE). Por defeito OFF. A alteração fica efetiva após reinício (CMD_RESET por software ou reinício físico).

6.3.1 Sequência de ativação (uma vez por módulo)

Text
1. write REG_FLEET_CONFIG (0x27) = 0x01    # bit0 = GC_ENABLE
2. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
3. issue CMD_RESET (opcode 0x01)
4. wait ~300 ms boot
5. verify: read REG_FLEET_CONFIG → bit 0 should be 1

6.3.2 Formato da trama GC

Text
I²C general-call address 0x00 | A5 27      (5-byte payload)
  • A5 — magic da trama.
  • 27 — opcode CMD_LATCH_PERIOD.
  • — 0x00 = all-call; caso contrário tem de coincidir com o REG_GROUP_ID (0x28) do dispositivo.
  • — contador de tick de 16 bits do lado do mestre (para numeração de janelas em toda a frota e deteção de tramas perdidas por módulo através de GC_TICK (0x59)).

Apenas instantâneo: as tramas GC não transportam opcodes destrutivos (SAVE_*, COMMIT_ADDR, FACTORY_RESET, etc.) por desenho.

6.3.3 Deteção de modos de falha — 2 níveis

Nível 1 — NACK do endereço GC (imediato, ao nível do barramento):

  • Se a GC estiver desativada em toda a frota → o mestre recebe um erro duro (NACK no endereço 0x00, ou o equivalente do lado do driver).
  • Este é um erro duro, NÃO uma perda silenciosa — o mestre pode detetá-lo e reagir.
  • Disparo: NACK na GC = "a GC não está ativada em nenhum dispositivo da frota."

Nível 2 — testemunha por módulo (após estabilização):

  • Se não houver NACK (pelo menos um módulo estiver a escutar), o mestre lê REG_V03_PERIOD_VALID (0x07) de cada escravo esperado.
  • 1 = o instantâneo teve êxito nesse módulo.
  • 0 = o GC está desativado nesse módulo específico, ou o período atual está vazio.

Recorra ao instantâneo por dispositivo se a testemunha reportar 0:

Text
foreach module where witness == 0:
    write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() envie a trama de instantâneo de Chamada Geral; verifique cada módulo
ESP-IDF rbamp_fleet_gclatch() / rbamp_fleet_check_sync() envie a trama de instantâneo de Chamada Geral; verifique cada módulo
Python fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) envie a trama de instantâneo de Chamada Geral; verifique cada módulo
ESPHome fleet_gc_enable: / registo de verificação de sincronização instantâneo de Chamada Geral opcional; linha de registo a confirmar que os módulos estão sincronizados

6.4 Sincronização de período — duas estratégias

Estratégia 1 — instantâneo sequencial + estabilização partilhada (qualquer firmware)

Text
for module in modules:
    write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
for module in modules:
    read_period_snapshot(module)   # skip_latch=true

Desvio entre módulos: ~1 ms por módulo a 50 kHz. Em 16 módulos, relativamente a um período de 60 segundos, isso dá 0.027 %. Negligenciável para a contabilização tarifária.

Janela de estabilização após CMD_LATCH_PERIOD:

  • Mínimo de 50 ms antes de ler V03_PERIOD_VALID (0x07) ou o instantâneo do período — isto cobre a latência de instantâneo no pior caso (1 período da rede a 50 Hz = 20 ms + commit RT + estabilização do periférico I²C).
  • Opcionalmente, o mestre pode consultar STATUS.bit0 (READY) em vez de uma pausa fixa: READY=1 significa que o bloco RT está num estado consistente, pelo que o instantâneo do período pode ser lido em rajada com segurança.
  • Num módulo novo (< ~100 ms após o arranque a partir da v1.2; < 200 ms antes) um instantâneo pode devolver V03_PERIOD_VALID = 0 porque ainda não se acumulou 1 período da rede — ver §6.0 cronologia do arranque a frio.

Estratégia 2 — instantâneo de difusão por Chamada Geral (requer ativação)

Desvio = 0 (atómico ao nível do barramento). Ver §6.3.

Quando usar cada um:

  • < 8 módulos: Estratégia 1 (mais simples, não requer ativação).
  • ≥ 8 módulos ou sincronização apertada: Estratégia 2.
  • Um método por módulo: o CMD_LATCH_PERIOD endereçado e o instantâneo broadcast GC repõem o mesmo acumulador único — misturá-los num módulo encurta o período em curso. O recurso por módulo (§6.3.3) é seguro porque só dispara num módulo que o broadcast não alcançou.
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodSnapshot(..., skip_latch=true) / RbAmpFleet::gcLatch() leitura sequencial após um instantâneo partilhado; trama de instantâneo General Call
ESP-IDF rbamp_read_period_snapshot(..., skip_latch=true) / rbamp_fleet_gclatch() leitura sequencial após um instantâneo partilhado; trama de instantâneo General Call
Python instantâneo sequencial, skip_latch=True / fleet.gc_latch() leitura sequencial após um instantâneo partilhado; trama de instantâneo General Call
ESPHome latch_interval: / fleet_gc_enable: cadência de instantâneo separada; instantâneo de Chamada Geral opt-in

6.5 Aprovisionamento — gravação nova + SAVE

Comportamento de um módulo recém-gravado:

  • No primeiro arranque após a gravação do firmware: REG_ERROR = 0xFB (FLASH_PARAMS_BAD) + EVENT_FLAGS.bit3 ativo.
  • A página de parâmetros não está inicializada → são carregadas as predefinições de fábrica.

Isto é NORMAL num módulo virgem e não é fatal. Não interrompa o aprovisionamento com um 0xFB no primeiro arranque.

Recovery:

Text
1. configure SENSOR_CLASS + CT_MODEL (per §6.2)
2. (optional) configure FLEET_CONFIG + GROUP_ID + LABEL
3. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
4. wait ~700 ms (flash write)
5. verify: REG_ERROR = 0x00, EVENT_FLAGS.bit3 cleared
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmpFleet::provision() / RbAmp::saveUserConfig() mover um módulo virgem para o seu endereço; gravar a configuração do utilizador
ESP-IDF rbamp_provision() / rbamp_save_user_config() mover um módulo virgem para o seu endereço; gravar a configuração do utilizador
Python provisionamento de frota / dev.save_user_config() aprovisione um módulo virgem, depois acrescente-o à frota; guarde a configuração do utilizador
ESPHome Fluxo de provisionamento / new_address: passo a passo em YAML para um módulo virgem; alteração de endereço única

6.7 Recuperação de estado de erro — árvore de decisão

Se no arranque ou em execução STATUS.bit1 (ERROR) = 1 ou o sinal durável EVENT_FLAGS.bit3 (ERROR) estiver ativo, o mestre lê REG_ERROR (0x02) e decide com base no código:

Text
read REG_ERROR (0x02):

  0x00  → no error (false signal — clear stale EVENT bit3 via W1C)
         action: write 1<<3 → EVENT_FLAGS (W1C clear)

  0xF9  → CLONE (reserved)
         action: not raised. If ever observed, treat as
                 vendor-reserved and contact the supplier.

  0xFA  → LUT_BAD (calibration LUT corrupted)
         action: device unusable for measurement. Factory recovery required.

  0xFB  → FLASH_PARAMS_BAD (params page uninitialized — virgin module)
         action: NORMAL for a freshly flashed module. Provision per §6.5
                 (configure SENSOR_CLASS/CT_MODEL/...; issue CMD_SAVE_USER_CONFIG).
                 Cleared after a successful SAVE.

  0xFC  → NOT_READY (transient; module still booting)
         action: wait 50 ms, retry. If persistent > 300 ms — power cycle.

  0xFD  → SENSOR_OVERFLOW (transient; signal saturated)
         action: physical overload detected. The chosen CT clamp has
                 insufficient range for the measured current, or a real overload.
                 Issue CMD_CLEAR_ERROR (0x31) after the cause is removed.

  0xFE  → PARAM (last operation rejected — invalid argument / unknown opcode;
                 EVENT bit3 set. Very early images, 1.2–1.4.3, ignored unknown
                 opcodes silently)
         action: master-side bug — review the last write. Issue CMD_CLEAR_ERROR
                 after fixing the master logic.

  0xFF  → UNHANDLED (firmware-side anomaly)
         action: open an issue with the vendor; CMD_CLEAR_ERROR attempts to clear.
                 If persistent after CMD_RESET — the device is suspect.

Fluxo geral de recuperação para erros transitórios (0xFC/0xFD/0xFE):

Text
1. capture context (what was the last write? master state?)
2. issue CMD_CLEAR_ERROR (opcode 0x31)
3. wait 5 ms
4. re-read STATUS / REG_ERROR — verify cleared

Para erros persistentes — emita CMD_RESET e percorra a cronologia do arranque a frio (§6.0). Se o erro persistir após o reset e não for 0xFB (gravação nova) — contacte o suporte do fornecedor.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readLastError() / RbAmp::clearError() leia o código de erro; limpe-o
ESP-IDF rbamp_read_last_error() / rbamp_clear_error() leia o código de erro; limpe-o
Python dev.read_last_error() / dev.clear_error() leia o código de erro; limpe-o
ESPHome write_clear_error() / write_reset() limpar o erro; reinício por software do módulo

6.6 Referência de comandos

Opcodes principais (escrever em REG_COMMAND (0x01))

Opcode Nome Estabilização Restrito Notas
0x01 RESET ~300 ms – Reset por software (HAL_NVIC_SystemReset)
0x27 LATCH_PERIOD 50 ms – Copiar os contadores RT para o instantâneo do período
0x28 SET_CT_MODEL_CH0 5 ms – Associar o REG_CT_MODEL preparado ao ch0
0x29 SET_CT_MODEL_CH1 5 ms – Associar o REG_CT_MODEL preparado ao canal 1
0x2A SET_CT_MODEL_CH2 5 ms – Associar o REG_CT_MODEL preparado ao canal 2
0x30 COMMIT_ADDR 700 ms – Gravar I2C_ADDRESS (veja §6.1)
0x31 CLEAR_ERROR 0 – Limpar REG_ERROR (apenas classes transitórias; CLONE (0xF9) está reservado, não é gerado)
0x32 SAVE_USER_CONFIG 700 ms – Gravar o grupo user_config (compatível com produção)
Nota

Os opcodes fora do intervalo público (uso de fábrica) não estão documentados nesta referência. Um mestre consumidor não os envia em funcionamento normal; um opcode não suportado → REG_ERROR = ERR_PARAM (0xFE).


7 · Semântica

7.0 Resistência da flash e comportamento no reinício

Nota

Lembrete: antes do fw 1.4.20, um reinício também reverte a escala do modelo de CT aplicada para o valor de fábrica (CAPABILITY bit 12 a zero) — veja §6.2.

Resistência da flash: ~10 000 ciclos por página (típico, especificação do fabricante). Cada CMD_SAVE_USER_CONFIG ou CMD_COMMIT_ADDR é um ciclo de apagamento+escrita na página de parâmetros.

Segurança

⚠ Não faça loop de SAVE/COMMIT num ciclo de execução. A 1 SAVE/s um módulo fica inutilizado em cerca de 3 horas. A configuração é feita uma vez na instalação; não são necessárias atualizações de configuração em execução (um mestre de consumidor raramente as altera).

Retenção: tipicamente 10+ anos à temperatura de funcionamento típica.

Comparação do comportamento no reinício:

Tipo de reset Preservado Limpo
CMD_RESET (0x01) flash (configuração, endereço, label, ganhos, NF) RAM (UPTIME, ZC_OFFSET, EVENT_FLAGS — exceto o bit RESET_OCCURRED 5 ativo no arranque; THRESH_*; DIGEST_CONFIG)
Ciclo de alimentação / pino de reset físico flash o mesmo que CMD_RESET, mais qualquer RAM externa mantida no lado do anfitrião
CMD_FACTORY_RESET (0xAA) (apenas modo de fábrica) nada tudo — o bloco de parâmetros completo, incluindo a calibração de fábrica dos canais
Segurança

⚠ CMD_FACTORY_RESET não é um "repor predefinições" ao nível do utilizador. Reescreve todo o bloco de parâmetros, incluindo a calibração de fábrica dos canais, e o módulo só o aceita em modo de fábrica — é uma operação de fabrico, não um passo de assistência. Um módulo BASIC não tem comando de reposição pelo utilizador. Para levar um módulo a um estado conhecido, use CMD_RESET (0x01) (reinício por software: nada na flash é alterado) e volte a configurar as definições do utilizador com CMD_SAVE_USER_CONFIG (0x32).

Padrão de bits de RESET_OCCURRED (canónico):

  • Após um reset, no arranque: EVENT_FLAGS.bit5 = 1.
  • O mestre vê o bit 5 → sabe que o módulo reiniciou → tem de reinicializar os campos apenas em RAM (DIGEST_CONFIG, THRESH_*, EVENT_MASK).
  • O mestre limpa o bit 5 via W1C: escrever 1<<5 → EVENT_FLAGS.

7.1 Modelo de persistência

Comando Produção Persiste
CMD_SAVE_USER_CONFIG (0x32) ✅ OK i2c_address (via duas fases), ct_model, sensor_class, fleet_config, group_id, label
CMD_COMMIT_ADDR (0x30) ✅ OK (armado por magic) i2c_address
CMD_RESET (0x01) ✅ OK — (reinício por software)
CMD_LATCH_PERIOD (0x27) ✅ OK — (captura o instantâneo do período)
CMD_CLEAR_ERROR (0x31) ✅ OK — (limpa REG_ERROR)
CMD_SAVE_GAINS (0x26) ❌ BLOQUEADO em produção (rejeitado: REG_ERROR = 0xFE; o reinício reverte) calibração de fábrica
CMD_FACTORY_RESET (0xAA) ❌ BLOQUEADO em produção —

7.2 Leitura de volta ≠ persistência

⚠ A proteção de produção aceita a escrita na RAM (uma leitura posterior devolve o valor escrito), mas a gravação em flash pode ser rejeitada. Após o reinício o valor reverte para o estado anterior à escrita.

A única forma válida de confirmar a persistência é CMD_RESET + espera do arranque + nova leitura:

Text
1. write target_reg(...)
2. issue CMD_RESET (0x01)
3. wait ~300 ms boot
4. re-read target_reg
5. assert read == written     # only now is persistence confirmed

O endereço é uma exceção (v1.3 canónico): REG_I2C_ADDRESS (0x30) no arranque lê o endereço ativo. Depois da preparação ecoa o candidato; após reinício mostra o valor efetivamente persistido.

7.3 Ressalva sobre a referência de tensão única

O módulo usa um canal U para calcular P em todos os canais I. Se uma pinça CT estiver num fio de outra fase (quadro de distribuição multifásico), as leituras de P desse canal estarão erradas (desfasamento U/I arbitrário). I_RMS continua correto.

A medição multifásica (L1/L2/L3 em simultâneo) é um SKU separado com especificação própria.

7.4 Integração de energia do mestre — cânone do relógio de parede

⚠ V03_PERIOD_LATCH_MS (0xEC) é um temporizador de diagnóstico do módulo; pode ler curto sob carga — use o relógio do mestre para a energia.

Integração canónica de energia do mestre:

Text
# CORRECT — master wall-clock
t_now = master_clock()
dt_s = (t_now - t_prev_latch) / time_unit
energy_wh[ch] += avg_p[ch] * dt_s / 3600
t_prev_latch = t_now

# WRONG — the module diagnostic timer may read short under load
dt_chip_s = read_u32(0xEC) / 1000.0
energy_wh[ch] += avg_p[ch] * dt_chip_s / 3600    # systematically under-reported

A medida do lado do módulo da janela fechada é V03_PERIOD_COMMIT_CNT (0xBE) vezes o comprimento do commit — conta commits RT completos e não é afetada pela falta de tempo do temporizador que faz V03_PERIOD_LATCH_MS ler baixo. Um commit = 0.1 s a partir da v1.2; as imagens mais antigas usavam 0.2 s. Para saber qual se aplica sem uma tabela de versões: o rácio V03_PERIOD_LATCH_MS / V03_PERIOD_COMMIT_CNT dá próximo de 100 ou próximo de 200. Use-o para verificações cruzadas; o relógio de parede do mestre continua a ser a referência para a contabilização tarifária.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::energyWh(ch) total Wh acumulado de um canal
ESP-IDF rbamp_energy_wh() total Wh acumulado de um canal
Python dev.energy.wh(ch) total Wh acumulado de um canal
ESPHome energy Contador de Wh por canal

7.5 Preservação do período de instantâneo falhado

O firmware PRESERVA o acumulador do período num instantâneo vazio. Quando g_period_count == 0 (um instantâneo sem período legível):

  • REG_V03_PERIOD_VALID = 0 (sinal desatualizado).
  • period_start_ms é preservado → o instantâneo seguinte bem-sucedido cobre o intervalo completo pretendido pelo mestre.

Implicação: o mestre não perde dados com um instantâneo desatualizado. Padrão para a integração do mestre:

Text
issue snapshot
if PERIOD_VALID == 1:
    integrate(avg_p, master_dt)
    reset_master_clock
# else: skip integration (FW will automatically recover on the next success)
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readPeriodSnapshot() / RbAmp::isPeriodValid() tire um instantâneo do período e integre apenas quando for válido; verifique o bit de pronto
ESP-IDF rbamp_read_period_snapshot() / rbamp_is_period_valid() tire um instantâneo do período e integre apenas quando for válido; verifique o bit de pronto
Python dev.read_period_snapshot() / RbAmpStaleError tira um instantâneo do período; levantado quando o instantâneo não está pronto, o seguinte cobre o intervalo completo
ESPHome Instantâneo do período inválido registado quando o sinalizador de validade é 0; o primeiro instantâneo após o arranque é descartado

7.6 Tolerância à deriva do relógio

Cânone: a base de tempo interna do módulo pode ler curto sob carga até 30 % — isto é normal, uma propriedade da base de tempo do módulo, por desenho. Medido em hardware sob carga de produção.

Aceitação: o circuito integrado está OK com deriva ≤ 30 %.

⚠ O limiar antigo de 3 % está ERRADO. Esse limiar rejeitaria em massa chips saudáveis.

7.7 Resiliência a EMI / transitórios de comutação

As leituras durante a comutação ativa de relés (EMI de 5 A) falham ~67 % das vezes (medido em hardware). As leituras em regime estável são fiáveis. O barramento recupera sozinho, não há bloqueio, nenhum módulo se perde.

Padrão do mestre — repetição ao nível da aplicação (obrigatório ao comutar cargas indutivas):

Text
for attempt in range(5):
    result = read_register(...)
    if result is OK:
        return result
    sleep(20 ms)
raise IOError("read failed after retries")

Um bus_reset apenas do lado do mestre não basta quando um glitch EMI se sobrepõe à janela de repetição do driver.


7.8 Resumo das limitações conhecidas

Lista consolidada das características conhecidas que o mestre deve ter em conta:

Tema Comportamento Ver
Desvio do temporizador do chip Pode ler baixo sob carga, até 30 % (envelope de aceitação) §7.4, §7.6
Comutação de relés (EMI) ~67 % de falhas de leitura durante a comutação; o barramento recupera sozinho §7.7
Latência assíncrona de EVENT.bit3 até uma janela (~100 ms; 200 ms antes da v1.2) desde a rejeição da escrita até o bit 3 ser ativado §5.3
V03_PERIOD_LATCH_MS (0xEC) Temporizador de diagnóstico do módulo; pode ler curto sob carga — o mestre usa o seu próprio relógio de parede §4.13, §7.4
Semântica de REG_ERROR (0x02) Resultado da última escrita (não persistente); bit 3 de EVENT = sinal durável §5.3
I_RMS = 0.0 Abaixo do limiar de ruído (medição válida), NÃO "sem dados" §5.4.3
U_RMS/U_PEAK/P nas variantes I Lido como 0.0 (válido apenas se o bit 8 de CAPABILITY = 1) §4.10, §7.3
Escrita de vários bytes Sem auto-incremento; é necessário um ciclo byte a byte §5.1
Verificação da alteração de endereço Através de uma pesquisa no barramento no novo endereço; 0x30 também é fiável após o reinício §6.1
Arranque com flash nova REG_ERROR = 0xFB é normal; o SAVE limpa-o §6.5
GC por defeito OFF (opt-in por módulo); NACK na GC = "não ativado" §6.3
Resistência da flash ~10 000 ciclos/página; não faça loop de SAVE §7.0

8 · Exemplos de traçado no barramento

8.1 Deteção — ler PRODUCT_ID + HW_VARIANT + CAPABILITY

Text
# I²C operations on default slave addr 0x50
S 0xA0 W 0x54 Sr 0xA1 R [PRODUCT_ID]  P     # read 0x54
S 0xA0 W 0x55 Sr 0xA1 R [HW_VARIANT]  P     # read 0x55
S 0xA0 W 0x57 Sr 0xA1 R [CAP_lo][CAP_hi] P  # burst-read 0x57..0x58 (auto-increment)

Onde S=start, Sr=start repetido, P=stop, W=bit de escrita, R=bit de leitura, 0xA0=endereço de escravo 0x50 << 1.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readVariant() / RbAmp::readCapability(out) ler a variante de hardware; ler o mapa de capacidades
ESP-IDF rbamp_read_variant() / rbamp_read_capability() ler a variante de hardware; ler o mapa de capacidades
Python dev.read_variant() / dev.read_capability() ler a variante de hardware; ler o mapa de capacidades
ESPHome get_variant_str() / get_capability_hex() a variante em texto; o mapa de funcionalidades em hexadecimal

8.2 Leitura em rajada do bloco RT (variante UI, todos os canais)

Text
# Read all of V03 RMS + P + PF (0x86..0xBD) — 56 bytes, atomic via read-freeze
S 0xA0 W 0x86 Sr 0xA1 R [56 bytes] P
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readAll(snapshot) ler todo o bloco em tempo real numa só chamada
ESP-IDF rbamp_read_all() ler todo o bloco em tempo real numa só chamada
Python dev.read_all() ler todo o bloco em tempo real numa só chamada
ESPHome leitura em rajada do bloco instantâneo o componente lê o bloco instantâneo numa rajada por atualização

8.3 Escrita de vários bytes — LABEL byte a byte

Text
# WRONG: burst-write — only 'M' is accepted
S 0xA0 W 0x68 'M' 'y' 'M' 'e' 't' 'e' 'r' '1' P

# CORRECT: byte-at-a-time loop
S 0xA0 W 0x68 'M' P
S 0xA0 W 0x69 'y' P
S 0xA0 W 0x6A 'M' P
S 0xA0 W 0x6B 'e' P
S 0xA0 W 0x6C 't' P
S 0xA0 W 0x6D 'e' P
S 0xA0 W 0x6E 'r' P
S 0xA0 W 0x6F '1' P
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::writeLabel(label) / RbAmp::readLabel(out) escreva o label de 8 bytes (apenas BASIC); leia-o de volta
ESP-IDF rbamp_write_label() / rbamp_read_label() escrever a etiqueta de 8 caracteres; ler de volta
Python dev.set_label(label) / dev.read_label() escreva o label de 8 bytes; leia-o de volta
ESPHome — opção de label não documentada

Instantâneo de difusão GC (8.4) com recurso de testemunha (witness)

Text
# Send GC frame: A5 27  
S 0x00 W 0xA5 0x27 0x00 0x2A 0x00 P

# Wait 50 ms settle

# Witness check for every expected module
foreach module in [0x50, 0x51, 0x52]:
    S (module<<1)|W 0x07 Sr (module<<1)|R [VALID] P
    if VALID != 1:
        # Fall back to per-device snapshot
        S (module<<1)|W 0x01 0x27 P    # CMD_LATCH_PERIOD
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() envie a trama de instantâneo de Chamada Geral; verifique cada módulo
ESP-IDF rbamp_fleet_gclatch() / rbamp_fleet_check_sync() envie a trama de instantâneo de Chamada Geral; verifique cada módulo
Python fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) envie a trama de instantâneo de Chamada Geral; verifique cada módulo
ESPHome fleet_gc_enable: / registo de verificação de sincronização instantâneo de Chamada Geral opcional; linha de registo a confirmar que os módulos estão sincronizados

8.5 Alteração de endereço em 5 passos

Text
# 1. Stage candidate addr (0x51) → REG_I2C_ADDRESS
S 0xA0 W 0x30 0x51 P

# 2. Arm magic → ADDR_COMMIT_MAGIC
S 0xA0 W 0x31 0xA5 P

# 3. Issue CMD_COMMIT_ADDR (opcode 0x30) → REG_COMMAND
S 0xA0 W 0x01 0x30 P

# 4. Wait 700 ms flash write

# 5. Issue CMD_RESET (opcode 0x01) → REG_COMMAND
S 0xA0 W 0x01 0x01 P

# Wait ~300 ms boot

# Verify: probe the new addr
S 0xA2 W 0x55 Sr 0xA3 R [HW_VARIANT] P   # 0xA2 = 0x51 << 1
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() defina e arme o novo endereço, depois confirme-o
ESP-IDF rbamp_prepare_address_change() / rbamp_commit_address_change() defina e arme o novo endereço, depois confirme-o
Python dev.prepare_address_change(new_addr) / dev.commit_address_change() defina e arme o novo endereço, depois confirme-o
ESPHome new_address: alteração de endereço única no arranque; remova a opção depois

8.6 Aprovisionamento após gravação nova

Text
# 1. Check fresh-flash state
S 0xA0 W 0x02 Sr 0xA1 R [0xFB] P   # ERR_FLASH_PARAMS_BAD — normal

# 2. Configure sensor_class
S 0xA0 W 0x25 0x01 P    # SCT_013

# 3. Stage CT model + bind ch0
S 0xA0 W 0x05 0x03 P    # SCT-013-030
S 0xA0 W 0x01 0x28 P    # CMD_SET_CT_MODEL_CH0
# Wait 5 ms

# 4. Save user_config
S 0xA0 W 0x01 0x32 P    # CMD_SAVE_USER_CONFIG
# Wait 700 ms

# 5. Verify: REG_ERROR should be 0x00 (read IMMEDIATELY before the next write)
S 0xA0 W 0x02 Sr 0xA1 R [0x00] P
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::configureChannels(cls, models, n) / RbAmp::saveUserConfig() definir a classe e todos os modelos de canal; guardar a configuração do utilizador
ESP-IDF rbamp_configure_channels() / rbamp_save_user_config() definir a classe e todos os modelos de canal; guardar a configuração do utilizador
Python dev.configure_channels(cls, models) / dev.save_user_config() definir a classe e todos os modelos de canal; guardar a configuração do utilizador
ESPHome sensor_class: / ct_model: Opções YAML para a classe do sensor e o modelo de CT

8.7 DIGEST ida e volta — configurar + ler

Text
# 1. Configure digest mask: I_RMS + U_RMS + P_REAL (bits 0+1+2 = 0x07)
S 0xA0 W 0x29 0x07 P

# 2. Wait one RT-commit cycle (~100 ms from v1.2; waiting 200 ms covers all images; or poll STATUS.bit0)

# 3. Burst-read the digest window (22 bytes)
S 0xA0 W 0x70 Sr 0xA1 R [22 bytes] P

# Parse the layout per DIGEST_CONFIG = 0x07 on UI1 (N_I = 1):
#   byte[0]   = STATUS_MIRROR
#   byte[1]   = SEQ
#   byte[2..3]  = I_RMS[0] u16 (0.01 A units)
#   byte[4..5]  = U_RMS u16 (0.1 V units)
#   byte[6..7]  = P[0] i16 (1 W units)
#   byte[8..21] = unused (0x00)
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino — janela de resumo não exposta
ESP-IDF rbamp_set_digest_fields() / rbamp_read_digest() escolha os campos de digest; leia-os numa única transação (BASIC)
Python — janela de resumo não exposta
ESPHome — janela de resumo não exposta

8.8 Fluxo de eventos de limiar — escrever limiar → disparo → limpeza W1C

Text
# 1. Write current threshold = 30 A (0x0BB8 in 0.01 A units → 2 bytes LE)
S 0xA0 W 0x2C 0xB8 P    # LO byte
S 0xA0 W 0x2D 0x0B P    # HI byte

# 2. Unmask THRESH_I event (bit 1) → DRDY solid-LOW on trip
S 0xA0 W 0x2B 0x02 P    # EVENT_MASK = bit 1 only

# 3. (runtime) The master polls EVENT_FLAGS
S 0xA0 W 0x2A Sr 0xA1 R [event_flags] P
# event_flags == 0x02 → threshold tripped

# 4. (optional) Read context — REG_ERROR, RT block, etc.

# 5. Clear EVENT_FLAGS.bit1 via W1C
S 0xA0 W 0x2A 0x02 P
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::setEventThresholds(i_amps, p_watts) / RbAmp::readEventFlags(out) definir os limiares de corrente e de potência; ler e limpar os sinalizadores de evento
ESP-IDF rbamp_set_event_thresholds() / rbamp_read_event_flags() definir os limiares de corrente e de potência; ler e limpar os sinalizadores de evento
Python dev.read_event_flags() ler e limpar os indicadores de evento (sem setter de limiar no dispositivo)
ESPHome Alarmes de limiar em YAML / get_event_flags() automatismos de limiar sobre os valores dos sensores; os indicadores de evento

8.9 Rajada de diagnóstico de captura bruta (CAPTURE_*)

CMD_CAPTURE_RAW (0x38) e os registos CAPTURE_* são uma facilidade de diagnóstico — não são necessários em funcionamento normal; use apenas quando o fornecedor pedir a captura de amostras brutas.

Text
# 1. Arm raw-capture
S 0xA0 W 0x01 0x38 P     # CMD_CAPTURE_RAW (opcode 0x38)
# Wait ~80 ms (3 DMA-TC cycles)

# 2. Check ready
S 0xA0 W 0x18 Sr 0xA1 R [status & 0x01] P   # bit 0 = ready

# 3. Select page 0 (16 raw I0 samples → CAPTURE_WINDOW)
S 0xA0 W 0x19 0x00 P

# 4. Burst-read CAPTURE_WINDOW (32 bytes = 16×u16 LE samples)
S 0xA0 W 0x1A Sr 0xA1 R [32 bytes] P

# Repeat steps 3-4 for pages 1..15 (256 samples total ≈ 1.3 mains periods)

8.10 Leitura de retorno do espelho de verificação do modelo de CT (sanidade pós-associação)

Text
# After the §6.2 sequence — verify the applied state per channel via 0x51..0x53 (burst):
S 0xA0 W 0x51 Sr 0xA1 R [model_ch0][model_ch1][model_ch2] P

# Expected on UI2 mixed-CT (e.g. ch0=SCT-013-005, ch1=SCT-013-030):
#   byte[0] = 0x01   # SCT-013-005 applied on ch0
#   byte[1] = 0x03   # SCT-013-030 applied on ch1
#   byte[2] = 0x00   # unused (UI2 N_I=2)
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::readCTModelCh(channel, out) leia o modelo de TC efetivamente aplicado num canal
ESP-IDF rbamp_read_ct_model_ch() leia o modelo de TC efetivamente aplicado num canal
Python dev.read_ct_model_ch(ch) leia o modelo de TC efetivamente aplicado num canal
ESPHome registo de arranque ct_model[0]: matches linhas de registo a confirmar que a classe do sensor e o modelo foram aplicados

9 · Aceitação / tolerância

Parâmetro Limiar Fonte
Deriva do relógio do chip vs relógio de parede do mestre ≤ 30 % validado em bancada
Taxa de falhas de leitura na comutação de relés (EMI) até ~67 % durante a comutação validado em bancada
Taxa de NACK do barramento (Linux/ESP I²C a 100 kHz sem repetição) até ~20 % característica do lado do anfitrião
Taxa de NACK no barramento @ 50 kHz + 3× repetição < 0.8 % validado em bancada
Valor de REG_ERROR no arranque com flash nova 0xFB (FLASH_PARAMS_BAD) NORMAL num módulo virgem
Arranque a frio até à primeira medição válida ~250 ms típico

10 · Registo de alterações

1.3.0 (2026-06-15) — Primeira versão pública.

Firmware de referência: protocol_version = 1.3, schema_version = 2. Contrato da página 0 congelado.

Principais alterações da v1.3 face às versões internas anteriores

  • Preparação pura do CT_MODEL: REG_CT_MODEL (0x05) já não se aplica automaticamente ao ch0 na escrita. A associação faz-se apenas através de CMD_SET_CT_MODEL_CHn (independente da ordem).
  • Confirmação do endereço em duas fases (compatível com produção): o I2C_ADDRESS é persistido através de ADDR_COMMIT_MAGIC + CMD_COMMIT_ADDR. REG_I2C_ADDRESS lê o endereço ativo no arranque.
  • REG_ERROR = resultado da última escrita (não persistente). EVENT_FLAGS.bit3 é o sinal durável (persistente W1C; ativa-se dentro de uma janela, ~100 ms, após a rejeição da escrita).
  • Opcodes desconhecidos / enums fora de gama → rejeitados: REG_ERROR = ERR_PARAM (0xFE) + EVENT.bit3. Imagens muito antigas (1.2–1.4.3) ignoravam opcodes desconhecidos em silêncio.
  • Provisionamento com flash nova: ERR_FLASH_PARAMS_BAD (0xFB) num módulo virgem → limpo através de CMD_SAVE_USER_CONFIG.
  • Instantâneo por broadcast GC — ativação por módulo através de FLEET_CONFIG.bit0 (por defeito OFF; efetivo após reinício). NACK com a funcionalidade desativada = erro grave, não silencioso.
  • Assimetria leitura/escrita por desenho: a LEITURA com auto-incremento ✅; a ESCRITA byte a byte é obrigatória ❌ (confirmado em hardware).
  • Registo CAPABILITY (0x57/0x58 u16 LE): mapa de funcionalidades em bits — detete as funcionalidades bit a bit (§3.2), nunca comparando o valor completo; bit 12 = SCT_RATING_SELF (fw 1.4.20+).
  • Atomicidade: o bloco RMS V03 + Digest têm congelamento de leitura (leitura em rajada atómica); os espelhos GC_TICK / I2C_ADDRESS / CT_MODEL_CHn são lidos duas vezes e têm de coincidir.
  • Semântica da pinça NF: I_RMS = 0.0 significa "abaixo do limiar de ruído", uma medição válida.
  • AC_FREQ com origem em ZC em todas as variantes (incluindo só-I).
  • A integração de energia do mestre deve usar o seu próprio relógio de parede, não V03_PERIOD_LATCH_MS (0xEC) (temporizador de diagnóstico do módulo — pode ler baixo sob carga).

Fim do documento.