rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub [Edit on GitHub]

04 · Cablagem

Este capítulo descreve a ligação física do módulo rbAmp às placas da família ESP32: pinagem do lado de baixa tensão, requisitos de alimentação, compatibilidade de níveis de tensão I²C, comprimento do barramento e os pinos predefinidos para os 7 chips ESP32 suportados (esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32h2).

O módulo em si é todo de baixa tensão; nas variantes UI* a referência de rede única é uma derivação L–N atrás de um divisor galvanicamente isolado. O lado de BT (alimentação + I²C + DRDY opcional) é descrito primeiro; a ligação à rede e às pinças de CT está em Ligação à rede e às pinças de CT abaixo.

Pinout do lado LV

Os pinos de baixa tensão do módulo: VCC, GND, SDA, SCL e a linha opcional de data-ready.
O módulo funciona com lógica I²C de 3.3 V e étolerante a 5 Vnas linhas de sinal. Todos os pinos de baixa tensão estão totalmente isolados galvanicamente da rede.

Pino Sinal Finalidade
VCC +5 V (4.5..5.5 V) Alimentação do módulo; mínimo de 4.5 V para funcionamento correto
GND Terra Partilhado com o master — obrigatório
SDA SDA I²C Dados I²C
SCL I²C SCL Relógio I²C
DRDY Data-ready (opcional) Dreno aberto, impulso LOW de ~10 µs a cada ~100 ms

Potência

Parâmetros de VCC

  • Tensão nominal: 5 V DC
  • Intervalo admissível: 4.5..5.5 V
  • Consumo de corrente: ~15 mA típico, ~25 mA de pico durante escritas na flash
  • Ripple: < 50 mV pico a pico (para a precisão da medição)

O módulo tem um regulador de bordo, filtro RC, condensadores cerâmicos e uma ferrite — não é necessária filtragem adicional por parte do utilizador. O módulo pode ser alimentado pela linha +5V ou +5V0 de qualquer placa DevKitC (alimentada por USB-5V).

Compatibilidade de níveis de tensão I²C

  • SDA / SCL operam em lógica de 3.3 V (as pull-ups integradas puxam as linhas para 3.3 V).

  • As linhas são tolerantes a 5 V, mas a família ESP32 já funciona a 3.3 V de qualquer forma — não são necessários conversores de nível.

  • O driver i2c_master do ESP-IDF usa saídas de dreno aberto nos GPIO — compatível com os pull-ups integrados do módulo.

Comportamento ao ligar

  • Arranque a frio: ~250 ms até ao primeiro resultado válido.
  • Após uma reposição (por software ou por quebra de tensão): ~250 ms para recuperar.
  • Até ao primeiro resultado válido os registos lêem 0, com a flag DATA_VALID = 0.

O componente aguarda que o módulo fique pronto dentro do próprio rbamp_begin(dev) — o código do utilizador limita-se a chamar rbamp_begin() e a continuar.

Isolamento

O próprio módulo é todo de baixa tensão — não há nele circuito de medição de alta tensão. A corrente é lida por uma pinça de CT que acopla magneticamente a partir do exterior do condutor isolado, sem contacto elétrico com o fio da rede. Nas variantes de deteção de tensão (UI) a referência de rede única é o terminal L–N, que alimenta um divisor de deteção galvanicamente isolado*; as variantes só de amperes não têm qualquer ligação à rede.

Consequences:

  • O GND do módulo não está ligado à linha de rede nem ao neutro.
  • Os terminais de baixa tensão ligam-se ao ESP32 sem referência à rede: a pinça acopla-se magneticamente e a tomada de tensão UI fica atrás de um divisor galvanicamente isolado. Isto não substitui as precauções de ligação à rede da secção seguinte.
Segurança

⚠ Não abra a caixa do módulo — isto anula a calibração de fábrica.

Ligação à rede e às pinças de CT

Cablagem do lado da rede: a derivação de L e N e a pinça no condutor de fase.

Segurança

