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

09 · Referência da API

Mapa de registos do módulo: o espaço de endereços da página 0, de 0x00 a 0xFF.

Instantâneo de período atómico: uma escrita fecha o período atual e abre o seguinte.

A API pública da biblioteca RbAmp para Arduino a partir da v1.6.1. Uma só classe serve as duas linhas de produtos — BASIC e STANDARD (STD): begin() deteta a linha e cada chamada é encaminhada internamente. As chamadas que existem apenas numa linha estão assinaladas; uma chamada sem equivalente na linha detetada falha com RB_ERR_NOT_IMPLEMENTED. Fonte de verdade — os ficheiros de cabeçalho src/RbAmp.h, src/RbAmpSnapshot.h, src/RbAmpEnergy.h, src/RbAmpSensorModels.h, src/RbAmpRegisters.h (os dois últimos são gerados automaticamente e não devem ser editados à mão).

Este capítulo é uma referência: assinaturas, valores de retorno, efeitos secundários, casos-limite. Para exemplos de trabalho, ver 06 · Exemplos; para o arranque rápido, ver 05 · Arranque rápido.

Ficheiros de cabeçalho

Incluir O que traz
Todos os tipos públicos (inclui o resto)
RbAmpSnapshot, RbAmpPeriodSnapshot, RbAmpTopology, RbAmpVariant, RbAmpLine, RbAmpSensorClass, RbAmpSctRating, RbAmpDrdyEvent e as estruturas RbAmpStd* da linha STD
RbAmpEnergy
Registo gerado de modelos de sensores — os códigos de modelo RBAMP_CT_* e rbamp_sensor_model_lookup()
Constantes de protocolo geradas automaticamente — RB_OK, RB_ERR_*, SETTLE_MS_*

Um sketch do utilizador precisa normalmente apenas de #include — o resto é incluído de forma transitiva.

Em que linha funciona uma chamada?

Grupo BASIC STD
Ciclo de vida, leituras em tempo real (readVoltage … readAll), medição por período, energy() sim sim
readReactivePower(), readApparentPower() não (RB_ERR_NOT_IMPLEMENTED) sim
Setters de classe do sensor / modelo de TC, saveUserConfig(), alteração de endereço, reset() sim sim (o modelo de TC é uma etiqueta no STD, ver abaixo)
factoryReset(), auxiliares General-Call, auxiliares de etiqueta, readCapability(), readCommitSeq(), readPeriodLatchMs() sim não (RB_ERR_NOT_IMPLEMENTED)
Linha de dados pronta e eventos (setDrdyPin(), waitDataReady(), setEventMask() …) sim sim (depende da imagem do módulo, ver abaixo)
chamadas std* (API da linha STD) não (RB_ERR_NOT_IMPLEMENTED) sim
Correção de calibre SCT-013 (sctRating*()) sim (classe SCT-013, firmware BASIC mais antigo) nunca aplicado (escala 1)

Algumas funcionalidades do STD dependem da versão da imagem do módulo: contadores de micro-energia, a corrente inicial para energia, os ângulos de fase da tensão e a sequência de fases exigem uma imagem de pelo menos 0x0001007B (stdReadImageVersion()). Numa imagem mais antiga a biblioteca reporta-as como "não disponíveis" (uma flag valid a false, um valor derivado, ou RB_ERR_NOT_IMPLEMENTED) — nunca como um número errado.

Classe RbAmp

O cliente principal. Uma instância por dispositivo escravo no barramento I²C. Várias instâncias podem partilhar um único barramento TwoWire para consultar vários módulos.

Construtor

C++
explicit RbAmp(TwoWire& bus,
               uint8_t addr = 0x50,
               RbAmpTopology hint = RbAmpTopology::Single) noexcept;
Parâmetro Descrição
bus Referência para o barramento TwoWire (normalmente Wire). O chamador tem de chamar bus.begin() ANTES de begin().
addr Endereço escravo de 7 bits. Intervalo 0x08..0x77, predefinido 0x50.
hint Sugestão de topologia: o número de canais de corrente (1/2/3). No firmware anterior à v1.3 o begin() não consegue determinar a variante de forma fiável, por isso a sugestão é usada como alternativa para SKU multicanal. Predefinição Single — a predefinição segura, que não dispara leituras espúrias de canais ausentes. Para módulos multicanal em firmware anterior à v1.3, passe explicitamente a sugestão correspondente.

O construtor não gera tráfego I²C.

Métodos do ciclo de vida

bool begin() noexcept

Sonde o dispositivo, detete a sua linha de produto e variante, prepare o instantâneo.

Sequence:

  1. Sondagem de identidade STD primeiro. Se o módulo responder como módulo STD, as contagens de canais vêm do próprio módulo, o banco de instantâneos 0 é armado e preparado, e begin() devolve — os passos BASIC abaixo são ignorados.

  2. Leia REG_VERSION (0x03). Se o dispositivo não fez ACK — false com RB_ERR_NACK. Se devolveu 0x00 / 0xFF — false com RB_ERR_VERSION.

  3. Guarde em cache a topologia: o byte de variante do módulo no firmware que o expõe; caso contrário, a sugestão hint do construtor. Depois disto, topology() / channels() devolvem valores válidos sem tocar no barramento. O número de canais nunca excede RBAMP_MAX_CHANNELS (7); os canais acima disso não são expostos e endereçá-los devolve RB_ERR_PARAM.

  4. Leia U_rms para determinar se existe um sensor de tensão (limiar 1.0 V).

  5. Escreva CMD_LATCH_PERIOD como preparação + aguarde 50 ms. O primeiro instantâneo após o arranque é descartado (não é entregue ao código do utilizador — mistura dados anteriores ao arranque).

  6. Guarde millis() para a integração de energia subsequente.

  7. Num módulo BASIC com a classe SCT-013, leia a correção de calibre por canal (ver correção de calibre SCT-013). Se o módulo estiver no estado que exige um reinício para aplicar o ganho correto, begin() reinicia-o uma vez.

Idempotente: seguro chamar de novo.

Devolve: true em caso de sucesso; false caso contrário — ver lastError() para detalhes.

bool probe() noexcept

Uma verificação leve de vida. Uma única leitura de REG_VERSION sem efeitos colaterais.

Devolve: true se o escravo respondeu com ACK e reportou uma versão suportada (nem 0 nem 0xFF).

bool waitReady(uint32_t timeout_ms = 1000) noexcept

Consulta a flag de prontidão do módulo até o bit 0 ficar ativo. Útil após ligar — o módulo pode precisar de até uma janela de medição (100 ms) para confirmar os primeiros dados.

Devolve: true se o bit foi visto antes de timeout_ms expirar; false com RB_ERR_TIMEOUT caso contrário.

uint8_t firmwareVersion() noexcept

Devolve: o byte REG_VERSION (0x03). Valores BASIC conhecidos: 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2, 0x04 = v1.3. Firmwares BASIC posteriores reportam valores mais altos. 0 ou 0xFF indicam um erro I²C (ver lastError()).

RbAmpLine line() const noexcept

Devolve: a linha de produto detetada por begin() — RbAmpLine::Basic (o valor até begin() ser executado) ou RbAmpLine::Std. Sem acesso ao barramento.

RbAmpTopology topology() const noexcept

Devolve: a topologia em cache. Sem acesso ao barramento.

uint8_t channels() const noexcept

Devolve: o número de canais de corrente, 1..RBAMP_MAX_CHANNELS (7). Na linha STD a contagem é a que o módulo reporta, limitada a RBAMP_MAX_CHANNELS.

bool hasVoltageHw() const noexcept

Devolve: true se um sensor de tensão foi detetado em begin(). Em cache, sem tráfego.

uint8_t address() const noexcept

Devolve: o endereço I²C de 7 bits atual. Atualizado após um commitAddressChange() bem-sucedido.

uint8_t rawTopology() noexcept

Uma leitura direta de REG_TOPOLOGY (0x24). Ao contrário de topology(), esta faz uma transação I²C.

Returns:

  • 1/2/3 — SINGLE/SPLIT_PHASE/THREE_PHASE.
  • 0xFF — erro I²C.
Nota

Para a deteção completa de SKU use readVariant() (lê REG_HW_VARIANT 0x55) — ver Identificação e provisionamento.

Leituras em tempo real (bloco RT, atualização de 100 ms)

Temporização da janela em tempo real: janelas de 100 ms seguidas, um impulso DRDY curto por janela e o bloco de resultado atómico lido numa só rajada.

Todos os métodos devolvem float. Em caso de erro devolvem NAN e definem lastError(). Por baixo, usa-se repetição + filtro de sanidade para robustez contra falhas raras de ligação no ESP-IDF (ver os contadores de diagnóstico abaixo). O módulo publica novos valores uma vez por janela de medição — 100 ms (firmware BASIC anterior à v1.2 e imagens STD até 0x7B: 200 ms).

float readVoltage(uint8_t phase = 0) noexcept

Tensão RMS instantânea. phase é 0 na linha BASIC; na linha STD é 0 .. n_voltage-1 (ver stdInfo()). Uma fase fora do intervalo devolve NAN com RB_ERR_PARAM.

float readVoltagePeak(uint8_t phase = 0) noexcept

Tensão de pico na janela RT. Mesma regra de phase.

float readCurrent(uint8_t ch = 0) noexcept

Corrente RMS instantânea num canal. ch tem de ser < channels() — caso contrário, NAN com RB_ERR_PARAM. Inclui qualquer canal igual ou superior a RBAMP_MAX_CHANNELS (7).

float readCurrentPeak(uint8_t ch = 0) noexcept

Corrente de pico num canal na janela RT.

float readPower(uint8_t ch = 0) noexcept

Potência ativa instantânea num canal. Com sinal — um valor negativo significa exportação (a carga devolve potência à rede; relevante em instalações FV / bidirecionais).

float readPowerFactor(uint8_t ch = 0) noexcept

Fator de potência num canal. Adimensional, intervalo −1..+1.

float readReactivePower(uint8_t ch = 0) noexcept — apenas STD

Potência reativa num canal, em var, com sinal. No BASIC, a potência reativa não é exposta por esta biblioteca: a chamada devolve NAN com RB_ERR_NOT_IMPLEMENTED.

float readApparentPower(uint8_t ch = 0) noexcept — apenas STD

Potência aparente num canal, em VA. Num módulo BASIC devolve NAN com RB_ERR_NOT_IMPLEMENTED.

float readFrequency() noexcept

Frequência da rede, em Hz.

bool readAll(RbAmpSnapshot& out) noexcept

O bloco RT completo numa única chamada, para uma estrutura RbAmpSnapshot. Equivalente a readVoltage() + readVoltagePeak() sequenciais

  • readCurrent(0..N) + readCurrentPeak(0..N) + readPower(0..N) + readPowerFactor(0..N) + readFrequency(). Os canais não utilizados (para além de channels()) são preenchidos com zeros.

Um único campo que é lido mas falha o filtro de sanidade física é definido como NAN e assinalado em out.implausible (bits RBAMP_FIELD_*); o resto do instantâneo continua utilizável.

Devolve: true a menos que uma leitura de transporte tenha falhado — nesse caso false e lastError() guarda o código do primeiro erro.

Medição por período

Veja 01 · Visão geral para o panorama geral e o passo 5 de 05 · Início rápido para um modelo mínimo.

bool latchPeriod() noexcept

Escreve CMD_LATCH_PERIOD (0x27) em REG_COMMAND. Não aguarda — quem chama tem de observar ele próprio a estabilização de 50 ms e verificar isPeriodValid() antes de ler.

Para a maioria das tarefas use readPeriodSnapshot() — encapsula a sequência completa.

Devolve: true numa escrita bem-sucedida.

bool isPeriodValid() noexcept

Lê o bit de prontidão do instantâneo. true se o último instantâneo estiver atualizado e pronto a ler.

float readPeriodAvgPower(uint8_t ch = 0) noexcept

Potência ativa média num canal ao longo do período fechado. Deve ser chamada após latchPeriod() + 50 ms de estabilização + verificação de validade.

float readPeriodMaxPower() noexcept

Potência instantânea de pico no canal 0 durante o período fechado.

uint32_t readPeriodLatchMs() noexcept

Duração do período do ponto de vista do dispositivo, em ms.

Valor de diagnóstico.

latch_ms é um temporizador de diagnóstico do módulo; não o use para energia — use o relógio do mestre (master_dt_ms de RbAmpPeriodSnapshot).

bool readPeriodSnapshot(RbAmpPeriodSnapshot& out, uint16_t settle_ms = 50, bool skip_latch = false) noexcept

O ponto de entrada recomendado para a medição por período. A sequência completa por baixo:

  1. Se skip_latch == true — salta a escrita do comando de instantâneo (aplica-se após broadcastLatch() ou uma série manual de comandos de instantâneo).

  2. Caso contrário — escreva CMD_LATCH_PERIOD.

  3. Capture millis() para calcular master_dt_ms.
  4. delay(settle_ms) — 50 ms por predefinição, segundo a especificação do protocolo.

  5. Verifique a flag de prontidão do instantâneo. Se for 0 — defina RB_ERR_STALE e registe o carimbo de tempo (para que o próximo instantâneo não faça dupla contagem por dt).

  6. Leia avg_p[0..channels-1] + max_p + latch_ms.

  7. Atualize o carimbo temporal + chame energy().tick(out, channels_) para a integração automática de Wh.
Parâmetro Descrição
out Estrutura de saída.
settle_ms Aguardar após o comando de instantâneo; 50 por predefinição.
skip_latch Se true — não envie o comando de instantâneo, leia apenas (para uma cena multi-placa sincronizada).

Devolve: true se out.valid == true; false se a leitura falhou ou o instantâneo está desatualizado.

Na linha STD a estabilização após um instantâneo é elevada para pelo menos 300 ms (o módulo atende o instantâneo na próxima fronteira de janela de medição), latch_ms é 0 e master_dt_ms é o período. Num módulo STD que mantém contadores de energia de vida persistidos em vez de bancos de instantâneos, o período é a diferença de duas leituras de contadores no calendário do mestre; avg_p_total, wh_net e module_restarted do instantâneo são preenchidos aí.

