Skip to content

[Improvement] Add optional manual assignment of batteries to individual phases #102

@nickles-lee

Description

@nickles-lee

Summary

Currently the dashboard and control logic are not aware of which electrical phase each battery is connected to.

That is fine for aggregate-of-all-phases-only strategies, but it becomes a limitation once the system starts exposing per-phase P1 metrics (#100) and supporting per-phase peak shaving / overload protection (#101). Without knowing which battery belongs to which phase, the controller cannot make phase-aware decisions in a sane way; the only alternative is to apply global throttling based on individual phases.

This improvement is to add an optional manual assignment of batteries to individual phases.

Requested functionality

Allow each configured battery to be manually assigned to one of the grid phases (or a default unassigned state):

  • Phase 1 (L1)
  • Phase 2 (L2)
  • Phase 3 (L3)
  • Unassigned

This assignment should be optional, so existing setups continue to work exactly as they do today.

Why this is needed

In a multi-battery setup, the controller currently treats battery capacity/power as if it were phase-agnostic.

In reality, each battery/inverter is physically connected to a specific phase. If the software does not know that mapping, it cannot correctly answer questions like:

  • which battery can help reduce overload on L1?
  • whether available discharge on L2 is relevant to a peak on L3 (it's not)
  • how much effective support exists on each phase
  • which batteries should be prioritized for phase-specific control

Proposed behavior

Add an optional per-battery configuration field such as:

  • phase: L1 | L2 | L3 | unassigned

or equivalent UI/config representation.

Expected behavior

  • A battery may be manually assigned to L1, L2, or L3
  • Assignment is optional
  • Existing users who do not configure a phase should keep current behavior
  • Dashboard can display the configured phase for each battery
  • Control logic can use the assignment when phase-aware features are enabled

Backward compatibility

This should remain fully backward compatible:

  • no battery phase assignment configured → current aggregate behavior remains unchanged
  • battery phase assignment configured but no phase-aware strategy enabled → no functional change except visibility
  • battery phase assignment configured and per-phase strategies enabled → controller can make phase-aware decisions

Suggested dashboard changes

It would be useful if the dashboard also exposed phase assignment clearly, for example, showing the assigned phase next to each battery / if it is unassigned

Design note

This should be a manual assignment, not an inferred one.

The software generally should not autodetect the real electrical phase for each battery, so explicit user configuration is the most predictable and transparent option. Autodetection is possible, but nontrivial/taking on actual risk.

Possible acceptance criteria

  • Each battery can optionally be assigned to L1, L2, or L3
  • Missing assignment does not break existing setups
  • Existing aggregate-only behavior is unchanged by default
  • Dashboard shows the configured phase assignment
  • Phase-aware control logic can access the battery-to-phase mapping
  • Unassigned batteries are handled gracefully

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions