rbAmp
PT
Loja
Docs
Atualizado

02 · Inicialização e arranque

O rbAmp começa a medir imediatamente após ligar. O mestre só precisa de:

  1. Ative o barramento I²C (inicialização padrão de Wire / HAL).
  2. Aguarde ~250 ms, ou consulte DATA_VALID = 1 no registo 0xCE.
  3. Opcionalmente, leia a versão do firmware em 0x03 como verificação de sanidade.
  4. Dados de leitura — prontos.

Não é necessário nenhum comando de arranque nem configuração ao nível de registo no chip. A calibração de fábrica é carregada automaticamente no arranque, pelo que o módulo emite valores em unidades físicas corretas desde a primeira leitura.

A sequência desde a ligação até à primeira leitura válida.

Nota

Importante para os módulos BASIC da série SCT usados com sensores SCT-013: após a primeira instalação, tem de escrever o modelo do sensor no registo de modelo. O módulo precisa do modelo para aplicar o coeficiente mV-por-ampere correto. O código do modelo fica guardado na flash e sobrevive a reinícios. Nos firmwares anteriores a 1.4.20 (CAPABILITY bit 12 a zero) a escala aplicada volta à predefinição de fábrica após um reinício do módulo — um mestre que selecionou um modelo não original tem de voltar a confirmá-lo após cada reinício detetado do módulo (ver O que persiste após um reinício e a regra de deteção de reinício em period-metering.md); a partir do fw 1.4.20 a troca de modelo sobrevive a um reinício. Nas imagens anteriores a 1.4.20, a energia fica errada após qualquer reinício do módulo, a não ser que CT_MODEL seja reconfirmado. As bibliotecas cliente tratam ambos os casos por si. Os detalhes estão na secção Definir a classe do sensor e o modelo de TC abaixo.

Os módulos da série BASIC CT são fornecidos em par com os respetivos sensores, pré-configurados e calibrados de fábrica para esse sensor; arrancam sem inicialização.

Nas bibliotecas cliente — a mesma tarefa sem acesso aos 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

Funções auxiliares (C neutro em relação à plataforma)

Todos os exemplos abaixo usam três funções auxiliares fáceis de implementar em qualquer plataforma:

C
// Read one byte from a slave register.
uint8_t rb_read_u8(uint8_t addr, uint8_t reg);

// Read a little-endian float32 (4 bytes from reg, reg+1, reg+2, reg+3).
// rbAmp supports READ auto-increment — both per-byte access and a single
// 4-byte burst-read are valid. The helpers below show per-byte for clarity;
// production code often uses burst-read for atomicity guarantees (see ch 11).
float rb_read_float_le(uint8_t addr, uint8_t reg);

// Write one byte to a slave register.
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val);

Arranque em Arduino (Wire.h)

Auxiliares

C++
#include 

uint8_t rb_read_u8(uint8_t addr, uint8_t reg) {
  Wire.beginTransmission(addr);
  Wire.write(reg);
  Wire.endTransmission(false);   // repeated start, do not release bus
  Wire.requestFrom(addr, (uint8_t)1);
  return Wire.read();
}

float rb_read_float_le(uint8_t addr, uint8_t reg) {
  uint8_t buf[4];
  for (int i = 0; i < 4; i++) {
    buf[i] = rb_read_u8(addr, reg + i);
  }
  float f;
  memcpy(&f, buf, 4);            // little-endian host (AVR, ESP32, ARM)
  return f;
}

void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val) {
  Wire.beginTransmission(addr);
  Wire.write(reg);
  Wire.write(val);
  Wire.endTransmission();
}

Teste de funcionamento (módulo único)

C++
#include 
#define RB_ADDR 0x50

void setup() {
  Serial.begin(115200);
  Wire.begin();
  Wire.setClock(50000);
  delay(300);                           // wait for module boot

  // Wait DATA_VALID bit
  while ((rb_read_u8(RB_ADDR, 0xCE) & 0x01) == 0) {
    Serial.println("waiting for DATA_VALID...");
    delay(50);
  }

  uint8_t ver = rb_read_u8(RB_ADDR, 0x03);
  Serial.printf("rbAmp ready, version 0x%02X\n", ver);
}

void loop() {
  float u_rms = rb_read_float_le(RB_ADDR, 0x86);
  float i_rms = rb_read_float_le(RB_ADDR, 0x8E);
  float p     = rb_read_float_le(RB_ADDR, 0xA6);
  float pf    = rb_read_float_le(RB_ADDR, 0xB2);

  Serial.printf("U=%.1f V  I=%.3f A  P=%.1f W  PF=%.3f\n",
                u_rms, i_rms, p, pf);
  delay(1000);
}

