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

09 · Referência da API

A API pública completa do componente rbamp para ESP-IDF. A fonte é o ficheiro de cabeçalho include/rbamp.h com comentários Doxygen; o gestor multimódulo está em include/rbamp_fleet.h e o tipo acumulador de Wh em include/rbamp_energy.h.

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

Ficheiro de cabeçalho

#include "rbamp.h" — o cabeçalho público principal. Inclui transitivamente esp_err.h para esp_err_t e driver/i2c_master.h para o tipo i2c_master_bus_handle_t. Não são necessárias inclusões adicionais.

A API está envolvida num bloco extern "C" — compatível com chamadores em C e em C++.

Idiomas gerais

A API segue os padrões habituais do ESP-IDF:

  • Handle opaco: rbamp_handle_t — um typedef para struct rbamp_obj_t *; o utilizador não acede aos seus internos. Criado com rbamp_new(), libertado com rbamp_del().

  • Valores devolvidos por esp_err_t — ESP_OK em caso de sucesso, um dos códigos ESP_ERR_* em caso de falha. Use ESP_ERROR_CHECK() para tratamento com aborto em caso de erro, ou verifique manualmente.

  • Saída por ponteiro: as funções que devolvem um valor recebem um ponteiro para um buffer como último parâmetro. Isto permite que uma única chamada devolva tanto um esp_err_t como um valor.

  • Textos de erro legíveis: rbamp_err_to_str(err) devolve um apontador para uma string estática. Nunca devolve NULL.

  • Um handle, duas linhas de módulos: o mesmo handle e a mesma API escalar servem a linha BASIC e a linha STD; rbamp_begin() deteta a linha e encaminha cada chamada. As funções que existem só numa linha devolvem ESP_ERR_NOT_SUPPORTED na outra (ver rbamp_line_t e Linha STD).

  • Os comandos não são repetidos. Uma escrita de comando (instantâneo, reposição, gravação, ...) nunca é repetida após um erro de transporte — uma repetição poderia entregar o opcode duas vezes. As leituras e escritas em registos de dados mantêm a repetição em caso de NACK.

  • Mapeamento de erros usado em toda a API: ESP_ERR_NOT_SUPPORTED — a função ou funcionalidade não existe nesta linha / firmware / módulo; ESP_ERR_NOT_FOUND — o módulo ou o registo não está presente (ninguém responde, não há tal registo de histórico, não há certificado); ESP_ERR_INVALID_STATE — uma pré-condição ou sequência de chamadas está errada, ou um módulo com sensor associado está protegido (ver Códigos de erro).

Tipos

rbamp_handle_t

C
typedef struct rbamp_obj_t *rbamp_handle_t;

Um handle opaco para um dispositivo escravo. O utilizador não tem acesso aos seus campos. Criado com rbamp_new(), libertado com rbamp_del().

rbamp_topology_t

C
typedef enum {
    RBAMP_TOPOLOGY_SINGLE      = 1,  /* 1 current channel (UI1 / I1) */
    RBAMP_TOPOLOGY_SPLIT_PHASE = 2,  /* 2 current channels (UI2 / I2) */
    RBAMP_TOPOLOGY_THREE_PHASE = 3,  /* 3 current channels (UI3 / I3) */
    RBAMP_TOPOLOGY_FIVE_CH     = 5,  /* 5 current channels (UI5)      */
    RBAMP_TOPOLOGY_SEVEN_CH    = 7,  /* 7 current channels (UI7)      */
} rbamp_topology_t;

O valor é o número de canais. rbamp_begin() adota-o da variante do módulo; rbamp_new_with_topology() fixa-o em vez disso. O enum é intencionalmente não contíguo (não existe 4 nem 6): os SKUs maiores saltam de 3 → 5 → 7.

Duas constantes dimensionam os seus arrays:

Macro Valor Significado
RBAMP_MAX_CHANNELS 7 O maior número de canais que qualquer SKU expõe. Dimensione os arrays de canais com ele.
RBAMP_SNAPSHOT_CHANNELS 3 Canais transportados por rbamp_snapshot_t (ch0–2). Os canais 3+ são lidos com rbamp_read_channel() / rbamp_read_all_channels().

rbamp_sensor_class_t

C
typedef enum {
    RBAMP_SENSOR_UNSET      = 0,  /* Factory default */
    RBAMP_SENSOR_SCT013     = 1,  /* SCT-013 fitted by the user */
    RBAMP_SENSOR_WIRED_CT   = 2,  /* Wired CT shipped with the module, calibrated as a pair */
    RBAMP_SENSOR_BUILTIN_CT = 3,  /* Built-in CT, calibrated as a pair */
} rbamp_sensor_class_t;

A classe 1 é um módulo ao qual o utilizador acopla uma SCT-013 à sua escolha — o modelo de CT seleciona o tipo de sensor. As classes 2 e 3 são módulos fornecidos já com o seu sensor e calibrados com ele. A biblioteca não reescreve a classe nem o modelo de um módulo destes: rbamp_set_sensor_class() e rbamp_set_ct_model_ch() devolvem ESP_ERR_INVALID_STATE. Uma reemparelhamento de assistência passa por rbamp_set_ct_model_ch_force().

rbamp_variant_t

A variante de build de hardware, devolvida por rbamp_variant() e rbamp_read_variant():

Valor Enum Canais Tensão / potência
0 RBAMP_VARIANT_UNKNOWN — ainda não lido / não publicado
1 RBAMP_VARIANT_UI1 1 sim
2 RBAMP_VARIANT_UI2 2 sim
3 RBAMP_VARIANT_UI3 3 sim
4 RBAMP_VARIANT_I1 1 não
5 RBAMP_VARIANT_I2 2 não
6 RBAMP_VARIANT_I3 3 não
7 RBAMP_VARIANT_UI5 5 sim
8 RBAMP_VARIANT_UI7 7 sim

rbamp_line_t

C
typedef enum {
    RBAMP_LINE_BASIC = 0,  /* default until rbamp_begin() has run */
    RBAMP_LINE_STD   = 1,
} rbamp_line_t;

Um tipo de handle e uma API servem as duas linhas de módulos. rbamp_begin() descobre a linha a partir do bloco de identidade do módulo e cada chamada seguinte é encaminhada internamente. Consulte-a com rbamp_line(dev). As chamadas sem equivalente na linha detetada devolvem ESP_ERR_NOT_SUPPORTED — nunca uma leitura de registo errado. O que só a linha STD oferece (potência reativa / aparente, THD, contadores de energia com sinal, bancos de instantâneos, histórico) está reunido em Linha STD.

rbamp_snapshot_t

Devolvido por rbamp_read_all(). Todos os campos estão em unidades SI. Os canais não usados (além de channels) ficam preenchidos com zeros.

C
typedef struct {
    float voltage;          /* V — RMS voltage */
    float voltage_peak;     /* V — peak voltage */
    float current[3];       /* A — RMS current, ch0–2 */
    float current_peak[3];  /* A — peak current, ch0–2 */
    float power[3];         /* W — active power, ch0–2 (signed) */
    float power_factor[3];  /* dimensionless, −1..+1 */
    float frequency;        /* Hz — mains frequency */
    rbamp_topology_t topology;
    uint8_t channels;       /* the module's channel count: 1, 2, 3, 5 or 7 */
    bool has_voltage_hw;    /* true if a voltage sensor is present */
    uint8_t implausible;    /* bitmask of RBAMP_FIELD_* classes set to NaN; 0 = all OK */
} rbamp_snapshot_t;

Os arrays guardam apenas os canais 0–2. Num UI5/UI7 channels reporta o número completo (5 ou 7); leia os canais 3+ com rbamp_read_channel() / rbamp_read_all_channels().

Campos inverosímeis. Um único campo fora de limites não faz falhar o instantâneo inteiro: um campo que ultrapasse o seu limite de sanidade por grandeza é definido como NaN e o seu bit de classe é levantado em implausible, enquanto o resto continua utilizável e rbamp_read_all() continua a devolver ESP_OK. Verifique implausible (ou isnan() por campo) antes de consumir um valor.

Bit Significado
RBAMP_FIELD_VOLTAGE tensão / voltage_peak rejeitado
RBAMP_FIELD_CURRENT uma corrente / pico de corrente rejeitado
RBAMP_FIELD_POWER uma potência rejeitada
RBAMP_FIELD_PF um power_factor rejeitado
RBAMP_FIELD_FREQUENCY frequência rejeitada

Os limites são RBAMP_SANITY_LIMIT_V / _I / _P / _PF (500 V, 150 A, 30 000 W, 1.5). Só uma falha genuína de transporte faz rbamp_read_all() devolver algo diferente de OK.

rbamp_channel_reading_t

Devolvido por rbamp_read_channel() / rbamp_read_all_channels() — um canal, qualquer índice.

C
typedef struct {
    float   i_rms;        /* A */
    float   i_peak;       /* A */
    float   p_real;       /* W (signed) */
    float   pf;           /* −1..+1 */
    uint8_t implausible;  /* RBAMP_FIELD_* bits; the flagged field is NaN */
} rbamp_channel_reading_t;

rbamp_period_snapshot_t

Devolvido por rbamp_read_period_snapshot(). A primitiva de contabilização de energia.

C
typedef struct {
    float    avg_p[3];          /* W — average active power over the period, ch0–2 */
    float    max_p;             /* W — peak power on channel 0 during the period */
    uint32_t latch_ms;          /* ms — module-reported duration; DIAGNOSTIC, not for energy */
    uint32_t master_dt_ms;      /* ms — master wall-clock window since the previous consumed read (CANONICAL) */
    bool     valid;             /* the period was ready at read time */
    float    avg_p_total;       /* W — average active power summed over ALL channels (signed) */
    double   wh_net;            /* Wh — net energy of this period as the library accounted it (signed) */
    bool     module_restarted;  /* the module rebooted inside this period */
    uint32_t module_window_ms;  /* ms — the module's own length of the closed window (0 on STD) */
    uint16_t module_commit_ms;  /* ms — length of one module commit as inferred: 100 or 200 (0 on STD) */
    uint32_t module_uptime_s;   /* s — module uptime read with the snapshot (0 if not published) */
    bool     window_from_boot;  /* the window started at the module's boot */
    bool     window_long;       /* module_window_ms exceeds 6 h */
} rbamp_period_snapshot_t;
Campo Notas
avg_p[3] Apenas canais 0–2. Num UI5/UI7 o módulo tira o instantâneo de potência média de todos os canais de forma atómica; leia os canais 3+ com rbamp_read_period_avg_power() e o respetivo Wh com rbamp_energy_wh() (o acumulador integra todos os canais).
max_p Um pico global, medido no canal 0.
latch_ms Apenas diagnóstico; pode ler curto sob carga. A janela de integração da energia é master_dt_ms ou module_window_ms.
master_dt_ms A janela sobre a qual a biblioteca integra energia: o tempo do esp_timer próprio do master entre duas leituras consumidas consecutivas.
avg_p_total, wh_net O período somado em todos os canais. wh_net é a potência média × master_dt_ms, ou — em módulos que mantêm a energia no dispositivo — a diferença do contador do próprio módulo.
module_window_ms, module_commit_ms A medida do módulo para a janela fechada: commits contados no relógio de medição do módulo, 100 ms cada na firmware atual e 200 ms em firmware anterior à v1.2 — a biblioteca infere qual a partir do mesmo instantâneo. Normalmente serve para cruzar com master_dt_ms. Ambos são 0 na linha STD.
module_restarted O módulo reiniciou dentro do período. As suas definições de RAM (relógio, máscara de eventos, limiares, campos de digest) têm de ser aplicadas de novo — a biblioteca reaplica as que lhe pertencem. Num módulo BASIC, isto é definido no primeiro instantâneo após rbamp_begin_resume() quando a janela começou no arranque do módulo.
module_uptime_s, window_from_boot window_from_boot é true quando a janela do instantâneo começou no arranque do módulo (um reinício, ou o primeiro instantâneo desde o arranque). É sempre false quando o firmware não publica o tempo de atividade (module_uptime_s = 0).
window_long A janela ultrapassa 6 h: a média do módulo perde precisão em janelas tão longas — tire instantâneos com mais frequência.
Segurança

⚠ latch_ms é de diagnóstico, não para energia. É a medida que o próprio módulo faz do período e pode ler valores curtos sob carga. Não o use para integrar energia. O dt canónico para a energia é master_dt_ms (ou a sua própria diferença de esp_timer_get_time()), ou module_window_ms para o primeiro instantâneo após rbamp_begin_resume().

Bits de evento — rbamp_event_bit_t

Bits do byte EVENT_FLAGS pegajoso, de escrita-1-para-limpar (ver Eventos):

Enum Significado
RBAMP_EVENT_PERIOD_READY Foi tirado um instantâneo de período
RBAMP_EVENT_THRESH_I Limiar de corrente ultrapassado
RBAMP_EVENT_THRESH_P Limiar de potência ultrapassado
RBAMP_EVENT_ERROR Indicador de erro durável (ver Modelo de erro)
RBAMP_EVENT_CONFIG_CHANGED Configuração persistida alterada
RBAMP_EVENT_RESET_OCCURRED A reposição do módulo desde a última limpeza
RBAMP_EVENT_NVM_FAULT Apenas STD: falha no armazenamento de energia

rbamp_drdy_event_t

Preenchido por rbamp_wait_data_ready() / rbamp_read_all_ready():

C
typedef struct {
    bool     fresh;        /* a new snapshot of THIS module is available (true on ESP_OK) */
    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: an unmasked event is pending on this module */
    uint8_t  event_flags;  /* EVENT_FLAGS consumed on an alarm (RBAMP_EVENT_*), else 0 */
    uint32_t latency_us;   /* edge to return, µs (0 when polling) */
} rbamp_drdy_event_t;

Tipos de digest

C
typedef enum {
    RBAMP_DIGEST_I  = ..., /* RMS current per channel */
    RBAMP_DIGEST_U  = ..., /* RMS voltage (modules with voltage sensing only) */
    RBAMP_DIGEST_P  = ..., /* real power per channel, whole watts, signed */
    RBAMP_DIGEST_PF = ..., /* |power factor| per channel */
} rbamp_digest_field_t;

typedef struct {
    uint8_t status;     /* STATUS mirror at the moment of the publish */
    uint8_t seq;        /* window sequence (one step per published window, wraps 255→0) */
    uint8_t n_ch;       /* channels in the digest: min(module channels, 3) */
    uint8_t fields;     /* which rbamp_digest_field_t bits were read */
    float   i_a[3];     /* A; 0 when the field is off */
    float   u_v;        /* V; 0 when off or no voltage sensing */
    int16_t p_w[3];     /* W, signed, truncated toward 0 (|P| < 1 W reads 0); 0 when off */
    float   pf[3];      /* |PF| 0..1; 0 when off */
} rbamp_digest_t;

Tipos de correção do SCT-013

C
typedef enum {
    RBAMP_SCT_NONE,           /* no correction (scale 1) */
    RBAMP_SCT_CORRECTED,      /* scale applied to this channel */
    RBAMP_SCT_UNCALIBRATED,   /* after a reset the module applies the raw preset; scale 1, warning logged */
    RBAMP_SCT_GAIN_UNEXPECTED,/* applied gain is not that of a 30 A-calibrated module; scale 1, warning logged */
    RBAMP_SCT_UNKNOWN_MODEL,  /* model code without a known preset; scale 1, warning logged */
    RBAMP_SCT_PENDING,        /* not evaluated yet (before rbamp_begin); scale 1 */
} rbamp_sct_status_t;

typedef struct {
    rbamp_sct_status_t status;
    uint8_t model;        /* CT model the module reports for the channel */
    float   scale;        /* factor applied to current, power, energy and digest (1.0 unless CORRECTED) */
    float   gain_applied; /* gain the module applies (0 when not read) */
} rbamp_sct_correction_t;

RBAMP_SCT_NONE é reportado na linha STD, para a classe de sensor 2/3, sem modelo associado, com o modelo 3 (o sensor de 30 A de fábrica), num módulo que se corrige a si próprio (ver Correção do calibre SCT-013) e quando CONFIG_RBAMP_SCT_RATING_CORRECTION está desligado.

Os tipos da linha STD (rbamp_std_info_t, rbamp_std_channel_t, ...) são descritos em conjunto com as respetivas funções em Linha STD.

Ciclo de vida

rbamp_new

C
esp_err_t rbamp_new(i2c_master_bus_handle_t bus,
                    uint8_t addr,
                    rbamp_handle_t *out);

Cria um handle opaco para um dispositivo escravo. Internamente cria um i2c_master_dev_handle_t através de i2c_master_bus_add_device().

O número de canais e a presença de tensão são obtidos do módulo em rbamp_begin(): um UI1 reporta 1 canal, um UI3 reporta 3, um UI7 reporta 7, e assim por diante, por isso rbamp_channels(dev) está correto logo após o begin, e a API por canal (rbamp_set_ct_model_ch, ...) protege contra canais que o módulo não tem. Só quando o módulo não publica a sua variante (firmware anterior à v1.3) é que o handle recorre a RBAMP_TOPOLOGY_THREE_PHASE; a sobredeteção é inofensiva aí — canais não usados leem 0.0 A. Use rbamp_new_with_topology() para fixar um número de canais independentemente do que o módulo diga.

Parâmetro Descrição
bus Handle do barramento I²C criado através de i2c_new_master_bus().
addr Endereço escravo de 7 bits. Intervalo 0x08..0x77, predefinido 0x50.
out Onde escrever o novo handle.

Devolve: ESP_OK em caso de sucesso; ESP_ERR_NO_MEM se não for possível alocar memória; ESP_ERR_INVALID_ARG se bus == NULL ou out == NULL ou se addr estiver fora do intervalo; o esp_err_t de i2c_master_bus_add_device() em caso de erro do driver do barramento.

rbamp_new_with_topology

C
esp_err_t rbamp_new_with_topology(i2c_master_bus_handle_t bus,
                                  uint8_t addr,
                                  rbamp_topology_t topology,
                                  rbamp_handle_t *out);

Igual a rbamp_new, mas com uma topologia explícita. Fixa a contagem de canais: rbamp_begin() mantém-na mesmo que o módulo reporte outra (é registado um aviso). A variante e a presença de tensão continuam a seguir o módulo. Necessário apenas para firmware anterior à v1.3 que não publica a sua variante, ou para expor deliberadamente menos ou mais canais do que os que o módulo tem.

rbamp_del

C
void rbamp_del(rbamp_handle_t dev);

Liberta o handle e remove o i2c_master_dev_handle_t associado do barramento. Seguro chamar com NULL — não faz nada.

rbamp_begin

C
esp_err_t rbamp_begin(rbamp_handle_t dev);

Sonda o dispositivo, deteta a linha do módulo, adota a contagem de canais e a variante, e prepara um instantâneo.

Sequence:

  1. Lê REG_VERSION (0x03). Se o dispositivo não fez ACK — ESP_FAIL. Se devolveu 0x00 / 0xFF — ESP_ERR_INVALID_RESPONSE.

  2. Deteta a linha de produto (BASIC / STD) a partir do bloco de identidade do módulo e guarda-a em cache (rbamp_line()). Na linha STD a identidade também fica em cache (rbamp_std_info()) e escolhe-se o mecanismo de período.

  3. Adota a contagem de canais, a variante e a presença de tensão a partir do módulo (a não ser que uma topologia tenha sido fixada por rbamp_new_with_topology).

  4. Avalie a correção do calibre SCT-013 (ver Correção do calibre SCT-013).

  5. Escreva CMD_LATCH_PERIOD como preparação + espere 50 ms. O primeiro instantâneo após ligar é descartado. (rbamp_begin_resume() salta este passo.)

  6. Guarde esp_timer_get_time() para a integração de energia seguinte.

Idempotente mas não gratuito: cada chamada emite um instantâneo de primer.

Devolve: ESP_OK em caso de sucesso; os códigos de erro acima nos restantes casos.

rbamp_begin_resume

C
esp_err_t rbamp_begin_resume(rbamp_handle_t dev);

rbamp_begin() sem o instantâneo de primer — mantém a janela que o módulo acumulou enquanto o mestre esteve ausente. Um módulo BASIC continua a fazer a média até ao instantâneo seguinte, pelo que, após um reinício ou uma interrupção do mestre, o módulo ainda guarda a janela inteira desde o último instantâneo consumido; rbamp_begin() tiraria um instantâneo e descartá-lo-ia, esta chamada não o faz.

O primeiro rbamp_read_period_snapshot() consumido após ele integra sobre a janela própria do módulo (module_window_ms): wh_net = avg_p_total × module_window_ms, master_dt_ms é definido igual a module_window_ms e module_restarted = window_from_boot. Todos os instantâneos seguintes usam o relógio mestre como de costume. Uma primeira leitura desatualizada (período não válido, acumulador vazio) é descartada como qualquer outra, e a leitura válida seguinte continua a usar a janela do módulo.

Em firmware que não publica o tempo de atividade, window_from_boot e module_restarted ficam a false: a janela recuperada pode então incluir um reinício do módulo que a biblioteca não consegue ver. Nos módulos STD a chamada é idêntica a rbamp_begin() (a energia deles vive em contadores no módulo).

rbamp_begin_event_flags

C
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);

Os EVENT_FLAGS tal como o rbamp_begin() os encontrou (ambas as linhas; 0 se não forem legíveis). RBAMP_EVENT_RESET_OCCURRED aqui significa que o módulo tinha reiniciado antes de a biblioteca o encontrar — volte a aplicar as suas definições de RAM (relógio, máscara de eventos, limiares). A biblioteca não limpa nada no begin. Sem tráfego no barramento.

rbamp_probe

C
esp_err_t rbamp_probe(rbamp_handle_t dev);

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

Devolve: ESP_OK se o escravo respondeu com ACK e reportou uma versão suportada (não 0 nem 0xFF); ESP_FAIL caso contrário.

rbamp_wait_ready

C
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);

Sonda o bit de pronto do módulo até o bit 0 ficar ativo. Útil após ligar — o módulo pode precisar de até 100 ms para a primeira janela RT.

Devolve: ESP_OK se o bit for visto antes de timeout_ms expirar; caso contrário, ESP_ERR_TIMEOUT.

Getters de estado do handle

C
uint8_t          rbamp_firmware_version(rbamp_handle_t dev);
rbamp_topology_t rbamp_topology         (rbamp_handle_t dev);
uint8_t          rbamp_channels         (rbamp_handle_t dev);
rbamp_variant_t  rbamp_variant          (rbamp_handle_t dev);
bool             rbamp_has_voltage_hw   (rbamp_handle_t dev);
uint8_t          rbamp_address          (rbamp_handle_t dev);
rbamp_line_t     rbamp_line             (rbamp_handle_t dev);

Todas devolvem valores em cache sem tocar no barramento.

Função Devolve
rbamp_firmware_version O byte REG_VERSION guardado em cache após rbamp_begin() — na linha STD é a versão do mapa de registos, e não a versão da imagem do firmware (ver rbamp_std_read_image_version). 0 antes de rbamp_begin() ou se este falhou.
rbamp_topology O enum de número de canais — do módulo após rbamp_begin(), ou como fixado por rbamp_new_with_topology(); THREE_PHASE antes de begin / em firmware que não publica a sua variante.
rbamp_channels Número de canais de corrente válidos (1, 2, 3, 5 ou 7).
rbamp_variant A variante guardada em cache por rbamp_begin(); RBAMP_VARIANT_UNKNOWN antes de begin ou quando o módulo não a publica. rbamp_read_variant() volta a ler o registo.
rbamp_has_voltage_hw true se foi detetado hardware de medição de tensão.
rbamp_address O endereço atual de 7 bits (atualizado após rbamp_commit_address_change()).
rbamp_line RBAMP_LINE_BASIC até rbamp_begin() ser executado, depois a linha detetada.

rbamp_basic_fw_name

C
const char *rbamp_basic_fw_name(uint8_t version);

Uma consulta pura (sem tráfego no barramento): o nome legível do firmware para o byte REG_VERSION de um BASIC, tal como devolvido por rbamp_firmware_version() — por exemplo 0x0D → "1.4.21", 0x0C → "1.4.20", 0x0B → "1.4.19", 0x0A → "1.4.18", 0x07 → "1.4.15-1.4.17", 0x05 → "1.4.4-1.4.14", 0x04 → "1.2-1.4.3", 0x00..0x03 → "<1.2". Qualquer outro byte → NULL (desconhecido, ou não é um módulo BASIC).

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

Todas as funções devolvem esp_err_t. Em ESP_OK o valor é escrito no ponteiro out; em caso de erro *out é indefinido. Por baixo existe uma disciplina de retentativa + sanidade para resistir às raras falhas de ligação na pilha I²C do ESP-IDF.

Leituras por canal

C
esp_err_t rbamp_read_voltage      (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_voltage_peak (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_current      (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_current_peak (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_power        (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_power_factor (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_frequency    (rbamp_handle_t dev,                float *out);
Função Valor de retorno Notas
rbamp_read_voltage Tensão RMS, V phase = 0 na linha BASIC
rbamp_read_voltage_peak Tensão de pico, V Lê 0 no mapa de módulo STD 0x34 e anteriores — use o max_u / min_u de um banco de instantâneos
rbamp_read_current Corrente RMS no canal, A ch < rbamp_channels(dev); os canais 3+ (UI5 / UI7) são encaminhados transparentemente pela janela de canais
rbamp_read_current_peak Pico de corrente no canal, A Lê 0 no mapa de módulo STD 0x34 e anteriores — use o max_i de um banco de instantâneos
rbamp_read_power Potência ativa, W (com sinal) Negativo = exportação (instalações fotovoltaicas / bidirecionais)
rbamp_read_power_factor Fator de potência Adimensional, −1..+1
rbamp_read_frequency Frequência da rede, Hz 50.0 ou 60.0 numa rede saudável. STD: um valor de módulo de 0 (sem rede) devolve ESP_ERR_INVALID_RESPONSE com *out = NaN

Se ch ou phase estiver fora do intervalo, devolve ESP_ERR_INVALID_ARG.

Leitura única de todo o bloco RT

C
esp_err_t rbamp_read_all(rbamp_handle_t dev, rbamp_snapshot_t *out);

Equivalente a chamadas sequenciais de rbamp_read_voltage + rbamp_read_voltage_peak + rbamp_read_current(0..N) + rbamp_read_current_peak(0..N) + rbamp_read_power(0..N) + rbamp_read_power_factor(0..N) + rbamp_read_frequency. Os canais não utilizados (além de rbamp_channels(dev)) são preenchidos com zeros.

Num módulo com mais de três canais (UI5 / UI7) só os canais 0–2 são lidos para a estrutura (RBAMP_SNAPSHOT_CHANNELS = 3); os canais 3+ não são tocados — leia-os com rbamp_read_channel() / rbamp_read_all_channels(). Na linha STD, o bloco de tensão e cada bloco de canal são lidos por inteiro (uma transação cada).

Um campo que ultrapassa o seu limite de sanidade não faz falhar a chamada: é definido como NaN e marcado em snap.implausible, e a chamada continua a devolver ESP_OK (ver rbamp_snapshot_t).

Devolve: ESP_OK em caso de sucesso (verifique implausible); caso contrário, o primeiro erro de transporte subjacente — nesse caso o conteúdo de out é parcial e não deve ser usado.

Potência reativa e aparente

C
esp_err_t rbamp_read_reactive_power(rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_apparent_power(rbamp_handle_t dev, uint8_t ch, float *out);

Potência reativa do canal ch em var (com sinal) e potência aparente em VA. Estas grandezas existem apenas na linha STD; no BASIC, a potência reativa não é exposta por esta biblioteca, e num handle BASIC ambas devolvem ESP_ERR_NOT_SUPPORTED.

Acesso aos canais (canais 3 e acima)

Os canais 0–2 vivem no bloco RT plano. Nos SKUs maiores (UI5 / UI7) os canais 3+ só são acessíveis através da janela de canais do módulo. A biblioteca trata disto de forma transparente: rbamp_read_current(), rbamp_read_current_peak(), rbamp_read_power() e rbamp_read_power_factor() aceitam qualquer ch em 0..rbamp_channels(dev)-1 e encaminham os canais 3+ pela janela. A seleção da janela é um recurso partilhado único dentro do módulo, e a seleção + leitura é uma secção atómica — não partilhe um handle entre tarefas sem o seu próprio mutex.

C
esp_err_t rbamp_read_channel     (rbamp_handle_t dev, uint8_t ch,
                                  rbamp_channel_reading_t *out);
esp_err_t rbamp_read_all_channels(rbamp_handle_t dev,
                                  rbamp_channel_reading_t *out, uint8_t n);
  • rbamp_read_channel lê os quatro campos RT de um canal para um rbamp_channel_reading_t. Um campo que ultrapasse o seu limite de sanidade fica com NaN e com o seu bit RBAMP_FIELD_* em implausible.

  • rbamp_read_all_channels preenche out[] com todos os canais preenchidos; n é a capacidade de out (dimensione-o com RBAMP_MAX_CHANNELS); a chamada preenche min(n, rbamp_channels(dev)) entradas.

Devolve: ESP_OK (verifique implausible); ESP_ERR_INVALID_ARG para um canal inválido ou NULL; caso contrário, o primeiro erro de transporte.

Estes são valores em tempo real e instantâneos. Uma varredura pelos canais lê janelas de publicação adjacentes e não é um instantâneo simultâneo — para energia alinhada entre canais use o caminho de período.

Nota

rbamp_read_all() num UI5 / UI7 devolve os primeiros três canais (RBAMP_SNAPSHOT_CHANNELS = 3) e deixa o resto intacto; snap.channels continua a indicar a contagem real do módulo.

rbamp_read_commit_seq

C
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);

Lê o byte de sequência do digest: um uint8_t que incrementa uma vez por janela de medição (a cada 100 ms no firmware atual, 200 ms em imagens anteriores à v1.2; passa de 255 para 0). Leia-o antes e depois de uma leitura de vários registos — um valor inalterado prova que todas as leituras vieram do mesmo commit. O digest não tem CRC.

Data-ready (DRDY)

Temporização da janela de tempo real de 100 ms, do pulso de dados prontos e da leitura atómica do bloco.
Cada módulo aciona uma linha de dreno aberto opcionalDRDYsaída: HIGH em repouso (pull-up do master), um pulso LOW de ~10 µs sempre que um instantâneo completo de medição é publicado (a cada 100 ms em toda a família; imagens BASIC anteriores à v1.2 e imagens STD até 0x7B: 200 ms). Vários módulos podem partilhar uma linha OR cablada. Os módulos BASIC também mantêm a linha firmemente em LOW enquanto houver um evento não mascarado pendente (alarme).

A biblioteca transforma o pulso num despertar, para que um leitor nunca leia o mesmo instantâneo duas vezes, nunca atravesse uma publicação e fique a saber quantos instantâneos perdeu. Nos módulos STD, o contador de publicação indica qual módulo emitiu o pulso numa linha partilhada. Sem um fio DRDY, as mesmas chamadas funcionam por sondagem do contador do módulo a cada CONFIG_RBAMP_DRDY_POLL_MS. Os módulos STD anteriores à imagem 0x00010075 acionam o pino de forma diferente: a biblioteca trata-os como sem linha DRDY e faz sondagem.

C
esp_err_t rbamp_set_drdy_gpio  (rbamp_handle_t dev, int gpio);
esp_err_t rbamp_wait_data_ready(rbamp_handle_t dev, uint32_t timeout_ms,
                                rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_all_ready (rbamp_handle_t dev, uint32_t timeout_ms,
                                rbamp_snapshot_t *out, rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_data_seq  (rbamp_handle_t dev, uint16_t *out);
Função Descrição
rbamp_set_drdy_gpio(dev, gpio) Ligue a linha DRDY deste módulo, ou desligue-a com -1. O GPIO é configurado como entrada com pull-up e interrupção na descida; qualquer número de handles pode partilhar um GPIO. Chame-a depois de rbamp_begin() (o contrato elétrico da linha depende do módulo detetado). Devolve ESP_ERR_NO_MEM se estiverem em uso mais de 4 linhas distintas ou mais de 8 handles por linha.
rbamp_wait_data_ready(dev, timeout_ms, ev) Bloqueia até o módulo publicar um instantâneo mais recente do que o último que esta chamada devolveu (ou a última leitura por rbamp_read_all_ready), no máximo timeout_ms. ev pode ser NULL.
rbamp_read_all_ready(dev, timeout_ms, out, ev) rbamp_wait_data_ready() seguido de rbamp_read_all(): uma leitura coerente por cada instantâneo publicado, nunca o mesmo instantâneo duas vezes.
rbamp_read_data_seq(dev, &seq) A sequência atual de instantâneos sem esperar.

Como funciona a espera com uma linha DRDY. Acorda na descida do sinal e verifica depois se a sequência do módulo avançou (um pulso numa linha partilhada pode pertencer a outro módulo — a chamada continua a aguardar). Se a linha continuar em LOW 5 ms após a descida, há um evento não mascarado pendente em algum módulo da linha: as flags de todos os módulos ligados a ela são lidas e limpas (escrita-1-para-limpar, que liberta a linha — uma linha presa esconderia os impulsos dos outros módulos). As flags deste módulo voltam em ev com alarm ativo; as flags dos outros módulos são entregues aos respetivos handles e reportadas na sua próxima espera.

Devolve (rbamp_wait_data_ready): ESP_OK (instantâneo novo); ESP_ERR_TIMEOUT; ESP_ERR_NOT_SUPPORTED em módulos STD sem contador de publicação (versão do mapa de registos abaixo de 0x36).

C
rbamp_set_drdy_gpio(dev, GPIO_NUM_4);
while (1) {
    rbamp_snapshot_t s;
    rbamp_drdy_event_t ev;
    if (rbamp_read_all_ready(dev, 500, &s, &ev) == ESP_OK) {
        if (ev.missed) ESP_LOGW(TAG, "missed %u snapshot(s)", ev.missed);
        /* use s — exactly one read per published snapshot */
    }
}

Digest BASIC

O digest é um bloco compacto que um módulo BASIC publica com cada janela. Permite ao mestre ler o resultado da janela numa transação I²C em vez de uma por campo.

C
esp_err_t rbamp_set_digest_fields(rbamp_handle_t dev, uint8_t fields);
esp_err_t rbamp_read_digest      (rbamp_handle_t dev, rbamp_digest_t *out);
  • rbamp_set_digest_fields(dev, fields) escolhe os campos que o módulo empacota no digest: um OR de RBAMP_DIGEST_I, _U, _P, _PF (não 0). O valor predefinido quando nunca é chamada é corrente + potência real, mais tensão nos módulos com deteção de tensão. A escolha é escrita no módulo na próxima rbamp_read_digest() (ou de imediato, quando o handle já estiver iniciado num módulo BASIC com a capacidade de digest). O módulo guarda-a apenas na RAM, por isso a biblioteca volta a escrevê-la após um reinício de módulo detetado. Devolve ESP_ERR_INVALID_ARG para 0, para bits desconhecidos, ou quando o módulo rejeita um campo que não tem (tensão num módulo só de corrente); ESP_ERR_NOT_SUPPORTED na linha STD ou em firmware sem a capacidade de digest.

  • rbamp_read_digest(dev, &d) lê o estado, a sequência de janelas e os campos escolhidos dos canais 0–2 numa só transação. Destina-se a ler cada janela publicada em DRDY: rbamp_wait_data_ready() seguido de rbamp_read_digest() dá a potência real com sinal de cada janela por poucos bytes de barramento. Os canais 3+ não estão no digest (use rbamp_read_channel()). A potência real vem em watts inteiros — uma carga abaixo de 1 W lê 0. Devolve ESP_OK; ESP_ERR_NOT_SUPPORTED na linha STD ou no firmware BASIC sem a capacidade de digest; erros de transporte.

Contabilização por período

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

rbamp_latch_period

C
esp_err_t rbamp_latch_period(rbamp_handle_t dev);

Escreve CMD_LATCH_PERIOD (0x27) em REG_COMMAND. Não espera — o chamador tem de aguardar 50 ms de estabilização e verificar rbamp_is_period_valid() antes de ler.

Para a maioria dos casos de uso, use rbamp_read_period_snapshot() — encapsula a sequência completa.

rbamp_is_period_valid

C
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);

Lê o bit de instantâneo pronto. *out = true se o último instantâneo estiver atualizado.

rbamp_read_period_avg_power

C
esp_err_t rbamp_read_period_avg_power(rbamp_handle_t dev,
                                      uint8_t ch, float *out);

Potência ativa média no canal durante o período do instantâneo. Deve ser chamada após rbamp_latch_period() + uma estabilização de 50 ms + uma verificação de validade.

rbamp_read_period_max_power

C
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);

Potência instantânea de pico no canal 0 durante o período do instantâneo. ch=0 apenas no firmware v1.

rbamp_read_period_latch_ms

C
esp_err_t rbamp_read_period_latch_ms(rbamp_handle_t dev, uint32_t *out);

A duração do período tal como vista pelo dispositivo, em ms.

Valor de diagnóstico.

O tempo reportado pelo módulo pode ler curto sob carga. Para a integração de energia, use master_dt_ms (ou module_window_ms) de rbamp_period_snapshot_t, e não este campo.

rbamp_read_period_snapshot

C
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
                                     rbamp_period_snapshot_t *out,
                                     uint16_t settle_ms,
                                     bool skip_latch);

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

  1. Se skip_latch == true — salta a escrita de LATCH (usado após uma sequência manual de comandos de instantâneo ou um instantâneo em difusão para sincronização multi-módulo).

  2. Caso contrário — escreva CMD_LATCH_PERIOD.

  3. Capture esp_timer_get_time() para calcular master_dt_ms.
  4. vTaskDelay(pdMS_TO_TICKS(settle_ms)) — 50 ms por omissão.
  5. Verifique a flag de instantâneo pronto. Se for 0 — defina ESP_ERR_INVALID_RESPONSE e registe o carimbo temporal (para que o instantâneo seguinte não conte dt em duplicado).

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

  7. Atualiza o carimbo temporal + invoca o integrador de energia para todos os canais (se o componente não tiver sido compilado com CONFIG_RBAMP_DISABLE_ENERGY).
Parâmetro Descrição
out Estrutura de saída.
settle_ms Aguarde após o instantâneo (recomendado 50).
skip_latch Se true — não escreva LATCH, leia apenas (para o padrão multi-módulo).

Devolve: ESP_OK se out->valid == true; ESP_ERR_INVALID_RESPONSE se o instantâneo estiver desatualizado (nesse caso a energia não é integrada e a âncora fica retida); ESP_ERR_NOT_SUPPORTED num módulo STD que não oferece bancos de instantâneos nem contadores; caso contrário, o esp_err_t das operações de barramento. Veja Chamadas de período na linha STD para o comportamento STD.

A energia integra sobre master_dt_ms — a janela própria do master entre leituras consumidas sucessivas. Após rbamp_begin_resume() o primeiro instantâneo consumido integra sobre a janela própria do módulo.

Cadência recomendada.

Entre chamadas de instantâneo: 60 s é confortável, 30 s é marginal, < 10 s garante leituras desatualizadas. O firmware integra o acumulador periódico internamente; chamar rbamp_read_period_snapshot() com mais frequência do que o firmware consegue preparar o período seguinte devolverá sempre um instantâneo desatualizado (ESP_ERR_INVALID_RESPONSE). Para telemetria de alta taxa use as funções RT rbamp_read_power(ch) / rbamp_read_all() — atualizam a ~10 Hz.

rbamp_read_uptime_s

C
esp_err_t rbamp_read_uptime_s(rbamp_handle_t dev, uint32_t *out);

Segundos desde o arranque do módulo. Um valor decrescente entre duas leituras significa que o módulo reiniciou. No firmware BASIC que não publica o tempo de atividade, lê 0.

Chamadas de período na linha STD

A mesma API de período serve as duas linhas, mas o que acontece por baixo depende do que o módulo STD oferece (rbamp_std_info_t.period_source, decidido por rbamp_begin()):

period_source Comportamento de rbamp_read_period_snapshot()
RBAMP_STD_PERIOD_LATCH O módulo tem bancos de instantâneos. A biblioteca usa o banco 0 (armado por rbamp_begin()): faz o latch, espera pelo menos 300 ms independentemente de um settle_ms menor (o módulo tira o instantâneo no próximo limite de janela de medição), lê o banco e converte-o em energia sobre master_dt_ms. Com skip_latch quem chama controla a temporização: faça o latch, espere ≥ 300 ms, depois leia. Mantenha o bit 0 ativo em rbamp_std_arm_banks().
RBAMP_STD_PERIOD_COUNTERS Sem bancos de instantâneos, mas com contadores de vida persistidos. Não é enviado nenhum latch e settle_ms / skip_latch são ignorados: a chamada lê os contadores e reporta a diferença desde a leitura consumida anterior em avg_p_total / wh_net. Nada se perde num reinício do módulo (module_restarted assinala-o).
RBAMP_STD_PERIOD_NONE Nenhuma das duas. As chamadas de período devolvem ESP_ERR_NOT_SUPPORTED em vez de reportar silenciosamente um período inválido.

No caminho de contadores: avg_p[] guarda o período para um módulo de canal único, as diferenças de contadores por canal nos módulos que publicam contadores por canal, e NaN nos módulos multicanal que não o fazem; max_p é NaN. Em módulos de contadores sem contadores de granularidade fina, escolha um período suficientemente longo para que um passo do contador seja uma pequena fração dele (minutos, não segundos). ESP_ERR_INVALID_RESPONSE reancora a biblioteca (esse período é descartado) quando o contador de geração do módulo mudou (os seus contadores foram repostos ou adotados) ou um contador recuou.

Outras notas STD: rbamp_latch_period() faz o latch do banco 0 (não-op que devolve ESP_OK em módulos de contadores); rbamp_is_period_valid() é true em módulos de contadores assim que a biblioteca tem uma âncora de contador (sempre após rbamp_begin()); rbamp_read_period_avg_power() devolve a média do último período consumido para módulos de contadores de canal único e ESP_ERR_NOT_SUPPORTED nos multicanal; rbamp_read_period_max_power() devolve ESP_ERR_NOT_SUPPORTED em módulos de contadores; rbamp_read_period_snapshot() devolve ESP_ERR_INVALID_RESPONSE quando o banco 0 não reporta janela decorrida — se um reinício do módulo limpou a máscara de armação do banco, a biblioteca rearma o banco 0, faz um instantâneo de primeira amostra e reinicia a âncora do relógio (essa janela não é integrada; a seguinte volta a ser completa).

Função auxiliar inline

C
static inline esp_err_t
rbamp_read_period_snapshot_simple(rbamp_handle_t dev,
                                  rbamp_period_snapshot_t *out);

Um invólucro de conveniência para os argumentos por omissão: settle_ms=50, skip_latch=false. Use-o para a sondagem periódica habitual.

Contabilização de energia (acumulador do lado do mestre)

Se o componente for compilado sem CONFIG_RBAMP_DISABLE_ENERGY=y, estão disponíveis funções de acesso ao acumulador de Wh dentro do handle:

C
double rbamp_energy_wh        (rbamp_handle_t dev, uint8_t ch);
void   rbamp_energy_reset     (rbamp_handle_t dev, uint8_t ch);
void   rbamp_energy_reset_all (rbamp_handle_t dev);
void   rbamp_energy_disable   (rbamp_handle_t dev);
void   rbamp_energy_enable    (rbamp_handle_t dev);

O acumulador é atualizado automaticamente em cada rbamp_read_period_snapshot() bem-sucedido. É com sinal — um valor negativo significa exportação líquida.

Função Descrição
rbamp_energy_wh(dev, ch) Total de Wh atual no canal. Se ch estiver fora do intervalo — 0.0.
rbamp_energy_reset(dev, ch) Põe a zero um único canal.
rbamp_energy_reset_all(dev) Põe todos os canais a zero.
rbamp_energy_disable(dev) Desative a integração automática. Útil quando o master mantém a sua própria persistência de Wh (deep-sleep — ver 06 · Exemplos, Cenário 9).
rbamp_energy_enable(dev) Reative a integração automática.

rbamp_energy_wh() aceita um índice de canal (0..rbamp_channels(dev)-1, até 6 num UI7) ou o seletor RBAMP_ENERGY_CH_TOTAL (0xFF) para o total de todos os canais. O valor tem sinal — negativo significa exportação líquida — e é 0 se ch estiver fora do intervalo ou se a energia estiver desativada.

Módulos STD sem bancos de instantâneos (caminho dos contadores): o total é a soma das diferenças dos contadores do próprio módulo — exato, nada é integrado no anfitrião. Os valores por canal vêm dos contadores por canal do módulo, quando os publica, são NaN nos módulos multicanal que não os publicam, e iguais ao total nos módulos de canal único.

Fórmula de integração:

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

Quando compilado com CONFIG_RBAMP_DISABLE_ENERGY=y, as funções (protótipos e armazenamento) são removidas do binário através de guardas #if — uma tentativa de chamar rbamp_energy_wh() produz um erro do linker "unresolved external".

O tipo do acumulador (rbamp_energy.h)

O acumulador por trás do handle vive num cabeçalho separado, rbamp_energy.h. O cabeçalho descreve-o como API interna — a aplicação normalmente usa os invólucros rbamp_energy_* acima e nunca precisa deste. Está listado aqui porque os símbolos são visíveis:

C
typedef struct {
    double wh[RBAMP_ENERGY_MAX_CH];  /* per-channel running total, Wh (signed) */
    double wh_total;                 /* all-channel total, Wh (signed) */
    bool   enabled;                  /* false: tick() is a no-op */
} rbamp_energy_t;

void   rbamp_energy_init      (rbamp_energy_t *e);
void   rbamp_energy_tick      (rbamp_energy_t *e, const float avg_p[], uint8_t channels,
                               uint32_t period_ms, bool valid);
double rbamp_energy_wh_get    (const rbamp_energy_t *e, uint8_t ch);
void   rbamp_energy_add_wh    (rbamp_energy_t *e, uint8_t ch, double wh);
void   rbamp_energy_reset_ch  (rbamp_energy_t *e, uint8_t ch);
void   rbamp_energy_reset_all_ch(rbamp_energy_t *e);
static inline void rbamp_energy_set_enabled(rbamp_energy_t *e, bool en);
Função Descrição
rbamp_energy_init Põe os contadores a zero; o acumulador começa ativo.
rbamp_energy_tick Integre um período: wh[ch] += avg_p[ch] × period_ms / 1000 / 3600 para até RBAMP_ENERGY_MAX_CH (7) canais. Ignorado silenciosamente se valid for false, se period_ms for 0 ou se o acumulador estiver desativado. period_ms tem de ser a janela de relógio de parede do mestre (master_dt_ms), e não o latch_ms do módulo.
rbamp_energy_wh_get Total acumulado de um canal; 0 se estiver fora do intervalo.
rbamp_energy_add_wh Acrescente uma quantidade já medida (Wh, com sinal) a um canal ou, com RBAMP_ENERGY_CH_TOTAL, ao total de todos os canais. Usado quando o módulo publica os próprios contadores de energia. Sem efeito enquanto estiver desativado.
rbamp_energy_reset_ch / rbamp_energy_reset_all_ch Põe a zero um canal / todos os canais.
rbamp_energy_set_enabled Ativa ou desativa a integração. Enquanto estiver desativada, tick() e add_wh() não fazem nada e as leituras continuam a devolver o valor congelado.

Identificação e provisionamento

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

rbamp_read_variant

C
esp_err_t rbamp_read_variant(rbamp_handle_t dev, rbamp_variant_t *out);

Lê o registo de variante e mapeia-o para o enum rbamp_variant_t (RBAMP_VARIANT_UI1 / _I1 / _I2 / _I3, _UI5, _UI7, ...; todos os códigos conhecidos são mapeados). Para compatibilidade com código antigo que lê o byte "bruto", pode convertê-lo de novo para uint8_t. O valor em cache de rbamp_begin() está disponível sem tráfego no barramento como rbamp_variant(). Valores:

Código SKU Canais I Canal U
1 UI1 1 sim
2 UI2 2 sim
3 UI3 3 sim
4 I1 1 não
5 I2 2 não
6 I3 3 não
7 UI5 5 sim
8 UI7 7 sim

O valor é só de leitura, guardado em ROM, e só muda com nova gravação de firmware em fábrica.

rbamp_read_capability

C
esp_err_t rbamp_read_capability(rbamp_handle_t dev, uint16_t *out);

Lê o mapa de funcionalidades a partir dos registos CAPABILITY (0x57/0x58), LE u16. Um flag indica a presença de um front-end de tensão: se estiver desligado, o módulo não calcula P / PF / Q e os valores desses registos são 0.0f. Ver a secção «CAPABILITY (0x57/0x58, u16 LE) — mapa de deteção de funcionalidades» abaixo.

rbamp_has_voltage

C
bool rbamp_has_voltage(rbamp_handle_t dev);

Uma função auxiliar sobre rbamp_read_capability — devolve true se o módulo tiver um canal U (ou seja, (cap >> 8) & 1). Fica em cache no handle na primeira chamada; as chamadas seguintes não fazem operação I²C.

rbamp_read_product_id

C
esp_err_t rbamp_read_product_id(rbamp_handle_t dev, uint8_t *out);

Lê PRODUCT_ID (0x54) — um identificador de byte da família (rbAmp = 0x01). Usado pelo scanner da frota para confirmar que o dispositivo num endereço é de facto um rbAmp, e não outro escravo I²C que por acaso respondeu nesse endereço.

rbamp_read_uid

C
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);

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 por módulo e não muda ao regravar o firmware — útil para registos em série, verificações anti-clone do lado do master e identificação ao substituir um módulo numa frota instalada.

rbamp_is_provisioned

C
esp_err_t rbamp_is_provisioned(rbamp_handle_t dev, bool *out);

Verifica se o módulo passou pelo provisionamento inicial. Tecnicamente verifica REG_ERROR != 0xFB (ERR_FLASH_PARAMS_BAD) num módulo recém-arrancado — o 0xFB é definido pelo firmware quando o bloco de configuração do utilizador está vazio / corrompido. Um módulo acabado de sair de fábrica devolve false — precisa de rbamp_save_user_config (ou de provisionamento através da frota) após a primeira configuração de modelo de TC e de endereço.

Nota

Na v1.3 este código é normal num módulo virgem (não é fatal). Não aborte o provisionamento na primeira ocorrência de 0xFB.

Linha STD. Devolve true quando o módulo reporta a sua página de calibração como válida. Fiável a partir da versão de imagem de módulo 0x00010079; as imagens anteriores também ativam o bit com os ganhos de fábrica, por isso "provisionado" não se distingue de "não calibrado" por esta chamada (use antes a fonte de calibração em rbamp_std_read_health()). A partir da versão de imagem 0x0001007A o bit vem de um marcador que o módulo escreve quando a calibração é guardada: uma unidade calibrada com firmware anterior lê false após a atualização, até um rbamp_save_gains() nela (a sua calibração em si mantém-se intacta).

rbamp_save_user_config

C
esp_err_t rbamp_save_user_config(rbamp_handle_t dev);

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

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

Returns:

  • ESP_OK — configuração guardada, sobrevive a um corte de energia.
  • ESP_ERR_TIMEOUT — o módulo não respondeu a tempo; a alimentação pode ter caído durante o ciclo de escrita na flash. Verifique de novo com reset + releitura.

  • ESP_FAIL — o módulo devolveu REG_ERROR != OK após o comando. Veja rbamp_read_last_error para os detalhes.

Releitura ≠ persistência

: confirmar que um valor foi gravado na flash exige um reinício + releitura. Ver a secção Modelo de erros v1.3 abaixo e 03 · Seleção do sensor de corrente.

rbamp_read_active_address

C
esp_err_t rbamp_read_active_address(rbamp_handle_t dev, uint8_t *out);

Lê o endereço I²C ativo do módulo. No arranque este registo é fiel — lê o endereço ativo na flash (um módulo reendereçado lê o seu novo endereço). Depois de preparar um candidato com rbamp_prepare_address_change(), repete o candidato até ao commit + reinício. Útil para verificar uma alteração de endereço em duas fases após o reinício pós-commit. Na linha STD lê o endereço persistido (aplica-se no próximo reinício).

Modelo de erros v1.3

Os erros têm dois canais independentes que funcionam de formas diferentes. Perceber a diferença é fundamental 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 do componente (biblioteca) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Quando dispara Antes da transação I²C (a biblioteca interceta) Após o FW aceitar uma escrita e a rejeitar
O que vê o master ESP_ERR_INVALID_ARG do setter; REG_ERROR mantém-se em 0x00 REG_ERROR = o código de rejeição imediata; o bit3 fica ativo algumas centenas de milissegundos após a transação
Persistente não (apenas um código de retorno) última escrita de REG_ERROR; bit3 pegajoso W1C
Caminho típico Argumento fora dos limites permitidos (canal ≥ rbamp_channels(dev), uma classe desconhecida, ...) Escrita de registo em bruto que o componente não valida previamente (uma escrita de baixo nível personalizada); um modelo de CT desconhecido, que o próprio módulo rejeita

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

Todos os setters do componente (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, etc.) verificam primeiro os argumentos contra os valores permitidos. Se um argumento estiver fora do intervalo, o setter devolve ESP_ERR_INVALID_ARG sem fazer qualquer transação I²C. Por isso, o REG_ERROR do dispositivo não é tocado:

C
esp_err_t err = rbamp_set_ct_model_ch(dev, /*channel=*/99, /*code=*/3);
/* err == ESP_ERR_INVALID_ARG  (lib client-side validation) */

uint8_t reg_err;
rbamp_read_last_error(dev, ®_err);
/* reg_err == 0x00 — REG_ERROR untouched, lib intercepted before I²C */

Isto significa que, se quiser saber exatamente porque um setter recusou, a fonte fiável é o código de retorno da função + a verificação do seu próprio argumento. O REG_ERROR não lhe dirá nada neste cenário (a transação bem-sucedida seguinte é que o define).

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

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

  • REG_ERROR (0x02) guarda imediatamente o código de motivo (por exemplo, 0xFE = ERR_PARAM). Este é o resultado da última escrita: qualquer escrita bem-sucedida seguinte substitui-o. Tem de o ler logo a seguir à sua própria escrita, antes de qualquer outra transação.

  • EVENT_FLAGS.bit3 (rbamp_has_error) — pegajosa W1C. Não fica ativa de imediato: na bancada mediu-se um atraso de algumas centenas de milissegundos entre a transação rejeitada e o bit3 ser definido. Logo após a escrita o bit3 continua em 0; ao fim de 300 ms fica em 1. Depois disso o bit3 mantém-se em qualquer número de leituras.

Saída de bancada (escrita em bruto DIGEST_CONFIG = 0xFF):

Text
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3):     immediate=0, +300 ms poll#1=1, poll#2=1
Segurança

⚠ Não use has_error para validar uma escrita que acabou de fazer. Para o resultado de essa escrita específica, só rbamp_read_last_error lido imediatamente após a escrita, antes de qualquer outra transação, é fiável (além do código de retorno do setter, se existir). has_error é um canal assíncrono para monitorização por sondagem de "houve alguma falha entre duas verificações", não para validação síncrona.

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

bit3 é reapanhado pelo firmware a cada poucas centenas de milissegundos a partir do estado atual de REG_ERROR. Por isso um simples clear_event_flags(1<<3) não funciona — o bit3 volta a ser ativado de imediato a partir do REG_ERROR ainda não limpo:

Text
state: REG_ERROR=0xFE, bit3=1

clear_event_flags(1<<3)          → bit3=1 still (re-latched from REG_ERROR=0xFE)

clear_error  +  clear_event_flags(1<<3)
                                  → bit3=0 (cleared cleanly)

A ordem correta: primeiro rbamp_clear_error() (limpa REG_ERROR), depois rbamp_clear_event_flags(1<<3) (limpa o latch pegajoso). Se quiser atomicidade, não pode haver nenhuma escrita rejeitada entre as duas.

rbamp_read_last_error

C
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);

Lê REG_ERROR (0x02) diretamente — o resultado da última transação aceite pelo barramento (uma escrita ou 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 alargado.

rbamp_has_error

C
esp_err_t rbamp_has_error(rbamp_handle_t dev, bool *out);

Uma função auxiliar de conveniência sobre EVENT_FLAGS.bit3 (ERROR_OCCURRED, registo 0x2A). Devolve true se o bit3 estiver ativo. Pegajosa, escrita-1-para-limpar; não é limpa até um clear explícito (com uma ressalva — ver a secção "Limpar um erro duradouro" acima).

Usado na monitorização por sondagem de "houve alguma falha" — por exemplo, em ciclos longos em que escritas intermédias podem ter sobrescrito o REG_ERROR, mas o bit3 preserva o facto de pelo menos uma ter sido rejeitada.

rbamp_read_event_flags / rbamp_clear_event_flags

C
esp_err_t rbamp_read_event_flags(rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_clear_event_flags(rbamp_handle_t dev, uint8_t mask);

EVENT_FLAGS (0x2A) — um byte de flags pegajosas (RBAMP_EVENT_*, ver Bits de evento, incluindo RBAMP_EVENT_ERROR = bit3). A limpeza é escrita-1-para-limpar: escreva uma máscara com uns nos bits que quer repor. As flags funcionam em ambas as linhas; na linha STD precisam da versão 0x36 ou mais recente do mapa de registos (ESP_ERR_NOT_SUPPORTED abaixo).

Ajuda a separar causas: pode primeiro ler todas as flags e depois repor apenas as tratadas, deixando as não tratadas para o ciclo de sondagem seguinte.

rbamp_clear_error

C
esp_err_t rbamp_clear_error(rbamp_handle_t dev);

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

Eventos e a linha de alarme

Os eventos são um único modelo nas duas linhas: flags pegajosas (RBAMP_EVENT_*), escrita de 1 para limpar. As flags que também estão definidas na máscara de eventos mantêm a linha DRDY em BAIXO (um alarme) até serem limpas ou desmascaradas. A máscara e os limiares vivem na RAM do módulo — volte a armá-los após cada reinício do módulo (RBAMP_EVENT_RESET_OCCURRED indica-o; veja também rbamp_begin_event_flags()).

C
esp_err_t rbamp_read_event_mask     (rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_set_event_mask      (rbamp_handle_t dev, uint8_t mask);
esp_err_t rbamp_set_event_thresholds(rbamp_handle_t dev, float i_amps, float p_watts);
Função Descrição
rbamp_read_event_mask Quais as flags que mantêm a linha DRDY em LOW (a classe de alarme).
rbamp_set_event_mask Defina a máscara (RAM no módulo; 0 = a linha nunca é mantida). A escrita é relida e verificada.
rbamp_set_event_thresholds Defina os limiares (RAM no módulo): o canal de corrente mais alto acima de i_amps define RBAMP_EVENT_THRESH_I; a potência ativa total acima de p_watts define RBAMP_EVENT_THRESH_P. Um valor <= 0 ou NaN desativa esse limiar. Devolve ESP_ERR_NOT_SUPPORTED num módulo STD com versão de mapa de registos inferior a 0x36.

A comparação difere por linha. A linha STD compara a potência total absoluta (o sentido não interessa). A linha BASIC compara a soma com sinal das potências dos canais, por isso a exportação nunca dispara o limiar de potência; valores além do que a codificação BASIC consegue representar são tratados como "desativado". No STD, rbamp_read_event_flags() exige versão de mapa de registos 0x36 ou posterior (caso contrário ESP_ERR_NOT_SUPPORTED).

Configuração multicanal

Em módulos multicanal (I2, I3, UI2, UI3, e os maiores UI5 / UI7), cada canal de corrente tem o seu próprio modelo de sensor TC. A utilidade atómica para configuração em massa é rbamp_configure_channels.

rbamp_configure_channels

C
esp_err_t rbamp_configure_channels(rbamp_handle_t dev,
                                   rbamp_sensor_class_t cls,
                                   const uint8_t *models,
                                   uint8_t n);

Parameters:

  • cls — a classe do sensor, aplicada primeiro através de rbamp_set_sensor_class().
  • models — um array de n códigos de modelo de CT, um por canal.
  • n — o comprimento do array. Limitado à variante: se n for maior do que o número de canais desta variante (por exemplo, n=3 num I2), a função limita-se à contagem real de canais; os elementos extra do array são ignorados. Se n for menor do que o número de canais, os canais em falta ficam intactos (mantêm o modelo anterior). Uma entrada 0 em models salta esse canal. A chamada abrange todos os canais do módulo, incluindo os canais 3+ num UI5 / UI7.

Internamente, a função executa:

  1. set_sensor_class(cls) uma vez.
  2. Para cada canal k < min(n, n_channels): associe models[k]; cada associação é verificada de forma síncrona e confirmada por releitura.

  3. Um salvamento final de configuração do utilizador (além do que existe dentro de set_sensor_class) — ou seja, dois ciclos de apagamento + escrita na flash para a configuração inteira, em vez de 1 + n. É esta a propriedade "amiga da flash".

Ler antes de escrever. Todo o pedido é decidido antes da primeira escrita. Uma classe ou modelo que o módulo já tem não é reescrito, por isso reaplicar a mesma configuração custa apenas leituras e nenhum ciclo de flash. Num módulo de classe 2 ou 3, um pedido que mude a classe ou qualquer modelo pedido é recusado logo à entrada com ESP_ERR_INVALID_STATE e nada é escrito. Num módulo de classe 1 com firmware antigo (até 1.4.19), uma configuração que altere um modelo termina com um reinício do módulo (ver rbamp_set_ct_model_ch).

Returns:

  • ESP_OK — configuração aplicada e guardada.
  • ESP_ERR_INVALID_ARG — cls ou models[k] inválidos (validação no passo de associação, ver a secção "Modelo de erro" acima).

  • ESP_ERR_INVALID_STATE — um canal não pôde ser associado, ou o módulo está calibrado com o sensor que tem acoplado (classe 2 / 3).

  • Outros códigos do ESP-IDF — erro de barramento, timeout, etc.

rbamp_read_ct_model_ch

C
esp_err_t rbamp_read_ct_model_ch(rbamp_handle_t dev,
                                 uint8_t channel,
                                 uint8_t *out);

Lê o modelo de sensor de TC efetivamente aplicado a um canal específico (0 = não definido). Use-o para verificar a associação após rbamp_set_ct_model_ch(). Os canais 0–2 leem os espelhos planos (0x51 / 0x52 / 0x53); os canais 3+ (UI5 / UI7) leem pela janela de canal. Isto é uma leitura da RAM, não uma confirmação de persistência — para confirmar uma gravação na flash, faça reinício + nova leitura. Na linha STD lê a entrada de mapa do canal.

Gestor de frota — gestão de vários módulos

A API de frota é a superfície de alto nível principal da biblioteca. Gere uma coleção de módulos num barramento I²C partilhado: descoberta, provisionamento, agregação de leituras, agregação de erros, instantâneos síncronos.

Todas as funções da frota são thread-safe através de um mutex interno; chamadas concorrentes de tarefas diferentes são serializadas. Um único dono de fleet a partir de uma tarefa, mais acesso só de leitura (por exemplo, _count, _get) a partir das outras, é aceitável, mas coordene explicitamente operações complexas de vários passos.

Ciclo de vida

C
esp_err_t rbamp_fleet_create(i2c_master_bus_handle_t bus,
                             rbamp_fleet_t *out);
void      rbamp_fleet_destroy(rbamp_fleet_t fleet);

create recebe um barramento e devolve uma frota vazia. destroy liberta todos os handles geridos e a própria frota — após a chamada, quaisquer apontadores de handle obtidos via rbamp_fleet_get ficam inválidos.

Descoberta — rbamp_fleet_scan

C
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
                           bool match_product,
                           size_t *added);

Sonda o barramento no intervalo 0x08..0x77; 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 o detetor de conflitos (dois sinais independentes; ver 10 · Resolução de problemas, secção "Frota: um módulo acabou em excluded"). Os endereços suspeitos vão para a lista excluded, e não para a frota.

  3. Executa uma vigia de canário de tier 2: sonda um endereço onde deve estar garantidamente ninguém. Se o canário receber um ACK, devolve ESP_ERR_INVALID_STATE — o barramento está bloqueado, a frota fica vazia (ver os diagnósticos no cap. 10).

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

Saída de bancada (validada em HW numa frota heterogénea UI1+I2+I3 com pull-ups externas de 4.7 kΩ):

Text
rbamp_fleet_scan() → 3 module(s), 0 excluded
  module[0] @0x50  channels=1  voltage=yes   (UI1 — mains)
  module[1] @0x51  channels=2  voltage=no    (I2 — sub-meter)
  module[2] @0x52  channels=3  voltage=no    (I3 — sub-meter)
rbamp_fleet_count()          = 3
rbamp_fleet_excluded_count() = 0

Neste cenário um conflito de endereço iria parar na lista de excluídos (excluded_count > 0), e um barramento bloqueado terminaria em ESP_ERR_INVALID_STATE com uma frota vazia (ver 10 · Resolução de problemas).

Acesso ao módulo

C
size_t          rbamp_fleet_count(rbamp_fleet_t fleet);
rbamp_handle_t  rbamp_fleet_get(rbamp_fleet_t fleet, size_t index);
rbamp_handle_t  rbamp_fleet_find(rbamp_fleet_t fleet, uint8_t address);
esp_err_t       rbamp_fleet_add(rbamp_fleet_t fleet, rbamp_handle_t dev);

size_t          rbamp_fleet_excluded_count(rbamp_fleet_t fleet);
esp_err_t       rbamp_fleet_excluded_addr(rbamp_fleet_t fleet,
                                          size_t index,
                                          uint8_t *out);

_get devolve NULL fora do intervalo; _find devolve NULL se o endereço não estiver na frota (por exemplo, por ter ficado excluído). _add permite acrescentar manualmente um handle criado à parte (por exemplo, após uma configuração manual inicial).

Sondagem — rbamp_fleet_poll_all

C
esp_err_t rbamp_fleet_poll_all(rbamp_fleet_t fleet,
                               rbamp_snapshot_t *snaps,
                               rbamp_fleet_poll_t *status,
                               size_t capacity,
                               size_t *n_ok);

Consulta todos os módulos da frota numa só chamada. Para cada módulo é feita uma leitura RT completa (rbamp_read_all), anexando o resultado ao elemento snaps[i] correspondente. Em paralelo, status[i] recebe o resultado por módulo: ESP_OK, ESP_ERR_TIMEOUT (módulo em silêncio), ESP_FAIL (rejeição de sanidade), etc.

Após o retorno, *n_ok é o número de módulos para os quais se obteve um instantâneo válido (status[i] == ESP_OK).

Resistente a falhas (MISS): um módulo silencioso não cancela a sondagem dos restantes. Isto importa numa frota de produção — perder um único módulo (uma falha de cablagem, uma queima) não pode interromper toda a monitorização.

Agregação

C
esp_err_t rbamp_fleet_total_power(rbamp_fleet_t fleet, float *out_w);
esp_err_t rbamp_fleet_total_energy_wh(rbamp_fleet_t fleet, double *out_wh);
esp_err_t rbamp_fleet_poll_errors(rbamp_fleet_t fleet,
                                  uint32_t *error_mask,
                                  size_t *n_errors);

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

_total_energy_wh soma de forma semelhante os acumuladores de Wh dos handles. Também funciona corretamente: as variantes I contribuem com 0, o UI1 contribui com a energia da rede.

_poll_errors percorre a frota, chamando rbamp_has_error em cada módulo. *error_mask é uma máscara de bits dos módulos assinalados com EVENT bit3, pela sua posição na frota (significativo para os primeiros 32 módulos); *n_errors é o total de módulos com flag de erro no momento da consulta. Qualquer dos ponteiros pode ser passado como NULL se não for necessário.

Endereçamento e verificação de conflitos

C
esp_err_t rbamp_fleet_assign_address(rbamp_fleet_t fleet,
                                     rbamp_handle_t dev,
                                     uint8_t new_addr);
esp_err_t rbamp_fleet_check_conflict(rbamp_fleet_t fleet,
                                     uint8_t addr,
                                     bool *collision);

_assign_address reendereça um módulo já existente na frota para um novo endereço: internamente — commit em duas fases + reinício; o handle na frota é atualizado automaticamente (as chamadas seguintes continuam a funcionar).

_check_conflict — uma verificação de melhor esforço, só de leitura, para um endereço específico: chame-a uma vez por cada endereço de interesse. Lê a identidade (PRODUCT_ID / HW_VARIANT / CAPABILITY) e compara com o estado em cache da frota. Se for detetada uma incoerência (dois dispositivos a responder no mesmo endereço com bytes "misturados"; identidade diferente do estado em cache) — *collision = true. Para varrer todos os endereços conhecidos, percorra a frota você mesmo: for i in 0..count, check_conflict(fleet, addr, &col). Não garante apanhar módulos idênticos — veja a disciplina de provisionamento.

Provisionamento — rbamp_provision

C
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
                          uint8_t desired_addr,
                          bool save_config,
                          rbamp_handle_t *out);

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

  1. Verifica se há resposta em 0x50 (ESP_ERR_NOT_FOUND se não houver).

  2. Verifica que ninguém existe ainda em desired_addr (ESP_ERR_INVALID_STATE se estiver ocupado).

  3. Executa um commit de endereço em duas fases.

  4. Reinicia o módulo e aguarda que ele apareça em desired_addr dentro da janela de arranque (ESP_ERR_TIMEOUT se não aparecer).

  5. Cria um handle; se save_config = true — chama rbamp_save_user_config (persiste na flash).

  6. Devolve o handle pronto via *out.

Segurança

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

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

C
esp_err_t rbamp_fleet_enable_gc_all(rbamp_fleet_t fleet,
                                    uint8_t group,
                                    size_t *ok_count);
esp_err_t rbamp_fleet_gclatch(rbamp_fleet_t fleet,
                              uint8_t group,
                              uint16_t tick,
                              uint32_t settle_ms);
esp_err_t rbamp_fleet_check_sync(rbamp_fleet_t fleet,
                                 uint16_t expected_tick,
                                 rbamp_fleet_sync_t *status,
                                 size_t status_cap,
                                 size_t *n_missed);

Para um sincronismo apertado de instantâneos (desvio < 1 ms em toda a frota) usa-se um broadcast de instantâneo I²C General-Call.

  1. _enable_gc_all 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 — é feito automaticamente. Basta chamá-la uma vez na configuração inicial da frota. *ok_count (opcional) é o número de módulos para os quais a ativação teve sucesso.

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

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

C
typedef struct {
    uint8_t  addr;        /* module I²C address */
    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 */
} rbamp_fleet_sync_t;

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

Segurança

Não os confunda: o rbamp_broadcast_latch por dispositivo (ver a secção "Barramento multimódulo" abaixo) é uma trama no barramento; a sincronização de frota GC é a mesma trama, mas a API de frota acrescenta uma verificação de testemunho (que chegou a todos os módulos esperados). Veja também 04 · Ligação sobre as pré-condições GC.

Configuração de frota por dispositivo

Estas funções trabalham com um único módulo diretamente (sem frota) — para casos em que configura um módulo individual antes de o juntar a uma frota, ou quer controlo fino.

rbamp_enable_gc / rbamp_read_fleet_config

C
esp_err_t rbamp_enable_gc(rbamp_handle_t dev, bool enable);
esp_err_t rbamp_read_fleet_config(rbamp_handle_t dev, uint8_t *out);

enable_gc(dev, true) escreve 1 em FLEET_CONFIG.bit0 (0x27) — o módulo começará a aceitar instantâneos GC após o próximo CMD_SAVE_USER_CONFIG + reinício. enable_gc(dev, false) faz o inverso, limpando o bit (o módulo deixa de aceitar GC após o reinício). read_fleet_config devolve o byte de configuração atual — útil para confirmar por releitura.

rbamp_set_group_id / rbamp_read_group_id

C
esp_err_t rbamp_set_group_id(rbamp_handle_t dev, uint8_t group_id);
esp_err_t rbamp_read_group_id(rbamp_handle_t dev, uint8_t *out);

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.

rbamp_read_gc_tick

C
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);

Lê GC_TICK (0x59) — o último valor de tick recebido de uma trama GC. Usado para detetar tramas perdidas (se dois módulos tiverem um tick diferente, alguém perdeu uma trama).

rbamp_read_label / rbamp_write_label

C
esp_err_t rbamp_read_label(rbamp_handle_t dev, char out[9]);
esp_err_t rbamp_write_label(rbamp_handle_t dev, const char *label);

LABEL (0x68..0x6F) — uma string de etiqueta do utilizador de 8 bytes (ASCII, preenchida com zeros). Ajuda a identificar os módulos numa frota — por exemplo, "MAINS", "BOILER", "AC1". read_label devolve sempre um array de 9 bytes (8 bytes de dados + um \0 final). write_label recebe uma string terminada em nulo — os bytes extra são truncados.

Nota

A escrita é byte a byte (sem incremento automático na escrita — ver "Escritas em registos" abaixo). Depois de escrever, é preciso rbamp_save_user_config para que a etiqueta sobreviva a um reinício.

rbamp_broadcast_latch_group

C
esp_err_t rbamp_broadcast_latch_group(i2c_master_bus_handle_t bus,
                                      uint8_t group_id,
                                      uint16_t tick);

Um envio de baixo nível da trama GC A5 27 group tick_lo tick_hi diretamente através do handle bus (sem frota). Útil se a frota ainda não tiver sido criada, ou se quiser controlo manual do contador de ticks.

rbamp_reset_counters

C
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);

Repõe os contadores de diagnóstico do módulo (contagem de erros i2c, contagem de reinicializações de periféricos). Não afeta a configuração do utilizador nem a calibração. Usado em testes de bancada e em reposições periódicas de contadores em testes de longa duração em produção.

Configuração do sensor

Uma sequência de dois passos: primeiro a classe do sensor, depois o modelo. Ambos os passos são obrigatórios num módulo com sensor acoplado pelo utilizador (classe 1). Os módulos fornecidos com o seu sensor (classe 2 / 3) chegam já configurados e estão protegidos contra reescrita acidental — ver as notas de leitura-antes-de-escrita abaixo.

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

rbamp_set_sensor_class

C
esp_err_t rbamp_set_sensor_class(rbamp_handle_t dev,
                                 rbamp_sensor_class_t cls);

Define a classe do sensor e persiste-a.

Ler antes de escrever. A função lê primeiro a classe que o módulo tem. Escrever o valor que já tem é um no-op sem escrita no barramento (ESP_OK) — no módulo qualquer escrita de classe, mesmo inalterada, limpa o modelo de TC e a forma de calibração de todos os canais, por isso uma escrita desnecessária degradaria as leituras. Um módulo cuja classe é 2 ou 3 (calibrado em conjunto com o sensor montado) não é reescrito: ESP_ERR_INVALID_STATE.

Caso contrário, escreve a classe, verifica se o módulo a aceitou e persiste-a com a gravação da configuração do utilizador (~700 ms, bloqueante). Definir a classe também limpa os modelos de TC no módulo, por isso defina os modelos depois.

No firmware v1.2+ uma classe definida é pré-condição para rbamp_set_ct_model() e rbamp_set_ct_model_ch() — chamar qualquer um deles enquanto a classe ainda é RBAMP_SENSOR_UNSET devolve ESP_ERR_INVALID_STATE. Ver 10 · Resolução de problemas, secção "Corrente lê zero", para o sintoma de "escrevi UNSET por engano".

Devolve: ESP_OK em caso de sucesso, ou quando o módulo já tem esta classe; ESP_ERR_INVALID_ARG para dev == NULL, um cls não reconhecido, ou quando o módulo rejeita a escrita; ESP_ERR_INVALID_STATE quando a classe atual do módulo é 2 ou 3; códigos de erro I²C numa falha de ligação.

Linha STD. Escreve a classe como metadados (a linha STD não tem tabela de predefinições) e persiste-a; o veredicto de comando do módulo é verificado.

rbamp_set_ct_model

C
esp_err_t rbamp_set_ct_model(rbamp_handle_t dev, uint8_t code);

A forma de um só parâmetro — define o modelo de TC apenas no canal 0 (equivalente a rbamp_set_ct_model_ch(dev, 0, code); na linha STD é essa chamada). Bloqueante, ~700 ms quando escreve.

O conjunto de modelos aceites para a classe ativa é a verdade do firmware em execução — a biblioteca não mantém do lado do cliente nenhuma lista de códigos. Um par (class, model) desconhecido é rejeitado pelo módulo e devolvido como ESP_ERR_INVALID_STATE (ou ESP_ERR_INVALID_ARG da verificação síncrona da escrita). Os códigos e nomes dos modelos estão no rbamp_sensor_models.h gerado (rbamp_sensor_model_lookup()); para a classe 1:

code Modelo
1 SCT-013-005
2 SCT-013-010
3 SCT-013-030
4 SCT-013-050
5 SCT-013-100
6 SCT-013-020
7 SCT-013-060

(Todos os sete códigos SCT-013 são selecionáveis; o conjunto aceite é {1, 2, 3, 4, 5, 6, 7}.)

Preconditions.

rbamp_set_sensor_class() tem de ter sido chamada primeiro (caso contrário ESP_ERR_INVALID_STATE, sem escrita). A guarda de leitura-antes-de-escrita de rbamp_set_ct_model_ch() aplica-se também.

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

rbamp_set_ct_model_ch

C
esp_err_t rbamp_set_ct_model_ch(rbamp_handle_t dev,
                                uint8_t channel, uint8_t code);

A forma por canal. Uma chamada pública para qualquer canal; o encaminhamento é interno: os canais 0–2 preparam o modelo e aplicam-no com o comando por canal, os canais 3+ (UI5 / UI7, firmware v1.4.18+) aplicam-no através da janela de canais. Em qualquer dos casos o modelo aplicado é confirmado por releitura e depois persistido (~700 ms). channel é validado contra a contagem real de canais do módulo.

Nota

A ordem de associação é arbitrária (cânone v1.3). A associação de TC é apenas preparação: cada aplicação por canal associa apenas o seu próprio canal, por isso os canais podem ser configurados em qualquer ordem — ascendente, descendente ou intercalada — sem se sobreporem:

C
rbamp_set_ct_model_ch(dev, 0, 1);  /* channel 0 = SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3);  /* channel 1 = SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6);  /* channel 2 = SCT-013-020 */
rbamp_set_ct_model_ch(dev, 4, 3);  /* channel 4 (UI5 / UI7) */

Guarda de leitura antes da escrita. Aplicar um modelo substitui qualquer calibração que a unidade tenha para esse canal pela predefinição genérica do modelo, e o módulo faz isso mesmo quando o modelo não muda. Por isso:

  • o modelo que o canal já tem (ver rbamp_read_ct_model_ch()) é um no-op sem escrita no barramento — reaplicar uma configuração guardada a cada reconexão é seguro e não causa nenhum reinício desnecessário do módulo;

  • um módulo de classe 2 ou 3 devolve ESP_ERR_INVALID_STATE; rbamp_set_ct_model_ch_force() é o caminho de assistência.

Reinício do módulo em firmware antigo de classe 1. Num módulo BASIC de classe 1 sem a capacidade de autocorreção (firmware até 1.4.19), uma chamada que de facto altere o modelo termina com um reinício do módulo (cerca de um segundo, o mesmo UID verificado): essa é a única forma de o módulo voltar ao seu ganho calibrado após uma escrita de modelo. A biblioteca avalia então a correção da classificação (rbamp_sct_correction()) e escala as leituras a partir do ganho que o módulo aplica. O estado da RAM do módulo (campos de digest, máscara de eventos, limiares) é reaplicado pela biblioteca onde ela o gere; os acumuladores de período recomeçam, como após qualquer reinício do módulo.

Devolve: ESP_OK; ESP_ERR_INVALID_ARG se dev == NULL ou channel >= rbamp_channels(dev); ESP_ERR_NOT_SUPPORTED em firmware anterior à v1.2 (canais 0–2), ou num módulo STD que não persiste um modelo de CT por canal; ESP_ERR_INVALID_STATE se a classe for UNSET, se o módulo rejeitar o par (class, model), se o modelo aplicado falhar a confirmação por releitura, ou se o módulo for de classe 2 / 3; ESP_FAIL / ESP_ERR_TIMEOUT em falha de transporte.

Linha STD. O modelo de TC é apenas referência (metadados do SKU): não define ganho — o módulo tem a sua própria calibração por canal. No firmware atual de módulo de canal único só o modelo do canal 0 sobrevive a uma reposição.

rbamp_set_ct_model_ch_force

C
esp_err_t rbamp_set_ct_model_ch_force(rbamp_handle_t dev,
                                      uint8_t channel, uint8_t code);

O caminho de assistência: como rbamp_set_ct_model_ch(), mas escreve independentemente da classe do módulo e do modelo atualmente guardado. Substitui a calibração emparelhada desse canal pela predefinição genérica do modelo — use apenas ao re-emparelhar um módulo com um sensor novo em assistência, e siga-a com uma calibração.

rbamp_read_sensor_class

C
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);

A classe de sensor de corrente do módulo, como valor de rbamp_sensor_class_t (BASIC: o registo de classe; STD: o campo de configuração de classe).

Limites do modelo de sensor

C
bool  rbamp_sensor_model_limits (uint8_t sensor_class, uint8_t code,
                                 float *nominal_a, float *fs_a, float *peak_a);
float rbamp_sensor_model_rated_a(uint8_t sensor_class, uint8_t code);

Consultas puras no registo de modelos gerado (rbamp_sensor_models.h) — sem tráfego no barramento.

  • rbamp_sensor_model_limits preenche (qualquer saída pode ser NULL): nominal_a — a corrente RMS nominal, A; fs_a — a corrente RMS a que uma sinusoide começa a cortar, A; peak_a — o teto instantâneo de corte, A (uma carga distorcida corta em peak_a dividido pelo seu fator de crista). 0 significa desconhecido para esse modelo (códigos legados de toroide / burden). Devolve true se o par (class, code) estiver no registo, false caso contrário (as saídas ficam então a 0).

  • rbamp_sensor_model_rated_a é a forma abreviada de nominal_a. É o calibre do sensor, que pode diferir dos amperes do nome do modelo (a pinça de "5 A" tem calibre de 4.6 A). Use rbamp_sensor_model_lookup() para o nome do modelo.

Uma correspondência no registo não significa que o módulo ligado aceite o código — isso é a verdade em tempo de execução.

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

Um módulo BASIC de classe de sensor 1 é calibrado de fábrica com o sensor de 30 A (modelo 3). No firmware até 1.4.19, uma mudança para outro modelo deixa o módulo a aplicar a calibração de 30 A após um reinício, pelo que um sensor maior lê baixo. Um módulo que reporta a capacidade de autocorreção (firmware 1.4.20 e posteriores) corrige-se a si próprio e não precisa de nada disto.

Para o firmware mais antigo a biblioteca lê o ganho que o módulo aplica de facto — em rbamp_begin(), após uma escrita de modelo e após cada reinício de módulo detetado — e escala a corrente, o pico de corrente, a potência real, a potência média do período, a energia integrada, o digest e os limiares de evento a partir desse ganho e do modelo selecionado. A tensão e o fator de potência não são escalados. O resultado por canal é rbamp_sct_status_t (ver Tipos). Um ganho que ainda seja igual à predefinição bruta (o modelo foi trocado neste arranque sem reinício) dispara um reinício do módulo; um ganho aplicado inesperado, um modelo desconhecido, ou uma predefinição bruta que sobreviva ao reinício deixam as leituras sem escala com um aviso no registo. CONFIG_RBAMP_SCT_RATING_CORRECTION (por defeito ativo) desliga o mecanismo, e os valores brutos do módulo são então devolvidos.

C
esp_err_t rbamp_sct_correction(rbamp_handle_t dev, uint8_t ch,
                               rbamp_sct_correction_t *out);
esp_err_t rbamp_sct_refresh   (rbamp_handle_t dev);
Função Descrição
rbamp_sct_correction(dev, ch, &c) A correção em cache do canal ch — sem tráfego no barramento. Avaliada por rbamp_begin(), por rbamp_set_ct_model*() e após um reinício de módulo detetado (um RESET_OCCURRED limpo, um RESET pendente no digest, um uptime decrescente). ESP_ERR_NOT_SUPPORTED na linha STD.
rbamp_sct_refresh(dev) Relê agora a classe, os modelos e os ganhos aplicados e recalcula as escalas. Emite um reinício do módulo (e volta a sondar o módulo, verificando o mesmo UID) quando o ganho aplicado de um canal ainda é a predefinição bruta de um modelo diferente do de 30 A. É chamada internamente quando necessário; exposta para um anfitrião que saiba que o módulo reiniciou por outros meios. Uma operação sem efeito que devolve ESP_OK na linha STD e num módulo com autocorreção.

rbamp_save_gains

C
esp_err_t rbamp_save_gains(rbamp_handle_t dev);

Uma escrita CMD_SAVE_GAINS "nua", sem alterações de registos associadas.

Segurança

⚠ Normalmente chamada dentro do componente. Um rbamp_save_gains() isolado só é apropriado se o chamador tiver escrito manualmente em registos de calibração não públicos via acesso bruto ao barramento — é uma operação fora da garantia, que contorna a tabela de predefinições por SKU. Valores incorretos produzirão leituras erradas de corrente/potência sem avisos explícitos. Cada chamada faz um ciclo de apagar+escrever na flash (~700 ms); a durabilidade da flash é finita (~10000 ciclos por página) — não a chame num ciclo.

Linha STD. Emite a gravação da calibração (persiste o bloco de calibração: ganhos, patamares de ruído e de THD) e verifica o veredicto do comando.

rbamp_prepare_address_change / rbamp_commit_address_change

A alteração do endereço I²C do módulo faz-se através de um commit em duas fases no modo de produção. O firmware exclui deliberadamente o endereço do fluxo geral CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS — a alteração exige uma sequência explícita armada por magic.

C
esp_err_t rbamp_prepare_address_change(rbamp_handle_t dev,
                                       uint8_t new_addr);
esp_err_t rbamp_commit_address_change(rbamp_handle_t dev);

Protocolo de fio, por baixo:

  1. prepare: valida o intervalo de new_addr (0x08..0x77, ≠ atual) → escreve new_addr em REG_I2C_ADDRESS (0x30) — fica na RAM.

  2. prepare: escreva 0xA5 em REG_ADDR_COMMIT_MAGIC (0x31) — isto "arma" o commit. A janela de estado armado é de 5 segundos.

  3. commit: verifique a frescura da armação → envie CMD_COMMIT_ADDR (opcode 0x30) → persista na flash → CMD_RESET

  4. ~400 ms de arranque → atualizar o campo de endereço interno do handle.

Após um commit bem-sucedido, todas as chamadas nesta instância de handle são dirigidas ao novo endereço. A operação funciona em modo de produção (não condicionada), o que permite a troca no terreno de módulos sobresselentes de produção.

Segurança

⚠ Se a janela armada (5 s) tiver expirado — commit devolve ESP_ERR_TIMEOUT, a flag de armação é limpa e tem de recomeçar com prepare.

Linha STD. A mudança de endereço é síncrona e o handle só comuta depois de um módulo responder no novo endereço — ver rbamp_commit_address_change na linha STD. Em caso de falha, o handle mantém o endereço antigo (ESP_ERR_NOT_FOUND).

⚠ A persistência só é confirmada após um reinício. Antes do reinício, rbamp_read_* pode devolver os valores novos da RAM, mas a escrita na flash pode não ter terminado. O próprio componente faz um CMD_RESET + espera de arranque dentro de commit, por isso, após um retorno bem-sucedido, o estado fica garantidamente persistido.

⚠ 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 nesta instância de handle são dirigidas ao novo endereço de forma transparente — mas qualquer OUTRO mestre 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 estado interno ser atualizado manualmente.

rbamp_factory_reset

C
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);

O comando CMD_FACTORY_RESET (0xAA) + uma 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 às predefinições de fábrica — rbamp_sensor_class_t passa a RBAMP_SENSOR_UNSET, REG_CT_MODEL passa a 0. Qualquer definição aplicada antes via rbamp_set_sensor_class() / rbamp_set_ct_model*() desaparece. O próximo utilizador TEM de voltar a aplicar rbamp_set_sensor_class() e rbamp_set_ct_model*() antes de a contabilização voltar a funcionar. Isto não é um "reinício suave" — para um reinício suave use rbamp_reset(). rbamp_factory_reset() é reservada à recuperação de um estado conhecido como mau ou à passagem do módulo para outro utilizador / instalação.

Linha STD. Não existe aí comando de reposição de fábrica: rbamp_factory_reset() devolve ESP_ERR_NOT_SUPPORTED.

rbamp_reset

C
esp_err_t rbamp_reset(rbamp_handle_t dev);

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

Barramento multimódulo

rbamp_broadcast_latch

C
esp_err_t rbamp_broadcast_latch(i2c_master_bus_handle_t bus,
                                uint32_t timeout_ms);

Na v1.3 do firmware (REG_VERSION = 0x04) este é o caminho canónico de sincronização da frota, depois de o General-Call estar ativado em toda a frota via rbamp_fleet_enable_gc_all(). A trama General-Call de 5 bytes A5 27 faz com que cada módulo tire o seu instantâneo no grupo correspondente no mesmo instante no fio, dando sincronização apertada entre sub-medidores. A função recebe apenas o barramento: transmite a trama (ESP_OK significa que o driver do host não deu erro — o General Call é só de escrita, nenhum módulo responde com ACK; ESP_ERR_INVALID_ARG para um barramento NULL). Módulos sem suporte a General-Call, ou com ele desativado, simplesmente ignoram a trama — verifique com o testemunho por módulo (abaixo) e use a alternativa sequencial se não tiverem tirado o instantâneo. rbamp_broadcast_latch_group(bus, group, tick, timeout_ms) é igual, com filtro de grupo explícito e tick da frota.

Recuo sequencial (firmware legado ou quando o GC foi deixado desativado): uma série de rbamp_latch_period() em cada dispositivo, uma estabilização comum de 50 ms, e um rbamp_read_period_snapshot(skip_latch=true) por dispositivo — ver 06 · Exemplos, cenário "Monitorização de vários módulos".

Linha STD

A linha de módulos STD fala um modelo de registos diferente atrás do mesmo handle. rbamp_begin() deteta-o; a API escalar dos capítulos anteriores funciona sem alterações nas duas linhas (rbamp_read_current, _power, _voltage, rbamp_read_period_snapshot, rbamp_energy_wh, as chamadas de configuração, …). As funções deste capítulo são as adições exclusivas do STD: canais inteiros numa só rajada, as grandezas que só esta linha mede (potência reativa / aparente, THD, contadores de energia com sinal), bancos de instantâneos, o relógio do módulo, histórico, saúde, atualização de firmware. Todas as funções rbamp_std_* devolvem ESP_ERR_NOT_SUPPORTED num handle BASIC.

Muitas funções exigem uma versão mínima do mapa de registos do módulo (indicada como "mapa 0x35+" e semelhantes abaixo). A ativação de funcionalidades segue as capacidades e a versão do mapa que o módulo reporta (rbamp_std_info()), nunca por adivinhação; quando um módulo é demasiado antigo a função devolve ESP_ERR_NOT_SUPPORTED — na maioria dos casos sem qualquer tráfego no barramento. Um exemplo funcional é examples/std_meter/.

Identidade e descoberta

C
typedef struct {
    uint8_t  map_version;
    uint16_t capabilities;      /* RBAMP_STD_CAP_* bitmap */
    uint8_t  status;            /* RBAMP_STD_ST_* bits at begin() time */
    uint8_t  n_voltage;         /* populated voltage channels */
    uint8_t  n_current;         /* populated current channels */
    uint8_t  variant;           /* raw RBAMP_STD_VARIANT_* byte */
    uint32_t active_bank;       /* running firmware bank, 0 without OTA capability */
    uint32_t ota_bank_size;     /* flash bank size, 0 if none */
    rbamp_std_period_source_t period_source;
} rbamp_std_info_t;

typedef struct {
    uint8_t  i2c_addr;
    uint8_t  map_version;
    uint16_t capabilities;
    uint8_t  variant;
    uint8_t  n_voltage, n_current;
    uint8_t  uid[12];           /* chip UID — the identity; addresses can change */
    uint32_t fw_version;        /* running image version (map 0x35+; 0 if unknown) */
    uint32_t board_id;          /* map 0x36+; 0 below */
} rbamp_std_identity_t;
Função Descrição
rbamp_std_info(dev, &info) A identidade guardada em cache por rbamp_begin() — sem tráfego no barramento. Devolve ESP_ERR_NOT_SUPPORTED num handle BASIC ou antes de rbamp_begin(). A limitação de canais segue n_voltage / n_current: os registos de canais além dessas contagens são indefinidos e a biblioteca recusa lê-los.
rbamp_std_identify(dev, &id) Tudo o que um mestre precisa para reconhecer o módulo por trás de um handle (duas a quatro leituras curtas).
rbamp_std_probe(bus, addr, &id) Sonda um endereço num barramento sem handle — o bloco de construção de uma varredura. Rápido: sem repetições, um NACK é a resposta. ESP_OK com id preenchido; ESP_ERR_NOT_FOUND se nada fizer ACK; ESP_ERR_INVALID_RESPONSE se responder algo que não é um módulo STD (um módulo BASIC, outro chip).
rbamp_std_read_image_version(dev, &v) A versão da imagem de firmware em execução (u32, por exemplo 0x00010072). Distinta de rbamp_firmware_version(), que é a versão do mapa de registos nesta linha. 0 se o módulo não o conseguir indicar.
rbamp_std_read_board_id(dev, &id) Identificador da placa da imagem em execução (mapa 0x36+): uma palavra que codifica o hardware para o qual a imagem foi construída. Uma imagem de firmware só é aceite quando a sua palavra de placa coincide (ver rbamp_std_ota_board_ok).
rbamp_std_locate(dev) Faça piscar os LED do módulo durante cerca de 10 s para que uma pessoa o consiga localizar.
rbamp_std_set_address_by_uid(bus, shared_addr, uid, new_addr, restart_ms) Dê a um módulo num endereço partilhado o seu próprio endereço, selecionado pelo UID (mapa 0x36+). Vários módulos podem estar em shared_addr (por exemplo, a predefinição de fábrica); só aquele cujo UID coincide aceita new_addr, persiste-o e reinicia, e os outros ignoram o comando. Não precisa de handle. Após o reinício, a biblioteca sonda new_addr e verifica aí o UID. restart_ms 0 = 1500 ms. ESP_ERR_NOT_FOUND se nada responder em new_addr; ESP_ERR_INVALID_RESPONSE se um módulo responder aí mas o UID for diferente.

Como um módulo STD entrega a energia do período

C
typedef enum {
    RBAMP_STD_PERIOD_NONE     = 0,
    RBAMP_STD_PERIOD_LATCH    = 1,
    RBAMP_STD_PERIOD_COUNTERS = 2,
} rbamp_std_period_source_t;

Decidido por rbamp_begin() a partir das capacidades do módulo e exposto em rbamp_std_info_t.period_source:

  • LATCH — o módulo tem bancos de instantâneos. Um período é de instantâneo a instantâneo no banco 0; as médias e a energia por canal vêm do banco. Ver Bancos de instantâneos.

  • COUNTERS — sem bancos de instantâneos, mas com contadores de vida persistidos. Um período é a diferença entre duas leituras de contador, feitas no calendário do master; não há comando de instantâneo, nada a armar, e nada se perde num reinício do módulo. Ver Contadores de energia de vida.

  • NONE — nenhum dos dois: as chamadas de período e de energia devolvem ESP_ERR_NOT_SUPPORTED.

Blocos em tempo real

C
typedef struct {
    float   i_rms;        /* A */
    float   i_peak;       /* A — reads 0 on module map 0x34 and earlier */
    float   p, q, s;      /* W (signed), var (signed), VA */
    float   pf;           /* −1..+1 */
    float   thd_i;        /* % — 0 while harmonics are off */
    float   pf1;          /* displacement power factor — 0 while harmonics are off */
    float   q1;           /* fundamental reactive power, var — 0 while harmonics are off */
    int64_t e_import_mws; /* raw signed import accumulator, mW·samples (>= 0) */
    int64_t e_export_mws; /* raw signed export accumulator, mW·samples (<= 0) */
    uint8_t implausible;  /* RBAMP_FIELD_* bits set to NaN */
} rbamp_std_channel_t;

typedef struct {
    float   u_rms, u_peak, thd_u;  /* V, V (0 on map 0x34 and earlier), % */
    uint8_t implausible;
    float   angle_deg;             /* phase angle against voltage input 0, (−180, 180]; input 0 reads 0 */
    bool    angle_valid;           /* the module publishes the angle for this input */
} rbamp_std_voltage_t;
Função Descrição
rbamp_std_read_channel(dev, ch, &c) Um bloco de canal de corrente (I / P / Q / S / PF / pico / acumuladores de energia / harmónicos) numa só rajada; ch é 0..rbamp_channels(dev)-1. Os campos são tão coerentes quanto o módulo os publica (por janela de publicação); para um instantâneo multi-campo estritamente atómico use o instantâneo de período. Um campo que ultrapasse um limite de sanidade fica NaN com o seu bit RBAMP_FIELD_* em implausible.
rbamp_std_read_totals(dev, k, &c) Um bloco agregado: k = 0 o total geral (soma de todos os canais de corrente), k = 1..3 os totais por fase A/B/C (apenas módulos multifásicos). Os totais por fase são publicados a partir do mapa 0x36 — num módulo monofásico k = 1 é igual ao canal 0 e k = 2/3 lêem 0; abaixo de 0x36 devolvem ESP_ERR_NOT_SUPPORTED (k = 0 funciona sempre). Os campos de energia (e_import_mws / e_export_mws) não são preenchidos nos blocos agregados e lêem 0 — a energia vem dos contadores persistentes (rbamp_std_read_energy).
rbamp_std_read_voltage(dev, v, &u) Um bloco de canal de tensão (RMS / pico / THD / ângulo de fase) numa só rajada; v é 0..n_voltage-1. angle_deg / angle_valid são publicados pelos módulos trifásicos com versão de imagem 0x0001007A ou posterior; caso contrário angle_valid é false e o resto do bloco não é afetado. Num módulo trifásico de sequência direta, a entrada 1 lê cerca de −120° e a entrada 2 cerca de +120°.
rbamp_std_read_phase_seq(dev, &seq) A ordem das entradas de tensão, derivada pelo módulo a partir dos ângulos: RBAMP_STD_PHASE_SEQ_NA (menos de três entradas, ou uma entrada demasiado baixa), _FORWARD (L1-L2-L3), _REVERSE (L1-L3-L2), _ABNORMAL (sem padrão de 120°, por exemplo duas entradas ligadas à mesma fase). Devolve ESP_ERR_NOT_SUPPORTED (e *seq = NA) em módulos com versão de imagem anterior a 0x0001007A, sem tráfego no barramento.
Nota

thd_i, pf1, q1 e thd_u leem 0, exceto se a extração de harmónicos estiver ativa — veja Configuração. e_import_mws / e_export_mws são os acumuladores brutos do módulo em mW·amostras; o módulo não tem relógio, por isso converter para Wh exige o número de amostras e a sua própria temporização do período (use o caminho de instantâneos ou os contadores de vida). Para monitorização, integre p no seu intervalo de sondagem.

rbamp_read_all() num módulo STD lê o bloco de tensão e cada bloco de canal por inteiro (uma transação cada) em vez de campo a campo. rbamp_read_frequency() num módulo STD devolve ESP_ERR_INVALID_RESPONSE com *out = NaN quando o módulo publica 0 (sem rede); rbamp_read_all() então levanta RBAMP_FIELD_FREQUENCY. rbamp_read_voltage_peak() / rbamp_read_current_peak() leem 0 no mapa de módulo 0x34 e anteriores — use o max_u / min_u / max_i de um banco de instantâneos para o pico ao longo de um período.

Estado de saúde

C
typedef struct {
    uint8_t  status;        /* RBAMP_STD_ST_* bits: cal_ok / sensor_ok / mains_ok / locked / time_valid */
    uint32_t frame_count;   /* sensor frame counter — must grow between polls */
    uint32_t crc_errors;    /* sensor frame CRC error counter */
    bool     time_valid;    /* the module clock is set; false after every module reset */
    bool     nvm_fault;     /* energy store fault or corrupt (details in lta_status) */
    uint8_t  lta_status;    /* life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service) */
    uint8_t  lta_src;       /* counters loaded from: 0 none · 1 NVM · 2 backup domain · 3 legacy · 4 rollback anchor */
    uint8_t  cal_src;       /* calibration in use: 0 defaults · 1 flash · 2 EEPROM · 3 stored cal is for another range */
    uint32_t lost_frames;   /* sensor frames lost since boot — should stay flat */
    uint16_t ring_drop;     /* acquisition ring overruns since boot — should stay flat */
    uint32_t uptime_s;      /* seconds since the module booted */
    bool     maint;         /* maintenance mode active */
    uint8_t  group_status;  /* per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
    uint16_t legal_noen;    /* metering-relevant operations executed outside maintenance mode */
    uint8_t  reset_cause;   /* image 0x76+: cause of THIS boot, RBAMP_STD_RST_* bits; 0 below */
    uint16_t boot_count;    /* image 0x76+: persisted boot counter (low 16 bits); 0 below */
} rbamp_std_health_t;

rbamp_std_read_health(dev, &h) lê o estado em tempo real. Considere as leituras válidas quando status tiver RBAMP_STD_ST_SENSOR_OK e frame_count aumentar entre duas consultas. Os campos após crc_errors existem nos módulos de mapa 0x35+ e lêem zero / false nos mais antigos.

Alerta em: nvm_fault ou lta_status >= 2 (armazenamento de energia); cal_src == 3 (a calibração armazenada é para outra gama, em uso os valores predefinidos, cal_ok também limpo); lost_frames / ring_drop a crescer; time_valid false (defina o relógio); uptime_s a diminuir (o módulo reiniciou). reset_cause transporta os bits RBAMP_STD_RST_* (pino, alimentação, software = reset / ativação / mudança de endereço, watchdogs, baixo consumo, byte de opção); o bit do pino acompanha a maioria dos resets internos, por isso julgue pelos outros bits.

Configuração

C
typedef struct {
    uint8_t  sensor_class;  /* rbamp_sensor_class_t value; 0 = unset. Persisted. */
    uint8_t  ct_model;      /* CT model reference for channel 0 (metadata, sets no gain). Persisted. */
    uint8_t  tier;          /* 0 or 1. 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) */
    uint16_t start_ua;      /* starting current for energy, µA (0 = off); 0 when start_ua_supported is false */
    bool     start_ua_supported;  /* the module has the starting-current setting */
} rbamp_std_config_t;
Função Descrição
rbamp_std_read_config(dev, &cfg) O bloco de configuração (uma rajada, mais o registo de corrente de arranque onde o módulo o tem).
rbamp_std_set_harmonics(dev, enable) Ativa ou desativa a extração de harmónicas de base (THD, PF de deslocamento, Q1). Desligado por defeito no escalão regular (poupa a CPU do módulo); os campos de harmónicas leem 0 enquanto estiver desligado. Só na RAM: volta a desligado num reset do módulo. Relida e confirmada. ESP_ERR_NOT_SUPPORTED sem a capacidade THD.
rbamp_std_cal_thd_floor(dev) Calibre o piso de THD da cadeia do sensor: captura o THD bruto suavizado atual como piso, persiste-o e aplica-o em tempo real. Pré-condição: rede limpa e NENHUMA carga na TC — o valor capturado é subtraído a todas as leituras de THD posteriores. Bloqueia durante a estabilização da persistência; o veredicto vem do registo de erros do módulo (mapa 0x34+). ESP_ERR_NOT_SUPPORTED sem a capacidade THD.
rbamp_std_get_start_current(dev, &ua) A corrente de arranque para energia, em µA (0 = desligado). Abaixo desta corrente do canal, o módulo não contabiliza energia para esse canal (importação ou exportação, total geral e por canal); as próprias leituras não são afetadas. ESP_ERR_NOT_SUPPORTED sem tráfego no barramento num módulo sem esta definição (versão de imagem anterior a 0x0001007B).
rbamp_std_set_start_current(dev, ua) Defina-o: 0 = desligado, caso contrário um valor do conjunto de passos aceite pelo módulo. Aplica-se de imediato; rbamp_save_user_config() persiste-o. Relido e confirmado. ESP_ERR_INVALID_ARG para um valor fora do conjunto aceite — nada é escrito; ESP_ERR_NOT_SUPPORTED como acima; ESP_ERR_INVALID_STATE se o módulo não aceitou o valor.

As chamadas de configuração escalares (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, rbamp_save_user_config, rbamp_save_gains, rbamp_prepare_address_change / rbamp_commit_address_change, rbamp_reset) funcionam nas duas linhas; cada uma tem uma nota "linha STD" na sua secção. Duas diferenças dignas de nota: rbamp_factory_reset() devolve ESP_ERR_NOT_SUPPORTED (não existe tal comando nesta linha), e rbamp_save_gains() persiste o bloco de calibração.

rbamp_commit_address_change() na linha STD é síncrono: a gravação da configuração aguarda o módulo e lê o veredicto (um endereço fora do intervalo → ESP_ERR_INVALID_ARG; o limite de taxa de escrita em flash do módulo → ESP_ERR_NOT_FINISHED — prepare de novo e tente após cerca de 5 s; nada muda em nenhum dos casos), depois reinicia o módulo e comuta o handle apenas depois de um módulo responder no novo endereço (em cerca de 3 s). Se nada responder aí, ESP_ERR_NOT_FOUND e o handle mantém o endereço antigo. rbamp_read_active_address() lê o endereço persistido.

Contadores de energia de vida

Para um módulo que mantém contadores de energia persistidos no dispositivo (RBAMP_STD_CAP_ONDEVICE_ENERGY).

C
typedef struct {
    int64_t  act_import_wh, act_export_wh, act_net_wh;   /* Wh; net = import − export */
    int64_t  rea_import_varh, rea_export_varh;           /* varh */
    uint32_t generation;       /* changes when the counters were reset or adopted */
    uint32_t uptime_s;         /* module uptime */
    int64_t  act_import_mwh, act_export_mwh, act_net_mwh;/* mWh (map 0x36+) */
    uint8_t  channels;         /* valid entries in the per-channel arrays (map 0x36+) */
    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, fine_reactive;
    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];
} rbamp_std_energy_t;

Os contadores são em unidades inteiras, monótonos e persistidos após perda de alimentação. A importação e a exportação são grandezas separadas. A energia de um período é a diferença entre duas leituras.

  • generation muda quando os contadores foram repostos ou adotados no módulo — nunca faça uma diferença que atravesse essa mudança.

  • uptime_s a diminuir significa que o módulo reiniciou. Os contadores são persistidos, por isso a diferença continua válida, mas o relógio e as definições de RAM do módulo perderam-se.

  • Após um corte de energia, um contador pode retomar ligeiramente abaixo da sua última leitura (uma fração de segundo de energia); rbamp_std_energy_delta() limita essa diferença a 0 e mantém o intervalo.

  • Os campos *_uwh / *_uvarh são sempre preenchidos, por isso pode usá-los em todos os módulos: um módulo que publica contadores de resolução µ (versão de imagem do módulo 0x0001007A e posteriores; reativa a partir de 0x0001007B) fornece-os a partir do mesmo instantâneo e fine / fine_reactive são true; nos módulos mais antigos são os contadores grosseiros escalados e fine é false.

  • channels > 0 (mapa 0x36+): o canal c é o canal de corrente c; num módulo trifásico, a fase c.

Persistir a estrutura.

rbamp_std_energy_t ganha campos entre versões do componente. Se o guardar (NVS, ficheiro), guarde os campos individuais de que precisa num formato fixo seu — não a estrutura como blob bruto.

Função Descrição
rbamp_std_read_energy(dev, &e) Leia os contadores. Cada bloco descodificado é uma transação (o módulo serve-o a partir de um instantâneo coerente). ESP_ERR_NOT_SUPPORTED a não ser que o módulo reporte a capacidade de energia no próprio dispositivo; ESP_ERR_INVALID_RESPONSE se o bloco for lido como não programado.
rbamp_std_energy_delta(&prev, &now, &delta, &restarted) Energia entre duas leituras com as regras de continuidade aplicadas. delta = agora − anterior por contador (magnitudes de importação / exportação, líquida, reativa; generation e uptime_s são copiados de now); restarted é verdadeiro se uptime_s desceu. Qualquer uma das saídas pode ser NULL. Um contador que desceu é limitado a uma diferença de 0, por canal também e em todas as resoluções; cada campo líquido é a diferença de importação menos a diferença de exportação. As diferenças por canal são produzidas quando ambas as leituras têm a mesma contagem de canais; caso contrário delta->channels é 0. ESP_ERR_INVALID_STATE se a geração for diferente — não contabilize esse intervalo; recomece a partir de now.

Bancos de instantâneos

O módulo mantém 8 bancos independentes (apenas nos módulos com a capacidade multi-instantâneo, period_source == RBAMP_STD_PERIOD_LATCH). Um banco acumula enquanto o seu bit estiver ativo na máscara de armação; rbamp_std_latch() tira o instantâneo e reinicia-o no próximo limite de janela de medição do módulo. Um período é, portanto, o intervalo entre dois instantâneos do mesmo banco, medido pelo relógio do master (o módulo não tem relógio). O banco 0 é também o que usam rbamp_read_period_snapshot() e rbamp_energy_wh(). As três chamadas de banco devolvem ESP_ERR_NOT_SUPPORTED sem tráfego de barramento em qualquer outro módulo — use aí rbamp_std_read_energy() / rbamp_std_energy_delta().

Uso típico: arme os bancos uma vez e, em cada banco, no seu próprio horário, rbamp_std_latch(bank) → aguarde ≥ 300 ms (um limite superior seguro de uma janela de medição em todas as imagens) → rbamp_std_read_latch() → rbamp_std_latch_wh() com o dt medido pelo mestre desde o instantâneo anterior.

C
typedef struct {
    float    p_avg, q_avg, s_avg;       /* average P / Q / S over the period */
    float    max_p, max_i, max_u, min_u;/* peaks in the period */
    int64_t  e_import_mws, e_export_mws;/* energy, mW·samples */
    uint32_t nsamp;                     /* sensor samples in the period */
    uint32_t win_count;                 /* measurement windows in the period (0 = not armed / nothing elapsed) */
    uint8_t  channels;                  /* valid entries in the per-channel arrays */
    uint8_t  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];
} rbamp_std_latch_t;
Função Descrição
rbamp_std_arm_banks(dev, mask) Defina a máscara de acumulação: bit b = o banco b acumula (bancos recém-armados começam limpos; bancos desarmados ficam congelados com o último instantâneo). O bit 0 tem de permanecer ativo se usar rbamp_read_period_snapshot(). A máscara está na RAM do módulo: qualquer reinício do módulo a limpa, e tirar um instantâneo de um banco não armado devolve um instantâneo vazio. A biblioteca rearma o banco 0 por si (em rbamp_begin(), após as suas próprias reposições e quando um instantâneo de período volta vazio). Para os seus próprios bancos, rbamp_std_read_latch() deteta a perda de armação, rearma e faz um instantâneo de primeira amostra.
rbamp_std_latch(dev, bank) Pede um instantâneo + reposição do bank no próximo limite de janela. Não espera — leia-o ≥ 300 ms depois.
rbamp_std_read_latch(dev, bank, &l) Lê o último instantâneo de bank (uma rajada: totais + energia por canal para cada canal preenchido). ESP_ERR_INVALID_RESPONSE se o módulo nunca tiver feito latch deste banco (os outros campos ficam a zero). ESP_ERR_INVALID_STATE se o instantâneo estiver vazio porque o banco foi desarmado por uma reposição do módulo — a biblioteca rearmou-o e fez-lhe latch de primeira amostra: descarte este período e reinicie a sua âncora dt. Leia um banco pelo menos uma janela de medição depois de fazer o latch; win_count == 0 significa que não estava armado ou que nenhuma janela decorreu.
rbamp_std_latch_wh(&l, dt_ms, ch, &wh_import, &wh_export) Converte os baldes de energia de um instantâneo em Wh sobre o período dt_ms medido pelo master (o relógio de parede do master entre o instantâneo anterior e este do banco). ch é um índice de canal ou RBAMP_STD_TOTAL (0xFF) para os totais do banco. Wh = E[mW·amostras] / 1000 / 3600 × (dt / nsamp): o número de amostras e o dt do master normalizam o resultado. Importação ≥ 0, exportação ≤ 0; qualquer uma das saídas pode ser NULL. ESP_ERR_INVALID_STATE se nsamp for 0.

