rbAmp
PT
Loja
Docs
Atualizado

Integração com o anfitrião

Como executar um módulo STD a partir do seu próprio código — com as nossas bibliotecas ou apenas com um mestre I²C/Modbus.

Com as bibliotecas rbAmp

Uma biblioteca cliente por plataforma cobre toda a linha; o número de canais e as funcionalidades são descobertos em tempo de execução:

  • Arduino (rbamp-arduino) — suporte STD: descoberta, tempo real, configuração, eventos/DRDY, OTA, histórico, energia em resolução fina, corrente de arranque, ângulo de fase e sequência. Num módulo com bancos de instantâneos e contadores de energia, use a v1.6.2 ou posterior (versões anteriores obtêm o período do banco 0 em vez dos contadores; origem da energia e versão mínima).
  • ESP-IDF (rbamp-esp-idf) — componente com suporte STD, incluindo energia em resolução fina e corrente de arranque. Num módulo com bancos de instantâneos e contadores de energia, use a v1.7.3 ou posterior (versões anteriores obtêm o período do banco 0 em vez dos contadores; versão mínima).
  • ESPHome / Home Assistant (rbamp-esphome) — componente externo: contadores de energia no dispositivo, corrente de arranque e diagnóstico de fase. Use a v1.9.0 ou posterior; bancos de instantâneos (period_banks:) a partir da v1.9.1.
  • Python (rbamp-python) — suporte STD: uma classe de cliente, a linha do módulo é detetada na ligação. Use a v1.6.0 ou posterior; chamadas de bancos de instantâneos a partir da v1.6.1. Validado em Python Linux padrão (smbus2).

As bibliotecas cobrem estes fluxos (controlo de descoberta, consulta de ocupado/erro, OTA com imagem preparada, contabilização de diferenças de energia), por isso prefira-as sempre que a plataforma o permitir.

As funcionalidades de energia de micro-resolução e de corrente de arranque, em resumo — cada chamada degrada-se com elegância nos módulos que não publicam a funcionalidade (sem tráfego no barramento, ou valores derivados dos contadores grosseiros):

Característica Arduino ESP-IDF ESPHome (YAML) Python
Energia de micro-resolução (os campos µWh / µvarh são sempre utilizáveis; um sinalizador fine indica se são os contadores próprios do módulo) stdReadEnergy() → campos *_uwh / *_uvarh de RbAmpStdEnergy, stdEnergyDelta() campos rbamp_std_energy_t *_uwh / *_uvarh, rbamp_std_energy_delta() energy_total · energy_exported_total · energy_net · reactive_energy / reactive_energy_exported read_std_energy() → campos RbAmpStdEnergy *_uwh / *_uvarh, RbAmp.std_energy_delta()
Corrente de arranque para energia stdSetEnergyStartCurrent() / stdReadEnergyStartCurrent() rbamp_std_set_start_current() / rbamp_std_get_start_current() start_current_ua: set_start_current() / get_start_current()
Ângulo de fase da tensão stdReadVoltage(v) → angle_deg / angle_valid rbamp_std_voltage_t.angle_deg / angle_valid voltage_angle_b / voltage_angle_c read_std_voltage(phase) → angle_deg / angle_valid
Sequência de fases stdReadPhaseSequence() rbamp_std_read_phase_seq() phase_sequence read_phase_sequence()

Se a sua aplicação guardar um instantâneo de energia da biblioteca (NVS, EEPROM, ficheiro), guarde os campos individuais de que precisa num formato fixo próprio, não a estrutura como blob bruto — as estruturas de instantâneo ganham campos entre versões da biblioteca.

Sem as nossas bibliotecas

Tudo o que as bibliotecas fazem é E/S de registos simples. O protocolo está documentado e é estável; as alterações de mapa são versionadas (VERSION) e condicionadas por funcionalidade (CAPABILITIES). Os fluxos canónicos passo a passo (inicialização, comando, configuração, alteração de endereço, energia, histórico, OTA, UNLOCK) estão em Sequências — abaixo estão os padrões de funcionamento mais curtos.

Arranque I²C mínimo (pseudocódigo)