Use uma carga de pelo menos ~1 % da potência nominal do sensor — abaixo disso as leituras ficam ruidosas e a classe não é garantida (um candeeiro de 60 W é apenas 0.9 % de uma pinça de 30 A; veja a tabela de características). Numa pinça de 30 A, uma chaleira de 2 kW é uma boa carga de teste de funcionamento. Para os módulos da série BASIC SCT com sensor SCT-013, defina a classe do sensor e o modelo de CT antes do teste de funcionamento (veja Definir a classe do sensor e o modelo de CT) — sem o modelo, as leituras de corrente não têm significado.

Saída esperada (uma chaleira de 2 kW em 230 V, pinça de 30 A):

Text
rbAmp ready, version 0x04
U=229.8 V  I=8.72 A  P=2004 W  PF=0.999
U=230.1 V  I=8.73 A  P=2008 W  PF=0.999
...

Arranque em STM32 HAL (C)

C
#include "stm32f1xx_hal.h"
extern I2C_HandleTypeDef hi2c1;

#define RB_ADDR_8BIT (0x50 << 1)        // HAL expects 8-bit address format

uint8_t rb_read_u8(uint8_t reg) {
  uint8_t v;
  HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg, I2C_MEMADD_SIZE_8BIT, &v, 1, 100);
  return v;
}

float rb_read_float_le(uint8_t reg) {
  uint8_t buf[4];
  for (int i = 0; i < 4; i++) {
    HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg + i, I2C_MEMADD_SIZE_8BIT,
                     &buf[i], 1, 100);
  }
  float f;
  memcpy(&f, buf, 4);
  return f;
}

void main_app(void) {
  while ((rb_read_u8(0xCE) & 0x01) == 0) HAL_Delay(50);

  uint8_t ver = rb_read_u8(0x03);
  printf("rbAmp version: 0x%02X\n", ver);

  while (1) {
    float u = rb_read_float_le(0x86);
    float i = rb_read_float_le(0x8E);
    float p = rb_read_float_le(0xA6);
    printf("U=%.1f V  I=%.3f A  P=%.1f W\n", u, i, p);
    HAL_Delay(1000);
  }
}

Módulos da série CT: arranque sem configuração

Um módulo da série CT é fornecido com cada canal de corrente já configurado: classe do sensor, calibre e calibração são escritos na fábrica para a pinça embalada com esse canal. Não são necessárias escritas de inicialização — o anfitrião apenas lê.

Segurança

⚠ Não escreva a classe do sensor nem o modelo do sensor num módulo da série CT. - Escrever o modelo num canal substitui a calibração de fábrica desse canal por uma predefinição genérica: o erro passa a −2…+3 % e o limiar de corrente baixa fica errado. - Escrever a classe apaga o modelo de todos os canais.

No firmware 1.4.22 e posteriores um módulo da série CT recusa escritas de classe e modelo em funcionamento normal com ERR_PARAM (0xFE); as bibliotecas cliente recusam-nas em todos os firmwares.

O canal e a sua pinça formam um par. Cada pinça está identificada com o canal a que pertence. Não mude uma pinça de canal nem ligue outra pinça a um canal: a calibração aplica-se apenas ao emparelhamento de fábrica. As potências nominais são fixas; não há calibre a escolher.

Sequência de arranque

  1. Ligue as pinças (com a seta virada para a carga — ver hardware-connection.md) e alimente o módulo.
  2. Leia a classe (SENSOR_CLASS, 0x25): 2 = série de pinças de TC.
  3. Leia o modelo aplicado de cada canal (0x51..0x53, um registo por canal; UI5/UI7 canais 3 e seguintes: através da janela de acesso a canais, campo CT_MODEL) e associe-o ao calibre:
Código do modelo 0x06 0x07 0x08 0x09 0x0A 0x0B 0x0D
Calibre 1 A 5 A 10 A 20 A 30 A 50 A 100 A

Use o calibre para ajustar as escalas de visualização e validar leituras; o módulo já reporta em amperes.

  1. Consulte como para qualquer módulo BASIC — janela de medição de 100 ms, pino data-ready ou leitura periódica (ver realtime-polling.md); medição por período como em period-metering.md.

Não é necessário mais nada: não há seleção de sensor, nem passo de ganho, nem comando de gravação. O módulo mantém a configuração após reinícios.

Substituir uma pinça ou um módulo

A calibração pertence ao par. Uma pinça ou canal não pode ser substituído no terreno: um módulo que precise de nova pinça é devolvido ao serviço de fábrica para novo emparelhamento.

Definir a classe do sensor e o modelo de TC

Nota

Necessário apenas para módulos BASIC da série SCT usados com sensores SCT-013. Os módulos BASIC da série CT são fornecidos em par com os seus sensores: tudo vem predefinido e calibrado de fábrica para esse sensor específico, e arrancam sem inicialização — salte esta secção.

