09 · Referência da API
A API pública completa do pacote rbamp. Fonte — __init__.py (reexportações), _rbamp_core.py (a classe principal RbAmp), _snapshot.py (estruturas POD + hierarquia de exceções), _energy.py (acumulador de Wh), _registers.py (constantes geradas automaticamente).
Este capítulo é uma referência: assinaturas, valores devolvidos, efeitos secundários, casos limite. Para exemplos práticos, vá a 06 · Exemplos; para um arranque rápido, veja 05 · Início rápido.
Importações
from rbamp import (
RbAmp, # main class
RbAmpEnergy, # Wh accumulator (accessed via dev.energy)
RbAmpSnapshot, # RT-block dataclass-style
RbAmpPeriodSnapshot, # period snapshot dataclass-style
RbAmpSensorClass, # sensor-class enum
TOPOLOGY_SINGLE, TOPOLOGY_SPLIT_PHASE, TOPOLOGY_THREE_PHASE,
TOPOLOGY_FIVE_CH, TOPOLOGY_SEVEN_CH,
topology_name, # helper: int → topology name
# STD module line (1.6.0)
RbAmpStdEnergy, RbAmpStdVoltage, RbAmpStdChannel,
RbAmpStdConfig, RbAmpStdHealth, # value objects
std_energy_delta, # energy between two read_std_energy() snapshots
phase_seq_name, # helper: phase-sequence code → name
PHASE_SEQ_NA, PHASE_SEQ_FORWARD, PHASE_SEQ_REVERSE, PHASE_SEQ_ABNORMAL,
# Exception hierarchy
RbAmpError, # base class of all errors
RbAmpIOError,
RbAmpTimeoutError,
RbAmpNotReadyError,
RbAmpStaleError,
RbAmpParamError,
RbAmpModeError,
RbAmpVersionError,
RbAmpNotSupportedError, # call not available on this module / firmware
# Metadata
__version__, # "1.6.0"
__protocol_version__, # 0x04 (RBAMP_PROTOCOL_VERSION)
REGISTERS, COMMANDS, # raw protocol constants (advanced use)
)
Importação mínima para uma aplicação típica:
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError
Idiomas gerais
A API segue os padrões Python habituais:
-
Uma classe para cada linha de módulos: a mesma classe
RbAmpserve os módulos BASIC e STANDARD (STD). A linha é detetada automaticamente embegin()(ver Linha de módulos STD); o utilizador nunca a escolhe. -
Baseada em classes: a classe principal
RbAmptem tudo — leituras RT, período, configuração, diagnósticos. O handle guarda internamente o backend e o acumulador de energia. -
Context manager:
with RbAmp(bus, addr) as dev:— o idioma recomendado.__enter__chama automaticamentedev.begin(). -
Propriedades para leituras RT:
dev.voltage,dev.frequency— uma propriedade = uma transação I²C. As indexadas por canal passam por_ChannelProxy:dev.current[ch],dev.power[ch],dev.power_factor[ch]. -
Métodos para leituras indexadas por canal:
dev.read_current(ch),dev.read_power(ch). Totalmente equivalentes à forma de propriedade — use a que for mais cómoda. -
Exceções para os erros: todo o erro é uma subclasse de
RbAmpError. O padrão Python standardtry / except(e nãolast_error()+ um código de retorno). -
Gerador assíncrono para streaming periódico:
async for snap in dev.stream_period(interval_s=...).
Tipos
RbAmp
class RbAmp:
def __init__(self, bus, addr: int = 0x50): ...
A classe principal. Uma instância por dispositivo escravo. O barramento é qualquer objeto com uma das assinaturas de API "conhecidas": smbus2.SMBus, machine.I2C, ou um backend personalizado (ver 04 · Hardware).
O backend é selecionado automaticamente no primeiro acesso ao barramento:
| método do objeto de barramento | Backend |
|---|---|
bus.readfrom_mem, bus.writeto_mem |
MachineI2CBackend (MicroPython) |
bus.read_byte_data, bus.write_byte_data |
SMBusBackend (CPython + smbus2) |
bus.read_byte, bus.register_acks, bus.now_ms |
já envolvido (mocks de teste, adaptadores FTDI) |
Se nenhuma assinatura corresponder, é levantado um RbAmpParamError com uma descrição.
Hierarquia de exceções
Todo o erro do pacote é uma subclasse de RbAmpError, que por sua vez herda de OSError (e não de Exception genérico). Isto quer dizer: o código existente com handlers except OSError: continua a apanhar erros rbAmp sem qualquer reescrita — a convenção Python standard para drivers de E/S de hardware.
: RbAmpParamError herda de RbAmpError + ValueError em CPython (herança múltipla). Em MicroPython, onde a herança múltipla não é suportada por todas as portas, recorre a herança simples. Do ponto de vista do utilizador, try / except RbAmpParamError funciona da mesma forma. Mas try / except ValueError só apanha em CPython — em MicroPython este handler falha. Código que depende de comportamento multiplataforma tem de apanhar RbAmpParamError explicitamente.
Utilização padrão:
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
# period not ready yet — the master timestamp was committed by the package
continue
except RbAmpIOError as e:
log.warning("bus failure: %s", e)
except RbAmpError as e:
log.error("unexpected: %s", e)
RbAmpSensorClass
class RbAmpSensorClass(IntEnum):
UNSET = 0 # factory value after reset
SCT_013 = 1 # SCT-013 series (shipping default)
WIRED_CT = 2 # factory-fitted wired CT (module ships paired)
BUILTIN_CT = 3 # factory-fitted built-in CT (module ships paired)
: em CPython usa-se o IntEnum do enum da biblioteca padrão. Em portas MicroPython sem módulo enum, usa-se um fallback de classe simples com os mesmos valores de membro. Do ponto de vista do utilizador as duas formas são idênticas: dev.set_sensor_class(RbAmpSensorClass.SCT_013) ou dev.set_sensor_class(1) — ambas funcionam.
SCT_013 é a classe a selecionar num módulo com pinças SCT-013 instaladas pelo utilizador. WIRED_CT e BUILTIN_CT descrevem módulos entregues emparelhados de fábrica com o seu sensor: set_sensor_class() e set_ct_model*() recusam alterar esses módulos (RbAmpModeError, ver guarda de leitura antes da escrita). Valores fora de 0..3 levantam RbAmpParamError.
RbAmpSnapshot
Devolvido por dev.read_all(). Uma classe Python simples (não um @dataclass, por compatibilidade com MicroPython). Todos os campos em unidades SI.
class RbAmpSnapshot:
voltage: float # V — RMS voltage
voltage_peak: float # V — peak voltage
current: list # [ch0, ch1, ...] — RMS current per channel, A
current_peak: list # [ch0, ch1, ...] — peak current, A
power: list # [ch0, ch1, ...] — active power (signed), W
power_factor: list # [ch0, ch1, ...] — dimensionless, −1..+1
frequency: float # Hz
topology: int # TOPOLOGY_* constant
channels: int # number of valid channels (1..3, or 5 / 7 on UI5 / UI7)
has_voltage_hw: bool # True if a voltage sensor is present
Os canais não utilizados (além de channels) são preenchidos com zeros.
RbAmpPeriodSnapshot
Devolvido por dev.read_period_snapshot(). A primitiva de contabilização de energia.
class RbAmpPeriodSnapshot:
avg_p: list # [ch0, ch1, ...] — average P over the period, W (all channels)
max_p: float # peak instantaneous power on channel 0
latch_ms: int # period duration (device's view)
master_dt_ms: int # master wall-clock dt since the last snapshot
valid: bool # True if the snapshot-ready flag was set
avg_p_total: float # STD: total average P over the period, W (0.0 on BASIC)
wh_net: float # STD: net energy over the period, Wh (0.0 on BASIC)
module_restarted: bool # STD counter source: the module restarted during the period
Para integração de energia use master_dt_ms, não latch_ms — latch_ms é um temporizador de diagnóstico do módulo.
Constantes de topologia
TOPOLOGY_SINGLE = 1 # 1 current channel (UI1 / I1)
TOPOLOGY_SPLIT_PHASE = 2 # 2 current channels (UI2 / I2)
TOPOLOGY_THREE_PHASE = 3 # 3 current channels (UI3 / I3)
TOPOLOGY_FIVE_CH = 5 # 5 current channels + voltage (UI5)
TOPOLOGY_SEVEN_CH = 7 # 7 current channels + voltage (UI7)
topology_name(topology: int) -> str # 1 → "SINGLE", 2 → "SPLIT_PHASE", ...
Ciclo de vida
RbAmp(bus, addr=0x50)
Construtor. A resolução do backend acontece em __init__. Nenhum tráfego I²C é gerado até begin().
| Parâmetro | Descrição |
|---|---|
bus |
Objeto de barramento I²C (smbus2.SMBus, machine.I2C, ou um wrapper) |
addr |
Endereço escravo de 7 bits. Intervalo 0x08..0x77, predefinido 0x50 |
Lança: RbAmpParamError se o objeto de barramento não for reconhecido ou se addr estiver fora de gama.
dev.begin()
02 · Inicialização e arranque (initialization) · BASIC ou STD? (initialization) · Ciclo de consulta contínuo (recomendado) (period-metering)
Sonda o dispositivo + deteta a linha do módulo + guarda a topologia em cache + prepara o comando de snapshot.
Deteção da linha de módulos (1.6.0). begin() verifica primeiro se o módulo é um módulo STD (mapa de registos de 16 bits). Se for, o handle passa ao modo STD (dev.is_std passa a True, dev.channels e dev.has_voltage_hw vêm do módulo) e begin() retorna. Se não, corre a sequência BASIC abaixo. Isto exige um backend de barramento capaz de transações de 16 bits; caso contrário o módulo é tratado como BASIC.
Sequência BASIC:
-
Lê
REG_VERSION— levantaRbAmpIOErrorem NACK,RbAmpVersionErrorse for devolvido0x00/0xFF. -
Guarda em cache a topologia (na versão atual do firmware,
begin()não faz auto-sondagem; usa a sugestão do construtor). -
Lê
U_rmspara determinar se existe um sensor de tensão (limiar 1.0 V). -
Escreve
CMD_LATCH_PERIOD(primer) + espera 50 ms. O primeiro snapshot após ligar é descartado. -
Guarda
time.monotonic()(outime.ticks_ms()em uPy) para a integração de energia seguinte.
Num módulo BASIC com pinças SCT-013, begin() também avalia a correção de comutação de calibre SCT-013.
Idempotente: seguro chamar repetidamente.
Context manager
with RbAmp(bus, 0x50) as dev:
# dev.begin() has already been called in __enter__
...
# __exit__ — no-op (bus closing is the caller's responsibility)
A forma recomendada. O __exit__ do pacote NÃO fecha o barramento — gerir o objeto do barramento continua a ser responsabilidade de quem chama (o padrão típico é with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: aninhado).
dev.probe() -> bool
Uma verificação de vida leve. Uma única leitura de REG_VERSION sem efeitos secundários.
Devolve: True se o escravo respondeu com ACK e reportou uma versão suportada; False caso contrário. Não lança exceções — para cenários de polling.
dev.wait_ready(timeout_ms=1000) -> None
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)
Consulta a flag de pronto do módulo até ser ativada. Útil após ligar — o módulo pode precisar de até 100 ms para a sua primeira janela em tempo real.
Lança: RbAmpTimeoutError se o bit não for visto antes de timeout_ms expirar.
Propriedades — 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)
dev.firmware_version: int # REG_VERSION — opaque byte
dev.topology: int # TOPOLOGY_* constant
dev.topology_name: str # "SINGLE" / "SPLIT_PHASE" / "THREE_PHASE"
dev.channels: int # 1..3 (BASIC), 5 / 7 on UI5 / UI7, or the STD module's channel count
dev.is_std: bool # True if begin() detected an STD module
dev.has_voltage_hw: bool # True if begin() detected U_rms > 1.0
dev.address: int # 7-bit I²C address (updated after commit_address_change)
firmware_version é uma propriedade ao vivo: cada leitura acede ao barramento (uma leitura de um byte de REG_VERSION). Guarde-a em cache do lado da aplicação se a consultar num ciclo intenso: fw = dev.firmware_version uma vez após begin(). Se begin() ainda não tiver sido chamado, firmware_version levanta RbAmpIOError (o módulo pode dar NACK enquanto o handle está "frio").
As restantes propriedades (topology, channels, has_voltage_hw, address) estão guardadas em cache no handle e devolvem os valores guardados após begin() sem aceder ao barramento.
Leituras em tempo real (bloco RT, atualização de 100 ms)
Todos os métodos levantam RbAmpIOError numa falha de comunicação (NACK após retry ou rejeição por sanidade) ou RbAmpParamError num argumento inválido.
Propriedades
Corrente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Janela de acesso aos canais (0x32 + 0x3C..0x3F) (api-reference)
dev.voltage -> float # V — RMS voltage
dev.voltage_peak -> float # V — peak voltage
dev.frequency -> float # Hz — mains frequency
Indexado por canal através de _ChannelProxy — suporta indexação [ch] e iteração:
dev.current # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak # _ChannelProxy
dev.power # _ChannelProxy
dev.power_factor # _ChannelProxy
Usage:
i0 = dev.current[0] # a single channel
for i in dev.current: # iterate over all valid channels
print(i)
total = sum(p for p in dev.power) # sum of all channels
len(dev.current) é igual a dev.channels.
Métodos (totalmente equivalentes à forma de propriedade)
Referência de registos RT (realtime-polling) · Contabilidade bidirecional (period-metering)
dev.read_voltage(phase=0) -> float
dev.read_voltage_peak(phase=0) -> float
dev.read_current(ch=0) -> float
dev.read_current_peak(ch=0) -> float
dev.read_power(ch=0) -> float # signed
dev.read_power_factor(ch=0) -> float
dev.read_frequency() -> float
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)
dev.read_all() -> RbAmpSnapshot
Equivalente a read_voltage + read_voltage_peak + read_current(0..N) + read_current_peak(0..N) + read_power(0..N) + read_power_factor(0..N) + read_frequency, em chamadas consecutivas. Os canais não usados (além de channels) são preenchidos com zeros.
Lança: RbAmpIOError se alguma sub-leitura falhar.
Os leitores comuns — voltage, voltage_peak, current, current_peak, power, power_factor, frequency e as suas formas read_* — funcionam em todas as linhas de módulos. Num módulo STD, phase em read_voltage() / read_voltage_peak() seleciona a entrada de tensão (0..n_voltage-1); num módulo BASIC só phase=0 é válido.
Linha de módulos STD (1.6.0)
⚠️ Estado de validação. As funcionalidades embutidas de energia, ângulo de tensão e corrente de arranque estão validadas em CPython (smbus2). As mesmas chamadas estão implementadas para MicroPython (machine.I2C), mas o caminho de 16 bits do MicroPython ainda não está validado em hardware — prefira CPython para estas funcionalidades embutidas até que uma nota de versão diga o contrário. As leituras comuns (dev.voltage, dev.current[ch], dev.power[ch], snapshots por período) funcionam em todos os hosts suportados, independentemente disso.
Uma única classe RbAmp serve ambas as linhas de módulos. begin() deteta a linha automaticamente; dev.is_std é True num módulo STD. Usam-se a mesma ligação I²C e o mesmo endereço (ver 04 · Hardware).
-
As leituras comuns (
voltage,current,power,power_factor,frequency) funcionam em qualquer módulo. -
As chamadas desta secção são exclusivas do STD. Num módulo BASIC levantam
RbAmpNotSupportedError. -
Algumas chamadas STD também precisam de uma imagem de módulo suficientemente recente (energia no dispositivo, contadores em micro-unidades, ângulos de tensão, corrente de arranque). Se o módulo não as fornecer, a chamada levanta
RbAmpNotSupportedError("não disponível"). -
As chamadas de período (
latch_period,read_period_*,stream_period) e o acumuladordev.energyfuncionam num módulo STD — ver "Contabilidade de período" abaixo. Os totais de vida do próprio módulo sãoread_std_energy(). -
As chamadas de configuração do sensor (
set_sensor_class,set_ct_model,set_ct_model_ch,set_ct_model_ch_force,read_ct_model_ch,read_sensor_class),reset,factory_reset, o par de mudança de endereço, os registos de identidade (firmware_version,read_variant,read_capability,read_product_id,read_uid,read_label,set_label,read_seq_digest), o canal de erros/eventos (read_last_error,read_event_flags,clear_event_flags,has_error,clear_error), os auxiliares de frota (read_fleet_config,enable_gc,set_group_id,read_group_id,read_gc_tick),read_period_latch_msewait_readysão exclusivos de BASIC: num módulo STD lançamRbAmpNotSupportedErrorantes de qualquer coisa ser enviada ao barramento.
dev.is_std -> bool # True on an STD module (set by begin())
dev.std -> object # internal STD client (advanced use) or None on BASIC
Leituras
dev.read_std_voltage(phase=0) -> RbAmpStdVoltage # RMS, peak, THD, angle
dev.read_voltage_angle(phase=0) -> (float, bool) # (degrees, valid)
dev.read_phase_sequence() -> int # 0..3
dev.read_std_channel(ch=0) -> RbAmpStdChannel # I / P / Q / S / PF + harmonics
dev.read_std_totals(k=0) -> RbAmpStdChannel # totals block k (0 = grand total)
dev.read_reactive(ch=0) -> float # var
dev.read_apparent(ch=0) -> float # VA
dev.read_std_config() -> RbAmpStdConfig
dev.read_std_health() -> RbAmpStdHealth
-
read_voltage_angle(phase)— ângulo de fase da tensão em relação à fase 0, devolvido como(degrees, valid).validéFalsenum módulo de tensão única ou numa imagem de módulo que não reporta ângulos. -
read_phase_sequence()— código da sequência de fases:PHASE_SEQ_NA(0, não disponível),PHASE_SEQ_FORWARD(1),PHASE_SEQ_REVERSE(2),PHASE_SEQ_ABNORMAL(3).phase_seq_name(code)devolve o nome em texto. LevantaRbAmpNotSupportedErrornum módulo BASIC ou numa imagem de módulo que não o reporta. -
read_reactive(ch)/read_apparent(ch)— potência reativa em var e potência aparente em VA para um canal. Apenas módulos STD; num módulo BASIC lançamRbAmpNotSupportedError(no BASIC, a potência reativa não é exposta por esta biblioteca). -
read_std_totals(k)— bloco de totaisk;k=0é o total geral. Os totais por fase dependem da versão do mapa de registos do módulo. -
read_std_config()/read_std_health()— blocos de configuração e de estado/saúde.
Objetos de valor
Classes simples (não @dataclass), todas reexportadas a partir de rbamp.
| Classe | Campos |
|---|---|
RbAmpStdVoltage |
u_rms, u_peak, thd_u, angle_deg, angle_valid |
RbAmpStdChannel |
i_rms, i_peak, p, q, s, pf, thd_i, pf1, q1 |
RbAmpStdConfig |
sensor_class, ct_model, tier, i2c_addr, rate_ms, harmonics, start_ua, start_ua_supported |
RbAmpStdHealth |
status, cal_ok, sensor_ok, mains_ok, time_valid, nvm_fault, maint, frame_count, crc_errors, lta_status, lta_src, cal_src, group_status, ring_drop, lost_frames, uptime_s, reset_cause, boot_count |
RbAmpStdEnergy |
veja abaixo |
dev.read_std_energy() -> RbAmpStdEnergy
Snapshot de energia de vida no dispositivo. Requer um módulo que forneça energia no dispositivo; caso contrário RbAmpNotSupportedError.
RbAmpStdEnergy contém:
| Grupo | Campos |
|---|---|
| Ativa, Wh | act_import_wh, act_export_wh, act_net_wh |
| Ativa, mWh | act_import_mwh, act_export_mwh, act_net_mwh |
| Ativa, µWh | act_import_uwh, act_export_uwh, act_net_uwh |
| Reativa | rea_import_varh, rea_export_varh; µvarh: rea_import_uvarh, rea_export_uvarh |
| Por canal | channels (número de entradas válidas); ch_import_mwh[], ch_export_mwh[], ch_import_uwh[], ch_export_uwh[] |
| Contabilidade | generation, uptime_s, group_status |
| Indicadores de proveniência | fine, fine_reactive |
Os campos µWh / µvarh estão sempre preenchidos. Quando a imagem do módulo não oferece os contadores mais finos, são escalados a partir dos mais grosseiros e fine (ativa) / fine_reactive ficam False — leia o sinalizador se precisar de saber a origem do valor.
RbAmp.std_energy_delta(prev, now) -> (delta, module_restarted)
Energia consumida entre dois snapshots de read_std_energy() (método estático; também exportado como std_energy_delta). À prova de corte de energia.
module_restartedéTruequandonow.uptime_s < prev.uptime_s.-
deltaé umRbAmpStdEnergycom o aumento por campo, ouNonequando o contadorgenerationmudou (as duas leituras não são comparáveis). -
Um contador que volta um pouco abaixo da leitura anterior (retoma após corte de energia) é limitado a 0;
neté sempre importação − exportação das partes limitadas. -
As entradas por canal só são preenchidas quando ambos os snapshots têm o mesmo número de canais.
prev = dev.read_std_energy()
time.sleep(60)
now = dev.read_std_energy()
delta, restarted = RbAmp.std_energy_delta(prev, now)
if delta is not None:
print(delta.act_import_wh, "Wh imported in this interval")
Corrente de arranque e configuração
dev.get_start_current() -> int # µA, 0 = off
dev.set_start_current(ua) -> None
dev.save_config() -> None # persist writable STD config to flash (blocking)
dev.set_time(unix_epoch) -> None # set the module's clock
-
get_start_current()— a corrente de arranque da energia em µA (0= desligado). -
set_start_current(ua)— abaixo desta corrente por canal o módulo não conta energia em importação/exportação; as leituras ao vivo (I, P, Q) não são afetadas. O valor aplica-se de imediato; chamesave_config()para o manter após um reinício. Um valor não suportado lançaRbAmpParamErrorantes de qualquer coisa ser escrita no barramento. O valor tem de ser0(desligado) ou um múltiplo de 10 µA dentro da gama suportada. -
save_config()— persiste a configuração STD gravável. Bloqueante. -
set_time(unix_epoch)— define o relógio do módulo a partir de uma época Unix; uma época anterior a 2020 lançaRbAmpParamError. Defina a hora de novo após reiniciar o módulo (read_std_health().time_validéFalseaté o relógio ser definido). -
get_start_current()/set_start_current()lançamRbAmpNotSupportedErrornuma imagem de módulo que não oferece a definição de corrente de arranque;RbAmpStdConfig.start_ua_supportedindica se oferece.
Latch banks
Um módulo STD que reporta bancos de latch mantém 8 bancos independentes. Um banco acumula enquanto o seu bit estiver ativo na máscara de armação; um latch tira o snapshot e repõe o banco na fronteira seguinte de janela de medição, pelo que um período é o intervalo entre dois latches do mesmo banco, medido pelo relógio do mestre. Estas chamadas precisam de um módulo que reporte bancos e lançam RbAmpNotSupportedError caso contrário; um número de banco fora de 0..7 lança RbAmpParamError.
dev.std_arm_banks(mask) -> None # bit i = bank i accumulates
dev.std_latch(bank) -> None # snapshot + reset; does not wait
dev.std_read_latch(bank) -> RbAmpStdLatch
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) -> (wh_import, wh_export)
-
std_arm_banks(mask)— define a máscara de armação. A máscara não se mantém após um reinício do módulo. -
std_latch(bank)— faz latch de um banco. Leia-o no mínimo 300 ms depois. -
std_read_latch(bank)— devolve o snapshot do banco. A flag valid do módulo só indica que o banco foi feito latch pelo menos uma vez; não é uma flag de frescura, por isso aguarde pelo menos uma janela (300 ms é um limite seguro) apósstd_latch(). Um banco que nunca foi feito latch levantaRbAmpStaleError. Um banco vazio que já não está armado (o módulo reiniciou) é rearmado e feito latch uma vez para iniciar um período novo, e a chamada levantaRbAmpStaleError: descarte esse período e reinicie a sua própria referência temporal. -
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF)— converte a energia do snapshot em Wh ao longo dedt_msdo relógio do mestre.ché um índice de canal, ou0xFF(predefinição) para o total do módulo. Devolve(wh_import, wh_export); a exportação é zero ou negativa. LançaRbAmpStaleErrorpara um snapshot sem amostras.
class RbAmpStdLatch:
bank: int # 0..7
valid: bool # the bank has been latched at least once
channels: int
p_avg, q_avg, s_avg: float # average P (W), Q (var), S (VA) over the period
max_p, max_i, max_u, min_u: float # peak P (W), peak I (A), peak / minimum U (V)
e_import_mws, e_export_mws: int # energy, mW·samples (export <= 0)
nsamp: int # samples in the period
win_count: int # measurement windows in the period (0 = not armed / nothing elapsed)
p_avg_ch: list # per-channel average P, W
e_import_ch_mws, e_export_ch_mws: list # per-channel energy, mW·samples
Contabilidade de período
Veja 01 · Visão geral para o panorama geral e o Passo 5 do 05 · Início rápido para um modelo mínimo.
Num módulo STD as mesmas chamadas funcionam. begin() escolhe a fonte do período a partir do que o módulo reporta:
| O módulo reporta | Fonte do período | Comando de latch |
|---|---|---|
| contadores de energia no dispositivo | diferença entre duas leituras de contador no calendário do mestre | nenhum |
| apenas bancos de latch | latch a latch no banco 0 (estabilização de pelo menos 300 ms) | CMD_LATCH_PERIOD no banco 0 |
| nenhuma | — | as chamadas de período levantam RbAmpNotSupportedError |
Na fonte de contadores o primeiro período começa em begin(), latch_period() não faz nada, is_period_valid() é True quando os contadores estão ancorados, read_period_max_power() levanta RbAmpNotSupportedError (sem pico), e read_period_avg_power(ch) só existe num módulo de canal único, depois de ter sido lido um período. Uma mudança de geração de contadores reancora o período e levanta RbAmpStaleError; um reinício do módulo dentro de um período é indicado em snap.module_restarted (a energia não é medida enquanto o módulo reinicia). Na fonte de latch, um snapshot vazio levanta RbAmpStaleError; se o banco tiver perdido a armação (reinício do módulo), é primeiro rearmado. O snapshot inclui avg_p_total, wh_net e module_restarted. read_period_latch_ms() é apenas BASIC.
dev.latch_period() -> None
04 · Medição por período e contabilidade tarifária (period-metering)
Escreve CMD_LATCH_PERIOD. Não espera — quem chama tem de aguardar a estabilização de 50 ms e verificar dev.is_period_valid() antes de ler.
Para a maioria das tarefas, use read_period_snapshot() — encapsula a sequência completa.
dev.is_period_valid() -> bool
04 · Medição por período e contabilização tarifária (period-metering) · Calibração e precisão (troubleshooting)
Lê o bit de snapshot pronto. Devolve True se o último snapshot for recente.
dev.read_period_avg_power(ch=0) -> float
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)
Potência ativa média num canal sobre o período fechado. Deve ser chamado após latch_period() + uma estabilização de 50 ms + uma verificação de validade.
Resolve cada canal do módulo (ch = 0..channels-1), incluindo os canais 3+ em módulos de 5 e 7 canais (UI5 / UI7). O snapshot de período e o acumulador de Wh cobrem também todos os canais. dev.read_period_avg_p(ch) é um alias com o mesmo comportamento.
dev.read_period_max_power() -> float
Registos de instantâneo do período (period-metering) · 4.12 V03 Q + período ch0 (0xD0..0xE3, build de produção) (api-reference)
Potência instantânea de pico no canal 0 durante o período fechado. ch=0 apenas no firmware v1.
dev.read_period_latch_ms() -> int
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)
Duração do período do ponto de vista do dispositivo, em ms.
O temporizador interno do módulo tem precisão limitada. Para a integração de energia, use master_dt_ms de RbAmpPeriodSnapshot, não este campo.
dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot
Ciclo de polling contínuo (recomendado) (period-metering) · Calibração e precisão (troubleshooting) · 4.11 Bloco de período V03 (0xBE..0xCF) (api-reference)
O ponto de entrada recomendado para a contabilização por período. A sequência completa por baixo:
-
Se
skip_latch=True— ignora a escrita do comando de snapshot (para o padrão multi-módulo após uma série manual de comandos de snapshot). -
Caso contrário — escreva
CMD_LATCH_PERIOD. - Capture
time.monotonic()para calcularmaster_dt_ms. time.sleep(settle_ms / 1000)— 50 ms por predefinição.-
Verifique a flag de snapshot pronto. Se for 0 — lance
RbAmpStaleError(o carimbo temporal anterior é mantido, pelo que o snapshot bem-sucedido seguinte cobre o intervalo completo e o Wh fica exato). -
Leia
avg_p[0..channels-1]+max_p+latch_ms. - Atualize o carimbo temporal e chame
energy.tick(snap)para integrar Wh (a não ser que o acumulador esteja desativado viaenergy.disable()).
| Parâmetro | Descrição |
|---|---|
settle_ms |
Espera após o comando de snapshot, em ms. Predefinido 50. |
skip_latch |
Se True — não envia o comando de snapshot, apenas lê. |
Lança: RbAmpStaleError (snapshot obsoleto); RbAmpIOError (falha do barramento).
async dev.stream_period(interval_s=60.0, skip_stale=True)
Um gerador assíncrono que devolve RbAmpPeriodSnapshot no intervalo interval_s. Funciona em asyncio do CPython e em uasyncio do MicroPython (MicroPython ≥ 1.20 — import asyncio também funciona; em versões anteriores use import uasyncio as asyncio).
async for snap in dev.stream_period(interval_s=60.0):
# snap is an RbAmpPeriodSnapshot, .valid guaranteed True (by default skip_stale=True)
print(snap.avg_p[0])
| Parâmetro | Descrição |
|---|---|
interval_s |
Período entre snapshots (recomendado ≥ 30 s) |
skip_stale |
True (predefinição) — os snapshots obsoletos são saltados automaticamente. False — são produzidos com snap.valid=False, e o seu código tem de verificar if not snap.valid: continue por si |
⚠ CPython: bloqueia o loop de eventos. Por dentro, stream_period() chama o read_period_snapshot() síncrono e bloqueante — que faz uma estabilização time.sleep(0.05) mais ~50–100 ms de leituras de um byte no barramento. Em CPython isto bloqueia todo o loop de eventos asyncio durante esses 100 ms — as outras corrotinas (MQTT, HTTP, keepalive do Wi-Fi) não recebem CPU. Em servidores de produção, envolva-o em run_in_executor:
import asyncio
async def stream_period_nonblocking(dev, interval_s=60.0):
loop = asyncio.get_event_loop()
while True:
await asyncio.sleep(interval_s)
snap = await loop.run_in_executor(None, dev.read_period_snapshot)
if snap.valid:
yield snap
Em MicroPython o problema é menor — o escalonador do uasyncio cede a outras tarefas com menos frequência, e o I²C bloqueante é considerado aceitável em padrões assíncronos embebidos. Se precisar de comportamento não bloqueante, use uma thread separada via _thread.start_new_thread (no ESP32 µPy).
Contabilização de energia (acumulador do lado do mestre)
dev.energy — instância de RbAmpEnergy
Algoritmo do lado do mestre (period-metering) · 7 · Semântica (api-reference)
Um acumulador de Wh por canal. Acedido através de uma propriedade — o pacote é dono da instância:
dev.energy.wh(ch=0) -> float # current Wh total for the channel
dev.energy.reset(ch=0) -> None # zero a single channel
dev.energy.reset_all() -> None # zero all channels
dev.energy.is_enabled -> bool # True while auto-integration is active (default)
dev.energy.disable() -> None # turn off auto-integration
dev.energy.enable() -> None # turn it back on
O acumulador é atualizado automaticamente em cada dev.read_period_snapshot() bem-sucedido. É com sinal — um valor negativo significa exportação líquida.
Fórmula de integração:
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
dev.energy.disable() é útil em cenários de deep-sleep em que o mestre gere ele próprio a persistência de Wh na memória RTC — ver 06 · Exemplos, Cenário 9.
Configuração do sensor
Uma sequência de dois passos. Para um guia detalhado de seleção de modelo, ver 03 · Seleção do sensor de corrente.
dev.set_sensor_class(cls) -> None
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)
Define a classe do sensor de corrente e guarda-a na flash. Bloqueante, ~705 ms.
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# or equivalently:
dev.set_sensor_class(1)
| Parâmetro | Descrição |
|---|---|
cls |
Um enum RbAmpSensorClass ou um int 0..3 |
Raises:
RbAmpParamError—clsfora de 0..3-
RbAmpModeError— o módulo está emparelhado de fábrica (classe atualWIRED_CT/BUILTIN_CT) eclsdifere; alterá-la limparia a calibração do sensor instalado -
RbAmpIOError— falha de comunicação
Tem de ser chamado antes de set_ct_model*(). Escrever a mesma classe que o módulo já tem é um no-op (sem escrita no barramento), porque uma escrita de classe apaga do lado do dispositivo os modelos TC por canal. Veja guarda de leitura-antes-de-escrita.
dev.read_sensor_class() -> int
Lê a classe de sensor fixada: 0 UNSET, 1 SCT_013, 2 WIRED_CT, 3 BUILTIN_CT (os valores de RbAmpSensorClass). Devolve 0 em firmware onde o registo não existe.
dev.set_ct_model(code) -> None
A forma de parâmetro único (legada) — define o modelo da pinça amperimétrica apenas no canal 0.
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 |
O conjunto aceite para a classe SCT_013 é {1, 2, 3, 4, 5, 6, 7}. A tabela completa de conjuntos aceites por classe está em 03 · Seleção do sensor de corrente.
Raises:
ValueError(e tambémRbAmpParamError) —codenão está no conjunto de aceitação por classe para oREG_SENSOR_CLASSatual (paraSCT_013é{1, 2, 3, 4, 5, 6, 7})-
RbAmpModeError— seset_sensor_class()não tiver sido chamado, ou o módulo estiver emparelhado de fábrica (classe 2/3) e o código for diferente (useset_ct_model_ch_force()em contexto de assistência técnica) -
RbAmpIOError— falha de comunicação
Definir o modelo que o canal já tem é um no-op (guarda de leitura-antes-de-escrita).
Mensagem de RbAmpModeError (classe não definida):
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first
Equivalente a dev.set_ct_model_ch(0, code).
dev.set_ct_model_ch(channel, code) -> None
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)
A forma por canal. Define o modelo da pinça amperimétrica num canal específico.
Por dentro: põe em fila REG_CT_MODEL (0x05) → comando CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) → estabilização de 5 ms → CMD_SAVE_USER_CONFIG (0x32) → 700 ms. Bloqueante, ~705 ms.
✅ v1.3: a ordem de ligação dos canais não importa. No v1.3, escrever REG_CT_MODEL (0x05) põe o valor em fila mas já não o aplica automaticamente ao ch0. A aplicação faz-se apenas através de CMD_SET_CT_MODEL_CHn. Pode configurar os canais em qualquer ordem.
dev.set_ct_model_ch(0, 1) # any order is OK on v1.3
dev.set_ct_model_ch(1, 3)
dev.set_ct_model_ch(2, 6)
Raises:
RbAmpParamError—channelfora de 0..dev.channels-1oucodefora do conjunto aceite por classe (paraSCT_013—{1, 2, 3, 4, 5, 6, 7})RbAmpModeError—set_sensor_class()não chamado, ou o módulo está emparelhado de fábrica e o código difere
dev.set_ct_model_ch_force(channel, code) -> None
Variante de set_ct_model_ch() para o caminho de assistência que contorna a guarda de leitura antes da escrita: escreve mesmo quando o módulo está emparelhado de fábrica ou já tem o código. Destinada a técnicos que reconfiguram o sensor de uma unidade. O módulo continua a validar o par (classe, código) e a chamada levanta RbAmpParamError para um par inválido.
Guarda de leitura antes da escrita
Escrever um modelo de CT substitui a calibração desse canal pela predefinição genérica do modelo, por isso desde a 1.6.0 os setters verificam primeiro:
| Chamada | O módulo já tem o valor | Módulo emparelhado de fábrica (classe 2/3) | Caso contrário |
|---|---|---|---|
set_sensor_class(cls) |
sem operação, sem escrita no barramento | RbAmpModeError se cls for diferente |
escritas + gravação |
set_ct_model(code) / set_ct_model_ch(ch, code) |
sem operação, sem escrita no barramento | RbAmpModeError se o código for diferente |
escritas + gravação |
set_ct_model_ch_force(ch, code) |
escritas | escritas | escritas |
Espelhos de verificação V2 — CT_MODEL_CH0/1/2 (0x51-0x53)
Registos só de leitura que refletem a predefinição de CT efetivamente aplicada em cada canal. O protocolo de escrita não muda — as escritas usam o mecanismo acima. 0x51-0x53 servem apenas de releitura para verificações de estado e padrões ler-comparar-escrever:
applied_ch0 = dev.read_ct_model_ch(0) # what is actually applied
applied_ch1 = dev.read_ct_model_ch(1)
applied_ch2 = dev.read_ct_model_ch(2)
Correção de comutação de calibre SCT-013
Os módulos SCT-013 são calibrados de fábrica com um modelo de pinça de referência. Quando um canal muda para outro modelo, uma imagem de módulo que não se reescala sozinha continua a aplicar o ganho de referência, pelo que corrente e potência seriam lidas à escala errada. Desde a 1.6.0 a biblioteca corrige isto automaticamente em módulos BASIC com classe de sensor SCT_013:
-
Corrente, potência e a energia derivada da potência (
read_current,read_current_peak,read_power,read_period_avg_power, e portanto o snapshot de período edev.energy) são corrigidas para o modelo escolhido, em relação ao ganho que o módulo efetivamente aplica. -
A tensão e o fator de potência nunca são alterados.
- No firmware do módulo até 1.4.19 uma mudança de modelo reinicia o módulo uma vez (cerca de um segundo); a partir de 1.4.20 o módulo corrige-se a si próprio. A correção de classificação do SCT escala corrente, potência e energia, nunca a tensão nem o fator de potência.
-
Os módulos cujo firmware executa isto por conta própria são detetados e deixados como estão (escala 1).
-
Módulos emparelhados de fábrica (classe 2/3) nunca são escalados.
- A correção é avaliada em
begin()e de novo após um reinício que a biblioteca provoca (reset()) ou um reinício detetado. Numa situação (um modelo escrito durante o ciclo de alimentação atual) a biblioteca pode emitir um reset do módulo para ler o ganho guardado.
dev.set_rating_correction(enabled: bool) -> None # default enabled
dev.rating_correction_enabled -> bool
dev.ct_rating_scale(ch=0) -> float # scale currently applied (1.0 = none)
dev.ct_rating_status(ch=0) -> (action, detail) | None
dev.refresh_rating_correction() -> None
-
set_rating_correction(enabled)— desliga a correção para ler os valores brutos, não corrigidos (ou num módulo cujo firmware já corrige). Recalcula de imediato. -
ct_rating_scale(ch)— a escala aplicada à corrente, potência e energia de um canal;1.0quando não há correção ativa. -
ct_rating_status(ch)—(action, detail)da última avaliação de um canal, ouNonese o canal nunca foi avaliado (por exemplo, não é um canal SCT).actioné um de"unity","ok","needs_reset","warn_uncal","warn_gain";detailé texto. As açõeswarn_*significam que a biblioteca não conseguiu determinar uma escala segura e deixou a leitura sem correção. -
refresh_rating_correction()— reavaliar após um reinício que a biblioteca não conduziu (por exemplo, um modelo guardado e o módulo reposto externamente).
Esta é uma funcionalidade do caminho SCT-013 em todas as bibliotecas rbAmp, não específica de Python.
dev.save_gains() -> None
Uma escrita "nua" de CMD_SAVE_GAINS (0x26) — apenas de fábrica.
⛔ BLOQUEADO no firmware de produção (a v1.3 devolve DEV_ERR_PARAM; o dispositivo rejeita a escrita e um reboot posterior reverte qualquer alteração em RAM). CMD_SAVE_GAINS está reservado ao modo de provisionamento de fábrica e persiste apenas ganhos / NF / coeficientes de fase. Para persistência destinada ao utilizador de sensor_class / ct_model por canal / endereço / etiqueta, use dev.save_user_config() (ou as chamadas por canal set_ct_model_ch() / set_sensor_class(), que já emitem CMD_SAVE_USER_CONFIG (0x32) internamente).
Lança: RbAmpModeError se o módulo não estiver em modo de provisionamento de fábrica, RbAmpIOError numa falha de comunicação.
dev.prepare_address_change(new_addr) -> None
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)
Passo 1 de 2 para mudar o endereço I²C do módulo. Adequado para produção no firmware atual (commit em duas fases do v1.3).
Cenário: validação de intervalo → escrever o candidato em REG_I2C_ADDRESS (0x30) em RAM → escrever o magic 0xA5 em REG_ADDR_COMMIT_MAGIC (0x31) — armado. O chamador tem de chamar commit_address_change() em 5 segundos, caso contrário a armação fica obsoleta.
Raises:
-
RbAmpParamError—new_addrfora de 0x08..0x77 ou igual ao endereço atual -
RbAmpIOError— falha de comunicação
dev.commit_address_change() -> None
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)
Passo 2 de 2. Tem de ser chamado até 5 segundos após prepare_address_change().
Cenário: verificar a frescura da armação mágica → CMD_COMMIT_ADDR (opcode 0x30) → persistir na flash → CMD_RESET → cerca de 300 ms de arranque até responder → atualizar o campo interno de endereço. Após o reboot, REG_I2C_ADDRESS (0x30) (v1.3) devolve o novo endereço ativo — esta é a verificação canónica.
⚠ Histórico: antes das correções da v1.3, a alteração de endereço estava incorretamente documentada como exclusiva de fábrica. Na v1.3 é uma operação de produção através de commit em duas fases.
Uma nuance adicional:
⚠ Reinício e re-enumeração após o commit. Após um commit bem-sucedido, o dispositivo reinicia e re-enumera-se no NOVO endereço. As chamadas seguintes neste handle usam o novo endereço de forma transparente — mas qualquer OUTRO mestre no barramento (outro script Python, um componente ESP-IDF, uma sonda de depuração) continua a pensar que o dispositivo está no endereço antigo até o seu estado interno ser atualizado manualmente.
Raises:
RbAmpTimeoutError— a janela de armação (5 s) expirouRbAmpIOError— falha de comunicação
dev.factory_reset() -> None
O comando CMD_FACTORY_RESET + uma espera de 1500 ms.
⚠ Operação destrutiva. Apaga TODOS os parâmetros da flash (modelo de CT, classe de sensor, coeficientes de calibração, endereço I²C). O módulo volta às predefinições de fábrica — RbAmpSensorClass passa a UNSET, REG_CT_MODEL passa a 0. Qualquer configuração aplicada antes via set_sensor_class() / set_ct_model*() desaparece. O próximo utilizador TEM de reaplicar set_sensor_class() e set_ct_model*() antes de a contabilização voltar a funcionar. Não é um "soft restart" — para um soft restart use reset(). factory_reset() está reservado para recuperar de um estado conhecido como defeituoso ou para passar o módulo a outro utilizador / outra instalação.
Lança: RbAmpIOError numa falha de comunicação.
dev.reset() -> None
O comando CMD_RESET + uma espera de 100 ms. Um reinício suave do dispositivo sem perder os parâmetros da flash.
Lança: RbAmpIOError numa falha de comunicação.
Identificação e provisionamento (v1.3)
Estes métodos permitem ao mestre perceber exatamente o que está ligado ao barramento (variante, mapa de bits de capacidades, UID, rótulo) e preparar um módulo novo ou recém-gravado para funcionar (provisionamento
- guardar a configuração na flash).
dev.read_variant() -> int
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)
Lê o registo HW_VARIANT (0x55) do módulo (o byte canónico de SKU do v1.3):
| Código | SKU | Canais I | Canal U |
|---|---|---|---|
1 |
UI1 | 1 | sim |
4 |
I1 | 1 | não |
5 |
I2 | 2 | não |
6 |
I3 | 3 | não |
Este é o caminho recomendado para a autodeteção — o caminho de sondagem por NACK foi removido (o firmware nunca faz NACK em leituras; endereços não mapeados → 0x00).
dev.read_capability() -> int
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)
Lê o mapa de funcionalidades de 16 bits dos registos CAPABILITY (0x57/0x58), u16 little-endian. O mapa inclui um flag de front-end de tensão. Use-o para deteção de funcionalidades (não heurísticas de versão).
dev.has_voltage() -> bool
Um auxiliar de conveniência sobre read_capability() — devolve True se o módulo tiver um canal U. Guardado em cache no handle na primeira chamada.
dev.read_product_id() -> int
3.5 PRODUCT_ID (0x54, u8, só leitura) (api-reference) · 4.8 Identidade (0x54..0x6F) (api-reference)
Lê PRODUCT_ID (0x54) — o byte identificador da família (rbAmp = 0x01). Usado pelo scanner da frota para confirmar que o dispositivo num endereço é de facto um rbAmp.
dev.read_uid() -> bytes
Lê o identificador único de 96 bits do MCU a partir de UID (0x5C..0x67) numa única operação em rajada (devolve um objeto bytes de comprimento 12). O UID é garantidamente único em cada módulo e não muda entre reflashes.
dev.read_label() -> str
Lê o rótulo de utilizador de 8 bytes a partir de LABEL (0x68..0x6F). ASCII, preenchido com zeros; devolve uma string (sem NUL). Uma string vazia se não houver rótulo definido.
dev.set_label(label: str) -> None
Escreve uma etiqueta de 8 bytes. A string é truncada a 8 bytes ou preenchida com zeros. A escrita é byte a byte (o rbAmp não faz auto-incremento nas escritas; o pacote faz o ciclo de bytes automaticamente). Após a escrita é necessário um dev.save_user_config() para que a etiqueta sobreviva a um reset.
Lança: RbAmpIOError numa falha de comunicação.
dev.is_provisioned() -> bool
Verifica se o módulo passou pelo aprovisionamento inicial. Verifica REG_ERROR != 0xFB (DEV_ERR_FLASH_PARAMS_BAD) — 0xFB é definido pelo firmware quando o bloco de configuração do utilizador está vazio / corrompido. Um módulo novo de fábrica devolve False — é necessário um save_user_config() após a primeira configuração de modelo de CT e de endereço.
No v1.3 este código é normal para um módulo virgem (não é fatal). Não aborte o provisionamento na primeira vez que vir 0xFB.
dev.save_user_config() -> None
6.5 Provisionamento — firmware novo + SAVE (api-reference) · 8.6 Provisionamento de firmware novo (api-reference)
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.
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.
Levanta: RbAmpIOError / RbAmpTimeoutError.
: confirmar que um valor foi escrito na flash exige um reboot + releitura. Ver a secção "Modelo de erros v1.3" abaixo.
Modelo de erros v1.3 — dois canais independentes
Os erros têm dois canais independentes que funcionam de formas diferentes. Perceber a diferença é crítico 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 pacote (_validate_ct_code etc.) |
REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Quando dispara | Antes da transação I²C (a biblioteca intercepta) | Após o FW aceitar uma escrita e a rejeitar |
| O que vê o master | O setter lança RbAmpParamError; REG_ERROR no dispositivo mantém-se 0x00 |
REG_ERROR = o código de rejeição de imediato; bit3 fica ativo algumas centenas de milissegundos depois da transação |
| Persistente | não (apenas uma exceção) | última escrita de REG_ERROR; bit3 pegajoso W1C |
| Caminho típico | Um argumento fora dos limites permitidos (channel ∉ {0,1,2}, code ∉ conjunto caracterizado, sensor_class fora do enum) | Uma escrita de registo em bruto que o pacote não pré-valida (dev._io.write_reg() de baixo nível com um byte inválido) |
Canal A — validação no cliente (setters do pacote)
Todos os setters do pacote (set_sensor_class, set_ct_model, set_ct_model_ch, configure_channels, etc.) verificam primeiro os argumentos contra os valores permitidos. Se um argumento estiver fora do intervalo, o setter levanta RbAmpParamError, sem fazer qualquer transação I²C. Assim, REG_ERROR no dispositivo fica intacto:
from rbamp import RbAmp, RbAmpParamError
try:
dev.set_ct_model_ch(99, 3) # invalid channel
except RbAmpParamError as e:
print(f"client-side guard: {e}")
reg_err = dev.read_last_error()
print(f"REG_ERROR on the device: 0x{reg_err:02X}")
# → 0x00 (the package stopped it before the wire, REG_ERROR untouched)
Isto significa que: se quiser saber exatamente porque um setter falhou, a fonte fiável é a própria exceção (RbAmpParamError.args / str(e)). O REG_ERROR do dispositivo não lhe diz nada neste cenário.
Canal B — rejeição do lado do DUT (assíncrono durável)
Se uma escrita passou pelo I²C (a biblioteca não a intercetou porque o argumento parecia válido) mas o firmware a rejeitou, entra o segundo canal:
-
read_last_error()devolve de imediato o código de causa (por exemplo,0xFE = DEV_ERR_PARAM). É o resultado da última escrita: qualquer escrita bem-sucedida seguinte sobrescreve-o. Tem de o ler imediatamente após a escrita, antes de qualquer outra transação. -
has_error()— o indicador pegajoso W1C deEVENT_FLAGS.bit3. Não ativa de imediato: na bancada, mediu-se um atraso de algumas centenas de milissegundos entre a transação rejeitada e a ativação do bit3.
⚠ Não use has_error() para validar uma escrita que acabou de fazer. Para o resultado dessa escrita específica, só read_last_error() é fiável, lido imediatamente após a escrita e antes de qualquer outra transação (mais a exceção do setter). has_error() é o canal assíncrono para monitorização por polling de "algo falhou entre duas verificações", não para validação síncrona.
Limpar um erro durável — limpe ambos (REG_ERROR e bit3)
bit3 é recalculado pelo firmware a cada poucas centenas de milissegundos a partir do estado atual de REG_ERROR. Logo, 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. A ordem correta:
dev.clear_error() # zero REG_ERROR
dev.clear_event_flags(1 << 3) # reset sticky bit3
Se quiser atomicidade, não pode haver nenhuma escrita rejeitada entre elas.
dev.read_last_error() -> int
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)
Lê o registo REG_ERROR (0x02) do dispositivo diretamente (uma leitura de fio) — o resultado da última transação aceite com sucesso no barramento (uma escrita ou um comando). Não é pegajoso: qualquer escrita bem-sucedida seguinte sobrescreve-o com o seu próprio resultado. Usado no Canal B (rejeição do lado do DUT) para o código de causa estendido.
dev.has_error() -> bool
Um auxiliar sobre EVENT_FLAGS.bit3 (ERROR_OCCURRED). Devolve True se o bit3 estiver ativo. W1C pegajoso; não é limpo até uma limpeza explícita (com uma ressalva — veja a secção "Limpar um erro durável" acima).
dev.read_event_flags() -> int / dev.clear_event_flags(mask: int) -> None
4.4 Configuração da frota (0x27..0x2F) (api-reference) · 8.8 Fluxo de eventos de limiar — escrever limiar → disparo → limpeza W1C (api-reference)
EVENT_FLAGS (0x2A) é um byte de flags pegajosas; os bits específicos estão descritos na especificação (incluindo ERROR_OCCURRED bit3). A limpeza é escrever-1-para-limpar.
dev.clear_error() -> None
Códigos de erro (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperação do estado de erro — árvore de decisão (api-reference)
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).
Configuração multicanal (v1.3)
Em módulos multicanal (I2, I3), cada canal de corrente tem o seu próprio modelo de sensor TC. A utilidade atómica para configuração em bloco é configure_channels().
dev.configure_channels(cls: RbAmpSensorClass, models: Sequence[int], n: int = None) -> None
Parameters:
-
cls— a classe do sensor (RbAmpSensorClass.SCT_013para as pinças amperimétricas SCT-013;WIRED_CT/BUILTIN_CTreservadas). -
models— uma sequência de códigos de modelo de CT (um por canal). n— o comprimento (opcional; predefinido =len(models)).
Internamente, a função executa:
set_sensor_class(cls)uma vez.-
Para cada canal: preparar
REG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. -
Um
CMD_SAVE_USER_CONFIGterminal no fim — ou seja, um ciclo de apagar + escrever na flash para toda a configuração.
Limitado pela variante: se len(models) for maior do que o número de canais da variante, os elementos extra são ignorados.
Raises:
-
RbAmpParamError—clsoumodels[k]inválido (validação do lado cliente por classe;REG_ERRORno dispositivo mantém-se em0x00). -
RbAmpIOError— erro de barramento. RbAmpTimeoutError— timeout de escrita na flash.
Códigos aceites por classe: SCT_013 → {1, 2, 3, 4, 5, 6, 7}; um código fora do conjunto lança RbAmpParamError antes de qualquer acesso ao barramento. Veja 03 · Seleção do sensor.
dev.read_ct_model_ch(ch: int) -> int
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)
Lê o modelo de sensor TC aplicado (espelho de verificação) num canal específico, a partir do registo 0x51 (ch0) / 0x52 (ch1) / 0x53 (ch2). Isto é uma leitura da RAM, não uma confirmação de persistência — para confirmar a gravação na flash, use dev.reset() + uma releitura do espelho.
RbAmpFleet — gestão de vários módulos
A classe RbAmpFleet é a principal superfície de alto nível do pacote v1.3. Gere uma coleção de módulos num barramento I²C partilhado: descoberta, aprovisionamento, agregação de polls, agregação de erros, snapshots síncronos através de um broadcast General-Call.
Uma frota fica ligada a um só barramento (normalmente SMBus(1) em CPython ou I2C(0, ...) em MicroPython). O limite flexível do número de módulos é RBAMP_FLEET_MAX_MODULES = 16.
Ciclo de vida
RbAmpFleet(bus, max_modules: int = 16)
Após del fleet, todos os handles adotados são libertados.
Descoberta — 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)
fleet.scan(match_product: bool = True) -> int
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 uma correspondência com o PRODUCT_ID do rbAmp. -
Executa o detetor de conflitos. Os endereços suspeitos vão para a lista
excluded, não para a frota.
Devolve o número de módulos adicionados à frota.
Lança: RbAmpIOError se o barramento estiver bloqueado (canário de bloqueio de Tier-2).
Acesso ao módulo
fleet.count # property: number of modules in the fleet
len(fleet) # equivalent to fleet.count
fleet[index] # a module by index
fleet.find(address) -> RbAmp | None # a module by address
fleet.add(dev: RbAmp) -> None # adopt an existing handle
for dev in fleet: # iteration
...
fleet.excluded -> tuple[int] # addresses that ended up in excluded
Polling — poll_all()
Configuração de vários módulos (initialization) · Consulta de vários módulos — três estratégias (realtime-polling)
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]
Consulta todos os módulos da frota numa única chamada. Devolve uma lista de tuplos; para cada módulo:
- um
RbAmpSnapshotouNone(em caso de falha) - um POD
RbAmpFleetPollcom os camposaddr,ok,channels
Resistente a falhas: um módulo silencioso não cancela o polling dos restantes.
Agregação
fleet.total_power() -> float # W; summed over all channels
fleet.total_energy_wh() -> float # W·h; per-handle accumulators
fleet.poll_errors() -> dict[int, bool] # per-addr bit3 status
total_power soma a potência ativa de todos os canais de todos os módulos. Nas variantes I não há potência ativa → contribuem com 0. No cânone, 80% do resultado ≈ a potência ativa do módulo da rede.
fleet.aligned_snapshot(group=0) -> list[dict]
Snapshot de período coerente em toda a frota, em todos os canais de cada membro: faz broadcast de um snapshot General-Call e depois lê o snapshot de potência média de cada membro sincronizado, para cada canal (read_period_avg_p). Devolve um dict por membro, pela ordem da frota, com as chaves addr, in_sync, period_valid, avg_p (lista, uma entrada por canal; None se o membro perdeu o tick ou não respondeu). O snapshot alinha apenas as médias do período — as leituras ao vivo (I, P, PF) não podem ser alinhadas entre canais.
Endereçamento e verificação de conflitos
fleet.assign_address(dev: RbAmp, new_addr: int) -> None
fleet.check_conflict(addr: int) -> bool # collision detected?
assign_address reatribui a um módulo existente da frota um novo endereço: internamente — commit em duas fases + reset; o handle na frota é atualizado automaticamente.
check_conflict é uma verificação de melhor esforço, só de leitura, para um endereço específico. Para percorrer todos os conhecidos, itere sobre a frota.
Provisionamento
6.5 Provisionamento — firmware novo + SAVE (api-reference)
⚠ Na build atual do rbamp, o provisionamento faz-se através de dev.prepare_address_change() + dev.commit_address_change() num handle RbAmp(bus, 0x50) criado manualmente, depois fleet.add(dev). Veja o excerto em 06 · Exemplos, Cenário 2.
OBRIGATÓRIO: exatamente um módulo virgem no barramento no momento do provisionamento. Dois módulos em 0x50 ao mesmo tempo são fisicamente indistinguíveis por I²C — não se distinguem nem com hardware especial.
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)
fleet.enable_gc_all(group: int = 0) -> int
fleet.gc_latch(group: int = 0, tick: int | None = None,
settle_ms: int = 50) -> int
fleet.check_sync(expected_tick: int) -> list[RbAmpFleetSync]
Para uma sincronização apertada de snapshots (desvio < 1 ms em toda a frota), usa-se um snapshot de difusão I²C General-Call.
-
enable_gc_all(group)define a flagGC_ENABLEde FLEET_CONFIG +GROUP_IDem todos os módulos da frota e emiteCMD_SAVE_USER_CONFIGem cada um (persistente). É obrigatório um reboot dos módulos após a ativação — feito automaticamente. Devolve o número de módulos em que a ativação teve sucesso. -
gc_latch(group, tick, settle_ms)envia a trama GCA5 27 group tick_lo tick_hipara o endereço0x00. Setick=None, o tick é incrementado automaticamente por um contador interno. Devolve o tick do broadcast. -
check_sync(expected_tick)lêGC_TICK (0x59)em cada módulo. Devolve uma lista de PODRbAmpFleetSynccom os campos:
class RbAmpFleetSync:
addr: int # I²C address of the module
gc_tick: int # REG_GC_TICK; 0xFFFF = never received a GC
in_sync: bool # True if gc_tick == expected_tick
reachable: bool # False if the read NACKs / times out
Configuração de frota por dispositivo (v1.3)
Estes métodos funcionam diretamente com um único módulo (sem frota).
dev.enable_gc(enable: bool = True) -> None
General Call (difusão no endereço 0x00) (initialization) · 4.4 Configuração da frota (0x27..0x2F) (api-reference)
enable_gc(True) escreve 1 na flag GC_ENABLE de FLEET_CONFIG (0x27), guarda na flash e faz reset — o módulo passa a aceitar snapshots GC após o arranque. enable_gc(False) limpa o bit de forma simétrica. Bloqueia durante cerca de 1 segundo (estabilização do SAVE_USER_CONFIG + estabilização do reset). Idempotente: não faz nada se o estado atual já corresponder ao pedido.
dev.read_fleet_config() -> int
Lê o byte FLEET_CONFIG (0x27). Útil para confirmação por releitura.
dev.set_group_id(group: int) -> None / dev.read_group_id() -> int
GROUP_ID (0x28) é um filtro de tramas GC: o módulo só reage a tramas GC com um group_id correspondente. Predefinição = 0x00 (broadcast).
dev.read_gc_tick() -> int
Lê GC_TICK (0x59) — o último valor de tick recebido de uma trama GC. 0xFFFF = o módulo nunca recebeu uma trama GC desde o arranque.
RbAmp.broadcast_latch_group(bus, group: int = 0, tick: int = 0) -> bool
Um método estático. Envio de baixo nível da trama GC A5 27 group tick_lo tick_hi diretamente sobre bus (sem frota). Útil se a frota ainda não tiver sido criada, ou se quiser controlo manual do contador de ticks.
RbAmp.broadcast_latch(bus) -> bool
Um método estático. Um invólucro legado — equivalente a broadcast_latch_group(bus, group=0, tick=0). Para desenvolvimento novo, prefere-se a forma explícita broadcast_latch_group com o seu próprio tick para verificação de testemunho.
: a capacidade de snapshot General-Call (CAP_GC_LATCH, reportada por REG_CAPABILITY) tem de estar no firmware e o GC tem de estar ativado em cada módulo (dev.enable_gc(True) ou fleet.enable_gc_all() altera a flag GC_ENABLE de FLEET_CONFIG, predefinida OFF). Um módulo novo com predefinições de fábrica não aceita GC — por desenho, é uma proteção contra broadcast acidental num barramento de arranque. Se o GC estiver desativado em toda a frota, o barramento rejeita a trama GC ao nível de NACK; isto é detetável, não uma perda silenciosa. Num módulo legado sem CAP_GC_LATCH, o wrapper recorre a um snapshot sequencial por dispositivo.
Diagnóstico
dev.set_logger(log_callable) -> None
Um destino opcional de diagnóstico. log_callable recebe um único argumento str. Se definido, o pacote regista brevemente os resultados de probe(), snapshots obsoletos e rejeições de modo.
Utilização típica:
import logging
log = logging.getLogger("rbamp")
log.setLevel(logging.INFO)
log.addHandler(logging.StreamHandler())
dev.set_logger(log.info)
# Or, simplest of all — a plain print:
dev.set_logger(print)
dev.sanity_reject_count: int
Um contador de valores float rejeitados pelo filtro de sanidade (!isfinite(x) or |x| > 10000). Em regime estável — 0. Um valor diferente de zero após a mitigação por retry costuma indicar um artefacto raro da pilha I²C que sobreviveu à camada de retry.
Contadores de diagnóstico do MachineI2CBackend (apenas MicroPython)
MachineI2CBackend (o backend interno em MicroPython) expõe dois contadores:
-
backend.retry_exhaustion_count— quantas vezes o ciclo de retry se esgotou sem sucesso (foi levantado umRbAmpIOError) -
backend.retry_count_total— quantas vezes o ciclo de retry recuperou com sucesso através de um retry silencioso
Estes contadores são acedidos através da API avançada:
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp
backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50) # the address is a parameter of RbAmp, not the backend
# ...soak-test for an hour...
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:", dev.sanity_reject_count)
SMBusBackend (CPython) não tem camada de retry — o driver I²C do kernel Linux não está sujeito ao padrão de NACK.
dev.read_seq_digest() -> int
Lê o byte da sequência de digest (0..255). Muda sempre que o módulo confirma um novo conjunto de leituras, pelo que duas leituras com o mesmo valor vêm do mesmo commit — útil como verificação de coerência em torno de polling em bloco. É apenas um marcador de alteração (sem checksum).
dev.reset_counters() -> None
Põe a zero todos os contadores (RbAmp + o backend, se for um MachineI2CBackend). Use-o no início de um teste de resistência.
Metadados e constantes de protocolo
rbamp.__version__ # "1.6.0" — PEP 440 version
rbamp.__protocol_version__ # 0x04 — RBAMP_PROTOCOL_VERSION (v1.3)
rbamp.RBAMP_REG_SCHEMA_CRC32 # CRC32 of the schema codegen contract
REGISTERS e COMMANDS são dicionários auto-gerados ao nível do protocolo:
from rbamp import REGISTERS, COMMANDS
REGISTERS["U_RMS"] # 0x86
REGISTERS["PERIOD_VALID"] # 0x07
COMMANDS["LATCH_PERIOD"] # 0x27
COMMANDS["SAVE_USER_CONFIG"] # 0x32 — user-facing persistence path
COMMANDS["SAVE_GAINS"] # 0x26 — factory-only; BLOCKED in production
COMMANDS["FACTORY_RESET"] # 0xAA
Usado dentro do pacote. Exposto para utilizadores avançados que fazem passagem direta através do seu próprio backend; os utilizadores comuns não lhe tocam.
Detalhes do protocolo de transmissão
Para portar ou depurar com um analisador lógico.
Leituras de registos — auto-incremento
Uma leitura em rajada devolve N bytes consecutivos a começar em addr. Em CPython, via bus.read_i2c_block_data(addr, start_reg, N) — uma única transação.
Escritas de registos — byte a byte (SEM incremento automático)
⚠ As escritas NÃO fazem auto-incremento. Uma ESCRITA em rajada grava apenas o primeiro byte.
Um registo de vários bytes é escrito byte a byte:
# WRONG — data loss
label = b"MyMeter1"
bus.write_i2c_block_data(0x50, 0x68, list(label)) # only 'M' lands
# CORRECT — byte-at-a-time loop
for i, byte in enumerate(label):
bus.write_byte_data(0x50, 0x68 + i, byte)
Afeta o multi-byte gravável: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, bloqueado de fábrica), NF (u16), THRESH (u16). As leituras — rajada OK.
Exceção: a trama de General Call (5 bytes para o endereço 0x00) é um caminho de protocolo de fios separado (receção de general-call), enviada como uma única transação I²C.
Deteção da variante
O byte de SKU autoritativo é REG_HW_VARIANT (0x55) (dev.hw_variant):
| valor | SKU |
|---|---|
0x01 |
UI1 |
0x02 |
UI2 |
0x03 |
UI3 |
0x04 |
I1 |
0x05 |
I2 |
0x06 |
I3 |
Snapshot de difusão General-Call
Opt-in por módulo através da flag GC_ENABLE de REG_FLEET_CONFIG. Por omissão OFF. Ativada através de CMD_SAVE_USER_CONFIG + CMD_RESET. Após o reset, o módulo fica à escuta da trama de broadcast no endereço 0x00:
addr=0x00 | A5 27
A5— mágico;27— o opcodeCMD_LATCH_PERIOD.—0x00= chamada geral a todos, caso contrário tem de corresponder aREG_GROUP_ID (0x28).— um contador de período de 16 bits.
Deteção de modos de falha (2 níveis, confirmado em hardware C.10):
- NACK do endereço GC: se o GC estiver desativado em toda a frota,
bus.write_i2c_block_data(0x00, ...)lançaOSError(ou o equivalente do backend). Este é um erro duro, não uma perda silenciosa. - Testemunha por módulo: se não tiver ocorrido NACK, leia
REG_PERIOD_VALID (0x07)em cada módulo.1= snapshot bem-sucedido;0= GC desativado nesse módulo ou o período está vazio.
Modelo de erros (v1.3)
REG_ERROR (0x02)— resultado da última escrita, NÃO pegajoso. Leia-o LOGO A SEGUIR à operação.EVENT_FLAGS (0x2A) bit3— sinal durável (W1C pegajoso). Deteção canónica de erros via bit3.
# Canonical durable monitoring
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
last_err = dev.read_reg(0x02)
# handle it
dev.write_reg(0x2A, (1 << 3)) # W1C clear
Referências
- 05 · Início rápido — o seu primeiro script a funcionar
- 06 · Exemplos — cenários funcionais
-
10 · Resolução de problemas — descodificar erros e corrigir problemas comuns
-
Fonte:
__init__.py,_rbamp_core.py,_snapshot.py,_energy.py,_io_micropython.py,_io_smbus.py
Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/09_api_reference.md (v1.6.1)