⚠ A tensão da rede pode matar. Desligue e bloqueie o circuito antes de ligar os terminais L/N ou de colocar a pinça; deixe trabalho na rede e qualquer intervenção dentro de um quadro a um técnico qualificado. Prenda APENAS um condutor (L) — nunca o cabo inteiro. Proteja a derivação L com fusível segundo as regras locais (obrigatório, até 0.1 A; fio AWG26–22 é suficiente — o sensor de tensão consome muito pouca corrente).

  • Tensão (apenas variantes UI): o módulo mede a tensão a partir da ligação L/N do lado da rede: a PCB expõe os terminais L (fase) e N (neutro), e a polaridade importa para o sinal da potência. As variantes I (I1/I2/I3) não têm entrada de tensão.

  • Corrente: a pinça SCT-013 liga-se à tomada CT de 3.5 mm do módulo (com chaveta para a polaridade correta; cada tomada da PCB tem a etiqueta do seu canal, I0, I1, …) e fecha-se à volta do condutor de fase (L). A seta no corpo da pinça aponta no sentido da corrente para a carga. Uma pinça invertida dá um P negativo numa carga consumidora.

  • Prenda o condutor de fase, não o neutro e não os dois condutores em conjunto.

  • Não abra o invólucro do módulo — isto anula a calibração de fábrica. As pontes de pull-up mencionadas abaixo estão no lado inferior da placa; siga as instruções do módulo para lhes aceder.

Resistências pull-up integradas — na placa

Importante: todos os módulos rbAmp têm resistências pull-up de 4.7 kΩ integradas em SDA e SCL para 3.3 V. Para um único módulo no barramento não são necessários pull-ups externos — ligue o ESP32 diretamente.

O i2c_master_bus_config_t do ESP-IDF também permite ativar os pull-ups GPIO internos através de flags.enable_internal_pullup = true. São fracos (~50 kΩ no ESP32) e funcionam em paralelo com os 4.7 kΩ externos do módulo — a combinação dá cerca de 4.4 kΩ efetivos, o que é aceitável. Em implementações de produção, prefira confiar nos 4.7 kΩ externos do módulo; os pull-ups GPIO internos são opcionais com os pull-ups do próprio módulo e servem sobretudo para testes de bancada sem módulo à mão (por exemplo, quando está apenas a verificar uma análise do barramento).

Quando desativar os pull-ups integrados

Se houver vários módulos rbAmp no barramento (ou outros dispositivos I²C com os seus próprios pull-ups), ligá-los em paralelo produz uma resistência efetiva demasiado baixa, o que:

  • Aumenta a corrente consumida no barramento
  • Pode exceder a corrente máxima de sink do andar de saída do mestre I²C
  • Acrescenta carga capacitiva num barramento longo, pouco contribuindo para a imunidade ao ruído

Solução: na face inferior da placa de cada módulo, junto às resistências de pull-up, existem pontes de jumper (serigrafia Pull-Up). Corte-as com uma lâmina afiada:

  • Deixe as pull-ups ativas em apenas um módulo (ou mova-as para um único ponto perto do ESP32).

  • Corte as pontes nos restantes módulos.

Regra prática

Regras de pull-up para um a três módulos num barramento curto e para quatro ou mais.
| Módulos rbAmp no barramento | Pull-ups | |:---:|---| | 1 | Deixe como está (a 4.7 kΩ integrada funciona) | | 2 | Deixe num, corte no outro | | 3 | Corte em todos os módulos, instale um par externo de 2.7…3.3 kΩ junto ao ESP32 | | 4…6 | Corte em todos os módulos, um par externo de 2.2…2.7 kΩ junto ao ESP32 | | 7…16 | Corte em todos os módulos, um par externo de 1.5…2.2 kΩ junto ao ESP32; verifique a capacidade do barramento (≤ 400 pF), baixe a velocidade do barramento se necessário |

Os valores externos são valores recomendados (calculados a partir da especificação I²C: corrente de sumidouro ≤ 3 mA a 3.3 V, capacidade do barramento ≤ 400 pF). Ligue os pull-ups externos a 3.3 V (o nível lógico do barramento), e não à alimentação VCC de 5 V.

Em caso de dúvida

: meça a resistência entre SDA e a linha de 3V3 com todos os dispositivos sem alimentação. Deve estar na faixa 1.5..4.7 kΩ. Se for inferior, há demasiadas pull-ups ativas em paralelo.