Medição de energia (acumulador do lado do master)

RbAmpEnergy& energy() noexcept

const RbAmpEnergy& energy() const noexcept

Acesso ao acumulador Wh por canal detido por esta instância de RbAmp. O acumulador é atualizado automaticamente em cada readPeriodSnapshot() bem-sucedido. Para detalhes veja a secção "classe RbAmpEnergy" abaixo.

double energyWh(uint8_t ch = 0) const noexcept

O total corrente de energia de um canal, como energy().wh(ch) — exceto num módulo STD que mantém contadores persistidos mas não publica a divisão por canal (mais de um canal, mapa de registos mais antigo): um pedido por canal devolve aqui NaN em vez de um 0 que se leria como "nada consumido". Use RBAMP_ENERGY_CH_TOTAL como ch para o total de todos os canais.

Configuração do sensor

Uma sequência em dois passos: primeiro a classe do sensor, depois o modelo. Ambos os passos são obrigatórios no firmware BASIC v1.2 e posteriores.

Para um guia detalhado de seleção de modelo veja 03 · Seleção do sensor de corrente.

Nota

Modelo de TC — uma predefinição funcional no BASIC, uma etiqueta no STD. Num módulo BASIC, escrever o modelo de TC aplica de imediato a predefinição correspondente — as leituras de corrente mudam. Alterar o RbAmpSensorClass repõe os modelos de TC dos canais a 0 no módulo. Num módulo STD o modelo é apenas uma referência (etiqueta do sensor): não define ganho, porque o módulo é calibrado por canal.

Ler antes de escrever. Os setters leem primeiro o módulo. Escrever uma classe ou modelo que o módulo já tem é uma operação vazia (true, sem escrita no barramento, sem ciclo de flash), pelo que uma configuração guardada pode ser reaplicada em cada arranque sem tocar na calibração do módulo. Um módulo de classe WiredCT ou BuiltinCT (fornecido e calibrado em conjunto com o seu sensor) não é reconfigurado: o setter devolve false com RB_ERR_MODE e não escreve nada. setCTModelChForce() é o caminho de assistência.

Definir um modelo de TC reinicia o módulo. No firmware BASIC até 1.4.19 com a classe SCT-013, setCTModel() (ambas as formas) e configureChannels() reiniciam o módulo após a gravação para que o novo modelo tenha efeito (cerca de um segundo no total, com bloqueio), e depois releem a correção de calibre. Não as chame em ciclo e não espere leituras durante esse tempo.

bool setSensorClass(RbAmpSensorClass cls) noexcept

Defina a classe do sensor de corrente com uma gravação na memória flash.

Sequência: ler a classe atual do módulo (ler antes de escrever) → escrever REG_SENSOR_CLASS (0x25) → CMD_SAVE_USER_CONFIG (0x32) → aguardar 700 ms (apagamento da flash). Bloqueante. Aprovado para produção — SAVE_USER_CONFIG não é controlado.

Tem de ser chamado antes de setCTModel(). Caso contrário, setCTModel() devolve false com RB_ERR_PARAM. Também repõe os modelos de TC a 0 do lado do dispositivo, pelo que defina os modelos depois. No STD a classe é metadados, persistida com a gravação de configuração do módulo, e aplicam-se as mesmas regras de ler-antes-de-escrever.

Argumento Significado
RbAmpSensorClass::Sct013 Pinça da série SCT-013 montada pelo utilizador; o modelo seleciona o tipo de sensor
RbAmpSensorClass::WiredCT TC ligado de fábrica fornecido com o módulo e calibrado em conjunto com ele — não é reescrito pelos setters
RbAmpSensorClass::BuiltinCT TC integrado, calibrado em conjunto com o módulo — não reescrito pelos setters

Devolve: true em caso de sucesso, ou quando o módulo já tem cls. false com RB_ERR_MODE quando o módulo é da classe WiredCT / BuiltinCT.

bool readSensorClass(uint8_t& out) noexcept

Lê a classe de sensor de corrente do módulo (um valor RbAmpSensorClass; 0 = não definida). Funciona em ambas as linhas.

Devolve: true em caso de sucesso.

bool setCTModel(uint8_t code) noexcept

A forma de parâmetro único — define o modelo de TC da pinça apenas no canal 0. Prática para SKUs de canal único (UI1/I1); em SKUs multicanal é equivalente a setCTModel(0, code).

Sequência: escrever REG_CT_MODEL (0x05) → CMD_SET_CT_MODEL_CH0 (opcode 0x28) → estabilização de 5 ms → CMD_SAVE_USER_CONFIG (opcode 0x32) → 700 ms. Aprovado para produção — usa o caminho de gravação da configuração do utilizador, sem controlo do modo de fábrica.

Nomeie o modelo com a define RBAMP_CT_* gerada (de RbAmpSensorModels.h), por exemplo RBAMP_CT_SCT013_030:

Definir code Modelo
RBAMP_CT_SCT013_005 1 SCT-013-005
RBAMP_CT_SCT013_010 2 SCT-013-010
RBAMP_CT_SCT013_030 3 SCT-013-030
RBAMP_CT_SCT013_050 4 SCT-013-050
RBAMP_CT_SCT013_100 5 SCT-013-100
RBAMP_CT_SCT013_020 6 SCT-013-020
RBAMP_CT_SCT013_060 7 SCT-013-060

Um code que não está no registo para a classe do módulo → false com RB_ERR_PARAM e sem escrita. Um código que está no registo mas que o módulo não aceita é rejeitado pelo módulo com RB_ERR_PARAM; o canal mantém o modelo anterior. Para o conjunto completo aceite por classe, ver 03 · Seleção do sensor de corrente.

Para módulos multicanal use a forma por canal abaixo.

bool setCTModel(RbAmpCTModel model) noexcept

Sobrecarga com enumeração tipada para os sete códigos SCT-013 (RbAmpCTModel::Sct013_030 …). Equivalente a setCTModel(static_cast(model)). Mantida por compatibilidade com versões anteriores; o código novo passa uma define RBAMP_CT_* gerada à forma uint8_t, que é a única forma de designar um modelo de TC ligado por fio.

bool setCTModel(uint8_t channel, uint8_t code) noexcept

A forma por canal. Define o modelo da pinça de TC num canal específico, 0 .. channels()-1 (os canais 3 e seguintes são os canais do SKU superior; exigem firmware BASIC v1.4.18 ou posterior).

Por baixo: escreva REG_CT_MODEL (0x05) → comando CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) conforme channel → estabilização de 5 ms → CMD_SAVE_USER_CONFIG (opcode 0x32) → 700 ms. Aprovado para produção — o caminho de gravação da configuração do utilizador é o canal de persistência de produção para ct_model / sensor_class / TC por canal. Os canais 3 e superiores são associados através da janela de canais e lidos de volta; um modelo que o módulo rejeite é reportado como RB_ERR_PARAM. No firmware anterior à v1.2 a chamada devolve RB_ERR_VERSION.

Nota

A ordem das chamadas é arbitrária na v1.3. Escrever REG_CT_MODEL (0x05) apenas prepara um valor — não é aplicado automaticamente ao canal 0. A aplicação faz-se exclusivamente através do opcode por canal CMD_SET_CT_MODEL_CHn (0x28 / 0x29 / 0x2A), que copia o valor preparado para o seu canal. Os canais podem, portanto, ser configurados em qualquer ordem — ascendente, descendente ou intercalada — sem sobreposição:

C++
dev.setCTModel(0, RBAMP_CT_SCT013_005);   // channel 0
dev.setCTModel(1, RBAMP_CT_SCT013_030);   // channel 1
dev.setCTModel(2, RBAMP_CT_SCT013_020);   // channel 2

Após uma associação multicanal, confirme o resultado com readCTModelCh(). Para uma configuração em lote, com uma só gravação, de todos os canais, prefira configureChannels().

Guarda RB_ERR_PARAM na pré-condição de setSensorClass(), igual à forma de parâmetro único. Um canal igual ou superior a channels() (e, portanto, qualquer canal acima de RBAMP_MAX_CHANNELS) → RB_ERR_PARAM. Aplicam-se a leitura-antes-de-escrita e a recusa RB_ERR_MODE como descrito acima. Na linha STD o modelo é uma etiqueta escrita na entrada do canal, lida de volta e persistida com a gravação de configuração do módulo; sem efeito secundário no canal 0.

Devolve: true em caso de sucesso, ou quando o canal já tem code.

bool setCTModel(uint8_t channel, RbAmpCTModel model) noexcept

Sobrecarga tipada (enum) da forma por canal (apenas códigos SCT-013).

bool setCTModelChForce(uint8_t channel, uint8_t code) noexcept

Caminho de assistência técnica. Igual a setCTModel(channel, code), mas escreve independentemente da classe do módulo e do modelo que o canal tem atualmente. Substitui a calibração emparelhada desse canal pelo predefinido genérico do modelo — use apenas ao voltar a emparelhar um módulo com um novo sensor em assistência técnica, e siga com uma calibração. Um código ausente do registo continua a ser rejeitado (RB_ERR_PARAM, sem escrita).

Devolve: true em caso de sucesso.

bool readCTModelCh(uint8_t channel, uint8_t& out) noexcept

Lê o modelo de TC efetivamente aplicado a um canal (a leitura de verificação do predefinido associado). Use-o para confirmar que a associação foi feita. out = 0 significa não definido.

Devolve: true em caso de sucesso.

Registo de sensores — sensorModel() / sensorModelRatedA()

Consultas puras no registo gerado (RbAmpSensorModels.h). Sem tráfego no barramento. Um resultado no registo não significa que o módulo ligado aceite o código — isso é decidido pelo módulo no momento da escrita.