Dois registos descrevem o sensor externo: SENSOR_CLASS (a família — pinças SCT-013 de encaixe, a série de pinças de TC com fios e o TC integrado) e CT_MODEL (o código de modelo específico dentro dessa família). Na v1.3 o modelo é escrito com um esquema de staging puro — escrever CT_MODEL não o aplica por si só; um comando dedicado por canal confirma o valor em staging.

Registos

Nome Endereço Tipo Notas
SENSOR_CLASS 0x25 u8 RW 0 = Não definido, 1 = SCT_013, 2 = WIRED_CT (a série de pinças de TC), 3 = BUILTIN_CT (sensor integrado, calibração de fábrica por unidade — sem código de modelo). Alterar a classe repõe CT_MODEL a 0.
CT_MODEL 0x05 u8 RW Código do modelo de CT — apenas registo de preparação. A escrita pura não aplica.

Escolher um sensor

Compre um dos modelos SCT-013 de saída em tensão indicados na tabela abaixo (ficha de 3.5 mm) — não uma variante de saída em corrente. Escolha a pinça de calibre mais pequeno que esteja acima da sua maior corrente esperada; para a classe indicada, a carga não deve ficar abaixo de cerca de 1 % do calibre (ver a tabela de exatidão).

Códigos de modelo de TC — família SCT-013 (SENSOR_CLASS = 1)

Código Sensor Calibre nominal Início do corte RMS Limite de pico
0x00 não definido (predefinição nos módulos BASIC da série SCT novos de fábrica) — — —
0x01 SCT-013-005 5 A 5.8 A 8.2 A
0x02 SCT-013-010 10 A 11.6 A 16.4 A
0x03 SCT-013-030 30 A 34.8 A 49.2 A
0x04 SCT-013-050 50 A 58 A 82 A
0x05 SCT-013-100 100 A 116 A 164 A
0x06 SCT-013-020 20 A 23.2 A 32.8 A
0x07 SCT-013-060 60 A 69.6 A 98.4 A
Nota

Os códigos 0x06 e 0x07 não são monótonos por valor nominal — foram acrescentados depois do conjunto original 0x01..0x05. Escolha sempre pelo valor nominal de que precisa, e não pela ordem dos códigos.

Semântica dos limites: a potência nominal e o início do corte RMS pressupõem uma carga sinusoidal; o início de corte medido é ≈ 1.16 × a nominal. O limite de pico (≈ 1.64 × a nominal) é o teto real — uma carga distorcida (fator de crista alto) começa a cortar em pico / fator de crista, abaixo dos valores RMS. Fique em ou abaixo da nominal para a exatidão especificada: as leituras cortam a cerca de 115–120 % da nominal.

Os valores por calibre (limiar detetável e legível, classe, tolerância do sensor, ponto de corte) estão na tabela de exatidão em overview.md. Alterar o modelo do sensor é escrever o código do modelo no módulo — nada mais é necessário; não há passo de recalibração.

Códigos de modelo de TC — série de pinças de TC com fios (SENSOR_CLASS = 2)

Os módulos da série CT- são fornecidos como um conjunto calibrado de fábrica com a sua própria pinça: classe e modelo já estão definidos e fazem parte da calibração — ver módulos da série CT: arranque sem configuração. Não os escreva. A tabela abaixo serve de referência para ler o modelo aplicado; o utilizador não seleciona nada num módulo da série CT-.

Código Pinça Calibre nominal Janela
0x01..0x05 predefinições de TC com fios legadas — —
0x06 Pinça CT, 1 A 1 A 6 mm
0x07 Pinça TC, 5 A 5 A 6 mm
0x08 Pinça CT, 10 A 10 A 6 mm
0x09 Pinça CT, 20 A 20 A 10 mm
0x0A Pinça TC, 30 A 30 A 10 mm
0x0B Pinça TC, 50 A 50 A 10 mm
0x0D Pinça TC, 100 A 100 A 16 mm
Nota

A dimensão da janela segue do calibre nominal (6 mm para 1–10 A, 10 mm para 20–50 A, 16 mm para 100 A) e não afeta a calibração.

Comandos

Nome Opcode Efeito Aguardar
CMD_SET_CT_MODEL_CH0 0x28 Associar o valor preparado de CT_MODEL ao canal 0 ~5 ms
CMD_SET_CT_MODEL_CH1 0x29 Vincular ao canal 1 (UI2/UI3/I2/I3) ~5 ms
CMD_SET_CT_MODEL_CH2 0x2A Associar ao canal 2 (UI3/I3) ~5 ms
CMD_SAVE_USER_CONFIG 0x32 Gravar o bloco de configuração do utilizador (classe do sensor, modelo de CT, endereço, etiqueta) na flash ~700 ms

