rbAmp
ES
Tienda

Proyecto · · 13 min de lectura

Disparar un relé por sobrecorriente desde una Raspberry Pi: control de carga local en Python

Lea la corriente de un circuito en una Raspberry Pi y conmute un relé GPIO cuando supere su límite: en local, en Python, sin Home Assistant, sin nube. Histéresis y antirrebote de arranque integrados.

Seguridad

⚠️ Lea esto primero: qué es y qué no es. Esto es una capa de comodidad y conveniencia, no un dispositivo de protección. Su interruptor automático sigue siendo el dispositivo de seguridad: nunca dimensione un circuito o una carga suponiendo que esta automatización actuará. Y el relé que conmuta debe estar dimensionado para la carga: un relé pequeño no puede cortar directamente 30–50 A. Para un circuito de alta corriente, use el relé GPIO para accionar un contactor de potencia adecuado. Para trabajar dentro de un cuadro eléctrico, llame a un electricista cualificado.

Lo que va a construir

  • Un módulo rbAmp que mide la corriente de un circuito en la Pi.
  • Un relé GPIO que dispara cuando la corriente se mantiene por encima de LIMIT_ON A y se libera por debajo de LIMIT_OFF (histéresis).
  • Antirrebote de arranque para que la punta de arranque de un motor o un hervidor no provoque un disparo molesto.
  • Alerta opcional con LED/zumbador. Todo local, en Python.

Lista de materiales

Elemento Cant. Notas
rbAmp BASIC SCT-I1 1 la I1 de solo corriente es la opción ligera; un UI1 también sirve · producto
CT SCT-013 1 calibre según el circuito · producto
Raspberry Pi 1 cualquier modelo con el cabezal de 40 pines
Módulo de relé 1 aislado, dimensionado para la carga, o accionando un contactor para alta corriente
LED / zumbador (opcional) 1 alerta local

Conéctelo

El módulo rbAmp va a los pines I²C de la Pi (SDA GPIO2 / SCL GPIO3, VCC 5 V; ¿por qué 5 V con un bus de 3.3 V?). La entrada de control del módulo de relé va a GPIO26 (BCM); ajuste RELAY_ACTIVE_HIGH en la configuración según su placa (muchas placas optoaisladas son activas en BAJO). Una alerta LED/zumbador opcional va a GPIO16. Conecte la carga por el contacto NO del relé, de modo que un relé desenergizado = carga APAGADA. Las pinzas CT se colocan alrededor del conductor del circuito: no invasivas en el lado de corriente.

La lógica: umbral, histéresis, antirrebote

Las mismas tres ideas que en la versión con microcontrolador:

  • Histéresis: dispare en LIMIT_ON, pero libere solo por debajo de un LIMIT_OFF inferior, para que el relé no oscile en el punto de consigna.

  • Antirrebote de arranque: exija que la corriente se mantenga por encima del límite durante unos segundos antes de disparar, para que una punta de arranque la supere.

  • La biblioteca lee el registro RMS de corriente del módulo en cada bucle (el módulo calcula el RMS internamente a unos 5 Hz): Python lo compara con los límites y conmuta el relé.

El script

Configure sus LIMIT_ON / LIMIT_OFF y pines, luego ejecute pip install rbamp smbus2 gpiozero y lance el programa. Relé en GPIO26, alerta en GPIO16 por defecto:

Python
"""
T-P3 -- Local current-limit -> Raspberry Pi GPIO relay (standalone, no HA).

One rbAmp module meters a circuit's current. When it stays over a limit for a
sustained interval, the Pi drives a GPIO relay to shed the load and lights an
alert LED (or drives a small buzzer). Everything runs in one Python loop --
no network, no Home Assistant round-trip, sub-second reaction once the
overload is confirmed.

=========================== SAFETY -- READ FIRST ===========================
 * The relay / switch MUST be rated for the load. A small hobby relay or
   smart-plug CANNOT break 30-50 A directly. Switch a high-current circuit
   with a properly rated CONTACTOR that this low-current relay drives.
 * This is a COMFORT / CONVENIENCE layer, NOT a protection device. The
   circuit BREAKER remains the safety device. Never size a circuit or a
   load assuming this automation will act. For a hard cut-off use a
   hardware overcurrent device (breaker / fuse / thermal cut-out).
 * The relay reaction is deliberately delayed by OVERLOAD_S to ride through
   inrush -- it is not, and must not be treated as, instantaneous
   overcurrent protection.
============================================================================

Module: a current-only rbAmp I-module (I1) at the default address 0x50 is the
        lean pick -- only current is needed, no voltage sensing. A UI1 works
        too; its voltage channel simply goes unused. Whichever you use,
        `dev.current[0]` is the metered channel.

Wiring (Raspberry Pi, hardware I2C + a relay module):
    rbAmp SDA -> GPIO2  (Pi pin 3)
    rbAmp SCL -> GPIO3  (Pi pin 5)
    rbAmp GND -> any GND pin
    rbAmp VCC -> 5V     (Pi pin 2 or 4)
                ^ rbAmp needs 5V for its analog front-end. Only the I2C
                  logic level is 3.3V (handled internally).

    Relay IN  -> RELAY_PIN  (BCM GPIO26 by default; edit below)
    Relay VCC -> 5V (opto-isolated relay boards usually want 5V on the
                     coil side; check yours)
    Relay GND -> Pi GND (common ground)
    Wire the LOAD through the relay's NO (normally-open) contact so a
    de-energised relay = load OFF (safe default at power-up before this
    script even runs).

    Alert     -> ALERT_PIN  (BCM GPIO16 by default) -> LED + series
                 resistor to GND, and/or an active buzzer.

Relay polarity: set RELAY_ACTIVE_HIGH below to match your module. Many
opto-isolated relay boards are ACTIVE-LOW (IN = LOW energises the coil).
gpiozero's `active_high=` argument handles both; we always call
`relay.on()` to mean "energise" (== load powered via the NO contact).

Enable I2C once on the Pi (same as T-P1/T-P2):
    sudo raspi-config    # Interface Options -> I2C -> Enable

Install:
    pip install rbamp smbus2 gpiozero

Run:
    python tp3_pi_gpio_load_relay.py

Set MY_CT / LIMIT_ON / LIMIT_OFF / OVERLOAD_S / COOLDOWN_S below to your
circuit's setpoints. Accuracy: per clamp rating — see the BASIC page for the class and the
sensor's own tolerance (current is the metered quantity here).
Ctrl-C to stop -- both the relay and the alert are released cleanly.
"""

import argparse
import time

from smbus2 import SMBus
from gpiozero import OutputDevice

from rbamp import (
    RbAmp,
    RbAmpError,
    RbAmpSensorClass,
)

# ---- configuration --------------------------------------------------------
RBAMP_ADDR = 0x50
METER_CH   = 0
MY_CT      = 3        # SCT-013-030; 1=-005, 2=-010, 4=-050, 6=-020

# Threshold with hysteresis (amps). Trip when the current stays at/above
# LIMIT_ON; a pending overload only clears when it falls below LIMIT_OFF,
# so the relay does not chatter around the setpoint. Keep LIMIT_OFF < LIMIT_ON.
LIMIT_ON   = 10.0
LIMIT_OFF  = 8.0

SAMPLE_S    = 0.2      # current sample cadence
OVERLOAD_S  = 3.0      # sustained over-limit before trip (rides inrush)
COOLDOWN_S  = 10.0     # stay shed before an auto re-arm attempt

# BCM GPIO pin numbers (edit to match your wiring).
RELAY_PIN         = 26
ALERT_PIN         = 16
RELAY_ACTIVE_HIGH = True    # set False for active-LOW opto-isolated boards


# ---- state machine --------------------------------------------------------
class LoadState:
    ARMED        = "ARMED"
    OVER_PENDING = "OVER_PENDING"
    TRIPPED      = "TRIPPED"


def ensure_ct_preset(dev, ct_code):
    """Verify-then-set CT preset, same pattern as T-P1/T-P2 -- no flash write
    on repeat runs."""
    try:
        applied = dev.read_ct_model_ch(0)
    except RbAmpError:
        applied = -1
    if applied == ct_code:
        return False
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model_ch(0, ct_code)
    return True


def _log_transition(t_ms, old, new, amps):
    print(f"[{t_ms:8d}ms] {old:>12s} -> {new:<12s}  (I={amps:6.3f} A)")