Text
# discovery (once)
id   = read(0x0000, 2)            # expect 'S','T'
ver  = read(0x0003, 1)            # map version, expect >= 0x36
caps = read_u16(0x0004)
nv   = read(0x0007, 1); ni = read(0x0008, 1)
uid  = read(0x00F4, 12)           # device identity for your database
fwv  = read_u32(0x0114)           # firmware version: high word . low word (1.126)

# clock (after every module reset: STATUS bit4 == 0)
write_u32(0x08C0, unix_epoch)     # TIME_SET
write(0x0060, 0x06)               # SET_TIME; then poll CMD_STATE 0x006A bit0 -> 0, check ERROR == 0

# realtime poll (every 0.2..1 s, or on the DRDY edge)
u_mv  = read_i32(0x0200 + v*0x20)             # per voltage channel
i_ua  = read_i32(0x1000 + c*0x40)             # per current channel
p_mw  = read_i32(0x1000 + c*0x40 + 0x04)      # signed
pf    = read_i16(0x1000 + c*0x40 + 0x10)      # /1024
freq  = read_u16(0x0010)                      # /100 Hz
tot_p = read_i32(0x0300 + 0x04)               # grand active power

Padrão de contabilização de energia

Text
# at each interval boundary (your clock):
blk = read(0x0800, 0x44)          # ONE transaction <= 128 B: Wh + mWh counters + LT_GEN — coherent
e_imp = i64(blk, 0x28); e_exp = i64(blk, 0x30)   # grand import/export, mWh
gen   = u32(blk, 0x40)            # LT_GEN (0x0840)
up    = read_u32(0x08A0)          # UPTIME

interval_import = e_imp - last_imp          # delta of cumulative counters
if gen != last_gen: re-anchor, no delta     # counter was reset/adopted (event-logged)
if up < last_up:    delta = max(0, delta)   # restart: ~last second of energy may be missing; re-feed time

Leia o bloco de energia numa única transação de ≤ 128 bytes — campos i64 lidos em transações separadas podem desfasar-se entre publicações (transporte I²C).

Nunca integre a potência ao longo do tempo no anfitrião — os contadores do módulo são compensados de lacunas e persistidos; o seu integral não é nem uma coisa nem outra. Detalhes: Medição e energia.

Ler os registos horários

Text
write(0x0C00, 1)                  # HIST_PERIOD = hourly
write_u16(0x0C04, n)              # n records back from newest
write(0x0060, 0x08)               # HIST_READ
poll CMD_STATE (0x006A) bit0 -> 0
err = read(0x0002, 1)             # 0xFC = no such record
flags = read(0x0C02, 1)           # bit0 = record valid
rec   = read(0x0C20, 80)          # one transaction; see record layout

Os registos trazem a Wh absoluta de vida útil no fim do período, mais a energia do período por fase (layout).

Consulta de estado

Veja a lista de verificação de diagnóstico — seis leituras cobrem disponibilidade, saúde do armazenamento, reinícios e gerações de contadores.

Integração Modbus sem bibliotecas

  • Perfil float32: os pontos que o módulo publica — V/I/P por fase, P total, frequência, importação/exportação kWh — nos endereços de entrada float32 (lista). Os outros endereços do perfil leem 0.

  • Perfil nativo: FC04 lê em 0x6000 (descoberta), 0x6100/0x6200 (canais), 0x6B00+ (energia), 0x6C00 (totais); configuração e comandos por FC16 em 0x8000+ com UNLOCK para comandos que alteram estado. Mapa completo: mapa de registos; regras: Transporte Modbus.

  • Mestres apenas FC03 leem os dados nativos pelo espelho 0xA000+ (entrada + 0x4000).

Regras de integração que vale a pena repetir

  1. Condicione os canais por N_VOLTAGE/N_CURRENT, as funcionalidades por CAPABILITIES e o layout do mapa por VERSION.
  2. Identifique os módulos pelo UID, não pelo endereço no barramento.
  3. Volte a armar o estado em RAM (máscara de eventos, limiares, relógio) após qualquer reinício detetado do módulo.
  4. Tolere NACK/clock-stretching durante comandos que tocam na flash; respeite os tempos de estabilização.
  5. Energia: diferenças dos contadores com tratamento de geração/reinício — nunca P·dt do lado do anfitrião.
  6. Atualizações de firmware: envie o ficheiro de versão preparado tal como está; verifique primeiro BOARD_ID.