Procedimento

  1. Ligue a(s) pinça(s) CT à(s) ficha(s) jack do módulo (seta para a carga — veja hardware-connection.md).
  2. Definir a classe do sensor(uma vez, se ainda não estiver definido):

    C++
    rb_write_u8(0x50, 0x25, 0x01);    // SCT_013
    

  3. Para cada canal o módulo expõe:

  4. Preparar o código do modelo de CT paraCT_MODEL:
    C++
    rb_write_u8(0x50, 0x05, 0x03);    // example: SCT-013-030
    
  5. Associe-o ao canal com o correspondenteCMD_SET_CT_MODEL_CHn:
    C++
    rb_write_u8(0x50, 0x01, 0x28);    // CMD_SET_CT_MODEL_CH0
    delay(5);
    
  6. Repita para ch1 / ch2 se a variante os tiver (os canais são independentes — pode misturar códigos de modelo por canal).
  7. Persistirpara a flash comCMD_SAVE_USER_CONFIG:

    C++
    rb_write_u8(0x50, 0x01, 0x32);
    delay(700);                          // flash erase/write
    

  8. Concluído — com uma ressalva no firmware anterior à 1.4.20 (CAPABILITY bit 12 a zero): aí o código do modelo guardado sobrevive aos reinícios, mas a escala aplicada não (veja O que persiste após um reinício abaixo) — se escolheu um modelo não-padrão de fábrica, repita o passo 3 (preparar + confirmar) após cada reinício de módulo detetado; CMD_SAVE_USER_CONFIG não precisa de ser repetido. A partir do fw 1.4.20 a troca de modelo sobrevive a reinícios.

Independência da ordem dos canais

: na v1.3 pode chamar CMD_SET_CT_MODEL_CH0/1/2 por qualquer ordem. Não é necessária nenhuma solução alternativa de ordem decrescente (era um artefacto interno dos firmwares anteriores).

Comportamento com as bibliotecas cliente atuais

As bibliotecas cliente do rbAmp (Arduino, ESP-IDF, ESPHome, Python) envolvem este procedimento e acrescentam:

  • Reescrever o mesmo valor é ignorado. Definir a classe do sensor ou o modelo de TC com o valor que o módulo já tem não gera nenhuma escrita no barramento nem ciclo de flash — chamar o setter em cada arranque é seguro.

  • Módulos emparelhados de fábrica não aceitam alterações de classe nem de modelo. Nos SKU fornecidos como um conjunto calibrado de fábrica com o seu próprio sensor de corrente (série CT-), a classe e o modelo do sensor fazem parte da calibração: o módulo (firmware 1.4.22 e posteriores) recusa a escrita com ERR_PARAM (0xFE) em funcionamento normal, e as bibliotecas recusam-na antes de enviar em todos os firmwares. Voltar a emparelhar um sensor de substituição é um serviço de fábrica.

  • Limites por modelo. Para cada modelo de TC as bibliotecas expõem a sua corrente nominal, o nível RMS em que começa o corte e o limite de pico — use-os para validar leituras face ao sensor ligado.

Verificação

Após a vinculação, o modelo de TC aplicado em cada canal é espelhado em 0x51..0x53 (espelhos de verificação só de leitura). NÃO são o registo de staging 0x05:

C++
uint8_t ch0 = rb_read_u8(0x50, 0x51);  // applied on ch0
uint8_t ch1 = rb_read_u8(0x50, 0x52);  // applied on ch1
uint8_t ch2 = rb_read_u8(0x50, 0x53);  // applied on ch2
Serial.printf("Applied: ch0=0x%02X ch1=0x%02X ch2=0x%02X\n", ch0, ch1, ch2);
Segurança

⚠ Leitura de retorno ≠ persistência. Uma leitura bem-sucedida de 0x51..0x53 confirma que o valor está ativo em RAM, mas não que sobreviveu à flash. Para verificar a persistência, execute CMD_RESET (ou desligue e volte a ligar) e leia de novo após a janela de arranque. O padrão completo está em period-metering.md.

Ao pôr em funcionamento um módulo novo, faça uma verificação de sanidade com uma carga resistiva conhecida (por exemplo, uma lâmpada incandescente de 100 W): I_rms ≈ 100 W / U_rms ≈ 0.43 A e P_real ≈ 100 W. Se as leituras estiverem muito erradas, o código do modelo está provavelmente errado.

O que persiste após um reinício

CMD_SAVE_USER_CONFIG persiste o bloco de configuração do utilizador na flash, mas nem tudo o que o mestre define é reaplicado no arranque seguinte. Nos firmwares anteriores a 1.4.20 (CAPABILITY bit 12 a zero):

