⚠️ 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_ONA e liberta abaixo deLIMIT_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 umLIMIT_OFFmais 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:
"""
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:
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
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
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_ONregista a hora e passa aOVER_PENDING. -
OVER_PENDING — cronómetro em marcha. Desce abaixo de
LIMIT_OFF→ volta a ARMED (sem disparo — histerese); mantém-se acima duranteOVERLOAD_S→ corta (relay.off()), alerta ativo, → TRIPPED. -
TRIPPED — após
COOLDOWN_Svolta 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
- Registe os disparos — escreva cada transição em CSV ou SQLite (a construção do registador).
-
Prioridades — meça vários circuitos (a construção multimódulo) e corte primeiro a carga de menor prioridade para ficar abaixo de um limite da casa inteira.
-
Prefere o Home Assistant? A versão HA — deslizadores, alertas, corte por prioridade — é controlo de carga em tempo real com rbAmp.