C++
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(uint8_t cls, uint8_t code) noexcept;
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(RbAmpSensorClass cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(uint8_t cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(RbAmpSensorClass cls, uint8_t code) noexcept;

sensorModel() devolve a entrada do registo ou nullptr se (class, code) não constar do registo. A entrada (rbamp_sensor_model_info_t) contém sensor_class, code, name, descriptor, status (caracterizado / reservado / legado) e os limites atuais nominal_a (corrente eficaz nominal), fs_a (corrente eficaz no início do corte para uma sinusoide) e peak_a (teto instantâneo de corte). 0 num limite = desconhecido para esse modelo.

sensorModelRatedA() devolve a corrente eficaz nominal em amperes (0 = desconhecida). Abrange a família SCT-013 e os modelos de pinça que indicam uma classificação; os códigos antigos de toroide / carga devolvem 0.

C++
float rated = RbAmp::sensorModelRatedA(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
const rbamp_sensor_model_info_t* m = RbAmp::sensorModel(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
if (m) Serial.println(m->descriptor);

Correção da classificação do SCT-013

No firmware BASIC até 1.4.19, um módulo da classe SCT-013 é calibrado com o SCT-013-030 e, após um reinício, aplica esse ganho calibrado seja qual for o modelo que um canal indique. A biblioteca compensa: begin() lê o modelo e o ganho aplicado de cada canal e define uma escala por canal. A escala é aplicada a readCurrent(), readCurrentPeak(), readPower(), readAll(), readPeriodAvgPower(), readPeriodMaxPower() e readPeriodSnapshot() — e, por consequência, à energia derivada deles. O fator de potência e a tensão não são alterados. Os limites de plausibilidade e setEventThresholds() são expressos em amperes e watts reais.

Assim, mudar a classificação do SCT-013 (por exemplo de 030 para 050) corrige automaticamente a corrente, a potência e a energia; não altera U nem PF. O firmware 1.4.20 e posteriores corrige-se sozinho — a escala fica 1 e uma escrita de modelo não exige reinício. Os módulos STD e as classes de TC cabeados / integrados nunca são escalados.

bool sctRatingRefresh() noexcept

Relê o estado de classificação de cada canal a partir do módulo. A biblioteca já faz isto depois de readEventFlags() indicar EVENT_RESET_OCCURRED; chame-o você mesmo após um reinício do módulo que detete de outra forma.

Devolve: true quando o módulo pôde ser lido.

bool sctRating(uint8_t channel, RbAmpSctRating& out) noexcept

Estado de um canal: model, applied_gain, noise_floor, scale e status.

Devolve: true se channel for válido.

RbAmpSctRatingStatus Significado
NotApplicable linha STD, uma classe diferente de SCT-013, firmware que se corrige a si próprio, ou modelo não definido — escala 1
Native o canal mostra o modelo com que o módulo foi calibrado (030) — nada a corrigir, escala 1
Corrected outro modelo de SCT-013 em firmware BASIC mais antigo — as leituras são escaladas
Uncalibrated o módulo aplica uma predefinição genérica sem ajuste próprio — apenas correção nominal
UnexpectedGain o ganho aplicado não é o que a correção espera — nada é assumido, escala 1
Unknown o estado não pôde ser lido — escala 1
float sctRatingScale(uint8_t channel) const noexcept

O fator aplicado às leituras de corrente / potência desse canal (1.0 quando nada é corrigido, e para um índice de canal além de RBAMP_MAX_CHANNELS).

static float sctPresetGain(uint8_t model) noexcept

O valor de ganho predefinido da biblioteca para um código de modelo SCT-013; 0 se desconhecido. Útil sobretudo para diagnóstico.

bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept

Ver Configuração multicanal.

bool saveGains() noexcept — apenas em modo de fábrica no BASIC

Uma escrita CMD_SAVE_GAINS (0x26) «simples» — o caminho de persistência de fábrica para os coeficientes de calibração (ganhos / piso de ruído / fase).

Segurança

⚠ Apenas de fábrica no BASIC. BLOQUEADO em produção. Num módulo BASIC de produção o CMD_SAVE_GAINS é rejeitado pelo firmware — a chamada devolve false, REG_ERROR fica com DEV_ERR_PARAM (0xFE), e o próximo reinício reverte as escritas apenas em RAM. Para toda a persistência voltada ao utilizador (classe do sensor, modelo de TC por canal, endereço, configuração da frota, etiqueta) use saveUserConfig() (CMD_SAVE_USER_CONFIG, opcode 0x32) — esse é o caminho de persistência aprovado para produção. O código do utilizador num contexto de implementação não deve chamar saveGains().

Linha STD: saveGains() emite a gravação de calibração do módulo, aguarda até o módulo indicar que o comando terminou e verifica o seu veredicto. O módulo escreve o seu armazenamento no máximo uma vez a cada 5 s; uma gravação dentro dessa janela é repetida uma vez após 5 s.

Devolve: true num comando bem-sucedido (produção BASIC: sempre false com RB_ERR_MODE).

bool prepareAddressChange(uint8_t new_addr) noexcept

Passo 1 de 2 para alterar o endereço I²C do módulo. Adequado a produção no firmware atual (commit em duas fases da v1.3, sem bloqueio de modo de fábrica para o endereço).

Sequência: valide o intervalo de new_addr (0x08..0x77, ≠ atual) → escreva o candidato em REG_I2C_ADDRESS (0x30) em RAM → escreva o valor mágico 0xA5 em REG_ADDR_COMMIT_MAGIC (0x31) — armado. O chamador tem de chamar commitAddressChange() em 5 segundos, caso contrário o armamento expira.

Devolve: true se armado com sucesso.

bool commitAddressChange() noexcept

Passo 2 de 2. Tem de ser chamado no prazo de 5 segundos após prepareAddressChange().

Sequência: verificar a atualidade do estado armado → CMD_COMMIT_ADDR (opcode 0x30) → persistir na flash → CMD_RESET (0x01) → ~300 ms do arranque até responder → atualizar o campo de endereço interno. Depois disto, todas as chamadas a esta instância endereçam o novo endereço.

Segurança

⚠ Nova enumeração após o commit. Após um commit bem-sucedido o dispositivo reinicia e volta a enumerar-se no NOVO endereço. As chamadas seguintes a esta instância de RbAmp usam o novo endereço de forma transparente — mas qualquer OUTRO master no barramento (um script Python, um componente ESP-IDF noutro MCU, uma sonda de depuração) continuará a pensar que o dispositivo está no endereço antigo até o seu estado interno ser atualizado manualmente.

⚠ Caminho de verificação (v1.3): após o reinício, REG_I2C_ADDRESS (0x30) lê o endereço ativo. Uma pesquisa no barramento no novo endereço também serve para confirmar a gravação.

A alteração de endereço é uma operação de produção (não exclusiva de fábrica). O endereço I²C — o caminho documentado é a reconfiguração através da bancada de fábrica (fora do âmbito da biblioteca).

Uma nota adicional para commitAddressChange():

Segurança

⚠ Reinício e nova enumeração após o commit. Após um commit bem-sucedido o dispositivo reinicia e volta a enumerar-se no NOVO endereço. As chamadas seguintes a esta instância de RbAmp usam o novo endereço de forma transparente — mas qualquer OUTRO master no barramento (um script Python, um componente ESP-IDF, uma sonda de depuração) continuará a pensar que o dispositivo está no endereço antigo até o seu estado interno ser atualizado manualmente.

Se a janela de armação expirou, commitAddressChange() devolve false com RB_ERR_TIMEOUT e limpa o flag de armação — será necessário um novo prepareAddressChange().

Devolve: true em caso de sucesso.

Linha STD: o campo de endereço é escrito e guardado (a chamada aguarda que a gravação termine; um endereço rejeitado devolve RB_ERR_PARAM e o módulo mantém o seu endereço), depois o módulo é reiniciado. A instância só passa para o novo endereço quando o módulo responder aí (até 3 s). Se voltar no endereço ANTIGO, a instância fica nele e é devolvido RB_ERR_NOT_READY.

bool factoryReset() noexcept

O comando CMD_FACTORY_RESET (0xAA) + espera de 1500 ms.

Segurança

⚠ Operação destrutiva. Apaga TODOS os parâmetros da flash (modelo de TC, classe do sensor, coeficientes de calibração, endereço I²C). O módulo volta aos valores de fábrica — RbAmpSensorClass passa a Unset, REG_CT_MODEL passa a 0. Qualquer definição aplicada antes por setSensorClass() / setCTModel() desaparece. O próximo utilizador TEM de voltar a aplicar setSensorClass() e setCTModel() antes de a medição voltar a funcionar. Não é um "reinício suave" — para um reinício suave use reset(). factoryReset() está reservado para recuperar de um estado conhecido como defeituoso ou para entregar o módulo a outro utilizador / outra instalação.

Devolve: true numa escrita de comando bem-sucedida.

Linha STD: não há equivalente — a chamada devolve false com RB_ERR_NOT_IMPLEMENTED.

bool reset() noexcept

O comando CMD_RESET (0x01) + aguardar 100 ms. Um reinício suave do dispositivo sem perder os parâmetros da flash.

Devolve: true numa escrita de comando bem-sucedida.

Linha STD: aguarda primeiro por qualquer comando em execução (um módulo nunca é reiniciado a meio de uma gravação), depois aguarda em silêncio (até 3 s) que o módulo volte a responder e rearma o caminho do período.

Barramento com vários módulos (estático)

static bool broadcastLatch(TwoWire& bus) noexcept

Envia um instantâneo de difusão por Chamada Geral I²C (A5 27 00 tick_lo tick_hi para o endereço 0x00) — todos os módulos com GC ativa tiram o instantâneo do período em simultâneo. No firmware v1.3 a GC é suportada como capacidade opt-in: ativação por módulo através de REG_FLEET_CONFIG.bit0 (desligada por predefinição); o mapa de capacidades do módulo indica se suporta o instantâneo por Chamada Geral. A Chamada Geral é uma funcionalidade da linha BASIC (as funções de Chamada Geral e de etiquetas devolvem RB_ERR_NOT_IMPLEMENTED numa instância STD).

Semântica de retorno:

  • Firmware v1.3, GC ativo em pelo menos um módulo — devolve true, a frota tira o seu instantâneo em sincronia (desvio < 1 ms entre módulos).

  • Firmware v1.3, GC desativado em todos os módulos — Wire.endTransmission() para 0x00 recebe NACK ao nível do barramento → devolve false. Correção: ativar o GC por módulo via enableGc(true) (escreve FLEET_CONFIG.bit0 + SAVE_USER_CONFIG + reinício), ou usar RbAmpFleet::enableGcAll().

  • Firmware legado sem suporte a Chamada Geral — devolve false sem tocar no barramento. Recorra a uma série sequencial de latchPeriod() em cada dispositivo — ver 06 · Exemplos, a secção do barramento com vários módulos.

Diagnóstico

int8_t lastError() const noexcept

Devolve: o código do último erro — RB_OK (0) ou um dos valores RB_ERR_* (negativos). A tabela completa está na secção «Códigos de erro» abaixo + 10 · Resolução de problemas.

static const char* errorString(int8_t code) noexcept

Devolve: uma string constante com a descrição legível do código de erro. Nunca devolve NULL.

void setLogStream(Stream* stream) noexcept

Um destino opcional de diagnóstico. Se definido, a biblioteca regista brevemente os resultados de probe(), instantâneos desatualizados e rejeições de modo. Passe nullptr para o desligar. Desligado por predefinição.

Utilização típica:

C++
dev.setLogStream(&Serial);

uint32_t retryExhaustionCount() const noexcept

Quantas vezes desde a alimentação (ou desde o último resetCounters()) o ciclo de repetição se esgotou durante uma única leitura de um byte. O valor em regime estável é 0. Um valor diferente de zero indica problemas de ligação (ver 10 · Resolução de problemas).

uint32_t sanityRejectCount() const noexcept

Quantos valores float em bruto foram rejeitados pelo filtro de sanidade (!isfinite(x) || |x| > 10000). Em regime estável — 0. Um valor diferente de zero após a mitigação por repetição indica normalmente um artefacto raro da pilha I²C do ESP-IDF que sobreviveu à camada de repetição.

void resetCounters() noexcept

Coloque ambos os contadores a zero. Use-o no início de um teste de resistência ou de uma janela de regressão para medir apenas os eventos dentro da janela.

const char* errorString() const noexcept

Atalho de instância para errorString(lastError()). Nunca devolve NULL.

bool readCommitSeq(uint8_t& out) noexcept — apenas BASIC

Lê o byte de sequência de commit do módulo. O módulo incrementa-o uma vez por janela de medição publicada (100 ms no firmware v1.2+, 200 ms antes), dando a volta de 255→0. Amostre-o antes e depois de uma leitura de vários registos para detetar que os valores publicados avançaram a meio da leitura. É apenas um indicador de alteração — não há CRC. Numa instância STD a chamada falha com RB_ERR_NOT_IMPLEMENTED (use readDataSeq()).

Devolve: true em caso de sucesso.

Identificação e provisionamento (v1.3)

Estes métodos permitem ao mestre perceber exatamente o que está ligado ao barramento (variante, mapa de bits de capacidades, UID, etiqueta) e preparar um módulo novo ou recém-gravado para funcionar (provisionamento + gravação da configuração na flash).

RbAmpVariant readVariant() noexcept

Lê o registo HW_VARIANT (0x55) do módulo e devolve um RbAmpVariant:

Valor SKU Canais I Canal U
UI1 (1) UI1 1 sim
UI2 (2) UI2 2 sim
UI3 (3) UI3 3 sim
I1 (4) I1 1 não
I2 (5) I2 2 não
I3 (6) I3 3 não
UI5 (7) UI5 (SKU superior) 5 sim
UI7 (8) UI7 (SKU sénior) 7 sim
Unknown (0) não identificado (firmware v1.0/v1.1, falha de I²C, ou não é um rbAmp) — —
Segurança

A deteção automática da variante via readVariant() é o caminho recomendado. A sugestão de topologia do construtor mantém-se como alternativa para firmware anterior à v1.2 (onde HW_VARIANT não está disponível). Sugestão predefinida = RbAmpTopology::Single — segura, não dispara leituras espúrias de canais ausentes em UI1/I1.

bool readCapability(uint16_t& out) noexcept — apenas BASIC

Lê o mapa de funcionalidades de 16 bits do módulo. Ramifique pelas constantes de capacidade com nome de RbAmpRegistersV2.h (namespace rbamp::v2), nunca por heurísticas de versão de firmware. Entre outras coisas, o mapa indica se o módulo tem uma entrada de tensão — se não tiver, não calcula P / PF / energia e esses valores leem 0 — e se suporta o instantâneo por difusão de Chamada Geral (ver broadcastLatch()). Numa instância STD a chamada devolve false com RB_ERR_NOT_IMPLEMENTED; use aí stdInfo().

uint8_t readProductId() noexcept

Lê PRODUCT_ID (0x54) — o identificador em byte da família (sensor rbAmp = 0x01, rbDimmer = 0x02; 0 em caso de falha). Usado pelo scanner da frota para confirmar que o dispositivo num endereço é de facto uma rbAmp e não outro escravo I²C que respondeu nesse endereço. Uma instância STD reporta a família do sensor.

bool readUid(uint8_t uid[12]) noexcept

Lê o identificador único de 96 bits do MCU a partir de UID (0x5C..0x67) numa única operação em rajada. O UID é garantidamente único para cada módulo e não muda com uma nova gravação — prático para registos de série, verificações anticlonagem do lado do master e identificação quando um módulo é substituído numa frota instalada. Funciona em ambas as linhas.

bool readLabel(char out[9]) noexcept — apenas BASIC

Lê a etiqueta de utilizador de 8 bytes de LABEL (0x68..0x6F). ASCII, preenchida com zeros à direita; o resultado é sempre terminado em nulo (um array de 9 bytes = 8 bytes de dados + o terminador \0). Etiqueta vazia = não definida.

bool writeLabel(const char* label) noexcept — apenas BASIC

Escreve a etiqueta de 8 bytes. Aceita uma cadeia terminada em nulo — os bytes extra são truncados, os que faltam são preenchidos com zeros. A escrita é byte a byte em escritas de múltiplos bytes (o protocolo de transmissão do rbAmp incrementa automaticamente as leituras de registos em modo rajada, mas não as escritas de registos — ver Detalhes do protocolo de transmissão abaixo; a biblioteca faz o ciclo de bytes automaticamente). Após a escrita é preciso dev.saveUserConfig() para que a etiqueta sobreviva a um reinício.

Nota

Um módulo acabado de sair de fábrica pode reportar o erro 0xFB (DEV_ERR_FLASH_PARAMS_BAD) no primeiro arranque: o bloco de configuração do utilizador ainda está vazio. Isto é normal (não fatal); saveUserConfig() limpa-o. Não aborte o provisionamento ao primeiro sinal de 0xFB.

bool saveUserConfig() noexcept

Emite CMD_SAVE_USER_CONFIG (opcode 0x32) — grava o bloco de configuração do utilizador na flash: SENSOR_CLASS, CT_MODEL por canal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Não grava os parâmetros de calibração de fábrica — esses estão sob um CMD_SAVE_GAINS separado, bloqueado em modo de produção.

Bloqueia a thread durante ~700 ms (ciclo de apagar + escrever da flash). Durante a chamada, não tente aceder ao módulo a partir de outras tarefas.

Linha STD: emite a gravação de configuração do módulo (classe, referência de TC, nível, endereço I²C; a calibração é preservada), aguarda até o módulo indicar que o comando terminou (sem pausa fixa) e verifica o seu veredicto — um campo inválido (por exemplo, um endereço fora do intervalo) devolve RB_ERR_PARAM. Uma gravação dentro do limite de 5 s de armazenamento do módulo é repetida uma vez após 5 s.

Releitura ≠ persistência

: confirmar que um valor foi gravado na flash exige um reinício + uma nova leitura. Ver a secção «modelo de erros v1.3» abaixo.

Modelo de erros v1.3 — dois canais independentes

Os erros têm dois canais independentes que funcionam de formas diferentes. Perceber a diferença é essencial para interpretar corretamente o estado do módulo.

Canal A — lado do cliente, síncrono Canal B — lado do DUT, assíncrono e durável
Onde vive Validação dentro da biblioteca (biblioteca Arduino) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Quando dispara Antes da transação I²C (a biblioteca interrompe-a) Depois de o FW aceitar a escrita e a rejeitar
O que vê o master o setter devolve false + lastError() == RB_ERR_PARAM; o REG_ERROR no dispositivo fica a 0x00 REG_ERROR = o código de falha de imediato; bit3 fica retido algumas centenas de milissegundos após a transação
Persistente não (apenas um valor booleano de retorno) última escrita de REG_ERROR; bit3 pegajoso W1C
Caminho típico Um argumento fora dos limites permitidos (canal ∉ {0,1,2}, código ∉ ao conjunto caracterizado, sensor_class fora do enum) Uma escrita de registo em bruto que a biblioteca não valida previamente (uso de baixo nível de writeReg() com uma máscara inválida)

Canal A — validação do lado do cliente (setters da biblioteca)

Todos os setters da biblioteca (setSensorClass, setCTModel, setCTModel(ch, code), configureChannels, etc.) verificam primeiro os argumentos contra os valores permitidos. Se um argumento estiver fora do intervalo, o setter devolve false e define lastError() == RB_ERR_PARAM, sem executar qualquer transação I²C. Por isso, o REG_ERROR do dispositivo não é tocado:

C++
if (!dev.setCTModel(/*ch=*/99, /*code=*/3)) {       // client-side guard
    Serial.print(F("rejected: "));
    Serial.println(dev.lastError());                 // RB_ERR_PARAM (lib cached)
    uint8_t reg_err = dev.readLastError();           // device REG_ERROR byte
    Serial.println(reg_err, HEX);                    // 0x00 — REG_ERROR untouched
}
Nota

lastError() vs. readLastError() — dois canais diferentes, não sinónimos. lastError() devolve o código RB_ERR_* em cache do lado da biblioteca da chamada anterior — sem nenhuma operação I²C. readLastError() faz uma única leitura no fio do registo REG_ERROR (0x02) do dispositivo — o resultado da última escrita do lado do firmware. No Canal A (acima), lastError() = RB_ERR_PARAM enquanto readLastError() = 0x00 (a biblioteca nunca chegou ao fio — REG_ERROR intacto). No Canal B (abaixo) ambos mostrarão um código, mas de forma diferente: lastError() — a semântica em cache mais recente da biblioteca; readLastError() — o valor exato do byte REG_ERROR neste momento.

Isto significa: se quiser saber exatamente porquê um setter recusou, a fonte fiável é o código de retorno da função + lastError(). O REG_ERROR no dispositivo não lhe dirá nada neste cenário.

Canal B — rejeição do lado do DUT (assíncrono durável)

Se a escrita passou por I²C (a biblioteca não a bloqueou porque o argumento parecia válido), mas o firmware rejeitou-a, entra em ação o segundo canal:

  • readLastError() devolve de imediato o código de motivo (por exemplo, 0xFE = DEV_ERR_PARAM). É o resultado da última escrita: qualquer escrita bem-sucedida seguinte o substitui. Tem de o ler imediatamente após a escrita, antes de qualquer outra transação.

  • hasError(out) — o indicador persistente W1C EVENT_FLAGS.bit3. Não ativa de imediato: na bancada mediu-se um atraso de alguns centenas de milissegundos entre a transação falhada e a ativação do bit3. Logo após a escrita o bit3 ainda está false; após 300 ms está true. Depois disso, bit3 mantém-se em qualquer número de leituras.

Segurança

⚠ Não use hasError() para validar uma escrita que acabou de fazer. Para o resultado desta escrita específica só readLastError() é fiável, lido imediatamente após a escrita e antes de qualquer outra transação (além do código de retorno do setter, se tiver um). hasError() é um canal assíncrono para monitorização por consulta de "se algo falhou entre duas verificações", não para validação síncrona.

Limpar um erro durável — limpe ambos (REG_ERROR e bit3)

bit3 é captado pelo firmware a cada poucas centenas de milissegundos a partir do estado atual de REG_ERROR. Assim, um simples clearEventFlags(1 << 3) não funciona — o bit3 volta a ser ativado de imediato a partir do REG_ERROR ainda não limpo. A ordem correta: primeiro clearError() (limpa REG_ERROR), depois clearEventFlags(1 << 3) (limpa o latch pegajoso). Se quiser atomicidade — não pode haver nenhuma escrita rejeitada entre as duas.

uint8_t readLastError() noexcept

Lê diretamente o registo REG_ERROR (0x02) do dispositivo (uma única leitura de fio; devolve 0x00 para OK, 0xFA..0xFF para uma classe de erro, e 0xFF se a própria leitura I²C falhar) — o resultado da última transação aceite com sucesso pelo barramento (uma escrita ou um comando). Não é persistente: qualquer escrita bem-sucedida seguinte substitui-o pelo seu próprio resultado. Usado no Canal B (rejeição do lado do DUT) para o código de motivo estendido. Na linha STD, o veredito do comando já está mapeado para lastError() (ver a API da linha STD).

Nota

Não confundir com lastError(): esse é um método diferente, que devolve o RB_ERR_* em cache da biblioteca, da chamada anterior, sem qualquer operação I²C. Ver a nota no Canal A acima.

bool hasError(bool& out) noexcept

Um auxiliar de conveniência sobre o EVENT_FLAGS.bit3. Devolve true em out se o bit3 estiver ativo. W1C persistente; não é limpo até uma limpeza explícita (com uma ressalva — ver a secção «Limpar um erro durável» acima).

bool readEventFlags(uint8_t& out) noexcept / bool clearEventFlags(uint8_t mask) noexcept

EVENT_FLAGS (0x2A) — um byte de flags persistentes; os bits específicos estão descritos na especificação (incluindo ERROR_OCCURRED bit3). A limpeza é write-1-to-clear: escreva uma máscara com uns nos bits que quer repor.

bool clearError() noexcept

Emite CMD_CLEAR_ERROR (opcode 0x31) — põe REG_ERROR a zero. Necessário para limpar um erro durável, em par com clearEventFlags(1 << 3) (ver acima). Sem clearError(), um simples clearEventFlags(1 << 3) deixa o bit3 a true após algumas centenas de milissegundos, por causa do re-latch.

Configuração multicanal (v1.3)

Em módulos multicanal, cada canal de corrente tem o seu próprio modelo de sensor de TC. O utilitário atómico para configuração em massa é configureChannels().

bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept

Parameters:

  • cls — a classe do sensor, aplicada primeiro. Com RbAmpSensorClass::Sct013 os modelos são associados; um pedido para associar modelos sob WiredCT / BuiltinCT é recusado logo à partida (false, RB_ERR_MODE, nada escrito).

  • models — um array de n códigos de modelo de TC (defines RBAMP_CT_* geradas), um por canal. 0 deixa o modelo existente desse canal intacto.

  • n — o comprimento do array. Limitado a channels(): os elementos extra do array são ignorados. Se n for menor, os canais em falta ficam intocados (mantêm o modelo anterior).

Internamente, a função executa:

  1. setSensorClass(cls) uma vez.
  2. Para cada canal k < min(n, channels): preparar REG_CT_MODEL = models[k] + CMD_SET_CT_MODEL_CHk.
  3. Uma gravação final no fim — um ciclo de apagar + escrever da flash para toda a configuração, em vez de um por canal (cerca de 3× menos ciclos de desgaste em três canais).

Aplica-se ler-antes-de-escrever: uma classe ou modelo que o módulo já tem não é reescrito, pelo que voltar a aplicar a mesma configuração custa apenas leituras e nenhum ciclo de flash. No firmware BASIC até 1.4.19 com a classe SCT-013, o módulo é reiniciado após a gravação (ver Configuração do sensor).

Return:

  • true — a configuração foi aplicada e guardada (ou já estava em vigor).
  • false + lastError() == RB_ERR_PARAM — um cls inválido ou um models[k] que não consta do registo (validação do lado do cliente, ver "Modelo de erros" acima); o lote é interrompido.

  • false + RB_ERR_MODE — o módulo é de uma classe emparelhada de fábrica.

  • false + outros códigos — erro de barramento, tempo limite, etc.
Nota

Códigos aceites para SCT_013: {1, 2, 3, 4, 5, 6, 7} (SCT-013-005, -010, -030, -050, -100, -020, -060). Detalhes — 03 · Seleção do sensor de corrente.

bool readCTModelCh(uint8_t ch, uint8_t& out) noexcept

Lê o modelo de sensor de TC aplicado (espelho de verificação) num canal específico. Trata-se de uma releitura da RAM, não uma confirmação de persistência — para confirmar uma gravação na flash use dev.reset() + uma nova leitura do espelho.

Linha de dados pronta e eventos

Ambas as linhas. A saída DRDY do módulo é de dreno aberto, em repouso HIGH (pull-up do anfitrião), e emite um impulso LOW de cada vez que um novo instantâneo completo é publicado — uma vez por janela de medição (100 ms). Vários módulos podem partilhar uma linha (wired-OR). Um módulo cujo evento mascarado está pendente mantém a linha em LOW constante (nível de alarme) até as flags serem limpas. Na linha STD o bloco de eventos existe nos módulos cuja imagem o disponibiliza; no BASIC a partir do firmware v1.3. Detalhes de hardware — 04 · Ligação.

bool setDrdyPin(int pin) noexcept

Ligue a linha DRDY deste módulo (ou desligue-a com pin < 0). Configura o pino como entrada com pull-up interna e interrupção por flanco de descida; a ISR apenas conta e marca o tempo do flanco — sem tráfego no barramento. Até 4 linhas distintas e 8 módulos por linha. Um módulo STD cuja imagem não suporta o contrato de linha de dados pronta recusa com RB_ERR_NOT_IMPLEMENTED; waitDataReady() passa então a consultar a sequência. Sem linha, waitDataReady() também consulta.

bool waitDataReady(uint32_t timeout_ms, RbAmpDrdyEvent* ev = nullptr) noexcept

Bloqueia até este módulo publicar um novo instantâneo (ou um alarme), no máximo timeout_ms (0 = uma verificação não bloqueante).

Com uma linha: aguarda a transição e depois confirma que foi deste módulo pela sequência do seu instantâneo (um impulso de outro módulo numa linha partilhada é ignorado). Se a linha continuar em LOW pouco depois da transição, algum módulo nela tem um alarme ativo: as flags de todos os módulos com capacidade de alarme na linha são lidas e limpas; as flags deste módulo voltam em ev, e as dos outros ficam guardadas nas respetivas instâncias e são reportadas na espera seguinte. Sem linha, consulta a sequência a cada RBAMP_DRDY_POLL_MS (predefinido 20 ms; defina-o antes de incluir a biblioteca para o alterar).

Devolve: true com ev preenchido; false com RB_ERR_TIMEOUT quando nada chegou, RB_ERR_NOT_IMPLEMENTED num módulo STD cuja imagem não tem contador de publicação.

bool readAllReady(uint32_t timeout_ms, RbAmpSnapshot& out, RbAmpDrdyEvent* ev = nullptr) noexcept

waitDataReady() seguido de readAll(), de modo que toda a leitura cai dentro de uma só janela de publicação: o instantâneo nunca é lido duas vezes nem atravessa uma publicação.

bool readDataSeq(uint16_t& out) noexcept

A sequência de instantâneos do módulo — o contador de publicação no STD, a sequência de commit no BASIC. Serve apenas para deteção de alterações.

uint8_t beginEventFlags() const noexcept

As flags de evento tal como o begin() as encontrou, antes de a biblioteca escrever seja o que for. EVENT_RESET_OCCURRED aí significa que o módulo reiniciou antes de esta instância o encontrar. Sem acesso ao barramento.

bool readEventMask(uint8_t& out) noexcept / bool setEventMask(uint8_t mask) noexcept

Lê / define quais os bits de evento que mantêm DRDY em LOW (bits rbamp::v2::EVENT_*). setEventMask() verifica por releitura. A máscara vive na RAM do módulo: volte a aplicá-la após um reinício do módulo (EVENT_RESET_OCCURRED indica-o).

bool setEventThresholds(float i_amps, float p_watts) noexcept

Define os limiares de corrente / potência por trás de EVENT_THRESH_I / EVENT_THRESH_P; um valor <= 0 desativa esse limiar. RAM no módulo.

  • O BASIC compara a corrente máxima dos canais e a soma com sinal das potências dos canais — a exportação nunca o aciona.

  • O STD compara a corrente de qualquer canal e a magnitude da potência total — independente do sentido.

Os eventos de limiar ficam fixados ao nível no módulo (reafirmados em cada janela enquanto a condição se mantiver): levante o limiar antes de esperar uma linha calma.

readEventFlags() / clearEventFlags() / hasError() estão descritos em Modelo de erros.

RbAmpDrdyEvent

C++
struct RbAmpDrdyEvent {
    bool     fresh;        // a new snapshot of THIS module is available
    bool     by_edge;      // woken by the DRDY edge (false = found by polling)
    uint16_t seq;          // snapshot sequence now
    uint16_t missed;       // snapshots published since the previous call that were not read
    bool     alarm;        // the line was held LOW (masked event pending on this module)
    uint8_t  event_flags;  // event flags consumed from this module on an alarm, else 0
    uint32_t latency_us;   // edge to return, µs (0 when polling)
};
C++
RbAmp dev(Wire, 0x50);
...
dev.setDrdyPin(15);                       // optional: omit to poll
dev.setEventThresholds(0, 3000);          // power threshold, W
dev.setEventMask(rbamp::v2::EVENT_THRESH_P);

RbAmpSnapshot snap;
RbAmpDrdyEvent ev;
if (dev.readAllReady(500, snap, &ev)) {
    if (ev.alarm) { /* ev.event_flags holds the cleared flags */ }
    // use snap
}

Visão geral das funcionalidades

Os resumos de funcionalidades abaixo foram transferidos do README.

  • Configuração do sensor de corrente — setSensorClass(class) escolhe a família (SCT-013 montado por si; os módulos com TC cabeados / integrados são fornecidos calibrados com o respetivo sensor e não são reconfigurados), depois setCTModel(code) — ou configureChannels(class, models[], n) para um módulo multicanal numa só chamada. Os setters leem antes de escrever: uma classe ou modelo que o módulo já tem não custa escrita no barramento nem ciclo de flash, pelo que voltar a aplicar uma configuração guardada em cada arranque é seguro. O conjunto de códigos SCT-013 aceite é {1=005A, 2=010A, 3=030A, 4=050A, 5=100A, 6=020A, 7=060A}. Os coeficientes de calibração carregam-se automaticamente a partir da tabela de predefinições de fábrica. Módulos BASIC até ao firmware 1.4.19 são calibrados no SCT-013-030: quando seleciona outro modelo SCT-013 a biblioteca reinicia o módulo após a gravação e, a partir daí, escala as leituras de corrente e potência em relação ao ganho que o módulo aplica (ver sctRating()); o fator de potência e a tensão não são afetados, e um módulo que reporta o bit de capacidade de autocorreção (firmware 1.4.20+) não precisa de nada.
  • Gestor RbAmpFleet — para vários módulos num barramento: scan() descobre-os e adota-os (com deteção de colisões), pollAll() lê-os numa só passagem, totalPower() / totalEnergyWh() agregam, e o caminho de Chamada Geral (enableGcAll() → gcLatch(tick) → checkSync()) tira o instantâneo do período de todos os módulos em simultâneo, com deteção de tramas perdidas por módulo. provision() / assignAddress() colocam módulos novos de fábrica no barramento, em endereços distintos.
  • Ambas as linhas de produtos, uma só API — begin() deteta se um módulo fala o modelo de registos BASIC (8 bits) ou STD (16 bits, vírgula fixa) e encaminha internamente cada chamada; line() indica qual. Num módulo STD as mesmas chamadas readVoltage(phase) / readCurrent(ch) / readPower(ch) / readPeriodSnapshot() funcionam, o número de canais vem do módulo (os módulos trifásicos são apenas N > 1), e os extras exclusivos do STD estão expostos como readReactivePower(ch) / readApparentPower(ch), stdReadChannel(ch) (uma rajada: I / P / Q / S / PF / pico / energia com sinal / harmónicos), stdReadVoltage(v), stdReadHealth() e oito bancos de instantâneos temporizados pelo mestre (stdArmBanks() → stdLatch(bank) → stdReadLatch(bank) → stdLatchWh()). Os módulos que mantêm contadores de energia de vida persistidos em vez de bancos de instantâneos são servidos pelas mesmas chamadas readPeriodSnapshot() / energy() (um período é a diferença de duas leituras de contadores; stdReadEnergy() devolve os contadores em bruto), além do relógio do módulo (stdSetTime()), histórico e registo de eventos (stdHistRead(), stdEventRead()), identidade (stdIdentify(), RbAmp::stdProbe()), comissionamento por UID (RbAmp::stdSetAddressByUid()) e atualização de firmware por I2C (stdOtaWritePreparedImage(), imagens preparadas no computador de compilação do fabricante). Cada comando aguarda que o módulo indique que terminou antes de se ler o veredicto, e os blocos de múltiplos bytes são lidos numa só transação, para que os contadores nunca sejam cortados a meio. Os módulos que publicam contadores de micro-resolução preenchem os campos *_uwh / *_uvarh de RbAmpStdEnergy (fine == true; derivados dos contadores grosseiros noutros casos, pelo que os campos são sempre utilizáveis), aceitam uma corrente inicial abaixo da qual um canal não conta energia (stdSetEnergyStartCurrent()), e reportam os ângulos de fase da tensão (angle_deg em stdReadVoltage()) e a sequência de fases (stdReadPhaseSequence()). Se o seu sketch persistir RbAmpStdEnergy (NVS, EEPROM, ficheiro), guarde os campos individuais de que precisa num formato próprio e fixo, e não a estrutura como blob bruto — a estrutura ganha campos entre versões da biblioteca e um blob antigo não terá o tamanho novo.
  • Linha de data-ready e eventos — setDrdyPin(pin) escuta a saída DRDY do módulo; waitDataReady() / readAllReady() devolvem logo que o módulo publica um novo instantâneo (vários módulos podem partilhar uma linha), e um módulo que detém a linha sinaliza um evento mascarado (setEventMask(), setEventThresholds()) que a espera lê e limpa por si. Sem linha, as mesmas chamadas fazem consulta.

API da linha STD

A linha de módulos STANDARD (STD) é detetada por begin() (dev.line() == RbAmpLine::Std). A API escalar acima (readVoltage(), readCurrent(), readPower(), readReactivePower(), readApparentPower(), readAll(), readPeriodSnapshot(), energy(), os setters de configuração, reset(), a alteração de endereço) funciona em ambas as linhas. As chamadas std* abaixo acrescentam leituras de blocos completos e as funcionalidades que só a linha STD tem.

  • Cada chamada std* falha com RB_ERR_NOT_IMPLEMENTED numa instância BASIC.
  • As funcionalidades dependem da imagem do módulo: verifique stdReadImageVersion() e as flags valid / fine das estruturas devolvidas. Uma funcionalidade que o módulo não tem é reportada como "não disponível" — nunca devolve um valor inventado.

  • begin() faz a deteção da linha e a descoberta dos canais. Os auxiliares internos correspondentes não fazem parte da API pública; chame begin(), readAll() e readPeriodSnapshot().

  • Cada comando aguarda que o módulo indique que terminou e depois verifica o seu veredito. Um valor rejeitado devolve RB_ERR_PARAM e deixa o módulo inalterado.

  • As primitivas de 8 bits recusam-se numa instância STD, pelo que um caminho exclusivo do BASIC nunca pode executar uma transação de registo errado num módulo STD.

C++
if (dev.begin() && dev.line() == RbAmpLine::Std) {
    RbAmpStdChannel c;
    if (dev.stdReadChannel(0, c)) {
        Serial.printf("P=%.1f W  Q=%.1f var  S=%.1f VA  PF=%.2f\n", c.p, c.q, c.s, c.pf);
    }
}

Fonte de energia e versão mínima da biblioteca

readPeriodSnapshot() e energy() obtêm o período de uma de duas fontes, escolhida uma vez por begin() a partir dos bits de capacidade do módulo e reportada em stdInfo().period_source:

O módulo reporta period_source O período / a energia provêm de
contadores de energia persistidos (bit 13), com ou sem bancos Counters os contadores do módulo (um período é a diferença de duas leituras)
apenas bancos de instantâneos (bit 8) Latch banco 0
nenhuma None as chamadas são recusadas com RB_ERR_NOT_IMPLEMENTED

A imagem STD em série 0x7E reporta ambos os bits. Precisa da biblioteca 1.6.2 ou posterior para obter a energia a partir dos contadores do módulo. A biblioteca 1.6.1 e anteriores leem o período do banco 0 nessa imagem, ou seja, a energia integrada no anfitrião em vez dos contadores próprios do módulo; atualize a biblioteca para obter os valores baseados em contadores. Os bancos continuam disponíveis em 0x7E através das chamadas em Bancos de instantâneos de período.

Identidade

bool stdInfo(RbAmpStdInfo& out) noexcept

Identidade em cache de begin() — sem tráfego no barramento. Falha com RB_ERR_NOT_IMPLEMENTED numa instância BASIC ou antes de begin().

C++
struct RbAmpStdInfo {
    uint8_t  map_version;   // register-map version
    uint16_t capabilities;  // feature bitmap of the module
    uint8_t  status;        // status bits at begin() time (live: stdReadHealth())
    uint8_t  n_voltage;     // populated voltage channels
    uint8_t  n_current;     // populated current channels (the library exposes up to RBAMP_MAX_CHANNELS)
    uint8_t  variant;       // raw variant byte (also mapped into readVariant())
    uint32_t active_bank;   // running firmware bank (firmware update), 0 if none
    uint32_t ota_bank_size; // firmware bank size the module reports, 0 if none
    RbAmpStdPeriodSource period_source; // which period / energy mechanism this module offers
};

RbAmpStdPeriodSource: Latch (o módulo tem bancos de instantâneos; o banco 0 serve readPeriodSnapshot()), Counters (sem bancos de instantâneos, mas com contadores de energia de vida persistidos — um período é a diferença de duas leituras de contadores; as chamadas de banco são recusadas sem tráfego no barramento) ou None (as chamadas de período / energia falham com RB_ERR_NOT_IMPLEMENTED).

bool stdIdentify(RbAmpStdIdentity& out) noexcept

Identidade deste módulo: os dados em cache de begin() mais o UID, a versão da imagem em execução e o id da placa (os dois últimos quando o módulo os reporta; caso contrário, 0).

C++
struct RbAmpStdIdentity {
    uint8_t  i2c_addr;      // 7-bit address the module answered on
    uint8_t  map_version;
    uint16_t capabilities;
    uint8_t  variant;
    uint8_t  n_voltage, n_current;
    uint8_t  uid[12];       // chip UID — the module's identity in a database
    uint32_t fw_version;    // running image version (0 if unknown)
    uint32_t board_id;      // board id (0 if unknown)
};

static int8_t stdProbe(TwoWire& bus, uint8_t addr, RbAmpStdIdentity& out) noexcept

Identifica o que responde em addr sem instância (varrimento do barramento). Uma tentativa por leitura, sem camada de repetição — um NACK é a resposta.

Devolve: RB_OK; RB_ERR_NACK nada responde nesse endereço; RB_ERR_VERSION algo que não é um módulo STD; RB_ERR_PARAM endereço fora de 0x08..0x77; RB_ERR_IO uma leitura posterior falhou.

bool stdReadImageVersion(uint32_t& out) noexcept

A versão da imagem em execução (não a versão do mapa de registos); 0 se o módulo não a reportar. Use-a para ver se uma funcionalidade que exige uma imagem recente está presente (energia de micro-resolução, corrente de arranque, ângulos de tensão e sequência de fases exigem uma imagem de pelo menos 0x0001007B).

bool stdReadBoardId(uint32_t& out) noexcept

Id da placa da imagem em execução.

Leituras em bloco

bool stdReadChannel(uint8_t ch, RbAmpStdChannel& out) noexcept

Um canal de corrente (0 .. channels()-1) numa única rajada: I, P, Q, S, PF, pico, acumuladores de energia brutos com sinal e campos de harmónicos.

bool stdReadTotals(uint8_t k, RbAmpStdChannel& out) noexcept

Um bloco agregado: k = 0 total geral (todos os canais de corrente), k = 1..3 totais por fase A / B / C (num módulo monofásico k = 1 é igual ao canal 0 e k = 2, 3 leem 0). Apenas I / P / Q / S / PF / pico — em módulos com contadores de vida útil os campos de energia leem 0 aqui; a energia vem de stdReadEnergy().

C++
struct RbAmpStdChannel {
    float   i_rms, i_peak;   // A
    float   p;               // W, signed
    float   q;               // var, signed
    float   s;               // VA
    float   pf;              // power factor, −1..+1
    float   thd_i;           // current THD, % — 0 unless harmonics are enabled
    float   pf1;             // displacement power factor — 0 unless harmonics are enabled
    float   q1;              // fundamental reactive power, var — 0 unless harmonics are enabled
    int64_t e_import_mws;    // raw import energy accumulator (>= 0), see stdLatchWh()
    int64_t e_export_mws;    // raw export energy accumulator (<= 0)
    uint8_t implausible;     // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};

Para monitorização, integre p você mesmo ou use stdReadEnergy(); os acumuladores em bruto existem para o caminho dos bancos de instantâneos.

bool stdReadVoltage(uint8_t v, RbAmpStdVoltage& out) noexcept

Um canal de tensão (0 .. n_voltage-1).

C++
struct RbAmpStdVoltage {
    float   u_rms, u_peak;   // V
    float   thd_u;           // voltage THD, % — 0 unless harmonics are enabled
    float   angle_deg;       // phase angle vs voltage 0, degrees; 0 when angle_valid is false
    bool    angle_valid;     // false on older images, when the input is too low to measure, and on single-voltage modules for v > 0
    uint8_t implausible;
};

bool stdReadPhaseSequence(RbAmpStdPhaseSeq& out) noexcept

Sequência de fases de um módulo de três tensões, derivada pelo módulo a partir dos ângulos de tensão. Devolve true com NotAvailable — e sem tráfego no barramento — numa imagem que não a publica; o próprio módulo reporta NotAvailable com menos de três entradas de tensão ou quando uma entrada é demasiado baixa para medir.

RbAmpStdPhaseSeq: NotAvailable, Forward (L1-L2-L3), Reverse (L1-L3-L2), Abnormal (sem padrão trifásico, por exemplo duas entradas na mesma fase).

bool stdReadHealth(RbAmpStdHealth& out) noexcept

Estado de saúde do módulo em tempo real. Considere as leituras válidas quando status tiver o bit de sensor OK e frame_count aumentar entre duas consultas.

C++
struct RbAmpStdHealth {
    uint8_t  status;       // status bits: cal_ok / sensor_ok / mains_ok / time_valid / nvm_fault / maint
    uint32_t frame_count;  // sensor frame counter — must grow between polls (liveness)
    uint32_t crc_errors;   // sensor frame error counter
    bool     time_valid;   // the module clock was set since its last restart — see stdSetTime()
    bool     nvm_fault;    // energy store unusable
    bool     maint;        // maintenance mode
    uint8_t  lta_status;   // life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service)
    uint8_t  lta_src;      // where the life-time counters were restored from
    uint8_t  cal_src;      // 0 built-in defaults · 1 flash · 2 EEPROM · 3 stored calibration is for another firmware
    uint8_t  group_status; // per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0
    uint16_t legal_noen, ring_drop;  // module diagnostics (ring_drop should stay 0)
    uint32_t lost_frames;  // should stay flat
    uint32_t uptime_s;     // seconds since the module's last restart
    uint8_t  reset_cause;  // cause of this boot (image-dependent; 0 below)
    uint16_t boot_count;   // persisted boot counter, low 16 bits — a master that missed a restart sees it step
};

Os campos marcados como "dependentes da imagem" ou documentados para mapas de registos mais recentes leem 0 / false em módulos que não os disponibilizam. cal_ok pode ler 0 numa unidade calibrada com uma imagem antiga até saveGains() ter sido executado uma vez; as próprias leituras não são afetadas.

Bancos de instantâneos do período

Um módulo STD que reporta bancos de instantâneos (bit de capacidade 8) mantém oito períodos independentes, cronometrados pelo master. Utilização típica: arme os bancos de que precisa uma vez; depois, por banco, no seu próprio calendário: stdLatch(bank) → aguarde pelo menos 300 ms → stdReadLatch(bank, snap) → stdLatchWh(snap, dt, ...) com o dt medido pelo master desde o instantâneo anterior desse banco. Os bancos são uma ferramenta própria: estão disponíveis seja qual for a fonte de energia do módulo (ver Fonte de energia e versão mínima da biblioteca). Num módulo sem bancos, stdArmBanks(), stdLatch() e stdReadLatch() recusam com RB_ERR_NOT_IMPLEMENTED e não escrevem nada. O banco 0 serve readPeriodSnapshot() e energy() apenas num módulo com bancos e sem contadores persistidos.

bool stdArmBanks(uint8_t mask) noexcept

Defina a máscara de acumulação: bit b = banco b acumula (os bancos recém-armados começam limpos; os bancos desarmados ficam congelados e mantêm o último instantâneo). Mantenha o bit 0 ativo se usar readPeriodSnapshot(). A máscara vive na RAM do módulo e perde-se num reinício do módulo; a biblioteca rearma um banco quando uma leitura encontra um instantâneo vazio num banco desarmado (ver stdReadLatch()).

bool stdLatch(uint8_t bank) noexcept

Peça um instantâneo + reinício de bank na próxima fronteira de janela do módulo. Não aguarda; leia-o pelo menos 300 ms depois.

bool stdReadLatch(uint8_t bank, RbAmpStdLatch& out) noexcept

Lê o último instantâneo de bank numa só rajada (totais + energia por canal de cada canal preenchido).

Devolve: false com RB_ERR_STALE se o módulo nunca tirou um instantâneo deste banco (out.valid == false), ou se o instantâneo está vazio (win_count == 0) porque o banco perdeu a armação após um reinício do módulo. Neste último caso a biblioteca rearma e tira um instantâneo de preparação do banco: descarte este período e reinicie a sua própria âncora dt (o intervalo de interrupção não tem dados).

C++
struct RbAmpStdLatch {
    float    p_avg, q_avg, s_avg;    // average W / var / VA over the period
    float    max_p, max_i;           // peak power (W) and peak RMS current (A)
    float    max_u, min_u;           // peak / minimum RMS voltage (V)
    int64_t  e_import_mws, e_export_mws;   // raw energy accumulators over the period
    uint32_t nsamp;                  // conversion divisor used by stdLatchWh()
    uint32_t win_count;              // measurement windows in the period (0 = not armed / nothing elapsed)
    uint8_t  channels, bank;
    bool     valid;                  // the bank has EVER been snapshotted (not a freshness signal)
    float    p_avg_ch[RBAMP_MAX_CHANNELS];
    int64_t  e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
};

static bool stdLatchWh(const RbAmpStdLatch& snap, uint32_t dt_ms, uint8_t ch, double& wh_import, double& wh_export) noexcept

Converte os acumuladores de energia em bruto de um instantâneo para Wh sobre o período dt_ms medido pelo mestre (tempo de parede entre o instantâneo anterior e este, no banco). ch é um índice de canal, ou RBAMP_STD_TOTAL para os totais do banco. wh_import é >= 0, wh_export é <= 0.

Devolve: false se ch estiver fora do intervalo ou se nada tiver sido acumulado.

Contadores de energia de vida

Os módulos que mantêm contadores de energia persistidos sobrevivem a uma falha de energia com eles; são monotónicos, com uma separação de importação / exportação com sinal.

bool stdReadEnergy(RbAmpStdEnergy& out) noexcept

Leia os contadores de vida útil do módulo. Cada bloco é lido numa só transação, pelo que um contador de 64 bits não pode ser cortado a meio de uma publicação.

Devolve: false com RB_ERR_NOT_IMPLEMENTED quando o módulo não mantém energia no dispositivo; RB_ERR_NOT_READY se o bloco não estiver programado.

C++
struct RbAmpStdEnergy {
    int64_t  act_import_wh, act_export_wh, act_net_wh;     // active energy, Wh (export is a magnitude)
    int64_t  rea_import_varh, rea_export_varh;             // reactive energy, varh
    uint32_t generation;       // steps when the counters were reset or adopted — never take a delta across a change
    uint32_t uptime_s;         // module uptime at the reading (a drop = the module restarted)
    int64_t  act_import_mwh, act_export_mwh, act_net_mwh;  // mWh (0 on modules without them)
    uint8_t  channels;         // valid entries in the per-channel arrays (0 on modules without them)
    uint8_t  group_status;     // per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0
    int64_t  ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
    bool     fine;             // true: the µWh / µvarh fields are the module's own micro-resolution counters
    int64_t  act_import_uwh, act_export_uwh, act_net_uwh;  // µWh
    int64_t  rea_import_uvarh, rea_export_uvarh;           // µvarh
    int64_t  ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
};

Os campos *_uwh / *_uvarh são sempre preenchidos, pelo que pode usá-los em qualquer módulo: quando fine == true são os contadores de micro-resolução do próprio módulo (imagem 0x0001007B ou posterior); caso contrário são derivados dos contadores mais grosseiros e avançam nessas unidades. Se o seu sketch persistir RbAmpStdEnergy, guarde os campos individuais de que precisa num formato próprio e fixo, em vez de guardar a estrutura como blob bruto — a estrutura ganha campos entre versões da biblioteca.

static bool stdEnergyDelta(const RbAmpStdEnergy& prev, const RbAmpStdEnergy& now, RbAmpStdEnergy* delta, bool* module_restarted) noexcept

Energia entre duas leituras: now − prev, limitando cada contador a 0 (um contador pode retomar ligeiramente abaixo da última leitura após um reinício do módulo); o líquido é recalculado como importação − exportação das variações limitadas. delta e module_restarted podem ser nullptr; delta->fine é true apenas quando ambas as leituras eram válidas; *module_restarted é true quando o tempo de atividade de now é inferior ao de prev.

Devolve: false quando generation mudou entre as leituras (reposição ou adoção do contador de vida útil) — não contabilize esse intervalo.

bool stdSetEnergyStartCurrent(uint16_t ua) noexcept

Defina a corrente de arranque para a contagem de energia, em µA: abaixo desta corrente de canal o módulo não conta energia para o canal (importação ou exportação, total e por canal). Sem carga, a potência medida é ruído de qualquer sinal e, de outro modo, entraria em ambos os contadores. As leituras (I / P / Q) não são afetadas. Aplica-se de imediato, com verificação por leitura; persista com saveUserConfig(). 0 desliga; caso contrário o valor tem de ser múltiplo de 10 µA dentro do intervalo que o módulo aceita — qualquer outro valor devolve RB_ERR_PARAM sem escrita no barramento.

Devolve: false com RB_ERR_NOT_IMPLEMENTED quando o módulo não tem corrente de arranque (sem energia de micro-resolução, ou com imagem mais antiga).

bool stdReadEnergyStartCurrent(uint16_t& ua) noexcept

A corrente de arranque atual para a contagem de energia, em µA (0 = desligada).

Configuração

bool stdReadConfig(RbAmpStdConfig& out) noexcept

O bloco de configuração numa só rajada.

C++
struct RbAmpStdConfig {
    uint8_t  sensor_class; // RbAmpSensorClass value, 0 = unset. Persisted.
    uint8_t  ct_model;     // CT model reference for channel 0 (label only, sets no gain). Persisted.
    uint8_t  tier;         // module tier code. Persisted.
    uint8_t  i2c_addr;     // persisted 7-bit address (applies on reset)
    uint16_t rate_ms;      // report-rate hint, ms (RAM only)
    bool     harmonics;    // base-harmonics extraction enabled (RAM only)
};

bool stdSetHarmonics(bool enable) noexcept

Ativa / desativa a extração de harmónicos de base (THD, PF de deslocamento, potência reativa fundamental). Apenas RAM (não persistido), com verificação por releitura. Requer a capacidade THD do módulo — caso contrário, RB_ERR_NOT_IMPLEMENTED.

bool stdCalThdFloor() noexcept

Capture o THD bruto sem carga como piso do sensor e guarde-o (cerca de 700 ms). Execute com rede limpa e sem carga; depois disso as leituras de THD são corrigidas pelo piso do sensor. Requer a capacidade THD.

Relógio

O relógio do módulo perde-se em cada reinício. Defina-o após begin() e sempre que RbAmpStdHealth::time_valid for false; sem ele o módulo não regista histórico.

bool stdSetTime(uint32_t unix_epoch) noexcept

Define o relógio do módulo (época Unix, UTC). Devolve false com RB_ERR_PARAM se o módulo recusar a época (anterior a 2020), RB_ERR_NOT_READY se aceitou o valor mas não reportou o relógio como válido em 300 ms.

bool stdReadTime(uint32_t& unix_epoch, bool& valid) noexcept

O relógio do módulo e se foi definido desde o último reinício do módulo.

Comandos e comissionamento

bool stdCommand(uint8_t opcode, uint32_t settle_ms, uint32_t timeout_ms = 0) noexcept

Emite qualquer comando do módulo e aguarda o seu veredicto: espera até o módulo ficar inativo (um comando escrito enquanto está ocupado é descartado), escreve o opcode, consulta o estado do comando até o módulo indicar que terminou, e depois lê o veredicto. settle_ms limita apenas a primeira consulta. timeout_ms = 0 significa 1000 ms; nunca menos de 1000.

Devolve: false com o veredito mapeado para um código de erro — PARAM, NOT_IMPLEMENTED (comando desconhecido), CHECKSUM (verificação do valor), MODE (chave / porta), NOT_READY (limite de taxa / repetição), TIMEOUT, IO (erro de armazenamento do módulo).

bool stdWaitIdle(uint32_t timeout_ms = 0) noexcept

Aguarde até o módulo indicar que não há comando em curso (0 = 1000 ms).

bool stdLocate() noexcept

Faça piscar os LEDs do módulo durante cerca de 10 s — para o encontrar num armário.

static int8_t stdSetAddressByUid(TwoWire& bus, uint8_t shared_addr, const uint8_t uid[12], uint8_t new_addr, uint32_t restart_ms = 0) noexcept

Atribui a um módulo entre vários num endereço partilhado o seu próprio endereço, selecionado pelo UID (comissionamento). É apenas de escrita no endereço partilhado (vários módulos podem responder, por isso não se lê nada aí). O módulo endereçado grava o novo endereço e reinicia; a chamada depois sonda o novo endereço e verifica o UID. Volte a executar begin() numa instância ligada ao novo endereço. restart_ms = 0 significa 1500 ms.

Devolve: RB_OK; RB_ERR_PARAM endereço fora do intervalo; RB_ERR_NACK nenhum módulo respondeu com ACK no endereço partilhado; RB_ERR_NOT_READY nada responde depois no novo endereço; RB_ERR_VERSION o módulo aí não é o endereçado (o UID é diferente).

Histórico e registo de eventos

Os registos existem apenas para períodos durante os quais o relógio do módulo era válido (ver stdSetTime()).

C++
enum class RbAmpStdHistPeriod : uint8_t {
    Min15  = 0,  // 15-minute energy records — RAM only (the last record survives no restart)
    Hour   = 1,  // hourly energy records — persistent ring (the one to backfill from)
    Events = 2,  // event log (read with stdEventRead())
};

bool stdHistInfo(RbAmpStdHistPeriod period, RbAmpStdHistInfo& out) noexcept

Resumo do anel: count, capacity, record_size, oldest_ts, newest_ts (tempo Unix). Os registos são obtidos do mais recente para o mais antigo através de um índice back.

bool stdHistRead(RbAmpStdHistPeriod period, uint16_t back, RbAmpStdHistRecord& out) noexcept

Obtém e descodifica um registo de período de energia (Min15 ou Hour; back = 0 é o mais recente). Devolve false com RB_ERR_NOT_READY quando não existe esse registo (anel vazio ou back para além dele); RB_ERR_PARAM para o anel de eventos (use stdEventRead()).

C++
struct RbAmpStdHistRecord {
    uint32_t ts;           // Unix time at the end of the period
    uint16_t flags;        // partial / power-up / clock / life-time-jump bits
    uint16_t n;            // measurement windows in the period
    bool     from_ram;     // served from RAM (not yet persisted)
    float    v_rms, i_total, p_avg, q_avg, s_avg, pf;
    float    p_min, p_max, i_min, i_max;
    uint64_t e_import_wh, e_export_wh;   // life-time ABSOLUTE counters at the end of the period
    uint8_t  phases;                     // valid entries in the per-phase arrays (0..3)
    double   ph_import_wh[3], ph_export_wh[3];  // THIS period's energy per phase
};

Só retire a energia de um período a partir de dois registos horários consecutivos quando os respetivos carimbos temporais diferem exatamente em um período e nenhum deles traz a flag de salto de vida útil.

bool stdHistReadRaw(RbAmpStdHistPeriod period, uint16_t back, uint8_t rec[rbamp_std::REG_HIST_REC_SIZE], uint8_t* flags) noexcept

Obtém um registo não descodificado de qualquer anel em rec; flags (opcional) recebe as flags de registo do módulo.

bool stdEventRead(uint16_t back, RbAmpStdEvent& out) noexcept

Obtém e descodifica um registo do registo de eventos (back = 0 é o mais recente); RB_ERR_NOT_READY = não existe esse registo.

C++
struct RbAmpStdEvent {
    uint32_t ts;         // Unix time (0 if the clock was not set)
    uint32_t uptime_s;   // module uptime at the event
    uint8_t  type;       // record type
    uint8_t  flags;
    uint16_t boot;       // boot counter at the event
    uint32_t a_before, a_after;          // event-specific values
    uint64_t e_before_wh, e_after_wh;    // life-time energy before / after, Wh
};

bool stdHistFlush() noexcept

Peça ao módulo que escreva agora os seus acumuladores de energia na memória.

Atualização de firmware por I²C

Uma atualização em duas fases: stdOtaBegin() → stdOtaWritePage() por cada página → stdOtaCommit() (verifica a imagem e arma a troca; sem reinício) → stdOtaActivate() (reinicia para a nova imagem quando estiver pronto). Na prática use stdOtaWritePreparedImage(), que faz begin + páginas + commit numa só chamada, e depois stdOtaActivate(). Os módulos aceitam apenas imagens preparadas pelo fabricante; uma imagem má é revertida pelo próprio módulo e a calibração sobrevive. Cada passo aguarda que o módulo indique que o comando terminou (sem pausas fixas). Todas as chamadas falham com RB_ERR_NOT_IMPLEMENTED a menos que o módulo reporte a capacidade de atualização.

C++
typedef void (*RbAmpOtaProgress)(uint32_t done, uint32_t total, void* ctx);
Chamada Descrição
bool stdOtaStatus(uint8_t& out) Estado de atualização do módulo (rbamp_std::OTA_IDLE / READY / OK / ERR / DOWNGRADE).
bool stdOtaBegin(uint32_t timeout_ms = 0) Apague o banco inativo e aguarde até o módulo indicar que está pronto. 0 = predefinido (5 s). false com RB_ERR_TIMEOUT se não for atingido.
bool stdOtaWritePage(uint32_t page_idx, const uint8_t* page) Escreve uma página de 256 bytes no índice page_idx. false com RB_ERR_CHECKSUM se a carga chegou corrompida (reenvie a mesma página), RB_ERR_IO se o módulo falhou a página, RB_ERR_NOT_READY se a sessão já não estiver aberta — nos dois últimos casos recomece a partir de stdOtaBegin() (ver stdOtaDiag()).
bool stdOtaCommit(uint32_t timeout_ms = 0) Verifica a imagem gravada e arma a troca de banco. 0 = predefinido (3 s). RB_ERR_CHECKSUM imagem corrompida, RB_ERR_VERSION imagem mais antiga do que a em execução (rejeitada), RB_ERR_TIMEOUT.
bool stdOtaActivate() Reinicia para a imagem armada, aguarda que o módulo volte, redescobre-o, confirma que o banco em execução mudou e aguarda que a nova imagem se confirme a si própria. Bloqueia durante toda a sequência (cerca de 12 s). A instância mantém-se associada e stdInfo() reflete o novo firmware. false com RB_ERR_NOT_READY se nada estava armado, se o módulo voltou ao banco anterior ou nunca confirmou a nova imagem; RB_ERR_VERSION se a imagem que passa a correr não for a preparada (repôs a versão anterior).
static uint32_t stdCrc32(const uint8_t* data, size_t len) CRC-32 (compatível com zlib) — a soma de verificação por página que o módulo verifica.
bool stdOtaWritePreparedImage(const uint8_t* image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Envia uma imagem de banco preparada (begin + páginas + commit; sem activate). len tem de ser igual ao tamanho do banco do módulo, senão RB_ERR_PARAM. As páginas seguem por ordem crescente, as páginas em branco são ignoradas, e uma página que o módulo reporta como corrompida é reenviada uma vez.
bool stdOtaWritePreparedImage(Stream& image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Forma de fluxo — uma página mantida em RAM.
bool stdOtaWritePreparedImage(const uint8_t* bank_a, const uint8_t* bank_b, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Forneça as duas imagens por banco; a biblioteca escolhe a do banco que não está em execução. RB_ERR_NOT_IMPLEMENTED se o módulo não reportar o banco em execução.
bool stdOtaActiveBank(uint8_t& out) Id do banco em execução: 0 = A, 1 = B.
bool stdOtaStagedVersion(uint32_t& out) Versão da imagem armada (com commit, ainda não ativada); 0 quando nada está armado.
bool stdOtaDiag(uint8_t& reason, uint8_t& hal_status) O motivo do módulo para a última falha de atualização mais um byte de estado de baixo nível. Leia-o após uma falha de commit ou de escrita de página.
bool stdOtaAbort() Feche a sessão de atualização / desarme uma imagem armada sem reiniciar.
bool stdOtaBoardOk(uint32_t image_board_word) Recusa uma imagem criada para outra placa antes de a enviar: compara o id da placa do módulo com a palavra de placa da imagem (do manifesto da imagem). Uma incompatibilidade devolve RB_ERR_PARAM; RB_ERR_NOT_IMPLEMENTED em módulos que não reportam id de placa.
bool stdOtaWriteImage(const uint8_t* image, size_t len, uint32_t version, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) e a forma Stream& Mantido apenas por compatibilidade de código-fonte: devolve false com RB_ERR_NOT_IMPLEMENTED sem tocar no módulo. Use stdOtaWritePreparedImage().

RbAmpFleet — gestão de vários módulos

A classe RbAmpFleet é a principal superfície de alto nível da biblioteca v1.3. Gere uma coleção de módulos num barramento I²C partilhado: descoberta, provisionamento, agregação de consultas, agregação de erros e instantâneos síncronos através de difusão General-Call.

Uma frota fica ligada a um único barramento TwoWire (normalmente Wire); cada módulo adotado é um handle RbAmp próprio. O limite flexível de módulos é RBAMP_FLEET_MAX_MODULES = 16.

Ciclo de vida

C++
RbAmpFleet(TwoWire& bus);
~RbAmpFleet();              // releases all adopted handles

Após ~RbAmpFleet(), quaisquer ponteiros de handle obtidos via get(idx) ficam inválidos.

Descoberta — scan()

C++
bool scan(bool match_product, size_t& added);

Sonda o barramento no intervalo 0x08..0x77, e para cada endereço que responde com ACK:

  1. Verifica a identidade (PRODUCT_ID, HW_VARIANT, CAPABILITY). Se match_product = true, exige correspondência com o PRODUCT_ID da rbAmp.

  2. Executa um detetor de conflitos com dois sinais independentes (consistência de identidade + valor em tempo real). Os endereços suspeitos vão para a lista excluded, e não para a frota.

  3. Executa uma verificação de bloqueio de Tier-2: sonda um endereço onde comprovadamente não deve haver ninguém. Se a verificação obtiver um ACK, devolve false — o barramento está bloqueado e a frota fica vazia (ver os diagnósticos no cap. 10).

Após o sucesso, added contém o número de módulos acrescentados à frota. excludedCount() (ver abaixo) está disponível através de um getter separado.

Acesso ao módulo

C++
size_t count() const noexcept;
RbAmp* get(size_t index) noexcept;
RbAmp* find(uint8_t address) noexcept;
bool add(RbAmp* dev) noexcept;

size_t excludedCount() const noexcept;
int excludedAddr(size_t i) const noexcept;

get devolve nullptr fora do intervalo; find devolve nullptr se o endereço não estiver na frota (por exemplo, porque ficou excluído). add permite acrescentar manualmente um identificador criado à parte (por exemplo, após um provisionamento manual).

Consulta — pollAll()

C++
bool pollAll(RbAmpSnapshot* snaps,
             RbAmpFleetPoll* status,
             size_t capacity,
             size_t& n_ok);

Consulta todos os módulos da frota numa só chamada. Para cada módulo executa uma leitura RT completa (readAll()), anexando o resultado ao elemento snaps[i] correspondente. Em paralelo, status[i] recebe o resultado por módulo (ok=true/false + addr + channels).

Após o retorno, n_ok é o número de módulos para os quais se obteve um instantâneo válido.

Resiliente a falhas (MISS): um módulo silencioso não cancela a consulta dos restantes. Isto é importante numa frota em produção — perder um módulo (um fio partido, uma queima) não pode derrubar toda a monitorização.

Agregação

C++
bool totalPower(float& out_w) noexcept;
bool totalEnergyWh(double& out_wh) noexcept;
bool pollErrors(uint32_t& error_mask, size_t& n_errors) noexcept;

totalPower soma a potência ativa de todos os canais de todos os módulos. Nas variantes I não há potência ativa → contribuem com 0. Na implementação canónica (UI1 de rede + sub-contadores I2/I3) o resultado é a potência ativa do módulo de rede.

totalEnergyWh soma igualmente os acumuladores de Wh dos handles. Também funciona corretamente: as variantes I dão 0, a UI1 dá energia por carga.

pollErrors percorre a frota, chamando hasError() em cada módulo; error_mask é uma máscara de bits dos módulos com a flag EVENT bit3 pela sua posição (significativa para os primeiros 32 módulos); n_errors é o número total de módulos com a flag de erro no momento da consulta.

Endereçamento e verificação de conflitos

C++
bool assignAddress(RbAmp* dev, uint8_t new_addr);
bool checkConflict(uint8_t addr, bool& collision) noexcept;

assignAddress reatribui um módulo existente da frota a um novo endereço: internamente — um commit em duas fases + reinício; o identificador na frota é atualizado automaticamente (as chamadas seguintes continuam a funcionar).

checkConflict — uma verificação de melhor esforço, só de leitura, para um endereço específico: lê a identidade (PRODUCT_ID / HW_VARIANT / CAPABILITY) e compara-a com o estado em cache da frota. Se for detetada uma inconsistência — collision = true. Para percorrer todos os endereços conhecidos, itere sobre a frota: for (size_t i = 0; i < fleet.count(); ++i) + checkConflict(fleet.get(i)->address(), col). Não garante apanhar módulos idênticos — ver a disciplina de provisionamento.

Provisionamento — provision() (estático)

C++
static bool provision(TwoWire& bus,
                      uint8_t desired_addr,
                      bool save_config,
                      RbAmp*& out_dev);

Recebe um TwoWire& (normalmente Wire) e out_dev como parâmetro de saída. Em caso de sucesso, out_dev passa a pertencer ao chamador — normalmente passa-o diretamente a fleet.add(out_dev):

Provisiona exatamente um módulo virgem (de fábrica em 0x50) para o endereço indicado. Internamente:

  1. Verifica se há resposta em 0x50.
  2. Verifica que ninguém está ainda em desired_addr.
  3. Executa o commit de endereço em duas fases.
  4. Reinicia o módulo e aguarda que apareça em desired_addr dentro da janela de arranque.

  5. Cria o identificador; se save_config = true — chama saveUserConfig() (grava na flash).

  6. Devolve o identificador pronto através de out.

Segurança

⚠ OBRIGATÓRIO: exatamente um módulo virgem no barramento no momento da chamada. Dois módulos em 0x50 ao mesmo tempo são fisicamente indistinguíveis em I²C — não se conseguem diferenciar nem com hardware especial. A garantia assenta no operador, não na biblioteca. Para recuperação veja 10 · Resolução de problemas, secção "Frota: falha no provisionamento".

Sincronização GC da frota — instantâneos síncronos em toda a frota

C++
bool enableGcAll(uint8_t group, size_t& ok_count);
bool gcLatch(uint8_t group, uint16_t tick, uint16_t settle_ms);
bool checkSync(uint16_t expected_tick,
               RbAmpFleetSync* status,
               size_t status_cap,
               size_t& n_missed);

Para uma sincronização apertada dos instantâneos em toda a frota utiliza-se um instantâneo de difusão I²C General-Call.

  1. enableGcAll define FLEET_CONFIG.bit0 + GROUP_ID em todos os módulos da frota e emite CMD_SAVE_USER_CONFIG em cada um (persistente). Um reinício dos módulos é obrigatório após a ativação — isto é feito automaticamente. ok_count é o número de módulos para os quais a ativação teve êxito.

  2. gcLatch envia a trama GC A5 27 group tick_lo tick_hi para o endereço 0x00 — todos os módulos com GC ativa e um group correspondente executam de imediato o comando de instantâneo (LATCH_PERIOD). settle_ms é a pausa após a trama (tipicamente 50 ms) antes da verificação.

  3. checkSync lê GC_TICK (0x59) em cada módulo para RbAmpFleetSync status[status_cap]. O resultado por módulo:

C++
struct RbAmpFleetSync {
    uint8_t  addr;        // I²C address of the module
    uint16_t gc_tick;     // REG_GC_TICK; 0xFFFF = never received a GC
    bool     in_sync;     // true if gc_tick == expected_tick
    bool     reachable;   // false if the read NACKed / timed out
};

n_missed é o número de módulos com in_sync = false (ou simplesmente sem resposta). Se todos estiverem em in_sync, então n_missed == 0.

Configuração de frota por dispositivo (v1.3)

Estes métodos trabalham com um único módulo diretamente (sem frota) — para os casos em que configura um módulo individual antes de o juntar a uma frota, ou quer controlo fino.

bool enableGc(bool enable) noexcept / bool readFleetConfig(uint8_t& out) noexcept

enableGc(true) escreve 1 em FLEET_CONFIG.bit0 (0x27) + grava na flash + reinicia — o módulo passa a aceitar instantâneos GC após o arranque. enableGc(false) limpa o bit de forma simétrica. Bloqueia durante ~1 segundo (estabilização do SAVE_USER_CONFIG + estabilização do reinício). readFleetConfig devolve o byte de configuração atual — útil para confirmar por leitura.

bool setGroupId(uint8_t group) noexcept / bool readGroupId(uint8_t& out) noexcept

GROUP_ID (0x28) — o filtro de tramas GC: o módulo só reage a tramas GC com um group_id correspondente. Predefinido = 0x00 (difusão, reage a qualquer uma). Usado em barramentos multi-inquilino — por exemplo, um grupo «fase A» e um grupo «fase B» num barramento partilhado.

bool readGcTick(uint16_t& out) noexcept

Lê GC_TICK (0x59) — o último valor de tick recebido de uma trama GC. Usado para deteção de tramas perdidas (se dois módulos tiverem ticks diferentes, alguém perdeu uma trama). 0xFFFF = o módulo nunca recebeu uma trama GC desde o arranque.

static bool broadcastLatchGroup(TwoWire& bus, uint8_t group, uint16_t tick) noexcept

Um envio de baixo nível da trama GC A5 27 group tick_lo tick_hi diretamente via bus (sem uma frota). Útil se a frota ainda não estiver criada, ou se quiser controlo manual sobre o contador de ticks.

bool readActiveAddress(uint8_t& out) noexcept

Lê REG_I2C_ADDRESS (0x30) — o endereço ativo (em funcionamento) do módulo. Na v1.3, no arranque, lê o endereço ativo, não um candidato em preparação. Na linha STD devolve o campo de endereço persistido (que se aplica após reinício). Útil para confirmar por releitura após commitAddressChange().

Classe RbAmpEnergy

Um acumulador de Wh por canal. Pertence a RbAmp e é acedido via dev.energy(). O utilizador normalmente não o cria diretamente.

Métodos públicos

C++
double wh(uint8_t ch = 0) const noexcept;

O total atual de Wh num canal, ou para todos os canais com RBAMP_ENERGY_CH_TOTAL. Com sinal — um valor negativo significa exportação líquida. Se ch estiver fora do intervalo, devolve 0.0. (Num módulo STD sem contadores por canal use RbAmp::energyWh() para obter NaN em vez de um 0 enganador.)

C++
void addWh(uint8_t ch, double wh) noexcept;

Adiciona uma energia com sinal a um canal ou ao total de todos os canais. Usado pela biblioteca no caminho de contadores STD; também disponível para código do utilizador que integre a energia por conta própria.

C++
void reset(uint8_t ch = 0) noexcept;
void resetAll() noexcept;

Zere um canal (ou o total com RBAMP_ENERGY_CH_TOTAL) ou todos os canais.

C++
void disable() noexcept;
void enable() noexcept;
bool isEnabled() const noexcept;

Ativa/desativa a integração automática. Enquanto a integração estiver desativada, readPeriodSnapshot() continua a funcionar mas não faz avançar o acumulador — útil se o master mantiver o seu próprio armazenamento persistente de Wh.

C++
uint32_t droppedDtCount() const noexcept;
void resetDroppedDtCount() noexcept;

Diagnóstico: quantos ticks de integração foram perdidos porque o período do master era superior ao limite de sanidade de uma hora.

O tick() interno

C++
void tick(const RbAmpPeriodSnapshot& snap, uint8_t channels) noexcept;

Chamado automaticamente a partir de RbAmp::readPeriodSnapshot() em caso de sucesso. O código do utilizador não o chama diretamente. Idempotente: instantâneos com valid == false são ignorados.

A fórmula de integração:

Text
wh[ch] += snap.avg_p[ch] × snap.master_dt_ms / 1000 / 3600
         [W]              [milliseconds]              → [Wh]

Exatidão

Depende da plataforma — para detalhes veja 04 · Hardware:

  • ESP32 / ESP8266 / STM32duino / SAMD / RP2040: um acumulador double de 64 bits.

  • Arduino AVR clássico (Uno, Mega, Nano): a toolchain define double como float de 32 bits. Em instalações de ensaio de longa duração, reponha o acumulador periodicamente (por exemplo, uma vez por dia).

Estruturas POD e enumerações

As estruturas da linha STD (RbAmpStd*) são descritas em conjunto com as chamadas que as devolvem na API da linha STD.

RbAmpSnapshot

Devolvido por readAll(). Todos os campos em unidades SI. Os canais não utilizados (para além de channels) são preenchidos com zeros.

C++
#define RBAMP_MAX_CHANNELS 7                       // override before including to shrink the arrays

struct RbAmpSnapshot {
    float voltage;                                 // V — RMS voltage
    float voltage_peak;                            // V — peak voltage
    float current[RBAMP_MAX_CHANNELS];             // A — RMS current per channel
    float current_peak[RBAMP_MAX_CHANNELS];       // A — peak current per channel
    float power[RBAMP_MAX_CHANNELS];               // W — active power per channel (signed)
    float power_factor[RBAMP_MAX_CHANNELS];        // dimensionless, −1..+1
    float frequency;                               // Hz — grid frequency
    RbAmpTopology topology;                        // Single / SplitPhase / ThreePhase / Five / Seven
    uint8_t channels;                              // 1..RBAMP_MAX_CHANNELS — number of valid channels
    bool has_voltage_hw;                           // true if a voltage sensor is present
    uint8_t implausible;                           // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};

bits de implausible: RBAMP_FIELD_VOLTAGE, RBAMP_FIELD_CURRENT, RBAMP_FIELD_POWER, RBAMP_FIELD_PF, RBAMP_FIELD_FREQUENCY.

RbAmpPeriodSnapshot

Devolvido por readPeriodSnapshot(). A primitiva de medição de energia.

C++
struct RbAmpPeriodSnapshot {
    float avg_p[RBAMP_MAX_CHANNELS]; // W — average active power over the period
    float max_p;                     // W — peak instantaneous power on channel 0
    uint32_t latch_ms;               // ms — period duration (device's view, diagnostic; 0 on STD)
    uint32_t master_dt_ms;           // ms — master wall-clock dt since the last snapshot
    bool valid;                      // true if the snapshot ready flag was set
    float avg_p_total;               // W — average active power over the period, all channels
    double wh_net;                   // Wh — net energy of this period (import − export)
    bool module_restarted;           // the module restarted inside this period (STD counter path only)
};
Nota

latch_ms é um temporizador de diagnóstico do módulo; não o use para energia — use o relógio do mestre (master_dt_ms).

RbAmpTopology

C++
enum class RbAmpTopology : uint8_t {
    Single      = 1,   // 1 current channel (UI1 / I1)
    SplitPhase  = 2,   // 2 current channels (UI2 / I2)
    ThreePhase  = 3,   // 3 current channels (UI3 / I3)
    Five        = 5,   // 5 current channels (UI5) — senior SKU
    Seven       = 7,   // 7 current channels (UI7) — senior SKU
};

RbAmpLine

C++
enum class RbAmpLine : uint8_t {
    Basic = 0,   // 8-bit register map (the default until begin() runs)
    Std   = 1,   // STANDARD (STD) line: 16-bit register map
};

RbAmpVariant

Unknown, UI1, UI2, UI3, I1, I2, I3, UI5, UI7 — ver readVariant().

RbAmpSensorClass

C++
enum class RbAmpSensorClass : uint8_t {
    Unset     = 0,  // Factory default; setCTModel() will refuse
    Sct013    = 1,  // SCT-013 series clamp fitted by the user
    WiredCT   = 2,  // Wired CT shipped with the module and calibrated together with it
    BuiltinCT = 3,  // Built-in CT, calibrated together with the module
};

WiredCT e BuiltinCT descrevem módulos que são fornecidos e calibrados em conjunto com o respetivo sensor. Os setters nunca reescrevem estes módulos (devolvem false com RB_ERR_MODE); setCTModelChForce() é o caminho de assistência técnica.

RbAmpCTModel

Um enum congelado de compatibilidade retroativa para os sete códigos SCT-013 (Sct013_005 … Sct013_060). O código novo passa uma define RBAMP_CT_* gerada às sobrecargas uint8_t.

RbAmpSctRating e RbAmpSctRatingStatus

Ver Correção da classificação do SCT-013.

RbAmpDrdyEvent

Ver Linha de data-ready e eventos.

Códigos de erro (espaço de nomes rbamp)

Definido em RbAmpRegisters.h, devolvido por lastError().

C++
namespace rbamp {
    constexpr int8_t RB_OK                  =  0;
    constexpr int8_t RB_ERR_IO              = -1;   // I²C transport error
    constexpr int8_t RB_ERR_NACK            = -2;   // retry exhausted, slave not responding
    constexpr int8_t RB_ERR_TIMEOUT         = -3;   // timeout (waitReady / waitDataReady / commit-addr window expired)
    constexpr int8_t RB_ERR_NOT_READY       = -4;   // module not ready / no such record / nothing armed
    constexpr int8_t RB_ERR_STALE           = -5;   // period snapshot not ready
    constexpr int8_t RB_ERR_PARAM           = -6;   // invalid channel / address / precondition; the module rejected a value
    constexpr int8_t RB_ERR_MODE            = -7;   // not allowed in the module's current mode (factory-paired class, factory-only command)
    constexpr int8_t RB_ERR_CHECKSUM        = -8;   // value check failed — checksum / signature / range
    constexpr int8_t RB_ERR_VERSION         = -9;   // unsupported firmware / image version
    constexpr int8_t RB_ERR_NOT_IMPLEMENTED = -10;  // no counterpart on this line or on this module image
    constexpr int8_t RB_ERR_NON_PHYSICAL    = -11;  // float rejected by the sanity filter
}

Receitas de diagnóstico para cada código — 10 · Resolução de problemas.

Receitas de diagnóstico para cada código — 10 · Resolução de problemas.

Configuração em tempo de compilação

Defina ANTES de #include para substituir os predefinidos:

C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5    // number of retry attempts per byte
#define RBAMP_NACK_RETRY_GAP_MS 5      // pause between attempts, ms
#include 

Predefinições da plataforma:

C++
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
#  define RBAMP_NACK_RETRY_ATTEMPTS 3
#else
#  define RBAMP_NACK_RETRY_ATTEMPTS 1
#endif
#define RBAMP_NACK_RETRY_GAP_MS 5

Para mais sobre o subsistema de resiliência — 10 · Resolução de problemas.

Constantes de tempo de estabilização

Definido em RbAmpRegisters.h. A biblioteca usa-os internamente; são exportados para os utilizadores que queiram respeitar a mesma temporização em acesso direto ao barramento:

C++
constexpr uint16_t SETTLE_MS_LATCH_PERIOD  =   50;  // after CMD_LATCH_PERIOD
constexpr uint16_t SETTLE_MS_SAVE_GAINS    =  700;  // after CMD_SAVE_GAINS (flash write)
constexpr uint16_t SETTLE_MS_RESET         =  300;  // after CMD_RESET
constexpr uint16_t SETTLE_MS_FACTORY_RESET = 1500;  // after CMD_FACTORY_RESET

Detalhes do protocolo de transmissão

Segurança

Esta secção descreve o protocolo de registos de 8 bits da linha BASIC. A linha STD usa um ponteiro de registos de 16 bits com leituras em rajada com auto-incremento; a biblioteca trata disso internamente (o begin() deteta a linha) e a cablagem física é o mesmo barramento I²C. O código da aplicação nunca precisa dos detalhes de cablagem STD — use as chamadas da API da linha STD.

Leituras de registos — auto-incremento

Uma leitura em rajada + N bytes devolve N bytes consecutivos a partir de addr. Os métodos da biblioteca usam rajadas sempre que possível (uma transação I²C = 4 bytes de float).

Escritas de registos — byte a byte (SEM incremento automático)

⚠ As escritas NÃO incrementam automaticamente. Uma escrita em rajada + N bytes grava apenas o primeiro byte — os bytes 1..N são descartados.

Um registo de múltiplos bytes é escrito um byte de cada vez — uma transação I²C separada de um byte para cada endereço:

C++
// WRONG — data loss
uint8_t label[8] = "MyMeter1";
Wire.beginTransmission(addr);
Wire.write(0x68);                  // start of LABEL
Wire.write(label, 8);              // burst — only 'M' lands
Wire.endTransmission();

// CORRECT — byte-at-a-time loop
for (int i = 0; i < 8; i++) {
    Wire.beginTransmission(addr);
    Wire.write(0x68 + i);
    Wire.write(label[i]);
    Wire.endTransmission();
}

Afeta os registos graváveis de múltiplos bytes: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, controlados pela fábrica), NF (u16), THRESH (u16). Leituras — rajada OK.

Exceção: a trama de difusão GC (5 bytes A5 27 g tl th para o endereço 0x00) é um caminho separado do protocolo de transmissão (receção general-call, não uma escrita de registo), enviado como uma única transação. Veja o cenário 12 em 06 · Exemplos.

Leitura de registos não mapeados

Qualquer leitura de um endereço não mapeado devolve 0x00. O firmware nunca emite NACK nas leituras de registos. A deteção de ausência do dispositivo faz-se pelo ACK do frame de endereço I²C, não sondando registos.

Deteção da variante

O byte de SKU autoritativo é REG_HW_VARIANT (0x55) (o método readVariant()):

valor SKU
0x01 UI1 (1× I + U)
0x02 UI2 (2× I + U)
0x03 UI3 (3× I + U)
0x04 I1 (1× I, sem U)
0x05 I2 (2× I, sem U)
0x06 I3 (3× I, sem U)
0x07 UI5 (5× I + U, SKU superior)
0x08 UI7 (7× I + U, SKU superior)

REG_TOPOLOGY (0x24) é auxiliar (indica apenas o número de canais, não distingue a presença de U). Na linha STD a biblioteca lê a identidade a partir do mapa de 16 bits do próprio módulo durante begin() e mapeia a variante em readVariant().

Instantâneo de difusão General-Call (sincronização multimódulo)

Opt-in por módulo via REG_FLEET_CONFIG.bit0 — GC_ENABLE. Predefinição DESLIGADA. Ativado via CMD_SAVE_USER_CONFIG + CMD_RESET (suave ou físico). Após a reposição o módulo fica à escuta de uma trama de difusão no endereço 0x00:

Text
addr=0x00 | A5 27   
  • A5 — marcador mágico; 27 — opcode CMD_LATCH_PERIOD.
  • — 0x00 = chamada geral a todos, caso contrário tem de corresponder a REG_GROUP_ID (0x28).
  • — o contador de período de sincronização do master de 16 bits.

A trama apenas tira o instantâneo; os opcodes destrutivos não são transmitidos por GC.

Deteção do modo de falha (dois níveis):

  1. NACK no endereço GC (imediato ao nível do barramento): se o GC estiver desativado em toda a frota — Wire.endTransmission() para 0x00 devolve um código não nulo (NACK). Isto é um erro duro, não uma perda silenciosa. A biblioteca trata-o como "GC não ativado" (exige as pré-condições de ativação + reinício).
  2. Testemunha por módulo (após a estabilização): se não ocorreu nenhum NACK — leia REG_V03_PERIOD_VALID (0x07) em cada módulo esperado. 1 = instantâneo bem-sucedido; 0 = GC desativado neste módulo ou período vazio; !=1 → recorra a um latch por dispositivo.

Referências


Fonte e problemas: rb-amp/rbamp-arduino · esta página no repositório: docs/09_api_reference.md (v1.6.2)