Item Sobrevive a um reinício?
Endereço I²C sim
Etiqueta do módulo sim
Classe do sensor + código do modelo de CT (legível de volta) sim
Escala aplicada por modelo antes do fw 1.4.20: não — reverte para a predefinição de fábrica; a partir de 1.4.20 (CAPABILITY bit 12 a 1): sim
FLEET_CONFIG (ativação do GC) + GROUP_ID sim (via CMD_SAVE_USER_CONFIG; efetivo após reinício)
configuração apenas em RAM (limiares de evento, configuração do resumo) não

A consequência nessas imagens: um módulo que foi comutado para um modelo diferente daquele com que saiu da fábrica lê de volta o código de modelo guardado após um reinício, mas mede com o escalonamento de fábrica até o modelo ser novamente confirmado. A regra para qualquer mestre (e para um hub que gere uma frota, indexado pelo UID do módulo):

  1. Detetar o reinício — UPTIME_S / bit de evento RESET_OCCURRED, ver period-metering.md → Deteção de reinício do módulo.

  2. Preparar de novo e confirmar de novo o modelo de CT em cada canal (CT_MODEL + CMD_SET_CT_MODEL_CHn) e, em seguida, reaplicar qualquer configuração apenas em RAM.

As bibliotecas cliente implementam exatamente isto no seu caminho de retoma. A partir do fw 1.4.20 (CAPABILITY bit 12, SCT_RATING_SELF) a troca de modelo mantém a calibração da unidade e sobrevive a reinícios — o passo 2 é então desnecessário para o modelo CT; a configuração apenas em RAM ainda precisa de ser reinicializada. Os módulos que funcionam no seu modelo de fábrica (incluindo todos os módulos da série CT- emparelhados de fábrica) não são afetados em nenhuma imagem — o escalonamento de fábrica é o correto.

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

Fluxo de trabalho com um só módulo

  1. Ligue o módulo conforme hardware-connection.md.
  2. Nos módulos da série BASIC SCT, escreva o modelo do sensor uma vez (secção anterior).
  3. Grave o mestre com o esboço de teste de funcionamento.
  4. Abra o monitor série — deverá ver U/I/P de segundo a segundo.
  5. Se as leituras parecerem erradas, veja troubleshooting.md.

Configuração com vários módulos

Cenário: três módulos rbAmp num único barramento para monitorizar diferentes secções de uma casa (alimentação principal, termoacumulador, ar condicionado).

Passo 1 — Endereços

De fábrica, os três módulos trazem o endereço 0x50. Têm de ser readdressados um de cada vez. Ligue apenas um módulo ao barramento até a alteração de endereço estar concluída.

Passo 2 — Teste de funcionamento com um módulo

Use a secção acima. Confirme que um módulo funciona corretamente.

Passo 3 — Alterar endereço (e, se necessário, definir o modelo de TC)

Use o procedimento de alteração de endereço abaixo. Se os módulos usarem sensores SCT-013 diferentes, defina o modelo de TC em cada um antes de alterar os endereços.

Passo 4 — ciclo de polling de vários módulos

C++
#include 

const uint8_t modules[] = {0x50, 0x51, 0x52};   // main, boiler, AC
const char* labels[]    = {"MAIN", "BOIL", "AC  "};
const int N = sizeof(modules) / sizeof(modules[0]);

void setup() {
  Serial.begin(115200);
  Wire.begin();
  Wire.setClock(50000);
  delay(300);

  for (int i = 0; i < N; i++) {
    Wire.beginTransmission(modules[i]);
    uint8_t rc = Wire.endTransmission();
    Serial.printf("Module %s (0x%02X): %s\n",
                  labels[i], modules[i], rc == 0 ? "OK" : "MISSING");
  }
}

void loop() {
  for (int i = 0; i < N; i++) {
    float u = rb_read_float_le(modules[i], 0x86);
    float p = rb_read_float_le(modules[i], 0xA6);
    Serial.printf("[%s] U=%.1f  P=%.1f W\n", labels[i], u, p);
  }
  Serial.println();
  delay(1000);
}

Saída esperada:

Text
Module MAIN (0x50): OK
Module BOIL (0x51): OK
Module AC   (0x52): OK
[MAIN] U=229.8  P=850.3 W
[BOIL] U=229.7  P=1850.0 W
[AC  ] U=229.9  P=0.0 W
...
Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmpFleet::scan(match_product, added) / RbAmpFleet::pollAll(snaps, status, capacity, n_ok) descubra os módulos no barramento; leia todos num só passo
ESP-IDF rbamp_fleet_scan() / rbamp_fleet_poll_all() descubra os módulos no barramento; leia todos num só passo
Python fleet.scan(match_product=True) / fleet.poll_all() descubra os módulos no barramento; leia todos num só passo
ESPHome rbamp: (list) um bloco rbamp: por módulo, cada um com o seu próprio id e address

Alteração de endereço

