Input Entities¶

Input entities are an intermediate layer between external Home Assistant sensors and the optimization model. They load, transform, and expose forecast data as Number and Switch entities that users can inspect and optionally modify.

Purpose¶

HAEO's input entity layer provides:

• Visibility: Users see loaded values as standard HA entities
• Editability: Values can be modified for what-if analysis or via automation service calls
• Decoupling: Data loading happens independently of optimization cycles
• Alignment: All inputs share synchronized forecast horizons

Architecture¶

graph LR
    subgraph "External"
        Sensors[HA Sensors]
    end

    subgraph "Input Layer"
        IE[Input Entities]
        HM[HorizonManager]
    end

    subgraph "Runtime Data"
        RD[runtime_data.inputs]
    end

    subgraph "Optimization"
        Coord[Coordinator]
    end

    Sensors -->|load| IE
    HM -->|horizon| IE
    IE -->|populate| RD
    RD -->|read| Coord

Input entities subscribe to the HorizonManager and refresh their data when the forecast horizon advances. The coordinator reads pre-loaded values from runtime_data.inputs rather than loading directly from sensors.

Input Field Registry¶

Each element type declares which configuration fields become input entities via the INPUT_FIELDS registry in its adapter module. The registry uses an InputFieldInfo dataclass that specifies the field name, entity description, output type, direction, and whether values vary per period.

See the element adapter modules for specific registrations.

Entity Creation¶

Input entities are only created for fields that are actually configured. When a user selects "Not Configured" (mode NONE) for an optional field during element setup, no entity is created for that field. This keeps the entity list focused on functionality the user has enabled.

Configured fields: An entity is created in either EDITABLE or DRIVEN mode depending on the input type.

Unconfigured fields: No entity is created. The field uses its default value in the optimization model without exposing an entity.

This behavior is controlled by the two-step config flow pattern documented in Config Flow Development.

Entity Types¶

Number Entities¶

Number entities represent numeric input parameters such as power limits, energy capacity, prices, and percentages. They allow user modification when in editable mode.

Switch Entities¶

Switch entities represent boolean input parameters. They toggle between on/off states and are typically editable.

Configuration Modes¶

Input entities operate in one of two modes based on how the field was configured:

Editable Mode¶

When the configuration specifies a constant value (not an external sensor):

• The entity displays the configured value
• Users can modify the value through the Home Assistant UI
• Service calls can update values for automation scenarios
• Changes persist and affect future optimizations
• Useful for what-if analysis and dynamic adjustments

Driven Mode¶

When the configuration specifies an entity ID or list of entity IDs:

• The entity loads data from source sensors using TimeSeriesLoader
• Values update automatically when source sensors change
• The source_entities attribute lists the driving sensors
• User modifications via UI are not supported (value comes from sources)

Entity Attributes¶

All input entities expose extra state attributes for debugging and automation:

Driven mode entities also expose source_entities listing the entity IDs providing the data.

Entity Naming¶

Entity IDs¶

Entity IDs follow Home Assistant conventions:

number.{element_name}_{field_name}
switch.{element_name}_{field_name}

Examples:

• number.battery_capacity
• number.main_grid_import_price
• switch.solar_curtailment

Device Association¶

Input entities belong to the same device as the element's output sensors, grouping all entities for an element together.

Forecast Attribute¶

The forecast attribute provides time-series data aligned to the optimization horizon. Each entry contains an ISO 8601 timestamp and the value for that period.

For scalar (non-time-series) inputs, all periods have the same value. For time-series inputs, values vary based on loaded forecast data.

Data Loading Flow¶

When the horizon changes or source sensors update:

1. HorizonManager notifies entity of new horizon
2. Entity calls TimeSeriesLoader with source entity IDs (driven mode only)
3. Loader extracts, combines, and fuses forecast data
4. Entity stores aligned values and updates HA state
5. Entity writes to runtime_data.inputs for coordinator access

Entity Category¶

Input entities use EntityCategory.CONFIG:

• Excluded from default dashboards and history
• Visible in device pages and entity lists
• Appropriate for configuration-like values

Users can add specific inputs to dashboards if desired for monitoring.

Related Documentation¶