Skip to content

Connection Modeling

The Connection device provides explicit user-defined power flow paths between elements. Unlike implicit connections created by other devices, Connection allows full control over bidirectional flow, efficiency, and pricing.

Model Elements Created

graph LR
    subgraph "Device"
        MC["PowerConnection<br/>{name}"]
    end

    Source[Source Element]
    Target[Target Element]

    Source <-->|links via| MC
    MC <-->|links to| Target
Model Element Name Parameters From Configuration
PowerConnection {name} All parameters mapped directly

The Connection device creates a PowerConnection model element, which extends the base Connection class to support efficiency, pricing, and power limits.

Devices Created

Connection creates 1 device in Home Assistant:

Device Name Created When Purpose
Primary {name} Always Explicit power flow path

Parameter Mapping

The adapter passes user configuration directly to the PowerConnection model:

User Configuration Model Element Model Parameter Notes
source PowerConnection source Source element name
target PowerConnection target Target element name
max_power_source_target PowerConnection max_power_source_target Optional, unlimited if not set
max_power_target_source PowerConnection max_power_target_source Optional, unlimited if not set
efficiency_source_target PowerConnection efficiency_source_target Optional, 100% if not set
efficiency_target_source PowerConnection efficiency_target_source Optional, 100% if not set
price_source_target PowerConnection price_source_target Optional, no cost if not set
price_target_source PowerConnection price_target_source Optional, no cost if not set

Sensors Created

Connection Device

Sensor Unit Update Description
power_source_target kW Real-time Power flow from source to target
power_target_source kW Real-time Power flow from target to source
power_max_source_target kW Real-time Configured max power (if set)
power_max_target_source kW Real-time Configured max power (if set)
shadow_power_max_* $/kW Real-time Shadow prices for power limits

See Connection Configuration for detailed sensor and configuration documentation.

Configuration Examples

AC/DC Inverter

Field Value
Name Inverter
Source DC Bus
Target AC Bus
Max Power Source to Target 10.0
Max Power Target to Source 10.0
Efficiency Source to Target 0.97
Efficiency Target to Source 0.96

Wheeling Charge

Field Value
Name Grid Transfer
Source Zone A
Target Zone B
Price Source to Target sensor.wheeling_charge
Price Target to Source sensor.wheeling_charge

Typical Use Cases

AC/DC Conversion: Model inverter efficiency losses between DC battery/solar and AC loads/grid with bidirectional efficiency parameters.

Wheeling Charges: Apply transmission costs for power transfer between geographic zones or utility territories.

Capacity Limits: Constrain power flow through physical bottlenecks like panel ratings or cable capacity using max_power parameters.

Time-Varying Availability: Use forecast sensors for max_power to model connection availability windows (e.g., scheduled maintenance).

Physical Interpretation

Connection represents a controllable power flow path between elements with optional constraints on capacity, efficiency, and cost.

When to Use Explicit Connections

Many device elements create implicit connections automatically:

  • Battery/Grid/PV/Load automatically connect to their target node
  • These implicit connections have sensible defaults (100% efficiency, no price)

Use explicit Connection devices when you need:

  • Additional power paths between nodes not covered by device defaults
  • Non-100% efficiency (inverter losses, transmission losses)
  • Non-zero pricing (wheeling charges, conversion costs)
  • Capacity constraints beyond those set by connected devices
  • Time-varying parameters (availability windows, dynamic pricing)

Configuration Guidelines

  • Bidirectional Control: Set both max_power_source_target and max_power_target_source for asymmetric capacity (common in inverters).
  • Efficiency Matters: Even small efficiency differences (95% vs 100%) significantly affect optimal battery dispatch strategies.
  • Price vs Limit: Use price to encourage/discourage flow while allowing the optimizer freedom. Use max_power for hard physical constraints.
  • Implicit Connections: Don't create explicit connections that duplicate implicit ones—this creates parallel paths with potentially confusing results.

Next Steps