Skip to content

ANTI_BACKFLOW

Prevents the site from exporting more than a configured cap by absorbing surplus with the battery.

Mode string ANTI_BACKFLOW (EMS_OP_ANTI_BACKFLOW)
Dispatcher ems_main.py → control_logic_updated.control_step
Config block functions.Anti_Backflow
Queue source tag control_logic (the writer's default)
Status Implemented

Purpose

Reads grid-meter active power. If the site is exporting more than export_limit_kw, the battery charges to absorb the excess. If the site is importing, it discharges to reduce the import. The battery is driven so that grid power is pulled back towards the export limit.

How it decides

grid_kw = values["gridMeter_lastValue__gridMeter_active_power_total_kw"]
deadband_kw = 0.05
  • grid_kw > export_limit_kw + deadband_kw → charge (absorb the export). total_charge_kw = max(0.0, grid_kw - export_limit_kw)
  • grid_kw < -deadband_kw → discharge (reduce the import). total_discharge_kw = max(0.0, -grid_kw) — note the export limit is not subtracted here.
  • Otherwise (inside the deadband) → all active PCS are commanded to 0 kW.

The command is written as -kW for charge and +kW for discharge.

Configuration

functions.Anti_Backflow

Key Live value Meaning
enabled false Master switch. Off ⇒ immediate return.
export_limit_kw null Export cap in kW. Defaults to 0.0 when null.
response_time_ms null Recorded only; not used by the control step.
ramp_rate_limit_kw_s null Recorded only; no ramp limiting is applied.
soc_limits {null, null} Legacy block; the effective SOC gates come from general_settings.pcs.<id>.soc_limits.
priority_rule anti_backflow_over_arbitrage_freq Documentation of intended precedence.
timezone Europe/Stockholm Used by control_windows only.
control_windows[] 5 entries start, end, enabled, export_cap_kw, days_of_week.
optional.fail_safe_behavior clamp-zero Intent: clamp to zero on fault.

Note: control_windows is present in the configuration but the control step does not evaluate time-of-day or days_of_week. The export cap in effect is always export_limit_kw.

Safety

  • Returns immediately when is_external_control_active().
  • Returns when enabled is false.
  • Returns when grid power telemetry is missing (grid_kw is None) — never guesses.
  • SOC gating via _soc_block_reason: charge is blocked at max_soc_pct, discharge at min_soc_pct; a PCS with missing SOC is blocked and force-written to 0 kW.
  • Per-PCS caps from power_limits.max_charge_kw / max_discharge_kw, applied during allocation and again as a final clamp inside _pcs_connect_and_set_power_kw.

Outputs

_pcs_connect_and_set_power_kw(cfg, pcs_id, ±kw) → queue action set_power_kw, one command per eligible PCS, source control_logic.