Parâmetros do barramento I²C

  • Endereço predefinido: 0x50 (7 bits)
  • Intervalo de endereços: 0x08..0x77 (reatribuível em fábrica)
  • Velocidade recomendada no ESP32: 50 kHz (ver a secção sobre a disciplina de retentativa + sanidade abaixo)

  • Incremento automático do ponteiro: apenas nas leituras. Uma leitura em rajada + N bytes devolve N bytes consecutivos a partir de addr (incremento automático). As escritas NÃO são incrementadas automaticamente: uma escrita em rajada + N bytes grava apenas o primeiro byte, os restantes são descartados. Os registos de vários bytes são escritos byte a byte — uma transação separada de um byte por endereço. Para detalhes veja 09 · Referência da API, a secção "Escritas de vários bytes".

Comprimento do barramento

O I²C é um barramento curto (~15 cm por predefinição). Muitos utilizadores ligam os módulos com fios de jumper de baixa qualidade, que captam muito ruído e perdem muitas transferências — daí o limite curto. Topologias recomendadas para o rbAmp:

Cabo Comprimento máximo Velocidade
JST padrão / 4 condutores planos até 0.15 m 100 kHz
Par entrançado UTP (cat-5/5e/6) — SDA+GND e SCL+GND em pares separados até 1 m 100 kHz
Par entrançado + buffer I²C (PCA9515 / TCA9617) até 3 m 100 kHz
Barramento diferencial (PCA9615 / LTC4332) até 100 m 100 kHz
Segurança

Os comprimentos acima foram verificados a 100 kHz. A velocidade por omissão do barramento no componente é 50 kHz (ver "padrão de NACK de referência do ESP32" abaixo), que tolera melhor cabos mais longos; mantenha 50 kHz e não ultrapasse estes comprimentos.

Para comprimentos acima de 0.15 m, um par entrançado é obrigatório: SDA e SCL têm de estar em pares diferentes, cada um com a sua própria massa. SDA e SCL no mesmo par criam acoplamento capacitivo cruzado que distorce os flancos.

⚠ Dentro de um armário elétrico, blinde o cabo I2C. Campos magnéticos fortes perto de condutores da rede, contactores e transformadores induzem ruído num cabo sem blindagem. Mantenha o cabo o mais curto possível e afastado da cablagem da rede.

Barramento multimódulo — a topologia principal

O caso de uso canónico da biblioteca é vários módulos rbAmp num único barramento I²C, geridos por um ESP32 através de um handle de frota. Todas as regras e otimizações abaixo foram concebidas precisamente para esta topologia; um módulo único é um caso particular (o mesmo handle, mas as chamadas de frota reduzem-se a triviais).

Vários módulos rbAmp num mesmo barramento I²C, com as pull-ups tratadas segundo as regras.

Implementações típicas

Cenário Configuração Número de módulos
80% canónico: contador principal da casa + submedidores 1× UI1 (principal, energia da rede) + 3-6× UI1 (cargas; potência e Wh exigem uma variante UI) 4-7
Subquadro com decomposição de corrente 1× UI1 (principal) + 1–2× I2/I3 (corrente por circuito) 3-5
Subcontagem industrial 1× UI1 (principal) + N× I2/I3 (por máquina, decomposição de corrente) até ~16

Restrições elétricas

  • Número de módulos: até ~16 (capacitância total do barramento ≤ 400 pF a 100 kHz).
  • Endereços: cada módulo tem o seu próprio endereço de 7 bits (intervalo 0x08..0x77). Todos os módulos saem de fábrica em 0x50 — reatribua-lhes endereços um de cada vez antes de os ligar em paralelo (ver abaixo sobre o commit em duas fases e o provisionamento via rbamp_provision()).
  • Pull-ups (importante num barramento de frota): as pull-ups internas do ESP32 (~45 kΩ) são fracas demais para um barramento multimódulo com pistas longas e ruído. Para uma operação fiável precisa de pull-ups externas (2.7…3.3 kΩ para 3 módulos, valores inferiores para barramentos maiores — ver a tabela acima) ligadas a 3.3 V em SCL/SDA num único ponto do barramento + a partir de 4 módulos (ou antes, num barramento com mais de 15 cm) as pull-ups integradas são cortadas em todos os módulos menos um — com 2–3 módulos num barramento até 15 cm deixe-as, esse caso está medido (ou corte em todos e mantenha apenas as externas). Isto faz parte da mitigação em três camadas contra o bloqueio do barramento num barramento marginal — ver 10 · Resolução de problemas.

