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.
: 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 |
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 semtBUF) 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.
— 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:
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
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
— 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.
— 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
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
— 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.
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..0x1Asão diagnóstico de produção, ver §4.2).0x36..0x3B,0x40..0x45— página 0 reservada (0x32+0x3C..0x3Fsã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 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) |
— 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) |
— 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 |
— 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.
— 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. |
— 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 |
— 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) |
— 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).
— 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 | – |
— 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. |
— 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 |
— 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 |
— 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
- ⛔ 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, e0x9Acontinua o passo — mas0x9AéV03_I0_PEAK, nãoV03_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. - 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 de0x3C..0x3Fnum ciclo sem voltar a escrever0x32devolve um valor congelado para sempre. Cada leitura nova exige uma nova escrita em0x32. 0x32endereço de registo ≠0x32opcode de comando.CMD_SAVE_USER_CONFIGusa o opcode0x32escrito emREG_COMMAND(0x01) — que é um espaço de endereços diferente deREG_CHANNEL_SELECT(que está no endereço de registo0x32). Nunca cite0x32sem dizer a que espaço se refere.- Para os canais 3+ o período/energia vem apenas do campo
13(CHFIELD_PERIOD_AVG_P). Os registosV03_PERIOD_AVG_P*(0xC2/0xC6/0xDC) cobrem apenas ch0/ch1/ch2. Não existe umV03_PERIOD_AVG_P_CH3plano — leia o campo 13 através da janela.
Exemplo ao nível do fio — ler a corrente RMS do canal 3
# 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.
# --- 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).
— 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
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):
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34) # LO byte
write(addr=0x2D, value=0x12) # HI byte
Exemplo ERRADO / CORRETO (pseudocódigo)
# 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õereg_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):
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):
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.
— 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.
5.4.2 Sem read-freeze — recomendado read-twice-agree
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:
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.
— 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) |
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:
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
— 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):
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)
: 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 deCMD_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_MAGICnã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
preparetem de ser repetido.
— 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
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):
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) quandoCMD_SET_CT_MODEL_CHné emitido →REG_ERROR = ERR_PARAM.CT_MODELfora de 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) emCMD_SET→ERR_PARAM.
— 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)
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
I²C general-call address 0x00 | A5 27 (5-byte payload)
A5— magic da trama.27— opcodeCMD_LATCH_PERIOD.—0x00= all-call; caso contrário tem de coincidir com oREG_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 deGC_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:
foreach module where witness == 0:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
— 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)
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=1significa 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 = 0porque 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_PERIODendereç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.
— 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.bit3ativo. - 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:
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
— 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:
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):
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.
— 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) |
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
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.
⚠ 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 |
⚠ 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:
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:
# 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.
— 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:
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)
— 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):
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
# 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.
— 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)
# 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
— 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
# 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
— 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)
# 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
— 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
# 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
— 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
# 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
— 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
# 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)
— 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
# 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
— 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.
# 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)
# 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)
— 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 deCMD_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 deADDR_COMMIT_MAGIC+CMD_COMMIT_ADDR.REG_I2C_ADDRESSlê 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 deCMD_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.0significa "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).