O endereço de fábrica 0x50 está guardado no bloco de configuração do utilizador na flash. A v1.3 usa uma sequência de commit em duas fases para tornar difíceis alterações acidentais de endereço: um endereço candidato entra primeiro num registo de staging em RAM, tem de ser armado com um byte magic, e só então é confirmado na flash por um comando explícito. Um reset volta a enumerar o módulo no novo endereço.

A alteração de endereço em duas fases: coloque o endereço candidato em staging, arme-o, confirme-o e depois reinicie.

Registos e comandos

Nome Endereço / opcode Tipo Finalidade
REG_I2C_ADDRESS 0x30 u8 RW Preparação para o endereço candidato (0x08..0x77). Uma regra: antes do reinício, 0x30 repete o candidato preparado; após o arranque lê o endereço ativo.
ADDR_COMMIT_MAGIC 0x31 u8 W Arme o commit com 0xA5. Consumido (limpo) na tentativa de commit.
CMD_COMMIT_ADDR opcode 0x30 escrito em REG_COMMAND (0x01) comando Valida o endereço em staging contra o magic e persiste-o na flash.
CMD_RESET opcode 0x01 escrito em REG_COMMAND (0x01) comando Reinício por software. O módulo volta a enumerar-se no novo endereço após ~300 ms.

Procedimento

  1. Ligue apenas um módulo (ainda em 0x50) ao barramento.
  2. Coloque o novo endereço em staging:

    C++
    rb_write_u8(0x50, 0x30, 0x51);    // candidate address → RAM staging
    

  3. Arme a confirmação:

    C++
    rb_write_u8(0x50, 0x31, 0xA5);    // ADDR_COMMIT_MAGIC
    

  4. ProblemaCMD_COMMIT_ADDR (opcode 0x30):

    C++
    rb_write_u8(0x50, 0x01, 0x30);
    

  5. Aguardar≥ 700 mspara o apagamento/escrita da flash:

    C++
    delay(700);
    

  6. ProblemaCMD_RESET (opcode 0x01) — CMD_COMMIT_ADDRdoesnão auto-reset:

    C++
    rb_write_u8(0x50, 0x01, 0x01);
    

  7. Aguarde ~300 ms pela janela de arranque. Não emita comandos durante esta janela.

  8. Verifique se o módulo faz ACK no novo endereço:

    C++
    uint8_t ver = rb_read_u8(0x51, 0x03);    // VERSION should be 0x04 on v1.3
    if (ver == 0x04) Serial.println("Address change OK");
    

  9. Marque a placa com o novo endereço usando um lápis de cera ou uma etiqueta, para o poder identificar fisicamente.

Notas importantes

  • As duas fases são obrigatórias. Escrever o candidato em 0x30 sozinho não faz nada de persistente — só fica em RAM e perde-se no próximo reset. O par magic-e-commit é o que realmente reescreve a flash.
  • O endereço preparado tem de estar no intervalo 0x08..0x77 (I²C válido de 7 bits). Escritas fora do intervalo são rejeitadas com ERR_PARAM; o módulo mantém o endereço atual.
  • Endereços I²C reservados: 0x00 (general-call, ver abaixo), 0x01..0x07 (CBus reservado), 0x78..0x7F (10 bits reservado). Não os use.
  • Uma regra de leitura de retorno: antes do reinício, 0x30 repete o candidato preparado; após o arranque lê o endereço ativo.
  • O magic armado expira após 5 s sem commit (capítulo 11 §6.1) — volte a armar se tiver esperado demasiado.
  • Lembrete de espaço de nomes — o mesmo valor de byte pode ser um endereço e um opcode:
Byte Como endereço de registo Como opcode (escrito em 0x01)
0x27 FLEET_CONFIG CMD_LATCH_PERIOD
0x28 GROUP_ID CMD_SET_CT_MODEL_CH0
0x30 REG_I2C_ADDRESS CMD_COMMIT_ADDR

Exemplo completo de alteração de endereço

C++
#include 

bool change_address(uint8_t old_addr, uint8_t new_addr) {
  if (new_addr < 0x08 || new_addr > 0x77) {
    Serial.println("ERROR: invalid address");
    return false;
  }

  Serial.printf("Changing 0x%02X -> 0x%02X\n", old_addr, new_addr);

  rb_write_u8(old_addr, 0x30, new_addr);   // 1. stage candidate
  rb_write_u8(old_addr, 0x31, 0xA5);       // 2. arm magic
  rb_write_u8(old_addr, 0x01, 0x30);       // 3. CMD_COMMIT_ADDR
  delay(700);                              // 4. flash erase/write
  rb_write_u8(old_addr, 0x01, 0x01);       // 5. CMD_RESET (mandatory)
  delay(300);                              // 6. boot window

  Wire.beginTransmission(new_addr);
  if (Wire.endTransmission() == 0) {
    Serial.printf("OK, module now at 0x%02X\n", new_addr);
    return true;
  }
  Serial.printf("FAIL: module not found at 0x%02X\n", new_addr);
  return false;
}