Endereçamento — provisionamento e troca no terreno

O endereço de fábrica por omissão é 0x50. Cada módulo novo ou de substituição passa por provisionamento (uma vez): reatribuição de 0x50 para um endereço de trabalho + gravação opcional da configuração (modelo de TC, group_id, etiqueta) na flash.

No código isto é uma única chamada — rbamp_provision(bus, desired_addr, save_config, &dev). Verifica que há efetivamente apenas um módulo virgem em 0x50 no barramento, reatribui-lhe o endereço através de um commit em duas fases (ver abaixo), opcionalmente guarda a configuração do utilizador e devolve um handle pronto.

Fluxo de provisionamento: ligue um módulo novo ao endereço 0x50, dê-lhe o seu endereço, depois o seguinte.

Segurança

⚠ Disciplina de provisionamento (OBRIGATÓRIO): tem de haver exatamente um módulo virgem (no 0x50) no barramento no momento em que rbamp_provision() é chamada. Se dois módulos no mesmo endereço responderem ao I²C em simultâneo — uma colisão na fase de dados, o comportamento é indefinido, e não há forma de os distinguir (AND cablado em dreno aberto). Caminho de recuperação: desligue a alimentação, passe fisicamente para uma colocação em funcionamento de um só módulo, provisione-os um de cada vez, depois ligue os restantes. Ver 10 · Resolução de problemas, a secção "Falha de provisionamento / conflito de endereço".

Se não tiver um handle de frota e reendereçar manualmente via rbamp_prepare_address_change() + rbamp_commit_address_change() (a forma de baixo nível) — a disciplina é exatamente a mesma: um virgem de cada vez.

Commit em duas fases para uma alteração de endereço

O firmware suporta uma alteração de endereço em modo de produção através de uma sequência em duas fases:

Os passos de uma mudança de endereço em duas fases, desde a preparação do novo endereço até à verificação.

Text
1. write candidate_addr → REG_I2C_ADDRESS (0x30, in RAM)
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31, armed)
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)
4. issue CMD_RESET (0x01)
5. wait ~300 ms; the new address is active

O componente envolve isto em rbamp_prepare_address_change() / rbamp_commit_address_change() — ver 09 · Referência da API. A persistência só é confirmada após um reinício (ver o aviso "modo de produção vs fábrica" em 03_sensor_selection.md).

Orçamento energético do barramento — quantos módulos a sua taxa de sondagem consegue sustentar

Num barramento de 50 kHz uma transação de leitura de registo ≈ 200–400 µs (depende do driver do MCU). Um bloco RT completo de um canal (U + I + P + PF) = 4 floats = 16 bytes + 4 fases de endereço ≈ 5–8 ms por canal.

Configuração Ciclo de barramento A 50 kHz Taxa máxima de consulta
1× UI1, bloco RT ~5 ms < 5 ms 100+ Hz (mas o módulo atualiza a 10 Hz)
1× I3, bloco RT + período ~25 ms ~25 ms até 10 Hz
5× UI1, bloco RT ~25 ms ~25 ms até 10 Hz
16× I3, RT + período ~400 ms 400 ms > 100 ms não consegue acompanhar o módulo (10 Hz); ~2 Hz na melhor das hipóteses
Nota

Os números acima são estimativas e dependem do MCU hospedeiro e do driver.

Regra: a 50 kHz, os limites confortáveis são 8–10× I3 ou 15–16× UI1 com sondagem a 5 Hz (a cada segunda janela do módulo), e cerca de metade disso a 10 Hz completos. Acima disso:

  • Reduza a taxa de sondagem (1 Hz = 10× de margem).
  • Passe a 100 kHz com repetição (espere NACKs frequentes e conte com a repetição).
  • Use o pino DRDY para o modo assíncrono — não consulte módulos que ainda não estejam prontos.

