rbAmp
PT
Loja

Projeto · · 13 min de leitura

Dispare um relé por sobrecorrente num Raspberry Pi — controlo de carga local em Python

Leia a corrente de um circuito num Raspberry Pi e comute um relé GPIO quando ultrapassa o seu limite — localmente, em Python, sem Home Assistant, sem nuvem. Histerese e anti-ressalto de arranque incluídos.

Segurança

⚠️ Leia isto primeiro — o que é e o que não é. Isto é uma camada de conforto e conveniência, não um dispositivo de proteção. O seu disjuntor continua a ser o dispositivo de segurança — nunca dimensione um circuito ou uma carga a contar que esta automação vai atuar. E o relé que comuta tem de ser dimensionado para a carga: um relé pequeno não consegue interromper 30–50 A diretamente. Para um circuito de corrente elevada, use o relé GPIO para acionar um contactor devidamente dimensionado. Para trabalhos dentro de um quadro elétrico, chame um eletricista qualificado.

O que vai construir

  • Um módulo rbAmp a medir a corrente de um circuito no Pi.
  • Um relé GPIO que dispara quando a corrente se mantém acima de LIMIT_ON A e liberta abaixo de LIMIT_OFF (histerese).
  • Anti-ressalto de arranque para que o pico de arranque de um motor ou de uma chaleira não cause um disparo indesejado.
  • Alerta LED/buzzer opcional. Tudo local, em Python.

Lista de materiais

Item Qtd. Notas
rbAmp BASIC SCT-I1 1 o I1 só de corrente é a escolha leve — um UI1 também funciona · produto
TC SCT-013 1 classificação adequada ao circuito · produto
Raspberry Pi 1 qualquer modelo com o cabeçalho de 40 pinos
Módulo de relé 1 isolado, dimensionado para a carga — ou a acionar um contactor para corrente elevada
LED / buzzer (opcional) 1 alerta local

Ligue tudo

O módulo rbAmp vai nos pinos I²C do Pi (SDA GPIO2 / SCL GPIO3, VCC 5 V — porquê 5 V com um barramento de 3.3 V?). A entrada de controlo do módulo de relé vai para o GPIO26 (BCM); defina RELAY_ACTIVE_HIGH na configuração para corresponder à sua placa (muitas placas com isolamento ótico são ativas em nível BAIXO). Um alerta LED/buzzer opcional vai para o GPIO16. Ligue a carga através do contacto NO do relé, para que um relé desenergizado = carga DESLIGADA. A pinça TC envolve à volta do condutor do circuito — não invasiva do lado da corrente.

A lógica: limiar, histerese, anti-ressalto

As mesmas três ideias da versão para microcontrolador:

  • Histerese — dispare em LIMIT_ON, mas só liberte abaixo de um LIMIT_OFF mais baixo, para que o relé não oscile no ponto de regulação.

  • Anti-ressalto de arranque — exija que a corrente se mantenha acima do limite durante alguns segundos antes de disparar, para que um pico de arranque passe sem problema.

  • A biblioteca lê o registo de RMS de corrente do módulo a cada ciclo (o módulo calcula o RMS internamente a cerca de 5 Hz) — o Python compara-o com os limites e comuta o relé.

O script

Defina o seu LIMIT_ON / LIMIT_OFF e os pinos, depois execute pip install rbamp smbus2 gpiozero e corra-o. Relé no GPIO26, alerta no GPIO16 por defeito:

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 em execução contra o simulador da biblioteca rbAmp + o MockFactory do gpiozero em CPython 3.12 — todas as transições de estado, mais um caso de NACK transitório a provar que uma leitura má nunca causa disparo falso nem repõe o temporizador de sobrecarga sustentada. O relé é conduzido ao nível de carga LIGADA seguro na construção, antes de o barramento ser tocado.)

O que verá

Transições de estado registadas à medida que acontecem — pico de arranque anulado pela histerese, uma sobrecarga sustentada a disparar, o arrefecimento a re-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

O que o script faz

É a mesma máquina de três estados da construção com relé Arduino — ARMED → OVER_PENDING → TRIPPED — em Python, a comandar um relé gpiozero.

Seguro por defeito — antes de tocar sequer no barramento

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

O relé é construído primeiro, com initial_value=True — assim o pino físico fica no nível "energizado" (carga LIGADA, via o contacto NO) imediatamente, antes de qualquer tráfego I²C. active_high esconde as duas polaridades das placas de relé atrás de uma só flag, por isso relay.on() significa sempre "energizar". Um bloco finally liberta os pinos à saída, para que uma nova execução os possa reclamar.

A máquina de estados — o ciclo

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; no momento em que a corrente atinge LIMIT_ON regista a hora e passa a OVER_PENDING.
  • OVER_PENDING — cronómetro em marcha. Desce abaixo de LIMIT_OFF → volta a ARMED (sem disparo — histerese); mantém-se acima durante OVERLOAD_S → corta (relay.off()), alerta ativo, → TRIPPED.

  • TRIPPED — após COOLDOWN_S volta a armar e a energizar; se a sobrecarga persistir, dispara de novo.

A histerese são os dois limiares; o anti-ressalto de arranque (debounce) é OVERLOAD_S. E o ponto que sustenta tudo: um RbAmpError transitório mantém o estado e não repõe o temporizador de sobrecarga — uma falha momentânea no barramento nunca pode causar um disparo falso nem um desarme falso. (A verificação de dev.lib-python exercitou exatamente esse caminho.)

O que se segue


Leia a seguir