def run(bus, relay, alert, addr=RBAMP_ADDR, ct_code=MY_CT,
        limit_on=LIMIT_ON, limit_off=LIMIT_OFF,
        sample_s=SAMPLE_S, overload_s=OVERLOAD_S, cooldown_s=COOLDOWN_S,
        max_iters=None):
    """Core loop -- takes actuators as args so a test harness can inject
    gpiozero MockFactory-backed OutputDevices."""
    # SAFETY: outputs already in the safe armed state (relay energised
    # via `initial_value=True`, alert off) BEFORE we touch the bus.
    if not relay.value:
        relay.on()
    alert.off()

    with RbAmp(bus, addr=addr) as dev:
        ensure_ct_preset(dev, ct_code)
        print(f"rbAmp @ 0x{dev.address:02X}  fw=0x{dev.firmware_version:02X}  "
              f"topology={dev.topology_name}  ch={dev.channels}")
        print(f"armed: trip >= {limit_on:.1f} A sustained {overload_s:.1f} s,  "
              f"clear < {limit_off:.1f} A,  cooldown {cooldown_s:.1f} s")
        print(f"relay pin={RELAY_PIN} (active_{'high' if RELAY_ACTIVE_HIGH else 'low'}), "
              f"alert pin={ALERT_PIN}")
        print("Ctrl-C stops (releases relay + alert). Accuracy: per clamp rating — see the BASIC page.\n")

        t0 = time.monotonic()

        def now_ms():
            return int((time.monotonic() - t0) * 1000.0)

        state         = LoadState.ARMED
        over_since_s  = 0.0
        tripped_at_s  = 0.0
        trip_count    = 0
        bad_reads     = 0
        iters         = 0

        try:
            while True:
                loop_start = time.monotonic()
                try:
                    a = dev.current[METER_CH]
                except RbAmpError as e:
                    # Graceful: transient read must NOT trigger a false trip
                    # or a false release. Hold state, skip this sample.
                    bad_reads += 1
                    if bad_reads % 10 == 1:
                        print(f"[{now_ms():8d}ms] read failed "
                              f"({type(e).__name__}: {e}) -- holding state={state}")
                    _wait(loop_start, sample_s)
                    iters += 1
                    if max_iters is not None and iters >= max_iters:
                        return {"state": state, "trip_count": trip_count,
                                "bad_reads": bad_reads}
                    continue

                now = time.monotonic()

                if state == LoadState.ARMED:
                    if a >= limit_on:
                        over_since_s = now
                        _log_transition(now_ms(), state, LoadState.OVER_PENDING, a)
                        state = LoadState.OVER_PENDING

                elif state == LoadState.OVER_PENDING:
                    if a < limit_off:
                        _log_transition(now_ms(), state, LoadState.ARMED, a)
                        state = LoadState.ARMED
                    elif (now - over_since_s) >= overload_s:
                        relay.off()          # de-energise -> load OFF
                        alert.on()
                        tripped_at_s = now
                        trip_count += 1
                        _log_transition(now_ms(), state, LoadState.TRIPPED, a)
                        state = LoadState.TRIPPED
                        print(f"           LOAD SHED (trip #{trip_count})")

                elif state == LoadState.TRIPPED:
                    if (now - tripped_at_s) >= cooldown_s:
                        relay.on()           # re-energise -> load ON
                        alert.off()
                        _log_transition(now_ms(), state, LoadState.ARMED, a)
                        state = LoadState.ARMED
                        print(f"           cooldown elapsed -- load re-energised")

                _wait(loop_start, sample_s)
                iters += 1
                if max_iters is not None and iters >= max_iters:
                    return {"state": state, "trip_count": trip_count,
                            "bad_reads": bad_reads}
        finally:
            # SAFETY: leave the outputs in a defined state -- release the alert,
            # but LEAVE THE RELAY whichever way the state machine last set it.
            # For "always re-energise on exit", change this to `relay.on()`.
            alert.off()


def _wait(loop_start, sample_s):
    """Sleep off the remainder of this sample window (no drift)."""
    elapsed = time.monotonic() - loop_start
    if elapsed < sample_s:
        time.sleep(sample_s - elapsed)


def main():
    ap = argparse.ArgumentParser(
        description="Local current-limit -> Pi GPIO relay (standalone, no HA)."
    )
    ap.add_argument("--bus",   type=int, default=1)
    ap.add_argument("--addr",  type=lambda s: int(s, 0), default=RBAMP_ADDR)
    ap.add_argument("--ct",    type=int, default=MY_CT)
    ap.add_argument("--relay-pin", type=int, default=RELAY_PIN)
    ap.add_argument("--alert-pin", type=int, default=ALERT_PIN)
    args = ap.parse_args()

    # SAFETY: construct the outputs BEFORE we touch the I2C bus, and drive
    # them to the safe armed state (load powered, alert off) IMMEDIATELY.
    # `initial_value=True` + `active_high=RELAY_ACTIVE_HIGH` guarantees the
    # physical pin lands on the "energised" level regardless of wiring.
    relay = OutputDevice(args.relay_pin,
                         active_high=RELAY_ACTIVE_HIGH,
                         initial_value=True)
    alert = OutputDevice(args.alert_pin,
                         active_high=True,
                         initial_value=False)

    try:
        with SMBus(args.bus) as bus:
            run(bus, relay, alert, addr=args.addr, ct_code=args.ct)
    except KeyboardInterrupt:
        print("\nstopped.")
    finally:
        alert.off()
        relay.close()
        alert.close()