Sincronização de período — sincronizar períodos para uma sincronização apertada

Para a contabilização tarifária, todos os módulos têm de tirar o seu instantâneo no mesmo intervalo de tempo. Duas estratégias:

Latch sequencial de cada módulo, comparado com uma trama General-Call que faz o latch de todos os módulos de uma só vez.

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

C
/* Phase 1: sequential snapshot */
for (int i = 0; i < n; i++) {
    rbamp_latch_period(devs[i]);
}

/* Phase 2: shared settle (≥ 50 ms for the snapshot + ~1 commit cycle for witness) */
vTaskDelay(pdMS_TO_TICKS(50));

/* Phase 3: read snapshots with skip_latch=true */
rbamp_period_snapshot_t snaps[n];
for (int i = 0; i < n; i++) {
    rbamp_read_period_snapshot(devs[i], &snaps[i], 0, /*skip_latch=*/true);
}

Desfasamento entre módulos: 16 módulos × ~1 ms/instantâneo = ~16 ms em relação a um período de 60 segundos → 0.027%. Desprezável.

Estratégia 2 — instantâneo broadcast General-Call (requer ativação):

Todos os módulos recebem o instantâneo numa única trama I²C no endereço geral 0x00:

O layout da trama de instantâneo General-Call de 5 bytes enviada ao endereço 0x00.

Text
addr=0x00 | A5 27      (5 bytes)

Desvio = 0 (atómico). Pré-configuração:

  1. Em cada módulo ative REG_FLEET_CONFIG.bit0 = 1 via CMD_SAVE_USER_CONFIG.
  2. CMD_RESET — a receção GC é ativada no arranque.
  3. Após o reinício, o master envia a trama de 5 bytes.
  4. Testemunha: para cada módulo esperado, leia REG_V03_PERIOD_VALID (0x07). !=1 → recue para a estratégia 1.

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.

Filtragem por grupo GC — um barramento multi-inquilino

REG_GROUP_ID (0x28) permite ter vários domínios GC num só barramento:

  • group = 0x00 → chamada geral (all-call; todos os módulos com GC ativo tiram o instantâneo).
  • group = N → apenas os módulos com REG_GROUP_ID = N tiram o instantâneo.

Exemplo: um barramento com 10 módulos, em que precisa de instantâneos de 5 para a tarifa A e 5 para a tarifa B de forma independente:

Text
write REG_GROUP_ID = 1 on the 5 tariff-A modules
write REG_GROUP_ID = 2 on the 5 tariff-B modules

GC frame [A5 27 01 tl th] → only tariff A takes a snapshot
GC frame [A5 27 02 tl th] → only tariff B takes a snapshot
GC frame [A5 27 00 tl th] → all 10 take a snapshot (all-call)

Modos de falha num barramento multi-módulo

Sintoma Causa O que fazer
i2c bus scan mostra vários módulos no mesmo endereço após uma adição no terreno O novo módulo em 0x50 entra em conflito com um já endereçado Volte a gravar o novo endereço do módulo separadamente antes de o juntar ao barramento
Um módulo começa a dar NACK com mais frequência do que os outros Falha de cabo / queda de VCC nesse módulo Verifique VCC sob carga + níveis lógicos
Os Wh de um módulo divergem de forma consistente O temporizador próprio do módulo difere do relógio do master Integrar a energia em relação ao relógio mestre (master_dt_ms)
Após uma trama GC, um módulo não tira o instantâneo FLEET_CONFIG.bit0 = 0 ou desfasamento de grupo Verifique REG_FLEET_CONFIG e REG_GROUP_ID

Notas de conceção do barramento

  • Stretching do relógio: o firmware atual minimiza o stretch (a janela __disable_irq em LatchPeriod é curta, ~µs). O instantâneo em si não puxa o SCL de forma significativa. Para o Raspberry Pi BCM283x (um erro de hardware conhecido de clock-stretching): aplique a cautela habitual — já se recomendam 50 kHz + repetição.
  • Comprimento do barramento com mais de 4 módulos: mesmo num par entrançado a capacitância efetiva cresce linearmente com o número. Considere um buffer I²C (PCA9515) com ≥ 8 módulos + comprimento > 1 m.

