02 · Inicialização e arranque
O rbAmp começa a medir imediatamente após ligar. O mestre só precisa de:
- Ative o barramento I²C (inicialização padrão de
Wire/ HAL). - Aguarde ~250 ms, ou consulte
DATA_VALID = 1no registo0xCE. - Opcionalmente, leia a versão do firmware em
0x03como verificação de sanidade. - 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.
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:
// 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
#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)
#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):
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)
#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ê.
⚠ 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
- Ligue as pinças (com a seta virada para a carga — ver hardware-connection.md) e alimente o módulo.
- Leia a classe (
SENSOR_CLASS,0x25):2= série de pinças de TC. - 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, campoCT_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.
- 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
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 |
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 |
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
- Ligue a(s) pinça(s) CT à(s) ficha(s) jack do módulo (seta para a carga — veja hardware-connection.md).
-
Definir a classe do sensor(uma vez, se ainda não estiver definido):
C++rb_write_u8(0x50, 0x25, 0x01); // SCT_013 -
Para cada canal o módulo expõe:
- Preparar o código do modelo de CT para
CT_MODEL:C++rb_write_u8(0x50, 0x05, 0x03); // example: SCT-013-030 - Associe-o ao canal com o correspondente
CMD_SET_CT_MODEL_CHn:C++rb_write_u8(0x50, 0x01, 0x28); // CMD_SET_CT_MODEL_CH0 delay(5); - Repita para ch1 / ch2 se a variante os tiver (os canais são independentes — pode misturar códigos de modelo por canal).
-
Persistirpara a flash com
CMD_SAVE_USER_CONFIG:C++rb_write_u8(0x50, 0x01, 0x32); delay(700); // flash erase/write -
Concluído — com uma ressalva no firmware anterior à 1.4.20 (
CAPABILITYbit 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_CONFIGnão precisa de ser repetido. A partir do fw 1.4.20 a troca de modelo sobrevive a reinícios.
: 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:
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);
⚠ 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):
-
Detetar o reinício —
UPTIME_S/ bit de eventoRESET_OCCURRED, ver period-metering.md → Deteção de reinício do módulo. -
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.
— 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
- Ligue o módulo conforme hardware-connection.md.
- Nos módulos da série BASIC SCT, escreva o modelo do sensor uma vez (secção anterior).
- Grave o mestre com o esboço de teste de funcionamento.
- Abra o monitor série — deverá ver U/I/P de segundo a segundo.
- 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
#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:
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
...
— 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.
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
- Ligue apenas um módulo (ainda em
0x50) ao barramento. -
Coloque o novo endereço em staging:
C++rb_write_u8(0x50, 0x30, 0x51); // candidate address → RAM staging -
Arme a confirmação:
C++rb_write_u8(0x50, 0x31, 0xA5); // ADDR_COMMIT_MAGIC -
Problema
CMD_COMMIT_ADDR(opcode0x30):C++rb_write_u8(0x50, 0x01, 0x30); -
Aguardar≥ 700 mspara o apagamento/escrita da flash:
C++delay(700); -
Problema
CMD_RESET(opcode0x01) —CMD_COMMIT_ADDRdoesnão auto-reset:C++rb_write_u8(0x50, 0x01, 0x01); -
Aguarde ~300 ms pela janela de arranque. Não emita comandos durante esta janela.
-
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"); -
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
0x30sozinho 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 comERR_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,
0x30repete 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
#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);
}
— 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:
- Defina o bit 0 de
FLEET_CONFIG:C++rb_write_u8(0x50, 0x27, 0x01); // bit0 = GC_ENABLE
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.
-
(Opcional) definir
GROUP_IDpara particionar a frota —0x00aceita todas as chamadas:C++rb_write_u8(0x50, 0x28, 0x00); // all-call -
Persist:
C++rb_write_u8(0x50, 0x01, 0x32); // CMD_SAVE_USER_CONFIG delay(700); -
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:
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 oGROUP_IDdo módulo).— contador de tick de 16 bits do lado do mestre, espelhado em cadaGC_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)
// 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.
— 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 |
Fluxo recomendado para implementação com vários módulos
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.
— 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
⚠ 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):
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.
— 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
- realtime-polling.md — polling em tempo real em detalhe (janela de 100 ms, DRDY)
- period-metering.md — acumulação de energia tarifária