if __name__ == "__main__":
    main()

(Verificado en ejecución con el simulador de la biblioteca rbAmp y MockFactory de gpiozero en CPython 3.12: cada flanco de estado, más un caso de NACK transitorio que demuestra que una mala lectura nunca dispara falsamente ni reinicia el temporizador de sobrecarga sostenida. El relé se lleva al nivel seguro de carga ENCENDIDA en la construcción, antes de tocar el bus.)

Lo que verá

Las transiciones de estado se registran a medida que ocurren: la punta de arranque se descarta por histéresis, una sobrecarga sostenida dispara, el enfriamiento vuelve a armar:

Text
rbAmp @ 0x50  fw=0x04  topology=SINGLE  ch=1
armed: trip >= 10.0 A sustained 3.0 s,  clear < 8.0 A,  cooldown 10.0 s
relay pin=26 (active_high), alert pin=16

[     200ms]        ARMED -> OVER_PENDING  (I=12.000 A)   <- inrush spike
[     401ms] OVER_PENDING -> ARMED         (I= 3.000 A)   <- inrush cleared (hysteresis)
[     601ms]        ARMED -> OVER_PENDING  (I=11.000 A)   <- real overload
[     902ms] OVER_PENDING -> TRIPPED       (I=11.000 A)   <- sustained -> trip
           LOAD SHED (trip #1)
[    1403ms]      TRIPPED -> ARMED         (I=11.000 A)   <- cooldown -> re-arm
           cooldown elapsed -- load re-energised

Qué hace el script

Es la misma máquina de tres estados que la construcción Arduino con relé: ARMED → OVER_PENDING → TRIPPED, en Python, accionando un relé gpiozero.

Seguro por defecto: antes de tocar siquiera el bus

Python
relay = OutputDevice(RELAY_PIN, active_high=RELAY_ACTIVE_HIGH, initial_value=True)
alert = OutputDevice(ALERT_PIN, active_high=True,              initial_value=False)

El relé se construye primero, con initial_value=True, de modo que el pin físico queda en el nivel «energizado» (carga ENCENDIDA, a través del contacto NO) de inmediato, antes de cualquier tráfico I²C. active_high oculta las dos polaridades de placa de relé tras un único indicador, de modo que relay.on() siempre significa «energizar». Un bloque finally libera los pines al salir, para que una nueva ejecución pueda recuperarlos.

La máquina de estados: el bucle

Python
a = dev.current[METER_CH]          # RbAmpError here -> hold state, skip (no false trip)
if state == ARMED and a >= LIMIT_ON:   over_since = now; state = OVER_PENDING
elif state == OVER_PENDING:
    if a < LIMIT_OFF:                    state = ARMED            # inrush passed
    elif now - over_since >= OVERLOAD_S: relay.off(); alert.on(); state = TRIPPED
elif state == TRIPPED and now - tripped_at >= COOLDOWN_S:  relay.on(); alert.off(); state = ARMED
  • ARMED: carga alimentada; en cuanto la corriente alcanza LIMIT_ON marca el momento y pasa a OVER_PENDING.
  • OVER_PENDING: en un cronómetro. Si cae por debajo de LIMIT_OFF → vuelve a ARMED (sin disparo; histéresis); si permanece por encima durante OVERLOAD_S → desconecta (relay.off()), activa la alerta y pasa a TRIPPED.

  • TRIPPED: tras COOLDOWN_S se rearma y vuelve a energizar; si la sobrecarga persiste, simplemente vuelve a disparar.

La histéresis son los dos umbrales; el antirrebote de arranque es OVERLOAD_S. Y el punto que sostiene la seguridad: un RbAmpError transitorio mantiene el estado y no reinicia el temporizador de sobrecarga; una inestabilidad del bus nunca puede provocar un disparo ni una liberación falsos. (La verificación de dev.lib-python ejercitó exactamente esa ruta.)

Qué sigue

  • Registre los disparos: escriba cada transición en CSV o SQLite (la versión de registro).
  • Prioridades: mida varios circuitos (la versión multimódulo) y desconecte primero la carga de menor prioridad para mantenerse por debajo de un límite de toda la vivienda.

  • ¿Prefiere Home Assistant? La versión de HA (deslizadores, alertas, desconexión por prioridad) es el control de carga en tiempo real con rbAmp.


Lea a continuación