rbAmp
IT
Negozio

Progetto · · 13 min di lettura

Far scattare un relè per sovracorrente da un Raspberry Pi — controllo locale dei carichi in Python

Legga la corrente di un circuito su un Raspberry Pi e commuti un relè GPIO quando supera il suo limite — in locale, in Python, senza Home Assistant, senza cloud. Isteresi e debounce dello spunto integrati.

Sicurezza

⚠️ Legga prima questo — che cosa è e che cosa non è. Questo è uno strato di comodità, non un dispositivo di protezione. Il suo interruttore automatico resta il dispositivo di sicurezza — non dimensioni mai un circuito o un carico supponendo che questa automazione interverrà. E il relè che commuta deve essere dimensionato per il carico: un relè piccolo non può interrompere direttamente 30–50 A. Per un circuito ad alta corrente, usi il GPIO relè per pilotare un contattore dimensionato correttamente. Per lavori all'interno di un quadro elettrico, si rivolga a un elettricista qualificato.

Cosa costruirà

  • Un modulo rbAmp che misura la corrente di un circuito sul Pi.
  • Un relè GPIO che scatta quando la corrente resta sopra LIMIT_ON A e rilascia sotto LIMIT_OFF (isteresi).
  • Debounce dello spunto perché lo spunto di avviamento di un motore o di un bollitore non provochi scatti fastidiosi.
  • Allarme LED/cicalino opzionale. Tutto locale, in Python.

Distinta dei materiali

Voce Q.tà Note
rbAmp BASIC SCT-I1 1 solo corrente I1 è la scelta leggera — anche un UI1 funziona · prodotto
TA SCT-013 1 portata da adattare al circuito · prodotto
Raspberry Pi 1 qualsiasi modello con l'header a 40 pin
Modulo relè 1 isolato, dimensionato per il carico — oppure che pilota un contattore per correnti elevate
LED / cicalino (opzionale) 1 allarme locale

Lo cablili

Il modulo rbAmp va sui pin I²C del Pi (SDA GPIO2 / SCL GPIO3, VCC 5 V — perché 5 V con un bus a 3.3 V?). L'ingresso di controllo della scheda relè va su GPIO26 (BCM); imposti RELAY_ACTIVE_HIGH nella configurazione in base alla sua scheda (molte schede optoisolate sono attive LOW). Un allarme LED/cicalino opzionale va su GPIO16. Colleghi il carico attraverso il contatto NO del relè, così un relè diseccitato = carico SPENTO. I TA si stringono attorno al conduttore del circuito — non invasivi sul lato corrente.

La logica: soglia, isteresi, debounce

Gli stessi tre concetti della versione a microcontrollore:

  • Isteresi — scatta a LIMIT_ON ma rilascia solo sotto un LIMIT_OFF più basso, così il relè non oscilla sul setpoint.

  • Debounce dello spunto — richiede che la corrente resti sopra il limite per qualche secondo prima di far scattare, così uno spunto di avviamento passa senza problemi.

  • La libreria legge il registro RMS della corrente del modulo a ogni ciclo (il modulo calcola internamente l'RMS a circa 5 Hz) — Python confronta con i limiti e commuta il relè.

Lo script

Imposti LIMIT_ON / LIMIT_OFF e i pin, poi esegua pip install rbamp smbus2 gpiozero e lo avvii. Relè su GPIO26, allarme su GPIO16 per impostazione predefinita:

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()

(Verificato in esecuzione con il mock della libreria rbAmp e MockFactory di gpiozero su CPython 3.12 — ogni transizione di stato, più un caso di NACK transitorio che dimostra che una lettura errata non fa mai scattare per errore e non azzera mai il timer del sovraccarico sostenuto. Il relè viene portato al livello sicuro di carico ON in fase di costruzione, prima di toccare il bus.)

Cosa vedrà

Le transizioni di stato vengono registrate man mano che avvengono — spunto cancellato dall'isteresi, un sovraccarico sostenuto che fa scattare, il cooldown che riarma:

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

Cosa fa lo script

È la stessa macchina a tre stati della build relè Arduino — ARMED → OVER_PENDING → TRIPPED — in Python, pilotando un relè gpiozero.

Sicuro per impostazione predefinita — prima ancora di toccare il bus

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

Il relè viene costruito per primo, con initial_value=True — così il pin fisico si porta subito al livello "eccitato" (carico ON, tramite il contatto NO) immediatamente, prima di qualsiasi traffico I²C. active_high nasconde entrambe le polarità delle schede relè dietro un solo flag, quindi relay.on() significa sempre "ecciti". Un blocco finally rilascia i pin all'uscita, così una riesecuzione può riprenderli.

La macchina a stati — il 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 — carico alimentato; nel momento in cui la corrente raggiunge LIMIT_ON registra l'istante e passa a OVER_PENDING.
  • OVER_PENDING — a cronometro. Scende sotto LIMIT_OFF → torna ad ARMED (nessuno scatto — isteresi); resta sopra per OVERLOAD_S → disinserisce (relay.off()), allarme attivo, → TRIPPED.

  • TRIPPED — dopo COOLDOWN_S si riarma e si rieccita; se il sovraccarico persiste, scatta di nuovo.

L'isteresi è data dalle due soglie; il debounce dello spunto è OVERLOAD_S. E il punto portante: un RbAmpError transitorio mantiene lo stato e non azzera il timer di superamento del limite — un'instabilità del bus non può mai causare uno scatto falso né un rilascio falso. (La verifica di dev.lib-python ha esercitato proprio quel percorso.)

Cosa segue

  • Registri gli scatti — scriva ogni transizione su CSV o SQLite (la build del logger).
  • Priorità — misuri più circuiti (la build multi-modulo) e disinserisca per primo il carico a priorità più bassa per restare sotto un limite dell'intera abitazione.

  • Preferisce Home Assistant? La versione HA — cursori, allarmi, disinserimento per priorità — è il controllo dei carichi in tempo reale con rbAmp.


Leggi anche