Os cenários detalhados multi-módulo estão em 06 · Exemplos, nos cenários "Submedição em barramento partilhado" e "Instantâneo GC em difusão".

Pinagem na família ESP32

Os 7 chips listados no início deste capítulo são suportados (conforme idf_component.yml). Abaixo estão os pinos predefinidos recomendados para I²C; em implementações de produção, escolha o GPIO conforme o layout específico da sua placa.

ESP32 (original / DevKitC / WROOM)

Ligação de referência de um ESP32 a um módulo rbAmp, com a pinça na tomada I0.

C
const i2c_master_bus_config_t bus_cfg = {
    .i2c_port  = I2C_NUM_0,
    .sda_io_num = GPIO_NUM_21,
    .scl_io_num = GPIO_NUM_22,
    .clk_source = I2C_CLK_SRC_DEFAULT,
    .glitch_ignore_cnt = 7,
    .flags.enable_internal_pullup = true,
};
Pino GPIO
SDA GPIO21
SCL GPIO22
DRDY qualquer GPIO livre que não seja um pino de strapping (no ESP32 clássico evite GPIO0/2/12/15)

ESP32-S2

Os mesmos GPIO21/22 predefinidos do ESP32 original. O S2 não tem Bluetooth — fica disponível cerca de mais 30 kB de heap para cenários TLS.

ESP32-S3

O S3 não tem valores I²C fixos no hardware — qualquer GPIO através da matriz. Na maioria das placas de desenvolvimento WROOM-S3, GPIO8/GPIO9 são uma escolha cómoda (confirme o esquema da sua placa: no N16R8 estes pinos podem estar ocupados pela flash QSPI; o USB-JTAG usa GPIO19/20). Ajuste os campos sda_io_num / scl_io_num em i2c_master_bus_config_t:

C
.sda_io_num = GPIO_NUM_8,
.scl_io_num = GPIO_NUM_9,

O S3 tem USB-OTG — pode ser usado para depuração sem um chip USB-UART externo.

ESP32-C2 / C3 / C6 / H2

Chips single-core RISC-V (o C3 e o C6 são single-core; o H2 é single-core com BLE+802.15.4; o C2 é single-core com RAM limitada). Os pinos I²C não são fixos no hardware — aqui está um exemplo para o ESP32-C3 (na C3-SuperMini os GPIO5/GPIO6 são cómodos; na C3-DevKitM-1 o USB-JTAG ocupa os GPIO18/19, e os GPIO8/9 são de strapping):

C
const i2c_master_bus_config_t bus_cfg = {
    .i2c_port  = I2C_NUM_0,
    .sda_io_num = GPIO_NUM_5,
    .scl_io_num = GPIO_NUM_6,
    .clk_source = I2C_CLK_SRC_DEFAULT,
    .glitch_ignore_cnt = 7,
    .flags.enable_internal_pullup = true,
};

Para os outros chips — consulte a documentação ESP-IDF específica do alvo (docs.espressif.com → ESP-IDF v5.2+ → o seu chip → API reference → peripherals → I2C).

ESP32-P4 — não é um alvo suportado

O ESP32-P4 não está na lista de alvos suportados: o suporte ao P4 exige ESP-IDF v5.3+, enquanto o mínimo do componente é a v5.2 (um build v5.2 para esp32p4 falharia com "target esp32p4 not in idf").

Padrão de NACK de base do ESP32 — velocidade de barramento de 50 kHz

Com o driver i2c_master do ESP-IDF v5, o rbAmp apresenta NACKs frequentes a 100 kHz, muito menos a 50 kHz (uma característica do driver do lado do ESP32, e não do escravo). O componente cobre isto em duas camadas:

  1. Velocidade de barramento por omissão de 50 kHz através do Kconfig CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000. O componente pede esta frequência ao adicionar o seu handle de dispositivo ao barramento que criar.

  2. Repetição por byte — CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 × intervalo de 5 ms. A 50 kHz a taxa de erro residual é < 0.8%.

Se necessário, substitua via idf.py menuconfig:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5     # for dense workloads
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200

Para mais sobre o diagnóstico de problemas ao nível do barramento — veja 10 · Resolução de problemas.

