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 parastruct rbamp_obj_t *; o utilizador não acede aos seus internos. Criado comrbamp_new(), libertado comrbamp_del(). -
Valores devolvidos por
esp_err_t—ESP_OKem caso de sucesso, um dos códigosESP_ERR_*em caso de falha. UseESP_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_tcomo um valor. -
Textos de erro legíveis:
rbamp_err_to_str(err)devolve um apontador para uma string estática. Nunca devolveNULL. -
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 devolvemESP_ERR_NOT_SUPPORTEDna outra (verrbamp_line_te 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
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
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
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
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.
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.
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.
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. |
⚠ 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():
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
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
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
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
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
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
02 · Inicialização e arranque (initialization) · BASIC ou STD? (initialization) · Ciclo de consulta contínuo (recomendado) (period-metering)
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:
-
Lê
REG_VERSION(0x03). Se o dispositivo não fez ACK —ESP_FAIL. Se devolveu0x00/0xFF—ESP_ERR_INVALID_RESPONSE. -
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. -
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). -
Avalie a correção do calibre SCT-013 (ver Correção do calibre SCT-013).
-
Escreva
CMD_LATCH_PERIODcomo preparação + espere 50 ms. O primeiro instantâneo após ligar é descartado. (rbamp_begin_resume()salta este passo.) -
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
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
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
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
02 · Inicialização e arranque (initialization) · 3. DATA_VALID (0xCE) nunca passa a 1 (troubleshooting) · 4 · Mapa de registos (produção v1.3) (api-reference)
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
BASIC ou STD? (initialization) · Corrente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloco em tempo real V03 (0x86..0xBD) (api-reference)
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
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
Referência de registos RT (realtime-polling) · Contabilidade bidirecional (period-metering)
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
Referência de registos RT (realtime-polling) · Consulta — módulo único (realtime-polling) · 4.10 Bloco em tempo real V03 (0x86..0xBD) (api-reference)
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
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)
Corrente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Janela de acesso aos canais (0x32 + 0x3C..0x3F) (api-reference)
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.
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_channellê os quatro campos RT de um canal para umrbamp_channel_reading_t. Um campo que ultrapasse o seu limite de sanidade fica comNaNe com o seu bitRBAMP_FIELD_*emimplausible. -
rbamp_read_all_channelspreencheout[]com todos os canais preenchidos;né a capacidade deout(dimensione-o comRBAMP_MAX_CHANNELS); a chamada preenchemin(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.
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
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)
01 · Ligação de hardware (hardware-connection) · 03 · Sondagem em tempo real (realtime-polling) · Sondagem — módulo único (realtime-polling)
DRDYsaí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.
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).
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
4.9 Janela de digest (0x70..0x85) (api-reference) · 8.7 Ida e volta do DIGEST — configurar + ler (api-reference)
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.
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 deRBAMP_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óximarbamp_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. DevolveESP_ERR_INVALID_ARGpara 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_SUPPORTEDna 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 derbamp_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 (userbamp_read_channel()). A potência real vem em watts inteiros — uma carga abaixo de 1 W lê 0. DevolveESP_OK;ESP_ERR_NOT_SUPPORTEDna 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
04 · Medição por período e contabilidade tarifária (period-metering)
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
04 · Medição por período e contabilidade tarifária (period-metering) · Calibração e precisão (troubleshooting) · 7.5 Preservação do período em instantâneo falhado (api-reference)
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
Registos de instantâneo do período (period-metering) · 4.11 Bloco de período V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + período ch0 (0xD0..0xE3, build de produção) (api-reference)
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
Registos de instantâneo do período (period-metering) · 4.12 V03 Q + período ch0 (0xD0..0xE3, build de produção) (api-reference)
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
13. Deriva do relógio de vários módulos em testes longos (troubleshooting) · 4.13 dt de diagnóstico do lado do chip (0xEC) (api-reference)
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.
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
Ciclo de consulta contínuo (recomendado) (period-metering) · Multimódulo — instantâneo simultâneo (period-metering) · Calibração e precisão (troubleshooting)
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:
-
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). -
Caso contrário — escreva
CMD_LATCH_PERIOD. - Capture
esp_timer_get_time()para calcularmaster_dt_ms. vTaskDelay(pdMS_TO_TICKS(settle_ms))— 50 ms por omissão.-
Verifique a flag de instantâneo pronto. Se for 0 — defina
ESP_ERR_INVALID_RESPONSEe registe o carimbo temporal (para que o instantâneo seguinte não contedtem duplicado). -
Leia
avg_p[0..channels-1]+max_p+latch_ms. - 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.
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
Detetar um reinício do módulo (period-metering) · 4.6 Estado de saúde / diagnóstico (0x46..0x4F) (api-reference)
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
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)
Algoritmo do lado do mestre (period-metering) · 7 · Semântica (api-reference)
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:
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:
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:
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
Deteção automática da variante do módulo (initialization) · Referência do protocolo de fio rbAmp (v1.3) (api-reference) · 3.6 Algoritmo canónico de deteção (api-reference)
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
Deteção automática da variante do módulo (initialization) · 3.2 CAPABILITY (registos 0x57/0x58, u16 LE, só leitura) (api-reference) · 8 · Exemplos de rastreio no fio (api-reference)
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
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
3.5 PRODUCT_ID (0x54, u8, só leitura) (api-reference) · 4.8 Identidade (0x54..0x6F) (api-reference)
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
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
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.
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
6.5 Provisionamento — firmware novo + SAVE (api-reference) · 8.6 Provisionamento de firmware novo (api-reference)
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 devolveuREG_ERROR != OKapós o comando. Vejarbamp_read_last_errorpara os detalhes.
: 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
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:
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 em0; ao fim de 300 ms fica em1. Depois disso obit3mantém-se em qualquer número de leituras.
Saída de bancada (escrita em bruto DIGEST_CONFIG = 0xFF):
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3): immediate=0, +300 ms poll#1=1, poll#2=1
⚠ 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:
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
3. DATA_VALID (0xCE) nunca passa a 1 (troubleshooting) · Códigos de erro (REG_ERROR = 0x02) (troubleshooting) · 4 · Mapa de registos (produção v1.3) (api-reference)
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
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
8.8 Fluxo de eventos de limiar — escrever limiar → disparo → limpeza W1C (api-reference)
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ódigos de erro (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperação do estado de erro — árvore de decisão (api-reference)
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
4.4 Configuração da frota (0x27..0x2F) (api-reference) · 8.8 Fluxo de eventos de limiar — escrever limiar → disparo → limpeza W1C (api-reference)
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()).
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
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 derbamp_set_sensor_class().models— um array dencódigos de modelo de CT, um por canal.n— o comprimento do array. Limitado à variante: senfor maior do que o número de canais desta variante (por exemplo,n=3numI2), a função limita-se à contagem real de canais; os elementos extra do array são ignorados. Senfor menor do que o número de canais, os canais em falta ficam intactos (mantêm o modelo anterior). Uma entrada0emmodelssalta esse canal. A chamada abrange todos os canais do módulo, incluindo os canais 3+ num UI5 / UI7.
Internamente, a função executa:
set_sensor_class(cls)uma vez.-
Para cada canal
k < min(n, n_channels): associemodels[k]; cada associação é verificada de forma síncrona e confirmada por releitura. -
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 de1 + 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—clsoumodels[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
4.7 Espelhos de verificação do modelo de TC (0x51..0x53) (api-reference) · 8.10 Releitura do espelho de verificação do modelo de TC (sanidade pós-associação) (api-reference)
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
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
Configuração de vários módulos (initialization) · Consulta de vários módulos — três estratégias (realtime-polling) · Problemas com vários módulos (troubleshooting)
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:
-
Verifica a identidade (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Sematch_product = true, exige correspondência com o PRODUCT_ID da rbAmp. -
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. -
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Ω):
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
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
Configuração de vários módulos (initialization) · Consulta de vários módulos — três estratégias (realtime-polling)
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
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
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
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:
-
Verifica se há resposta em
0x50(ESP_ERR_NOT_FOUNDse não houver). -
Verifica que ninguém existe ainda em
desired_addr(ESP_ERR_INVALID_STATEse estiver ocupado). -
Executa um commit de endereço em duas fases.
-
Reinicia o módulo e aguarda que ele apareça em
desired_addrdentro da janela de arranque (ESP_ERR_TIMEOUTse não aparecer). -
Cria um handle; se
save_config = true— chamarbamp_save_user_config(persiste na flash). -
Devolve o handle pronto via
*out.
⚠ 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
Chamada Geral (difusão no endereço 0x00) (initialization) · Multi-módulo — instantâneo simultâneo (period-metering) · 6.3 Instantâneo de difusão GC — sincronização de frota opt-in (api-reference)
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.
-
_enable_gc_alldefineFLEET_CONFIG.bit0+GROUP_IDem todos os módulos da frota e emiteCMD_SAVE_USER_CONFIGem 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. -
_gclatchenvia a trama GCA5 27 group tick_lo tick_hipara o endereço0x00— todos os módulos com GC ativo e umgroupcorrespondente tiram instantaneamente o instantâneo (LATCH_PERIOD).settle_msé a pausa após a trama (tipicamente 50 ms) antes da verificação. -
_check_synclêGC_TICK (0x59)em cada módulo pararbamp_fleet_sync_t status[status_cap]. O resultado por módulo:
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.
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
General Call (difusão no endereço 0x00) (initialization) · 4.4 Configuração da frota (0x27..0x2F) (api-reference)
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
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
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
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.
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
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
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
Definir a classe do sensor e o modelo de TC (initialization) · 4.3 Sistema (0x20..0x25) (api-reference) · 6.2 Associação do modelo de TC — preparação pura + CMD por canal (api-reference)
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
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}.)
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
Definir a classe do sensor e o modelo de TC (initialization) · 6.2 Associação do modelo de TC — preparação pura + CMD por canal (api-reference)
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.
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:
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
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
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
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_limitspreenche (qualquer saída pode serNULL):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 empeak_adividido pelo seu fator de crista).0significa desconhecido para esse modelo (códigos legados de toroide / burden). Devolvetruese o par(class, code)estiver no registo,falsecaso contrário (as saídas ficam então a 0). -
rbamp_sensor_model_rated_aé a forma abreviada denominal_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). Userbamp_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.
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
esp_err_t rbamp_save_gains(rbamp_handle_t dev);
Uma escrita CMD_SAVE_GAINS "nua", sem alterações de registos associadas.
⚠ 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
Alteração de endereço (initialization) · 4.5 Endereço (0x30..0x31) (api-reference) · 6.1 Alteração de endereço — commit em duas fases (aprovado para produção) (api-reference)
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.
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:
-
prepare: valida o intervalo denew_addr(0x08..0x77, ≠ atual) → escrevenew_addremREG_I2C_ADDRESS(0x30) — fica na RAM. -
prepare: escreva0xA5emREG_ADDR_COMMIT_MAGIC(0x31) — isto "arma" o commit. A janela de estado armado é de 5 segundos. -
commit: verifique a frescura da armação → envieCMD_COMMIT_ADDR(opcode 0x30) → persista na flash →CMD_RESET -
~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.
⚠ 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
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);
O comando CMD_FACTORY_RESET (0xAA) + uma espera de 1500 ms.
⚠ 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
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
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
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
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 devolvemESP_ERR_NOT_SUPPORTED.
Blocos em tempo real
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. |
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
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
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).
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.
-
generationmuda quando os contadores foram repostos ou adotados no módulo — nunca faça uma diferença que atravesse essa mudança. -
uptime_sa 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/*_uvarhsã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ódulo0x0001007Ae posteriores; reativa a partir de0x0001007B) fornece-os a partir do mesmo instantâneo efine/fine_reactivesão true; nos módulos mais antigos são os contadores grosseiros escalados efineé false. -
channels > 0(mapa 0x36+): o canalcé o canal de correntec; num módulo trifásico, a fasec.
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.
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.
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).
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
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:
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
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ósCONFIG_RBAMP_NACK_RETRY_ATTEMPTStentativas, 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 devolveESP_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:
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.
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:
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:
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
Leituras de registos — auto-incremento
Uma leitura em rajada 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)
chegaapenas 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:
/* 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.
⚠ 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):
/* 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)
- 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:
addr=0x00 | A5 27
A5— mágico.27— o opcodeCMD_LATCH_PERIOD.—0x00= chamada geral (all-call), caso contrário tem de coincidir comREG_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):
- NACK do endereço GC (imediato, ao nível do barramento): se o GC estiver desativado em toda a frota —
i2c_master_transmitpara0x00devolveESP_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). - 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.
Ligações
- 05 · Arranque rápido — o seu primeiro projeto a funcionar
- 06 · Exemplos — cenários de funcionamento
-
10 · Resolução de problemas — descodificar erros e resolver problemas comuns
-
O ficheiro de cabeçalho-fonte com comentários Doxygen:
include/rbamp.h
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)
// 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
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));
Ler um período — sem o componente
// 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
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âmetrosettle_ms), leitura correta do instantâneo (instantâneo atómico no lado do módulo). -
Verificação do flag
REG_V03_PERIOD_VALIDantes de ler (o camposnap.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
doubledentro 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
Diagramas de interação
O fluxo de 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)
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)