Integración con el host
Cómo ejecutar un módulo STD desde su propio código — con nuestras bibliotecas o solo con un maestro I²C/Modbus.
Con las bibliotecas de rbAmp
Una biblioteca cliente por plataforma cubre toda la línea; el número de canales y las funciones se descubren en tiempo de ejecución:
- Arduino (rbamp-arduino) — soporte STD: descubrimiento, tiempo real, configuración, eventos/DRDY, OTA, historial, energía de resolución micro, corriente de arranque, ángulo de fase y secuencia. En un módulo con bancos de instantáneas y contadores de energía, use v1.6.2 o posterior (las versiones anteriores toman el período del banco 0 en lugar de los contadores; origen de energía y versión mínima).
- ESP-IDF (rbamp-esp-idf) — componente con soporte STD, incluida la energía de resolución micro y la corriente de arranque. En un módulo con bancos de instantáneas y contadores de energía, use v1.7.3 o posterior (las versiones anteriores toman el período del banco 0 en lugar de los contadores; versión mínima).
- ESPHome / Home Assistant (rbamp-esphome): componente externo con contadores de energía en el dispositivo, corriente de arranque y diagnóstico de fase. Use la v1.9.0 o posterior; bancos de instantáneas (
period_banks:) desde la v1.9.1. - Python (rbamp-python): compatibilidad con STD; una sola clase cliente, y la línea del módulo se detecta al conectar. Use la v1.6.0 o posterior; las llamadas a bancos de instantáneas desde la v1.6.1. Validado en Python estándar de Linux (smbus2).
Las bibliotecas cubren estos flujos (control de descubrimiento, sondeo de ocupado y error, actualización OTA con imágenes preparadas, contabilidad de diferencias de energía), así que prefiéralas siempre que la plataforma lo permita.
Resumen de las funciones de energía de microresolución y de corriente de arranque: cada llamada se degrada con elegancia en los módulos que no publican la función (sin tráfico de bus, o con valores derivados de los contadores gruesos):
| Característica | Arduino | ESP-IDF | ESPHome (YAML) | Python |
|---|---|---|---|---|
Energía de microresolución (los campos µWh / µvarh siempre son utilizables; una marca fine indica si son contadores propios del módulo) |
stdReadEnergy() → campos *_uwh / *_uvarh de RbAmpStdEnergy, stdEnergyDelta() |
campos *_uwh / *_uvarh de rbamp_std_energy_t, rbamp_std_energy_delta() |
energy_total · energy_exported_total · energy_net · reactive_energy / reactive_energy_exported |
read_std_energy() → campos *_uwh / *_uvarh de RbAmpStdEnergy, RbAmp.std_energy_delta() |
| Corriente de arranque para energía | stdSetEnergyStartCurrent() / stdReadEnergyStartCurrent() |
rbamp_std_set_start_current() / rbamp_std_get_start_current() |
start_current_ua: |
set_start_current() / get_start_current() |
| Ángulo de fase de tensión | 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 |
| Secuencia de fases | stdReadPhaseSequence() |
rbamp_std_read_phase_seq() |
phase_sequence |
read_phase_sequence() |
Si su aplicación persiste una instantánea de energía de la biblioteca (NVS, EEPROM, archivo), guarde en su propio formato fijo los campos individuales que necesite, no la estructura como blob en bruto — las estructuras de instantánea ganan campos entre versiones de la biblioteca.
Sin nuestras bibliotecas
Todo lo que hacen las bibliotecas es E/S de registros simple. El protocolo está documentado y es estable; los cambios de mapa se versionan (VERSION) y se controlan por características (CAPABILITIES). Los flujos canónicos paso a paso (inicialización, comandos, configuración, cambio de dirección, energía, historial, OTA, desbloqueo) están en Secuencias; a continuación figuran los patrones de trabajo más breves.
Puesta en marcha mínima de I²C (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
Patrón de contabilidad de energía
# 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
Lea el bloque de energía en una transacción de ≤ 128 bytes — los campos i64 leídos en transacciones separadas pueden desfasarse entre dos publicaciones (transporte I²C).
Nunca integre la potencia en el tiempo en el host: los contadores del módulo compensan los huecos y se persisten; su integral no es ninguna de las dos cosas. Detalles: Medición y energía.
Lectura de los registros horarios
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
Los registros contienen el Wh de vida absoluto al final del periodo, más la energía de periodo por fase (estructura).
Consulta de salud
Consulte la lista de comprobación de diagnóstico: seis lecturas cubren la disponibilidad, la salud del almacenamiento, los reinicios y las generaciones de contadores.
Integración Modbus sin bibliotecas
-
Perfil float32: los puntos que publica el módulo (V/I/P por fase, P total, frecuencia, kWh importados/exportados) en las direcciones de entrada float32 (lista). Las demás direcciones del perfil leen 0.
-
Perfil nativo: FC04 lee en 0x6000 (descubrimiento), 0x6100/0x6200 (canales), 0x6B00+ (energía), 0x6C00 (totales); la configuración y los comandos van por FC16 en 0x8000+, con UNLOCK para los comandos que cambian el estado. Mapa completo: mapa de registros; reglas: Transporte Modbus.
-
Los maestros que solo usan FC03 leen los datos nativos por el espejo 0xA000+ (entrada + 0x4000).
Reglas de integración que conviene repetir
- Controle los canales según
N_VOLTAGE/N_CURRENT, las funciones segúnCAPABILITIES, y la disposición del mapa segúnVERSION. - Identifique los módulos por UID, no por su dirección en el bus.
- Vuelva a armar el estado en RAM (máscara de eventos, umbrales, reloj) tras cualquier reinicio detectado del módulo.
- Tolere NACK y estiramiento de reloj durante los comandos que tocan la flash; respete los tiempos de estabilización.
- Energía: deltas de contadores con gestión de generación y reinicio; nunca P·dt en el host.
- Actualizaciones de firmware: envíe el archivo de versión preparado tal cual; compruebe antes
BOARD_ID.