void setup() {
  Serial.begin(115200);
  Wire.begin();
  delay(300);
  change_address(0x50, 0x51);
}
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

General Call (broadcast no endereço 0x00)

O protocolo I²C reserva o endereço 0x00 (general call) — as tramas enviadas para este endereço são recebidas por todos os escravos do barramento em simultâneo. O rbAmp pode tirar o seu instantâneo de período numa trama general-call, mas apenas depois de a funcionalidade ter sido explicitamente ativada no módulo.

Adesão opcional (por defeito OFF)

A receção de instantâneos General Call está desativada por defeito — um módulo novo fará NACK à trama general-call, o que o mestre deteta como erro grave e recorre automaticamente a instantâneos sequenciais por módulo. Para ativar o GC num módulo:

  1. Defina o bit 0 deFLEET_CONFIG:
    C++
    rb_write_u8(0x50, 0x27, 0x01);    // bit0 = GC_ENABLE
    
Nota

Nota sobre o valor 0x27: este é o endereço do registo de FLEET_CONFIG. O mesmo valor de byte 0x27 também é o opcode de comando de CMD_LATCH_PERIOD (um espaço de nomes separado — os opcodes vão para REG_COMMAND em 0x01). A colisão é puramente cosmética; o endereço e o opcode nunca se confundem ao nível do barramento.

  1. (Opcional) definirGROUP_IDpara particionar a frota —0x00aceita todas as chamadas:

    C++
    rb_write_u8(0x50, 0x28, 0x00);    // all-call
    

  2. Persist:

    C++
    rb_write_u8(0x50, 0x01, 0x32);    // CMD_SAVE_USER_CONFIG
    delay(700);
    

  3. Reponha e verifique se o bit ficou escrito:

    C++
    rb_write_u8(0x50, 0x01, 0x01);    // CMD_RESET
    delay(300);
    uint8_t cfg = rb_read_u8(0x50, 0x27);
    if (cfg & 0x01) Serial.println("GC enabled");
    

Formato da trama GC

As tramas de instantâneo GC têm um layout fixo de magic e opcode:

Layout de bytes da trama de instantâneo de chamada geral.

Text
addr 0x00 | A5 27   
  • A5 — magic da trama (o escravo rejeita qualquer outro byte).
  • 27 — opcode (CMD_LATCH_PERIOD).
  • — grupo-alvo (0x00 = all-call; caso contrário tem de coincidir com o GROUP_ID do módulo).
  • — contador de tick de 16 bits do lado do mestre, espelhado em cada GC_TICK (0x59) do módulo para deteção de tramas perdidas.

Por desenho, as tramas GC transportam apenas o comando de instantâneo — os opcodes destrutivos (SAVE_*, COMMIT_ADDR, FACTORY_RESET) não são respeitados através da chamada geral.

Exemplo de instantâneo de difusão (após ativação)

C++
// All modules with GC enabled take their snapshots at once.
Wire.beginTransmission(0x00);
Wire.write(0xA5);                       // frame magic
Wire.write(0x27);                       // CMD_LATCH_PERIOD opcode
Wire.write(0x00);                       // group_id = all-call
Wire.write(tick & 0xFF);                // tick_lo
Wire.write((tick >> 8) & 0xFF);         // tick_hi
uint8_t rc = Wire.endTransmission();
if (rc != 0) {
  // NACK at GC level → no module on the bus has GC enabled.
  // Fall back to per-module sequential snapshot.
}

Após o broadcast, cada módulo atualiza o seu instantâneo de forma independente. O mestre lê então cada módulo pelo seu endereço individual. Verificação de testemunha (recomendada): após ~50 ms de estabilização, leia V03_PERIOD_VALID (0x07) em cada módulo esperado — 1 confirma que o instantâneo foi recebido; 0 recorre ao instantâneo por módulo apenas nesse módulo.

Aplicação: sincronização precisa de períodos para o balanceamento de energia de vários módulos (por exemplo mains_input − solar_output), onde o instante do instantâneo tem de ser idêntico em todos os módulos.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::enableGc(enable) / RbAmpFleet::gcLatch(group, tick, settle_ms) ativar o General Call num módulo; enviar a trama de instantâneo para a frota
ESP-IDF rbamp_enable_gc() / rbamp_fleet_gclatch() ativar o General Call num módulo; enviar a trama de instantâneo para a frota
Python dev.enable_gc(enable=True) / fleet.gc_latch(group, tick, settle_ms) ativar o General Call num módulo; enviar a trama de instantâneo para a frota
ESPHome fleet_gc_enable: / group_id: Opções YAML para adesão ao General Call e ID de grupo
Text
Step 1: Unbox all modules — every module is on address 0x50.