Relógio, comandos e serviço

O módulo mantém o seu relógio na RAM: fica inválido após cada reinício do módulo. Sem relógio válido o módulo não regista histórico.

Função Descrição
rbamp_std_set_time(dev, unix_epoch) Define o relógio do módulo (segundos Unix) e aguarda a conclusão. Chame-a após rbamp_begin() e sempre que rbamp_std_health_t.time_valid for false (ou um período reportar module_restarted). A primeira definição após um reset fecha o intervalo de histórico em curso sem o transportar. ESP_ERR_INVALID_ARG se o módulo recusar a época (anterior a 2020); ESP_ERR_INVALID_STATE se o relógio não ficar válido; ESP_ERR_NOT_SUPPORTED abaixo do mapa 0x35.
rbamp_std_read_time(dev, &epoch, &valid) Lê o relógio do módulo e indica se é válido.
rbamp_std_command(dev, opcode, settle_ms, timeout_ms) Escreve um opcode de comando e aguarda a sua conclusão: espera primeiro que o módulo fique inativo (um comando escrito enquanto está ocupado é descartado), dorme settle_ms, aguarda que o BUSY seja limpo e depois lê o veredicto. timeout_ms 0 = 1 s. Veredictos: ESP_ERR_INVALID_ARG (parâmetro inválido), ESP_ERR_NOT_SUPPORTED (comando desconhecido), ESP_ERR_INVALID_CRC (verificação de valor), ESP_ERR_NOT_FINISHED (escrita na flash com limite de taxa — tente de novo após cerca de 5 s), ESP_ERR_NOT_ALLOWED (chave ou bloqueio de manutenção), ESP_ERR_TIMEOUT (ainda ocupado).
rbamp_std_wait_idle(dev, timeout_ms) Aguarde até o módulo terminar o comando que está a executar. Todo o comando emitido por esta biblioteca já espera; use isto apenas à volta de comandos que escreve você mesmo no registo de comandos — um comando escrito enquanto BUSY é descartado. Devolve de imediato em módulos sem registo de estado de comando.
rbamp_std_hist_flush(dev) Escreva agora os acumuladores de energia na flash (também implicado pelo reinício / commit do firmware).

Uma escrita de comando nunca é repetida após um erro de transporte (uma repetição poderia entregar o opcode duas vezes); as leituras e escritas em registos de dados mantêm a repetição.

Histórico e registo de eventos

O módulo mantém o último registo de 15 minutos em RAM (perde-se num reinício do módulo — é um indicador em tempo real, não um histórico) e um anel horário em flash que sobrevive aos reinícios e é o anel a usar para preencher lacunas; ambos são escritos apenas enquanto o relógio do módulo for válido. Um registo de eventos nunca apagado regista as alterações relevantes para a medição. Cada registo HORÁRIO traz os contadores de vida absolutos no fim do período: a energia total do período é a diferença entre dois registos consecutivos (reinícios e lacunas continuam visíveis). Recuperação após uma avaria do master: percorra back a partir de 0 (o mais recente) até chegar às marcas temporais que já tem.

C
typedef enum {
    RBAMP_STD_HIST_MIN15  = 0,  /* 15-minute records (RAM, lost at module reset) */
    RBAMP_STD_HIST_HOUR   = 1,  /* hourly records (flash ring) */
    RBAMP_STD_HIST_EVENTS = 2,  /* event log — read with rbamp_std_event_read */
} rbamp_std_hist_period_t;

typedef struct {
    uint16_t count;        /* records available (0 while the ring is being cleared) */
    uint16_t capacity;     /* ring depth */
    uint16_t record_size;  /* bytes per record */
    uint32_t oldest_ts, newest_ts;  /* unix */
} rbamp_std_hist_info_t;

typedef struct {
    uint32_t ts;           /* period start, unix */
    uint16_t flags;        /* RBAMP_STD_HF_* bits */
    uint16_t n;            /* samples (MIN15) or 15-minute children (HOUR: 4 = complete) */
    bool     from_ram;     /* record came from the RAM ring (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 counters ABSOLUTE at period end */
    uint8_t  phases;                     /* valid entries in the per-phase arrays */
    double   ph_import_wh[3], ph_export_wh[3];  /* per-phase energy OF THIS PERIOD, Wh */
} rbamp_std_hist_record_t;

typedef struct {
    uint32_t ts;           /* unix time (0 = clock was not set) */
    uint32_t uptime_s;     /* module uptime at the event */
    uint8_t  type;         /* RBAMP_STD_EV_* */
    uint8_t  flags;        /* RBAMP_STD_EVF_* (maintenance mode was active) */
    uint16_t boot;         /* boot counter (low 16 bits) */
    uint32_t a_before, a_after;        /* type-specific values before / after the change */
    uint64_t e_before_wh, e_after_wh;  /* grand import counter before / after, Wh */
} rbamp_std_event_t;
Função Descrição
rbamp_std_hist_info(dev, period, &info) Estado do anel de um período do histórico (também o seleciona no módulo).
rbamp_std_hist_read(dev, period, back, &rec) Obtém e descodifica o registo back (0 = o mais recente) de MIN15 ou HOUR. ESP_ERR_NOT_FOUND se não existir tal registo. Obtenha a energia de um período a partir de dois registos consecutivos apenas quando as respetivas marcas temporais diferirem exatamente de um período e nenhum deles tiver a flag RBAMP_STD_HF_LTA_JUMP.
rbamp_std_hist_read_raw(dev, period, back, rec, &flags) O mesmo registo sem descodificar: rec (um buffer de RBAMP_STD_REG_HIST_REC_SIZE; o comprimento significativo é record_size) recebe os bytes do registo do módulo, flags recebe os flags do registo do módulo.
rbamp_std_event_read(dev, back, &ev) Obtém e descodifica a entrada back do registo de eventos (0 = a mais recente). ESP_ERR_NOT_FOUND se não houver nenhuma. Os tipos de evento são as constantes geradas RBAMP_STD_EV_* (reposição / adoção do contador de vida útil, gravação de calibração, commit de firmware, limpeza do histórico, ...).

Autenticidade

Um módulo provisionado tem um certificado do dispositivo assinado pela chave do fabricante e responde a um desafio com uma assinatura digital feita pela chave do dispositivo nomeada nesse certificado. A biblioteca obtém ambos; verificá-los é trabalho da aplicação (com a biblioteca de assinatura da sua escolha).

C
typedef struct {
    uint8_t  raw[RBAMP_STD_REG_SEC_CERT_SIZE];  /* certificate bytes as read */
    uint8_t  state;          /* the module's own check: 0 none · 1 ok · 2 bad · 3 not checked yet (shortly after boot) */
    uint8_t  version, variant, hw_rev;
    uint8_t  uid[12];        /* chip UID the certificate was issued for (compare with rbamp_read_uid) */
    uint32_t batch, issued;  /* production batch; issue time, unix */
    uint8_t  device_pubkey[32];
    uint32_t mfr_key_id;
} rbamp_std_certificate_t;

typedef struct {
    uint8_t  signature[64];  /* signature over the attested message */
    uint8_t  data[24];       /* attested data exactly as signed */
    uint32_t fw_version, generation;   /* from data */
    int64_t  e_import_wh, e_export_wh; /* from data: life-time import / export, Wh */
} rbamp_std_attestation_t;
Função Descrição
rbamp_std_read_certificate(dev, &cert) Lê o certificado do dispositivo. ESP_ERR_NOT_FOUND se o módulo não tiver nenhum (não provisionado; state continua preenchido); ESP_ERR_NOT_SUPPORTED abaixo do mapa 0x35.
rbamp_std_attest(dev, challenge, &att) Desafie o módulo com 32 bytes aleatórios à sua escolha (guarde a sua cópia — o módulo sobrescreve a área do desafio com a assinatura) e obtenha a resposta assinada (cerca de 60 ms). Os dados atestados vinculam a versão do firmware e os contadores de vida útil à chave do dispositivo. ESP_ERR_NOT_FOUND se o módulo não tiver chave do dispositivo; ESP_ERR_INVALID_STATE se o módulo não tiver reportado a atestação como concluída.

Atualização de firmware (OTA)

Uma atualização em duas fases sobre I²C. Todas as funções aqui devolvem ESP_ERR_NOT_SUPPORTED a menos que o módulo reporte a capacidade OTA (mapa 0x33 ou posterior). Cada comando completa-se de forma síncrona dentro da biblioteca (aguarda o estado de comando do módulo, não um atraso fixo).

Sequência: rbamp_std_ota_begin → rbamp_std_ota_write_page × N (páginas de 256 bytes; as páginas em branco 0xFF podem ser saltadas) → rbamp_std_ota_commit (verifica e arma a troca, sem reinício) → rbamp_std_ota_activate (reinicia para a nova imagem quando estiver pronto). O módulo sai do barramento durante alguns segundos e depois corre um teste de cerca de 10 s antes de a imagem ser confirmada. Após cada página, a sessão tem de continuar aberta, caso contrário a chamada falha com ESP_ERR_INVALID_STATE (reinicie a partir de begin). Uma imagem defeituosa é revertida pelo próprio módulo; a calibração sobrevive.

Só são aceites imagens preparadas pelo fabricante. As imagens de distribuição são produzidas pelas ferramentas do fabricante do módulo (assinadas e, quando exigido, cifradas); o módulo recusa um cabeçalho gerado no anfitrião no commit. rbamp_std_ota_write_image() (imagem gerada no anfitrião, não assinada) devolve, portanto, ESP_ERR_NOT_SUPPORTED antes de tocar no módulo, e é mantida apenas por compatibilidade ABI.

Função Descrição
rbamp_std_ota_status(dev, &st) O estado OTA do módulo (RBAMP_STD_OTA_IDLE / READY / OK / ERR / DOWNGRADE).
rbamp_std_ota_begin(dev, timeout_ms) Apague o banco inativo e aguarde até o módulo reportar PRONTO. timeout_ms 0 = predefinido (5 s). ESP_ERR_TIMEOUT se PRONTO não for atingido.
rbamp_std_ota_write_page(dev, page_idx, page) Escreve uma página de 256 bytes no índice page_idx (deslocamento / 256 dentro do banco). ESP_ERR_INVALID_STATE se o módulo assinalar um erro de escrita.
rbamp_std_ota_commit(dev, timeout_ms) Verifica a imagem escrita e arma a troca de bancos. timeout_ms 0 = predefinição (3 s). ESP_OK armada · ESP_ERR_INVALID_CRC imagem defeituosa (CRC / cabeçalho) · ESP_ERR_INVALID_MAC falha de autenticação · ESP_ERR_INVALID_VERSION imagem mais antiga do que a em execução · ESP_ERR_TIMEOUT.
rbamp_std_ota_diag(dev, &reason) Motivo pelo qual o módulo rejeitou a última página ou commit: o byte de motivo do diagnóstico OTA (0 = nenhum). rbamp_std_ota_commit() já associa o motivo ao código de erro acima e regista o seu nome; chame isto quando precisar do próprio código.
rbamp_std_ota_activate(dev) Reinicie para a imagem armada, aguarde o regresso do módulo (cerca de 4 s), volte a detetá-lo e depois mantenha a janela de teste e confirme: o banco em execução mudou, a imagem em execução é a versão preparada, a troca já não está pendente. Bloqueia durante cerca de 10 s no total — não reinicie nem desligue o módulo nessa janela (o carregador de arranque reverte uma imagem não confirmada). O handle continua válido e rbamp_std_info() reflete o novo firmware. ESP_ERR_INVALID_STATE se nada tiver sido armado, se o módulo regressou na imagem anterior (reversão), ou se a troca continuar pendente após o teste.
rbamp_std_ota_staged_version(dev, &v) Versão da imagem armada (com commit, ainda não ativada); 0 quando nada está armado (mapa 0x35+).
rbamp_std_ota_abort(dev) Fecha uma sessão de atualização e desarma uma imagem armada; o módulo continua a correr o que estava a correr (mapa 0x35+).
rbamp_std_ota_board_ok(dev, image_board_word) Verificação prévia antes de transferir uma imagem preparada: a palavra de placa da imagem (fornecida junto ao ficheiro de imagem pelas ferramentas do fabricante) tem de ser igual ao identificador de placa do módulo. ESP_OK se coincidir; ESP_ERR_INVALID_ARG se não (registado); ESP_ERR_NOT_SUPPORTED abaixo do mapa 0x36.
rbamp_std_ota_write_prepared(dev, image, size, cb, ctx) Envie em fluxo uma imagem de banco preparada tal como está: início, páginas por ordem crescente (a página 0 é sempre enviada; as outras páginas todas-0xFF são saltadas), commit. A biblioteca não altera nada. Não ativa. size tem de ser igual ao tamanho do banco que o módulo reporta (rbamp_std_info_t.ota_bank_size) — caso contrário ESP_ERR_INVALID_SIZE e nada é escrito. cb(done, total, ctx) é um callback opcional de progresso (rbamp_std_ota_progress_cb_t).
rbamp_std_ota_write_prepared_pair(dev, bank_a, size_a, bank_b, size_b, cb, ctx) Tal como acima, dadas as imagens dos dois bancos: a biblioteca pergunta ao módulo qual banco está em execução e transmite o outro. ESP_ERR_NOT_SUPPORTED nos módulos que não reportam o banco em execução (mapa abaixo de 0x35) — use rbamp_std_ota_write_prepared() e escolha você mesmo pelo active_bank.
rbamp_std_crc32(data, len) CRC-32 (compatível com zlib) — a soma de verificação que o módulo valida no commit.
rbamp_std_ota_make_header(out, version, len, crc32) Constrói o cabeçalho de imagem little-endian. Disponível apenas quando o cabeçalho de registos gerado define as constantes do cabeçalho; mantido por compatibilidade ABI.

Diagnóstico

rbamp_err_to_str

C
const char *rbamp_err_to_str(esp_err_t err);

Devolve um ponteiro para uma string estática com uma descrição legível do código de erro. Nunca devolve NULL. Usa o esp_err_to_name() padrão para os códigos do sistema e estende as descrições para a semântica específica do rbamp (por exemplo, o que ESP_ERR_INVALID_STATE significa no contexto de set_ct_model_ch sem set_sensor_class).

Utilização típica:

C
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "snapshot failed: %s", rbamp_err_to_str(err));
}

rbamp_retry_exhaustion_count / rbamp_sanity_reject_count / rbamp_reset_counters

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count   (rbamp_handle_t dev);
void     rbamp_reset_counters        (rbamp_handle_t dev);

Getters públicos de dois contadores de diagnóstico (ambos devolvem 0 num handle NULL):

  • rbamp_retry_exhaustion_count(dev) — um contador monótono de eventos de "orçamento de retentativas esgotado". Cada incremento = uma transação de um byte que, após CONFIG_RBAMP_NACK_RETRY_ATTEMPTS tentativas, nunca recebeu ACK do dispositivo.

  • rbamp_sanity_reject_count(dev) — um contador monotónico de rejeições pelo filtro de sanidade em leituras de float (NaN, Inf, ou um valor absoluto acima do limite por grandeza — RBAMP_SANITY_LIMIT_V / _I / _P / _PF). Cada incremento = um float que veio do barramento, foi considerado não parecido com um valor físico e foi descartado; a leitura devolve ESP_ERR_INVALID_RESPONSE.

rbamp_reset_counters(dev) põe a zero ambos os contadores neste handle (sem efeito para NULL). Destina-se a cenários de teste que precisem de uma base limpa. Para monitorização em produção, prefira o padrão canónico "taxa sobre um intervalo" — instantâneo + diferença, robusto contra janelas de reinício perdidas:

C
uint32_t prev = rbamp_retry_exhaustion_count(dev);
/* ...60 s of normal operation... */
uint32_t delta = rbamp_retry_exhaustion_count(dev) - prev;
if (delta > THRESHOLD) { /* alert */ }

Estes nomes coincidem com a biblioteca Arduino em todas as plataformas (dev.retryExhaustionCount() / dev.sanityRejectCount() — a mesma semântica, em snake_case). Para cargas práticas e limiares de alarme, veja 10 · Resolução de problemas, secção "Monitorizar contadores".

Registo através de esp_log

O componente regista sob a etiqueta "rbamp". O nível de registo é compilado através do Kconfig — o esp_log_level_set("rbamp", ...) em tempo de execução funciona, mas fica limitado acima pelo nível de compilação.

C
esp_log_level_set("rbamp", ESP_LOG_DEBUG);   /* for debugging */

Códigos de erro

As funções rbamp_* devolvem valores esp_err_t padrão. Os códigos específicos e a sua semântica no contexto do rbamp:

