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

02 · Linhas de módulos

Os módulos rbAmp vêm em linhas de módulos: BASIC e STANDARD (STD). Uma linha de módulos é um pacote completo de revisão de hardware e firmware, não um sinalizador de software. Passar de uma linha para outra exige uma troca física de SKU, não uma atualização de firmware.

O que é uma linha de módulos

As linhas de módulos BASIC e STANDARD (STD) lado a lado.

Do ponto de vista do componente e do código do utilizador: um handle e uma API rbamp_* servem as duas linhas de módulos comercializadas. rbamp_begin() deteta se o módulo por trás do handle é BASIC ou STD (rbamp_line()), e as chamadas que só existem numa delas devolvem ESP_ERR_NOT_SUPPORTED na outra. As diferenças aparecem nos valores que o módulo devolve, nas grandezas extra que o módulo STD mede e na forma como o firmware trata os dados (em particular — a exportação para a rede).

Estado atual

Os módulos BASIC e STANDARD (STD) estão a ser fornecidos e são ambos suportados por este componente (versão 1.7.3).

Linha de módulos Estado neste componente
BASIC ✅ em distribuição — RBAMP_LINE_BASIC
STANDARD (STD) ✅ em distribuição — RBAMP_LINE_STD

BASIC — linha de módulos de medição de consumo de gama de entrada

Hardware

Um caminho analógico de custo otimizado, adequado a cargas domésticas típicas. O módulo inclui uma frente analógica isolada, um regulador de alimentação de bordo e calibração de fábrica guardada na flash.

Comportamento do firmware

A lógica de um contador de disco mecânico clássico — a contagem só avança, e a exportação para a rede não é subtraída.

Os três «níveis» dos valores de potência ativa comportam-se de forma diferente:

Sinal Significado Comportamento no BASIC
rbamp_read_power(dev, ch, &p) potência RT instantânea, atualizada a cada ~100 ms com sinal — um valor negativo é visível em tempo real (exportação)
snap.avg_p[ch] (dentro de rbamp_read_period_snapshot) potência média ao longo do período cada janela de potência média de 100 ms é limitada a max(P, 0) antes de ser somada ao acumulador do período
rbamp_energy_wh(dev, ch) Wh acumulados pelo componente monotónico — apenas consumo; a exportação não é contada

Por outras palavras: o utilizador vê a exportação na leitura RT, mas o contador de Wh do componente no BASIC não a inclui.

Aplicações típicas

  • Casas sem produção própria (sem painéis solares, turbinas eólicas, sistemas de bateria)

  • Submedidores para cargas puramente consumidoras (esquentadores, motores, aparelhos domésticos)

  • Monitorização do consumo em edifícios onde a medição bidirecional não é necessária

Medição bidirecional no BASIC (lado do mestre)

Como a energia é produzida num módulo BASIC (integrada no mestre) e num módulo STANDARD (STD) (contadores no próprio dispositivo).
Se precisar de contabilizar a exportação para a rede separadamente num módulo BASIC,faça-o do lado do mestre. A potência RTrbamp_read_power(dev, 0, &p)é assinado, portanto:

C
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

static double consume_wh = 0.0;
static double export_wh  = 0.0;

void bidirectional_loop(rbamp_handle_t dev) {
    int64_t t_prev_us = esp_timer_get_time();

    while (1) {
        /* Sample RT power at 10 Hz. Slower polling loses resolution
         * on sharp load transitions; faster adds little for typical
         * mixed loads with an inverter. */
        vTaskDelay(pdMS_TO_TICKS(100));

        int64_t t_now_us = esp_timer_get_time();
        double  dt_s     = (double)(t_now_us - t_prev_us) / 1e6;
        t_prev_us = t_now_us;

        float p;
        if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;

        double dwh = (double)p * dt_s / 3600.0;
        if (p >= 0.0f) consume_wh += dwh;
        else           export_wh  += -dwh;
    }
}

Um exemplo completo do padrão está em 06_examples.md, no cenário "Medição bidirecional do lado do master".

STANDARD (STD) — a linha de módulos de medição alargada