DATA_READY (DRDY)

Um pino opcional para otimizar a sondagem. Se a aplicação sondar o módulo no máximo uma vez a cada 100 ms — o DRDY pode ficar desligado.

Parâmetros elétricos

  • Tipo de saída: dreno aberto (sem pull-up ativa para VCC)
  • Nível de repouso: HIGH (requer uma pull-up no lado do master — um gpio_pullup_en() interno ou uma resistência externa; recomenda-se 10 kΩ para 3.3 V)

  • Pulso de pronto: LOW durante ~10 µs depois de os registos RT terem sido atualizados com dados novos

  • Taxa de pulsos: ~10 Hz (um pulso por janela RT de ~100 ms)

Semântica

Uma transição descendente em DRDY garante que todos os registos RT estão sincronizados e publicados (o firmware atualiza-os de forma atómica na ISR antes de baixar o pino). Após a transição descendente, o mestre pode ler o bloco RT sem risco de obter uma amostra partida.

Padrão de interrupção — semáforo FreeRTOS

O ESP-IDF oferece um modelo limpo: uma ISR em IRAM levanta um semáforo binário, e uma tarefa FreeRTOS separada espera pelo semáforo e lê o RT.

C
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"
#include "driver/gpio.h"

#define DRDY_GPIO GPIO_NUM_4   /* a free GPIO; do not use
                                 * GPIO0/2/12/15 — strapping pins
                                 * (ESP32 classic), they can disrupt boot
                                 * if the open-drain DRDY goes LOW
                                 * during reset */
static SemaphoreHandle_t drdy_sem;

static void IRAM_ATTR drdy_isr_handler(void *arg) {
    BaseType_t hi_task_woken = pdFALSE;
    xSemaphoreGiveFromISR(drdy_sem, &hi_task_woken);
    if (hi_task_woken) portYIELD_FROM_ISR();
}

void bidir_task(void *arg) {
    rbamp_handle_t dev = arg;
    while (1) {
        if (xSemaphoreTake(drdy_sem, portMAX_DELAY) == pdTRUE) {
            float p;
            if (rbamp_read_power(dev, 0, &p) == ESP_OK) {
                /* integrate + publish */
            }
        }
    }
}

void app_main(void) {
    /* ...rbamp_new + rbamp_begin... */

    drdy_sem = xSemaphoreCreateBinary();

    /* The ISR service is installed ONCE for the whole project — if another
     * component (LCD, encoder, anything) has already installed it,
     * gpio_install_isr_service() returns ESP_ERR_INVALID_STATE.
     * This is normal, do not fail on it. ESP_INTR_FLAG_IRAM keeps the
     * ISR dispatcher in IRAM — important for the single-core C3/C6/H2/S2,
     * where non-IRAM code is unavailable while the flash cache is disabled. */
    esp_err_t err = gpio_install_isr_service(ESP_INTR_FLAG_IRAM);
    if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
        ESP_ERROR_CHECK(err);
    }

    gpio_config_t io_cfg = {
        .pin_bit_mask = 1ULL << DRDY_GPIO,
        .mode         = GPIO_MODE_INPUT,
        .pull_up_en   = GPIO_PULLUP_ENABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type    = GPIO_INTR_NEGEDGE,
    };
    gpio_config(&io_cfg);
    gpio_isr_handler_add(DRDY_GPIO, drdy_isr_handler, NULL);

    /* Priority 6 — above idle (0), below WiFi (23) and the standard
     * MQTT (5+). 4096 bytes of stack are enough for rbamp_read_* +
     * ESP_LOG; if you add an MQTT publish right in this task —
     * raise it to 6144. On dual-core ESP32/S3, for a clean
     * separation from the WiFi task (usually core 0), you can pin
     * this task to core 1: xTaskCreatePinnedToCore(..., 1).
     * On the single-core C3/C6/H2/S2 — keep xTaskCreate. */
    xTaskCreate(bidir_task, "bidir", 4096, dev, 6, NULL);
}

DRDY é opcional — a sondagem a qualquer taxa ≤ 10 Hz também funciona sem ele. O componente não depende de DRDY em nenhum dos seus caminhos.


Fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/04_hardware.md (v1.7.3)