Código Quando Onde procurar
ESP_OK (0) Sucesso —
ESP_FAIL (-1) A transação I²C falhou após as retentativas cablagem, alimentação, velocidade do barramento — secção "O módulo não responde por I²C" em 10 · Resolução de problemas
ESP_ERR_INVALID_ARG (0x102) Argumento inválido: dev == NULL, channel ou phase fora do intervalo, um cls não reconhecido, um valor que o módulo rejeita (modelo de TC desconhecido, corrente de arranque fora do conjunto aceite, relógio anterior a 2020) verifique os argumentos da chamada
ESP_ERR_TIMEOUT (0x107) rbamp_wait_ready / rbamp_wait_data_ready expirou; a janela de rbamp_commit_address_change (5 s) expirou; um comando STD ou o estado OTA não foi concluído verifique a capacidade de resposta através de rbamp_probe()
ESP_ERR_INVALID_STATE (0x103) Uma pré-condição ou sequência de chamadas está errada: set_ct_model* antes de set_sensor_class; o módulo está na classe 2 / 3 (calibrado com o seu sensor — use rbamp_set_ct_model_ch_force() para assistência técnica); o módulo rejeitou o par (class, model); commit de endereço não armado; banco de instantâneos STD rearmado após um reinício do módulo (descarte este período); contador de geração STD alterado (rbamp_std_energy_delta); sessão OTA não aberta secção "rbamp_set_* devolve ESP_ERR_INVALID_STATE" em 10 · Resolução de problemas
ESP_ERR_NOT_SUPPORTED (0x106) A função ou funcionalidade não existe nesta linha / firmware / módulo: qualquer chamada rbamp_std_* num handle BASIC, potência reativa / aparente em BASIC, rbamp_read_digest em STD ou sem a capacidade de digest, chamadas de período num módulo STD sem bancos de instantâneos nem contadores, rbamp_factory_reset em STD, uma versão do mapa de registos demasiado antiga, OTA sem a capacidade verifique rbamp_line(dev), rbamp_std_info() e rbamp_variant(dev)
ESP_ERR_NOT_FOUND Nada presente: rbamp_std_probe — nada responde no endereço; sem histórico / registo de eventos; sem certificado nem chave do dispositivo; commit de endereço — nada responde no novo endereço (o handle mantém o antigo) verifique a cablagem / o endereço; recue back apenas até rbamp_std_hist_info().count
ESP_ERR_INVALID_RESPONSE (0x108) Instantâneo de período desatualizado (flag de pronto = 0) ou período ignorado (contadores STD reancorados, banco rearmado); REG_VERSION = 0/0xFF em rbamp_begin; um float reprovou o filtro de sanidade; frequência de rede STD 0 (sem rede); rbamp_std_probe — responde algo que não é um módulo STD secção "Instantâneos de período estão sempre desatualizados" / "Não é possível sair de rbamp_begin" em 10 · Resolução de problemas
ESP_ERR_NO_MEM (0x101) Não foi possível alocar memória para o handle; mais de 4 linhas DRDY / 8 handles por linha verifique o orçamento de heap
ESP_ERR_NOT_FINISHED STD: a escrita em flash do módulo tem limite de frequência tente novamente após cerca de 5 s
ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_MAC, ESP_ERR_INVALID_VERSION, ESP_ERR_INVALID_SIZE, ESP_ERR_NOT_ALLOWED Veredictos de comando / OTA STD: uma verificação de valor ou imagem falhou, a autenticação falhou, a imagem é mais antiga do que a que está em execução, a imagem não cabe no banco, o módulo recusou a operação (ver rbamp_std_command, rbamp_std_ota_commit) rbamp_std_ota_diag() para o motivo

Todos os códigos devolvidos podem ser impressos em formato legível através de rbamp_err_to_str().

Configuração em tempo de compilação (Kconfig)

Os seguintes símbolos CONFIG_RBAMP_* estão disponíveis em idf.py menuconfig → Configuração do componente [Component config] → rbAmp client:

Símbolo Tipo Intervalo / escolha Predefinido Finalidade
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ int 50000–1000000 Hz 50000 Frequência SCL. 50 kHz é a determinação para o firmware atual no ESP32.
CONFIG_RBAMP_I2C_TIMEOUT_MS int 10–1000 ms 100 Timeout de i2c_master_transmit/receive. Tem de ser suficientemente longo para absorver a latência de pré-leitura do módulo.
CONFIG_RBAMP_I2C_SCL_WAIT_US int 2000–60000 µs 10000 Tolerância ao clock-stretch de SCL: durante quanto tempo o periférico I²C aceita que o módulo mantenha SCL em baixo antes de desistir da transação. O padrão do driver é 2 ms; um módulo estica SCL durante mais tempo enquanto apaga um setor de flash durante uma atualização de firmware, e cada um desses esticamentos acabaria numa linha de registo "I2C hardware timeout" e numa retentativa. 10 ms cobre o apagamento do setor. O ESP32 original não consegue esperar mais do que cerca de 13 ms (contador de hardware de 20 bits); o componente limita o valor a esse máximo nesse alvo.
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS int 1–10 3 Tentativas por leitura de um byte.
CONFIG_RBAMP_NACK_RETRY_GAP_MS int 1–100 ms 5 Intervalo entre tentativas de retentativa.
CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION bool n/y n Quando todas as repetições de NACK de uma transação falham, chame i2c_master_bus_reset() uma vez antes da última tentativa. O driver do IDF já reinicia a sua máquina de estados após cada transação falhada, e a reposição explícita não toma o bloqueio do barramento: com várias tarefas a partilhar o barramento pode interromper a transação de outra tarefa (no ESP32 emite um STOP nos pinos, que o manipulador de interrupções do driver pode confundir com o fim de uma leitura). Deixe desligado, a menos que o master tenha uma só tarefa e o barramento se confirme bloqueado após erros do driver.
CONFIG_RBAMP_SCT_RATING_CORRECTION bool n/y y Correção das leituras SCT-013 no firmware BASIC até 1.4.19, que mantém a calibração de 30 A depois de o utilizador mudar o canal para outro modelo. A biblioteca escala a corrente, a potência, a potência periódica, a energia e o digest para o modelo selecionado (rbamp_sct_correction() reporta o resultado por canal). Um módulo que se corrige a si próprio (firmware 1.4.20 e posteriores) não é afetado. Desligue para ler os valores brutos do módulo. Veja Correção da classificação SCT-013.
CONFIG_RBAMP_DRDY_POLL_MS int 5–50 ms 20 Quando um handle não tem GPIO DRDY, rbamp_wait_data_ready() sonda o contador de publicação do módulo (STD) ou a sequência de commit (BASIC) a este intervalo. O módulo publica a cada 100 ms (imagens antigas: 200 ms).
CONFIG_RBAMP_DISABLE_ENERGY bool n/y n Remove o acumulador de Wh da compilação por completo (armazenamento e API).
CONFIG_RBAMP_LOG_LEVEL_* escolha NONE / ERROR / WARN / INFO / DEBUG INFO LOG_LOCAL_LEVEL em tempo de compilação para a etiqueta rbamp. Controla se as strings de registo chegam sequer a ser compiladas no binário; é independente de CONFIG_LOG_DEFAULT_LEVEL.

Um exemplo de sdkconfig.defaults para um cenário típico de produção:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=100
CONFIG_RBAMP_LOG_LEVEL_INFO=y
# leave CONFIG_RBAMP_DISABLE_ENERGY disabled (default n)

Para um teste de bancada sob carga pesada:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

Constantes de tempo de estabilização

O componente usa internamente os seguintes tempos de estabilização ao executar comandos (para um utilizador que trabalhe sobre a API em bruto através de i2c_master_transmit_receive e queira respeitar os mesmos tempos):

A biblioteca exporta um pequeno conjunto de constantes de tempo de estabilização (ms) para utilizadores da API em bruto que enviam comandos diretamente para o dispositivo e têm de esperar que o dispositivo termine o processamento antes de ler os registos afetados. As funções de encapsulamento do componente (rbamp_save_gains, rbamp_factory_reset, rbamp_set_ct_model_ch, etc.) aplicam internamente o atraso correto — estas constantes só são necessárias se contornar as funções de encapsulamento.

Macro Finalidade ms
RBAMP_SETTLE_MS_LATCH_PERIOD Após CMD_LATCH_PERIOD 50
RBAMP_SETTLE_MS_RESET Após CMD_RESET 100
RBAMP_SETTLE_MS_SAVE_GAINS Após CMD_SAVE_GAINS (apagamento + escrita da flash) 700
RBAMP_SETTLE_MS_FACTORY_RESET Após CMD_FACTORY_RESET 1500
RBAMP_SETTLE_MS_SET_CT_MODEL_CH0 Após CMD_SET_CT_MODEL_CH0 5
RBAMP_SETTLE_MS_SET_CT_MODEL_CH1 Após CMD_SET_CT_MODEL_CH1 5
RBAMP_SETTLE_MS_SET_CT_MODEL_CH2 Após CMD_SET_CT_MODEL_CH2 5

A fonte de verdade é o bloco @defgroup rbamp_settle_ms em include/rbamp.h. Os números são os mínimos de especificação do protocolo rbAmp; não se pode ir abaixo, pode-se ir acima.

Detalhes do protocolo de transmissão

Mapa a cores do espaço de registos do módulo.
Para portar para plataformas onde o componente não é usado, ou para depurar com um analisador lógico:

Leituras de registos — auto-incremento

Uma leitura em rajada + N bytes devolve N bytes consecutivos a partir de addr. Exemplo: uma única transação i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) lê 16 bytes a partir de 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK no UI1).

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

As leituras fazem incremento automático enquanto as escritas são feitas byte a byte.
⚠ As escritas NÃO são com incremento automático.Uma ESCRITA em rajada + N byteschegaapenas o primeiro byte— os bytes 1..N são descartados.

Um registo de vários bytes escreve-se byte a byte — uma transação I²C separada de um byte por cada endereço:

C
/* WRONG — data loss */
uint8_t label[8] = "MyMeter1";
uint8_t buf[9] = { 0x68, 'M', 'y', 'M', 'e', 't', 'e', 'r', '1' };
i2c_master_transmit(slave, buf, 9, 100);   /* only 'M' lands */

/* CORRECT — byte-at-a-time loop */
for (int i = 0; i < 8; i++) {
    uint8_t tx[2] = { 0x68 + i, label[i] };
    i2c_master_transmit(slave, tx, 2, 100);
}

Isto afeta os registos graváveis de vários bytes: LABEL (0x68-0x6F), U_GAIN / I_GAIN (f32, protegidos de fábrica), NF (u16), THRESH (u16). As leituras admitem rajada (o auto-incremento funciona na LEITURA).

Leitura de registos não mapeados

Qualquer leitura de um endereço não mapeado devolve 0x00. O firmware nunca responde com NACK nas leituras de registos. A deteção de um dispositivo em falta tem de ser feita pelo ACK do frame de endereço I²C, não por sondagem de registos.

Deteção da variante

O byte de SKU autoritativo é o registo 0x55 (em cache como rbamp_variant()):

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)
0x08 UI7 (7× I + U)

rbamp_topology() é auxiliar; devolve apenas o número de canais (1/2/3/5/7) e não distingue a presença de U.

Segurança

⚠ REG_SENSOR_CLASS (0x25) NÃO é um discriminador de variante (é fornecido pela configuração do utilizador). O invariante de variante = HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) — ambos só de leitura.

CAPABILITY (0x57/0x58, u16 LE) — mapa de deteção de funcionalidades

Um mapa das capacidades do dispositivo (por exemplo: front-end de tensão presente, instantâneo General-Call suportado, bloco digest, flags de evento, mudança de endereço em duas fases). A forma canónica de detetar funcionalidades (em vez de comparar números de versão). Verifique flags de capacidade individuais através das funções auxiliares; o conjunto de flags cresce com o firmware do módulo.

has_voltage (sem ler HW_VARIANT):

C
/* Option 1 — the cached helper (no bus traffic after rbamp_begin). */
bool has_voltage = rbamp_has_voltage(dev);

/* Option 2 — read the full 16-bit CAPABILITY (LE). */
uint16_t cap;
rbamp_read_capability(dev, ∩);
bool has_voltage_2 = (cap & RBAMP_CAP_ZC_PHASE_OFFSET) != 0;  /* voltage front-end flag */

As duas opções são equivalentes.

Coerência HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 (UI) → flag de front-end de tensão ativa; HW_VARIANT 4..6 (I) → flag inativa. Uma incoerência = uma anomalia de hardware.

Atomicidade / congelamento de leitura (B1)

O instantâneo atómico do período que fecha um período e abre o seguinte, sem intervalo nem sobreposição.

  • Bloco RMS float V03 (0x86+: U_RMS, U_PEAK, I_RMS, I_PEAK, P, PF, freq) — congelamento de leitura presente, a leitura em rajada é atómica.
  • Bloco digest (0x70-0x85) — congelamento de leitura presente.
  • GC_TICK (0x59) / espelho de endereço (0x30) / espelhos de modelo de CT (0x51-0x53) — sem congelamento de leitura; para uma leitura fiável, use o padrão ler-duas-vezes-e-concordar (leia duas vezes, considere o valor válido apenas se coincidirem).

Semântica da pinça NF

I_RMS = 0x00000000 significa "sinal abaixo do patamar de ruído" (o FW calcula rms_corr² = max(0, raw² − nf²)), e não "sem dados" / "erro". É uma medição válida para cenários sem carga.

Registos só de tensão em variantes só de corrente

U_RMS, U_PEAK em I1/I2/I3 leem 0. São válidos apenas quando o flag do front-end de tensão de CAPABILITY está ativo. REG_AC_FREQ provém de passagem por zero e está disponível em todas as variantes (incluindo I*).

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

Opt-in por módulo através do bit0 do registo REG_FLEET_CONFIG (0x27) — GC_ENABLE. Por omissão DESLIGADO. Ativado via CMD_SAVE_USER_CONFIG + CMD_RESET (suave ou total). Após um reinício o módulo escuta a trama broadcast no endereço I²C General-Call 0x00:

Text
addr=0x00 | A5 27   
  • A5 — mágico.
  • 27 — o opcode CMD_LATCH_PERIOD.
  • — 0x00 = chamada geral (all-call), caso contrário tem de coincidir com REG_GROUP_ID (0x28).
  • — contador de período de 16 bits (sincronização do mestre).

A trama apenas dispara o instantâneo de período; nunca transporta opcodes destrutivos.

Deteção do modo de falha (dois níveis, confirmado em HW C.10):

  1. NACK do endereço GC (imediato, ao nível do barramento): se o GC estiver desativado em toda a frota — i2c_master_transmit para 0x00 devolve ESP_FAIL / ESP_ERR_INVALID_STATE. Este é um erro duro, não uma descarga silenciosa. A biblioteca trata o NACK como "GC não ativado" (exige as pré-condições de ativar + reinício).
  2. Testemunho por módulo (após a estabilização): se não houve NACK — o master lê REG_V03_PERIOD_VALID (0x07) em cada escravo esperado: 1 = instantâneo bem-sucedido, 0 = GC desativado neste módulo específico, ou o período está vazio.

Apêndice — Por baixo do capô

Movido do capítulo de Visão geral: comparação ao nível de registos, arquitetura e diagramas de interação.

Sem o componente (acesso direto via i2c_master_transmit_receive)

C
// Read U_RMS — a single 4-byte burst-read (the firmware supports
// address auto-increment on read).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
    .device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);

uint8_t reg = 0x86, buf[4] = { 0 };
if (i2c_master_transmit_receive(slave, ®, 1, buf, 4,
                                /*xfer_timeout_ms=*/100) != ESP_OK) {
    return;   // handle the error
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));

Com o componente

C
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));

Ler um período — sem o componente

C
// Snapshot + 50 ms settle + ready-flag check + burst-read avg_p
uint8_t latch_cmd[2] = { 0x01, 0x27 };   // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));   // settle

uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
    // snapshot is stale — t_latch_us STILL must be recorded,
    // otherwise the next snapshot will count Wh over two periods
    return;
}

// burst-read 4 bytes of avg_p (auto-increment), then assemble the float
// and integrate Wh:
//   double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
//   E_Wh += avg_p * dt_s / 3600.0;

Ler um período — com o componente

C
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
    // snap.avg_p[0] is populated,
    // rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
    // master_dt_ms = master wall-clock dt between snapshots (canonical for energy).
    // snap.latch_ms (0xEC) — diagnostic module timer, NOT for energy.
}

Internamente, o componente garante:

  • Uma estabilização de 50 ms após CMD_LATCH_PERIOD (configurável através do parâmetro settle_ms), leitura correta do instantâneo (instantâneo atómico no lado do módulo).

  • Verificação do flag REG_V03_PERIOD_VALID antes de ler (o campo snap.valid).

  • Registo do tempo pelo relógio do mestre mesmo num instantâneo desatualizado (protege contra a dupla contagem de Wh no período seguinte).

  • Acumulação de Wh por canal em precisão dupla (o tipo double dentro do handle).

  • Carregamento automático dos coeficientes de calibração quando o sensor de corrente é selecionado via rbamp_set_sensor_class() + rbamp_set_ct_model() — o utilizador não precisa de conhecer os registos internos de calibração.

Quando usar o componente, quando usar o acesso direto ao barramento

Tarefa Componente Acesso direto via i2c_master_*
Leitura de U / I / P / PF / frequência ✅ apenas para depuração com um analisador lógico
Contabilização de energia por período ✅ apenas se o Wh for guardado fora do componente (por exemplo, numa base de dados do lado do master)
Vários módulos num mesmo barramento ✅ (instantâneo sequencial + estabilização partilhada, ver 06_examples.md) —
Contabilização bidirecional no BASIC ✅ (através de leituras RT — ver 06_examples.md) a alternativa é o seu próprio ciclo de leitura RT + integração manual
Adaptação a outra plataforma n/a ✅ — ver 09 · Referência da API para os detalhes do protocolo de fio
Limite rígido de RAM raramente importa (~85 bytes por handle) ✅ se até esses ~85 bytes forem críticos

Para todas as tarefas típicas das primeiras linhas, o componente é a escolha certa.

Arquitetura

Camadas desde a tarefa da aplicação, passando pelo componente rbamp e pelo driver I²C, até ao módulo rbAmp.

Diagramas de interação

O fluxo de rbamp_begin()

Sequência de transações de barramento executadas por rbamp_begin().

O primeiro instantâneo é um primer (o módulo devolve o que tiver acumulado desde o arranque, o que não é adequado para a contabilização tarifária). O próprio componente regista que este instantâneo tem de ser descartado — o código do utilizador nunca o vê.

O fluxo rbamp_read_period_snapshot(dev, &snap, 50, false)

Sequência de uma leitura de instantâneo de período e da integração de energia no master.

O instantâneo atómico no lado do módulo garante que cada medição dentro de um período cai exatamente num instantâneo — sem duplicação nem perdas na fronteira do período.

Correspondência com a API de registos direta

Uma tabela para quem migra do seu próprio código de acesso direto:

API direta (i2c_master_transmit_receive) Equivalente através do componente
Leitura manual de 4 bytes + memcpy rbamp_read_voltage(dev, 0, &v) / rbamp_read_power(dev, ch, &p)
tx([0x01, 0x27]); vTaskDelay(50) rbamp_latch_period(dev); vTaskDelay(pdMS_TO_TICKS(50)) (ou rbamp_read_period_snapshot() diretamente)
Verificar read_u8(0x07) & 1 o campo snap.valid após rbamp_read_period_snapshot()
Fórmula manual E_Wh += avg_p * dt_s / 3600 rbamp_energy_wh(dev, 0) — atualizado automaticamente
Configuração manual do sensor de corrente através da API de registos direta rbamp_set_sensor_class(dev, cls) + rbamp_set_ct_model(dev, code) — as predefinições de fábrica são carregadas automaticamente

Código-fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/09_api_reference.md (v1.7.3)