Os módulos STD são suportados pela mesma API rbamp_*; rbamp_begin() deteta-os. Para além do que o BASIC oferece, um módulo STD fornece:

  • Energia com sinal. Importação e exportação são grandezas separadas, e o módulo mantém contadores de vida persistidos (Wh / varh, com resoluções mais finas em firmware mais recente). A exportação não é descontada: a energia de um período é a diferença entre duas leituras de contador (rbamp_std_read_energy() / rbamp_std_energy_delta()), e rbamp_energy_wh() transporta um valor líquido com sinal nesses módulos.

  • Mais grandezas: potência reativa e potência aparente por canal (rbamp_read_reactive_power(), rbamp_read_apparent_power(), rbamp_std_read_channel()), totais por fase e globais e — quando a extração de harmónicos estiver ativa — THD e fator de potência de deslocamento. Os módulos trifásicos também reportam os ângulos de fase de tensão e a sequência de fases.

  • Mecanismos de período: bancos de instantâneos (oito períodos independentes, temporizados pelo master) nos módulos que os têm, ou diferenças de contadores nos módulos que mantêm a energia no dispositivo. O mecanismo é escolhido em rbamp_begin() (rbamp_std_info_t.period_source).

  • O modelo de CT é apenas uma etiqueta. Num módulo STD o modelo de CT é apenas uma etiqueta e não define qualquer ganho.

  • Relógio do módulo, histórico no dispositivo e registo de eventos, estado de saúde e diagnóstico, atualização de firmware por I²C, certificado do dispositivo e atestação.

Tudo isto está documentado em 09 · Referência da API, capítulo "Linha STD". Um exemplo funcional é examples/std_meter/ (ver 06 · Exemplos, Cenário 18).

Comportamento que difere do BASIC

Tema BASIC STD
Exportação em rbamp_energy_wh() não contabilizada (monotónica, apenas consumo) com sinal — líquido de importação e exportação
Potência reativa / aparente, THD não disponível — no BASIC, a potência reativa não é exposta por esta biblioteca (ESP_ERR_NOT_SUPPORTED) disponível
Fonte do período instantâneo do acumulador do período bancos de instantâneos ou diferenças de contadores
Relógio do módulo nenhum defina-a com rbamp_std_set_time() após cada reposição do módulo
rbamp_factory_reset() suportado ESP_ERR_NOT_SUPPORTED
Digest (rbamp_read_digest()) suportado no firmware com a capacidade ESP_ERR_NOT_SUPPORTED
Chamadas de período num módulo sem bancos de instantâneos nem contadores — ESP_ERR_NOT_SUPPORTED

Aplicações típicas

  • Casas com produção solar em telhado, turbinas eólicas ou baterias
  • Cargas regenerativas, carregamento de veículos elétricos V2G
  • Instalações que precisam de potência reativa, fator de potência e harmónicos além da potência ativa

Como detetar a linha do módulo em tempo de execução

Fluxograma para descobrir se tem um módulo BASIC ou STANDARD (STD).
A linha de produto é detetada automaticamente porrbamp_begin():

C
/* BASIC or STD — available after rbamp_begin() */
rbamp_line_t line = rbamp_line(dev);    /* RBAMP_LINE_BASIC / RBAMP_LINE_STD */

/* Full SKU — cached by rbamp_begin(), no bus traffic */
rbamp_variant_t variant = rbamp_variant(dev);   /* UI1 / UI2 / ... / I3 / UI5 / UI7 */

/* Voltage-sensing presence (UI* variants vs I*-only) */
bool voltage_hw = rbamp_has_voltage_hw(dev);

/* Number of current channels (1 / 2 / 3 / 5 / 7) */
uint8_t channels = rbamp_channels(dev);

/* Firmware: BASIC — REG_VERSION byte; STD — register-map version */
uint8_t fw = rbamp_firmware_version(dev);

/* STD only: identity, capabilities and the period mechanism */
rbamp_std_info_t info;
if (rbamp_line(dev) == RBAMP_LINE_STD && rbamp_std_info(dev, &info) == ESP_OK) {
    /* info.capabilities, info.n_voltage, info.n_current, info.period_source */
}
Nota

: rbamp_line() distingue BASIC de STD. Use a etiqueta do SKU no invólucro do módulo como fonte de verdade para o produto exato.

Onde os detalhes dependentes da linha estão assinalados na documentação

No texto do componente e na documentação canónica, as funcionalidades dependentes da linha são assinaladas explicitamente, por exemplo:

Apenas STD

— esta função não está disponível no módulo BASIC (ESP_ERR_NOT_SUPPORTED).

Ou, inversamente, comportamento específico do BASIC:

BASIC

: o contador rbamp_energy_wh(dev, ch) é monotónico — a exportação para a rede não é contabilizada. Para medição bidirecional, veja o cenário "Medição bidirecional do lado do master" em 06_examples.md, ou use um módulo STD.

O que vem a seguir


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