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