Step 2: For each module, one at a time:
   a) Connect only this module to the bus.
   b) If it is a BASIC SCT-series module: set SENSOR_CLASS (0x25), stage CT_MODEL (0x05),
      issue CMD_SET_CT_MODEL_CHn for each channel, then CMD_SAVE_USER_CONFIG.
   c) On images before fw 1.4.20 (`CAPABILITY` bit 12 clear): after any later reset of this
      module, re-stage and re-commit CT_MODEL on each channel (see the persistence table above).
   d) Run change_address(0x50, ).
   e) Verify the module responds at the new address.
   f) Physically mark the module (label with 0x51, 0x52, ...).
   g) Disconnect and move to the next module.

Step 3: After readdressing all modules, connect them in parallel.
        With four or more modules (or a longer bus), cut the built-in
        pull-up jumpers on all but one (see hardware-connection.md → I2C pull-ups).

Step 4: At master boot, run a scan loop and verify every readdressed
        module responds at its expected address.

BASIC ou STD?

A linha STD do rbAmp responde no mesmo barramento, mas usa um mapa de registos diferente, de 16 bits. Antes de aplicar a deteção BASIC abaixo, pode distinguir: envie o ponteiro de 16 bits 0x00 0x00 e leia 2 bytes — um módulo STD devolve o par ASCII 'S','T' (0x53 0x54); um módulo BASIC não (trata os bytes como escritas de registos de 8 bits e devolve os seus dados normais). Os módulos STD estão cobertos pela sua própria documentação de referência.

Não precisa de fazer isto por si quando usa uma biblioteca cliente. As bibliotecas (Arduino, ESP-IDF, Python, ESPHome) já detetam a linha do módulo e tratam os diferentes tamanhos de registo — não tem de pensar se o mapa de registos é de 8 ou de 16 bits.

Como distinguir em execução um módulo BASIC de um módulo STD.

Nas bibliotecas cliente

— a mesma tarefa sem acesso a registos:

Biblioteca Chamada O que faz
Arduino RbAmp::line() / RbAmp::begin() linha detetada em begin(); lê-a de volta a partir do valor em cache
ESP-IDF rbamp_line() / rbamp_begin() linha detetada em begin; leia-a de volta do valor em cache
Python dev.is_std / dev.begin() linha detetada em begin(); leia-a de volta da propriedade
ESPHome — não exposto — a deteção é automática, nada a configurar no YAML

Deteção automática da variante do módulo

Segurança

⚠ Não detete a variante sondando por NACK em leituras de registos. O firmware nunca responde com NACK às leituras de registos — os endereços não mapeados devolvem 0x00 (ver capítulo 11 §5.2). Uma verificação baseada em NACK reporta sempre "canal presente".

Use o par canónico HW_VARIANT (0x55) + CAPABILITY (0x57/0x58):

C++
struct VariantInfo {
  uint8_t hw_variant;     // 1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3
  uint8_t n_current;      // 1..3
  bool    has_voltage;    // true on UI*, false on I*
};

VariantInfo detect_variant(uint8_t addr) {
  VariantInfo v = {0, 0, false};
  uint8_t product = rb_read_u8(addr, 0x54);             // PRODUCT_ID
  if (product != 0x01) return v;                         // not an rbAmp sensor
  v.hw_variant = rb_read_u8(addr, 0x55);                 // HW_VARIANT
  uint8_t hw = v.hw_variant;
  v.n_current = (hw == 1 || hw == 4) ? 1
              : (hw == 2 || hw == 5) ? 2
              : (hw == 3 || hw == 6) ? 3 : 0;
  uint8_t cap_hi = rb_read_u8(addr, 0x58);               // CAPABILITY high byte
  v.has_voltage = (cap_hi & 0x01) != 0;                  // bit 8 of u16 = voltage-HW
  return v;
}

HW_VARIANT 1..3 são variantes UI (has_voltage == true); 4..6 são variantes só de corrente (has_voltage == false). Uma incompatibilidade entre a família HW_VARIANT e CAPABILITY.bit8 indica um módulo avariado ou com firmware gravado incorretamente.

AC_FREQ (0x20) funciona em todas as variantes — o sinal de passagem por zero vem de um pino dedicado de ZC da rede, independente do front-end de tensão.

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 e o mapa de funcionalidades
ESP-IDF rbamp_read_variant() / rbamp_read_capability() ler a variante de hardware e o mapa de funcionalidades
Python dev.read_variant() / dev.read_capability() ler a variante de hardware e o mapa de funcionalidades
ESPHome get_variant_str() / get_capability_hex() string de variante e mapa de capacidades a partir da superfície de identidade

Seguinte