### Example Configuration for Grid Power Outage

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/02-types.md

This YAML example demonstrates how to configure grid power outage detection using the `gridPowerOutage` type. It specifies the entity for monitoring and customizes the alert state, label, and icon.

```yaml
grid:
  entity:
    consumption: sensor.grid_consumption
    production: sensor.grid_production
  power_outage:
    entity: binary_sensor.grid_status
    state_alert: "off"
    label_alert: "Grid Down"
    icon_alert: "mdi:alert"
```

--------------------------------

### Full Configuration Example

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/README.md

A comprehensive configuration demonstrating various customization options including custom icons, names, display states, and individual entity configurations.

```yaml
type: custom:energy-flow-card-plus
entities:
  home:
    entity: sensor.home_consumption
    color_icon: solar
  fossil_fuel_percentage:
    entity: sensor.fossil_fuel_percentage
    icon: mdi:pine-tree
    color_icon: true
    display_zero: true
    name: Non Fossil
    state_type: power
  grid:
    icon: mdi:ab-testing
    name: Provider
    entity:
      production: sensor.grid_production
      consumption: sensor.grid_consumption
  solar:
    icon: mdi:solar-panel-large
    entity: sensor.solar_production
  battery:
    name: Bateria
    icon: mdi:bat
    entity:
      consumption: sensor.battery_consumption
      production: sensor.battery_production
  individual:
    - entity: sensor.car_power
      icon: mdi:car-electric
      color: "#80b8ff"
      name: Denim Flash
      color_icon: false
    - entity: sensor.motorbike_power
      name: Qivi
      color_icon: true
      display_zero: true
      color: "#ff8080"
      icon: mdi:motorbike-electric
base_decimals: 0
kilo_decimals: 2
min_flow_rate: 0.9
max_flow_rate: 6
kilo_threshold: 10000
clickable_entities: true
title: Energy Flow Card Plus
```

--------------------------------

### Standard Installation Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

A comprehensive configuration for displaying grid, solar, battery, and home energy consumption. Includes optional color customization for grid entities.

```yaml
type: custom:energy-flow-card-plus
title: House Energy
entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_production
    color:
      consumption: "#488fc2"
      production: "#a280db"
  solar:
    entity: sensor.solar_production
    color: "#ff9800"
  battery:
    entity:
      consumption: sensor.battery_discharge
      production: sensor.battery_charge
    state_of_charge: sensor.battery_soc
  home:
    entity: sensor.home_consumption
```

--------------------------------

### Optimize for Large Installations with Aggregated Sources

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Aggregate multiple entities into a single circle for combined production or load display, useful for managing large installations with numerous sources.

```yaml
type: custom:energy-flow-card-plus

# Multiple sources aggregated
entities:
  solar:
    entity:
      - sensor.solar_1
      - sensor.solar_2
      - sensor.solar_3
      - sensor.solar_4
    # Single circle shows combined production

  individual1:
    entity:
      - sensor.charger_1
      - sensor.charger_2
      - sensor.charger_3
    # Single circle shows combined load
```

--------------------------------

### Subscription Setup

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Details the subscription process initiated by Home Assistant, including polling for energy data and handling different subscription modes based on the energy_date_selection flag.

```javascript
hassSubscribe() called by Home Assistant
  ↓
Check energy_date_selection flag
  ↓
IF energy_date_selection !== false:
  │
  ├─ Poll for EnergyCollection (timeout: 10s)
  │  └─ Retry every 100ms until available
  │
  ├─ Subscribe to collection updates:
  │  ├─ Receive EnergyData (period, start, end)
  │  ├─ Call getStatistics() for all monitored entities
  │  ├─ Convert kWh/MWh to Wh
  │  └─ Update this.states with results
  │
  └─ Set error if data unavailable after 20s
  
ELSE:
  │
  └─ Return empty array (no subscriptions)
     └─ Card uses instantaneous values from hass.states
```

--------------------------------

### Advanced Full Configuration with Customizations

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/03-configuration-schema.md

This comprehensive example demonstrates advanced options like custom titles, links, flow rate settings, thresholds, decimal precision, and detailed entity styling.

```yaml
type: custom:energy-flow-card-plus
title: Energy Management
dashboard_link: /energy
dashboard_link_label: More Details
min_flow_rate: 0.5
max_flow_rate: 5
use_new_flow_rate_model: true
min_expected_energy: 100
max_expected_energy: 5000
wh_kwh_threshold: 1000
wh_decimals: 0
kwh_decimals: 2
clickable_entities: true

entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_return
    name: Utility
    icon: mdi:transmission-tower
    color:
      consumption: "#488fc2"
      production: "#d0a856"
    color_icon: true
    color_circle: color_dynamically
    display_state: one_way
    power_outage:
      entity: binary_sensor.grid_connected
      state_alert: "off"
      label_alert: "No Grid"
      icon_alert: mdi:alert-circle

  solar:
    entity: sensor.solar_production
    color: "#ff9800"
    color_icon: true
    color_value: true
    secondary_info:
      entity: sensor.solar_forecast
      unit_of_measurement: kWh
      decimals: 1

  battery:
    entity:
      consumption: sensor.battery_discharge
      production: sensor.battery_charge
    state_of_charge: sensor.battery_percentage
    color:
      consumption: "#4db6ac"
      production: "#a280db"
    color_icon: color_dynamically
    color_circle: color_dynamically

  home:
    entity: sensor.home_consumption
    color_icon: true
    color_value: true

  individual1:
    entity: sensor.ev_charger_power
    name: EV Charger
    icon: mdi:car-electric
    color: "#80b8ff"
    secondary_info:
      entity: sensor.ev_status
      template: "{{ states('sensor.ev_status') }}"
```

--------------------------------

### Install Energy Flow Card Plus via HACS

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/00-readme.md

Follow these steps to install the card using Home Assistant Community Store (HACS).

```bash
# Via HACS
1. HACS → Frontend → "Search" → "Energy Flow Card Plus"
2. Click Install
```

--------------------------------

### Solar Configuration Example

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/03-configuration-schema.md

Configure solar power entities, including single or multiple entities, display labels, icons, colors, and secondary information like forecasts.

```yaml
entities:
  solar:
    entity: sensor.solar_production
    # Or multiple entities (will be summed)
    entity:
      - sensor.solar_production_1
      - sensor.solar_production_2

    name: Solar               # Display label
    icon: mdi:solar-power     # Icon path
    
    color: "#ff9800"          # Hex color (or RGB array [255, 152, 0])
    color_icon: false         # Color the icon
    color_value: false        # Color the value text
    
    display_zero: true        # Show even if 0 or unavailable
    display_zero_state: true  # Show value even if 0
    display_zero_tolerance: 10 # Hide if below this value
    
    secondary_info:
      entity: sensor.solar_forecast
      unit_of_measurement: Wh
      icon: mdi:weather-sun
      template: "{{ states('sensor.solar_forecast') }}"
```

--------------------------------

### Custom Card Styling with YAML

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Apply custom styles to the card's background and shadow using YAML. This example sets a gradient background and a subtle shadow.

```yaml
type: custom:energy-flow-card-plus
title: Energy Flow

# Customize card appearance
style_ha_card: |
  ha-card {
    border-radius: 12px;
    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
    box-shadow: 0 8px 24px rgba(0,0,0,0.4);
  }

# Customize card content
style_card_content: |
  svg {
    filter: drop-shadow(0 0 10px rgba(255,255,255,0.1));
  }

entities:
  grid:
    entity: sensor.grid_consumption
```

--------------------------------

### Get Stub Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Provides a default configuration object for the card, detecting available energy entities using the Home Assistant instance.

```typescript
public static getStubConfig(hass: HomeAssistant): Record<string, unknown>
```

--------------------------------

### Get Configuration Element

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Dynamically imports and returns the UI editor component for visual configuration of the card.

```typescript
public static async getConfigElement(): Promise<LovelaceCardEditor>
```

--------------------------------

### Common Grid, Solar, and Battery Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/03-configuration-schema.md

This configuration is suitable for typical home energy setups, including grid, solar production, battery state, and home consumption.

```yaml
type: custom:energy-flow-card-plus
title: House Energy
entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_production
  solar:
    entity: sensor.solar_production
  battery:
    entity:
      consumption: sensor.battery_discharge
      production: sensor.battery_charge
    state_of_charge: sensor.battery_soc
  home:
    entity: sensor.home_consumption
```

--------------------------------

### Minimal YAML Configuration for Energy Flow Card Plus

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/00-readme.md

This is a basic example of how to configure the Energy Flow Card Plus using YAML. It includes essential entities like grid, solar, battery, and home consumption.

```yaml
type: custom:energy-flow-card-plus
entities:
  grid:
    entity: sensor.grid_power
  solar:
    entity: sensor.solar_power
  battery:
    entity: sensor.battery_power
    state_of_charge: sensor.battery_soc
  home:
    entity: sensor.home_consumption
```

--------------------------------

### Card Implementation of hassSubscribe

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Example implementation of the hassSubscribe method in a Home Assistant card. It conditionally returns subscriptions based on configuration and handles energy data updates.

```typescript
public hassSubscribe() {
  if (this._config?.energy_date_selection === false) {
    return []
  }
  
  const energyPromise = new Promise<EnergyCollection>(...)
  
  return [
    energyPromise.then(async collection => {
      return collection.subscribe(async data => {
        // Handle energy data update
      })
    })
  ]
}
```

--------------------------------

### Usage Example for logError

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Demonstrates how to call the debounced logError function with a specific error message.

```typescript
logError(`Entity "sensor.solar" is not available or misconfigured`)
```

--------------------------------

### Fossil Fuel Percentage Configuration Example

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/03-configuration-schema.md

This YAML configuration defines how to display fossil fuel percentage data, including entity mapping, display labels, colors, state types, and zero-value handling.

```yaml
entities:
  fossil_fuel_percentage:
    entity: sensor.carbon_emission_percentage
    
    name: Low-Carbon              # Display label
    icon: mdi:leaf               # Icon path
    
    color: "#0f9d58"             # Hex color
    color_icon: false            # Color the icon
    color_value: false           # Color the value
    color_label: false           # Color the label
    
    state_type: percentage       # "percentage" | "power"
    
    display_zero: true           # Show even if zero
    display_zero_state: true     # Show value if zero
    display_zero_tolerance: 0    # Threshold to hide
    
    unit_white_space: true       # Space before unit
    decimals: 0                  # Decimal places
    
    calculate_flow_rate: true    # Animate or set seconds: 3
    
    secondary_info:
      entity: sensor.carbon_emissions
      unit_of_measurement: g
      icon: mdi:smoke
    
    use_metadata: false
```

--------------------------------

### Configuration Validation in setConfig

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Example of validating configuration object and required entities within the setConfig method. Throws an error for invalid configurations.

```typescript
// In setConfig()
if (typeof config !== 'object') {
  throw new Error(localize('common.invalid_configuration'))
}
if (!config.entities || 
    (!config.entities?.battery?.entity && 
     !config.entities?.grid?.entity && 
     !config.entities?.solar?.entity)) {
  throw new Error('At least one entity for battery, grid or solar must be defined')
}
```

--------------------------------

### Grid Entity Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/03-configuration-schema.md

Configure a single grid entity using its power sensor. This is suitable for simple setups where consumption and production are measured by the same sensor.

```yaml
entities:
  grid:
    # Simple entity (positive=consumption, negative=production)
    entity: sensor.grid_power
    
    # Or split entities (consumption and production separate)
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_production

    name: Grid                  # Display label
    icon: mdi:transmission-tower # Icon path
    
    # Colors
    color:
      consumption: "#488fc2"   # Grid consumption color
      production: "#a280db"    # Grid production/return color
    
    # Icon coloring
    color_icon: false           # false | true (dynamic) | "production" | "consumption"
    
    # Circle coloring
    color_circle: consumption   # "production" | "consumption" | true (dynamic)
    
    # Display mode
    display_state: two_way      # "two_way" | "one_way" | "one_way_no_zero"
    
    # Value filtering
    display_zero_tolerance: 0   # Hide consumption/production below this value
    
    # Secondary information
    secondary_info:
      entity: sensor.grid_frequency
      unit_of_measurement: Hz
      icon: mdi:sine-wave
      unit_white_space: true
      display_zero: false
      decimals: 2
    
    # Power outage detection
    power_outage:
      entity: binary_sensor.grid_status
      state_alert: "off"        # State value indicating outage
      label_alert: "Grid Down"  # Text to display
      icon_alert: mdi:alert-circle
      calculate_flow_rate: true # Animate generator power during outage

```

--------------------------------

### Get Stub Configuration using JavaScript

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Obtain a stub configuration for the Energy Flow Card Plus by calling `getStubConfig` with the Home Assistant object. This function helps in detecting available entities.

```typescript
// In Home Assistant UI editor
const stubConfig = await EnergyFlowCardPlus.getStubConfig(hass)

// Returns detected entities from Home Assistant:
// {
//   entities: {
//     grid: { entity: "sensor.grid_consumption", ... },
//     solar: { entity: "sensor.solar_production", ... },
//     battery: { entity: "sensor.battery_power", ... },
//     home: { entity: "sensor.home_consumption", ... }
//   },
//   // + other detected available entities
// }
```

--------------------------------

### Setup Custom Localization Function

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Use this default export to set up custom localization. It retrieves the user's language from localStorage, looks up the translation key, and falls back to English or the original key if not found.

```typescript
export default function setupCustomlocalize(key: string): string
```

```typescript
setupCustomlocalize('card.label.car')      // "Car" (English)
setupCustomlocalize('card.label.motorbike') // "Motorcycle" (English)
setupCustomlocalize('unknown.key')          // "unknown.key" (fallback)
```

--------------------------------

### EnergyData Interface

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Defines the structure of energy data, including start and end timestamps, and the selected period.

```typescript
interface EnergyData {
  start: number      // Unix timestamp (ms)
  end: number        // Unix timestamp (ms)
  period: 'day' | 'month' | 'year' | 'week'  // Selected period
}
```

--------------------------------

### Project File Structure

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/MANIFEST.md

This snippet shows the directory structure for the generated documentation files and related project assets.

```bash
/workspace/home/output/
├── INDEX.md                        # Navigation guide (START HERE)
├── 00-readme.md                    # Overview & quick reference
├── 01-card-component.md            # Main class documentation
├── 02-types.md                     # Type definitions
├── 03-configuration-schema.md      # Configuration reference
├── 04-utility-modules.md           # Helper functions
├── 05-data-flow.md                 # Architecture & data flow
├── 06-usage-examples.md            # Usage examples
├── MANIFEST.md                     # This file
└── GENERATION_REPORT.txt           # Generation statistics

```

--------------------------------

### Connection Interface

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/02-types.md

Defines the structure for a connection line between entities, including start and end points, state, and color.

```typescript
interface Connection {
  startY: number
  startSize: number
  endY: number
  endSize: number
  state: number
  startColor?: string
  endColor?: string
  highlighted?: boolean
}
```

--------------------------------

### Step 1: Initial Solar to Home Calculation

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Calculates the initial direct flow of solar energy to the home, accounting for exports and battery charging.

```plaintext
solar.state.toHome = solar.state.total 
                   - grid.state.toGrid 
                   - battery.state.toBattery
```

--------------------------------

### Call Service on Long-Press

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Execute a Home Assistant service call when the card element is long-pressed. This example shows how to turn off a switch.

```yaml
entities:
  solar:
    entity: sensor.solar_production
    name: Solar
    # Long-press to toggle solar production (e.g., disconnect)
    hold_action:
      action: call-service
      service: switch.turn_off
      data:
        entity_id: switch.solar_production
```

--------------------------------

### Minimal Grid Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Use this configuration for a simple display showing only grid consumption/production with animated flow lines.

```yaml
type: custom:energy-flow-card-plus
entities:
  grid:
    entity: sensor.grid_power
```

--------------------------------

### Get Card Size

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Returns the card's height in grid units, which is fixed at 3. This is used by Home Assistant to determine layout.

```typescript
public getCardSize(): Promise<number> | number
```

--------------------------------

### Grid and Solar Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Configure with both grid and solar entities to visualize energy flow between them and the home.

```yaml
type: custom:energy-flow-card-plus
entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_production
  solar:
    entity: sensor.solar_production
```

--------------------------------

### Get Energy Data Collection

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Retrieves the active energy data collection from the dashboard's energy-date-selection card. Returns null if no collection is available.

```typescript
export function getEnergyDataCollection(hass: HomeAssistant): EnergyCollection | null
```

--------------------------------

### Open URL on Tap

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Set up a tap action to open an external URL, such as an inverter's web interface.

```yaml
entities:
  battery:
    entity: sensor.battery_soc
    name: Battery
    # Click to open inverter web interface
    tap_action:
      action: url
      url_path: http://inverter.local
```

--------------------------------

### Action Configuration: URL

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Configures an action to open a URL in a new browser tab. An error toast is shown if the URL is not provided.

```json
{
  action: "url",
  url_path: "https://example.com"
}
```

--------------------------------

### Action Configuration: More Info

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Configures an action to open the entity details modal. This is the default behavior if no specific action is set.

```json
{
  action: "more-info",
  entity?: "sensor.alternate_entity"  // Optional: show different entity
}
```

--------------------------------

### Get Entity State Object

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Retrieves the Home Assistant entity state object based on the provided entity ID. Returns undefined if the entity is not found.

```typescript
private getEntityStateObj(entity: string | undefined): HassEntity | undefined
```

--------------------------------

### getConfigElement

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Dynamically imports and returns the UI editor component for the Energy Flow Card Plus, enabling visual configuration of the card's settings.

```APIDOC
## getConfigElement

### Description
Dynamically imports and returns the UI editor component for visual configuration of the card.

### Method
static getConfigElement

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Promise<LovelaceCardEditor>** - UI editor element for card configuration

### Response Example
None
```

--------------------------------

### Action Configuration: Navigate

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Configures an action to navigate to a different dashboard. An error toast is shown if the navigation path is not provided.

```json
{
  action: "navigate",
  navigation_path: "/lovelace/1"
}
```

--------------------------------

### Dynamic Color Customization with Templates

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Dynamically set entity colors using Home Assistant templates that reference input text helpers. This allows for flexible color control.

```yaml
type: custom:energy-flow-card-plus

entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_production
    color:
      consumption: "#{{ state_attr('input_text.grid_color_in', 'value') }}"
      production: "#{{ state_attr('input_text.grid_color_out', 'value') }}"

  solar:
    entity: sensor.solar_production
    # Use helper to control solar color dynamically
    color: "{{ state_attr('input_text.solar_color', 'value') or '#ff9800' }}"
```

--------------------------------

### setupCustomlocalize

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Sets up custom localization for the application. It retrieves the user's selected language, looks up the translation key, and falls back to English or the key itself if no translation is found.

```APIDOC
## setupCustomlocalize

### Description
Sets up custom localization for the application. It retrieves the user's selected language, looks up the translation key, and falls back to English or the key itself if no translation is found.

### Signature
```typescript
export default function setupCustomlocalize(key: string): string
```

### Parameters
#### Path Parameters
- **key** (string) - Required - Translation key in dot notation

### Returns
`string` - Translated string or key if not found

### Behavior
- Gets user's selected language from `localStorage.selectedLanguage`
- Looks up key in language dictionary
- Falls back to English if translation not found
- Returns original key if no translation exists

### Example
```typescript
setupCustomlocalize('card.label.car')      // "Car" (English)
setupCustomlocalize('card.label.motorbike') // "Motorcycle" (English)
setupCustomlocalize('unknown.key')          // "unknown.key" (fallback)
```

### Supported Languages
| Code | Language |
|------|----------|
| en | English |
| de | Deutsch (German) |
| pt_PT | Português (Portugal) |
| pt_BR | Português (Brasil) |
| es | Español (Spanish) |
| nl | Nederlands (Dutch) |
| it | Italiano (Italian) |
| fr | Français (French) |
| ru | Русский (Russian) |
| fi | Suomi (Finnish) |
| pl | Polski (Polish) |
| cs | Čeština (Czech) |
| dk | Dansk (Danish) |
| sk | Slovenčina (Slovak) |
| sv | Svenska (Swedish) |
```

--------------------------------

### Get Translated String Helper Function

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

This internal helper function retrieves a translated string for a given key and language. It splits the key by '.' and traverses the language dictionary. It is called by setupCustomlocalize.

```typescript
function getTranslatedString(key: string, lang: string): string | undefined
```

--------------------------------

### Minimal Grid Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/README.md

Configure the card to display only grid power. Useful for basic energy monitoring.

```yaml
type: custom:energy-flow-card-plus
entities:
  grid:
    entity: sensor.grid_power
    power_outage:
      entity: sensor.power_outage
    display_state: one_way
    color_circle: true
kilo_threshold: 10000
```

--------------------------------

### Numeric Entity State Formats

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/00-readme.md

Energy entities must provide numeric values. These examples show valid state formats, including large values that will be auto-converted based on their unit of measurement.

```python
"1234"      # 1234 Wh
"1.5"       # 1.5 Wh
"2000000"   # 2 MWh (if unit is MWh)
```

--------------------------------

### Open UI Editor using JavaScript

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Programmatically open the UI editor for the Energy Flow Card Plus by calling `getConfigElement`. This returns the custom element for the editor.

```typescript
// Open UI editor for card configuration
const editor = await EnergyFlowCardPlus.getConfigElement()
// Returns: <energy-flow-card-plus-editor> element
```

--------------------------------

### Configuration Application

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Explains how the setConfig function validates and applies the user-provided configuration, including entity extraction and default value coercion.

```javascript
setConfig(config) called
  ↓
┌─ Validate config object
│
├─ Check for required entities (battery/grid/solar)
│
├─ Coerce numeric values to defaults:
│  ├─ min_flow_rate → 0.75
│  ├─ max_flow_rate → 6
│  ├─ wh_decimals → 1
│  ├─ kwh_decimals → 1
│  ├─ wh_kwh_threshold → 0
│  ├─ kwh_mwh_threshold → 1000000
│  ├─ max_expected_energy → 2000
│  └─ min_expected_energy → 0.01
│
├─ Store config in _config property
│
├─ populateEntitiesArr():
│  └─ Extract all entity IDs from config
│     └─ Result: this.entitiesArr = [...]
│
└─ resetSubscriptions():
   └─ Trigger Lit element re-render
   └─ Subscribe to Home Assistant data
```

--------------------------------

### Get Statistics for Energy Data

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Fetches historical statistics for given entities and a time period from the energy data. Requires a Home Assistant instance, energy data object, and a list of entity IDs.

```typescript
export async function getStatistics(
  hass: HomeAssistant,
  data: EnergyData,
  entityIds: string[]
): Promise<Record<string, number>>
```

--------------------------------

### Card Instance Creation

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Details the instantiation of the card element when a user adds it to their dashboard.

```html
User adds card to dashboard
  ↓
<energy-flow-card-plus> element instantiated
  ↓
LitElement lifecycle begins
  ↓
@property hass is set by Home Assistant
```

--------------------------------

### Get Entity State

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Retrieves the numeric state of an entity, coercing it to a number or returning 0 if unavailable. It selects the state from either energy data or Home Assistant's instantaneous states based on configuration.

```typescript
private getEntityState(entity: string | undefined, instantaneousValue?: boolean): number
```

--------------------------------

### Grid, Solar, and Battery Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/README.md

Integrate grid, solar, and battery entities to show a comprehensive energy flow. Includes state of charge for the battery.

```yaml
type: custom:energy-flow-card-plus
entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_production
    display_state: one_way
    color_circle: true
  solar:
    entity: sensor.solar_production
  battery:
    entity:
      consumption: sensor.battery_consumption
      production: sensor.battery_production
    state_of_charge: sensor.battery_state_of_charge
    display_state: one_way
    color_circle: true
  home:
    color_icon: true
kilo_threshold: 10000
```

--------------------------------

### Get Entity State in Watt-hours

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Calculates the total energy value in Watt-hours (Wh) for a given entity or array of entities. Handles unit conversions from kWh and MWh, sums values, and logs errors for unavailable entities.

```typescript
private getEntityStateWatthours(entity: baseEntity | undefined, instantaneousValue?: boolean): number
```

--------------------------------

### Missing Energy Integration Handling

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Shows a scenario where the Energy Integration is required but not set up. The card will display an error message and suggests solutions.

```yaml
type: custom:energy-flow-card-plus
energy_date_selection: true  # Requires energy integration
entities:
  grid:
    entity: sensor.grid_consumption
```

--------------------------------

### Step 2: Handle Solar Over-Export

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Adjusts solar energy flows when production exceeds immediate home needs and export capacity, prioritizing battery charging and grid export.

```plaintext
IF solar.state.toHome < 0:  // More being exported than produced
  
  IF battery available:
    grid.state.toBattery = abs(solar.state.toHome)
    
    IF grid.state.toBattery > grid.state.fromGrid:
      battery.state.toGrid = min(grid.state.toBattery - grid.state.fromGrid, 0)
      grid.state.toBattery = grid.state.fromGrid
    
  solar.state.toHome = 0
```

--------------------------------

### Data Flow Diagram

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Illustrates the interaction between Home Assistant, the Energy Date Selection Card, and the Energy Flow Card Plus. It shows how data flows from energy integrations and entity states to the card for rendering.

```mermaid
graph TD
    subgraph Home Assistant
        EI[Energy Integration]
        EDS[Energy Date Selection Card]
        ES[Entity State Subscriptions]
    end

    subgraph Energy Flow Card Plus
        EFC[EnergyFlowCardPlus (Lit Element)]
        SVG[SVG Canvas]
        EH[Event Handlers]
    end

    EI -- Tracks consumption/production --> EDS
    EDS -- User selects time period --> EDS
    EDS -- Triggers updates --> EFC
    EI -- Subscriptions --> EFC
    ES -- Real-time entity data --> EFC
    EFC -- Renders --> SVG
    SVG -- User interaction --> EH
    EH -- Handles events --> EFC
    EFC -- Updates --> SVG
    EFC -- Properties --> hass
    EFC -- Properties --> _config
    EFC -- Properties --> _data
    EFC -- Properties --> states
    EFC -- Properties --> entitiesArr
    EFC -- Properties --> _width
    EFC -- Properties --> error
    EFC -- Methods --> render
    EFC -- Methods --> setConfig
    EFC -- Methods --> hassSubscribe
    EFC -- Methods --> getEntityState
    EFC -- Methods --> circleRate
    EFC -- Methods --> mapRange
    EFC -- Methods --> internal_methods
    ES -- Used for instantaneous values --> battery_state
    ES -- Used for instantaneous values --> grid_presence
    ES -- Used for instantaneous values --> power_outage
    ES -- Used for instantaneous values --> secondary_info
    ES -- Used for energy/statistical --> consumption_totals
    ES -- Used for energy/statistical --> production_totals
    ES -- Used for energy/statistical --> flow_calculations
    EDS -- Enables --> ES
    EFC -- Render --> SVG
    SVG -- DOM updates --> EFC
    EFC -- User interaction --> EH
    EH -- openDetails --> EFC
    EH -- handleAction --> EFC
```

--------------------------------

### getStubConfig

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/01-card-component.md

Provides a default configuration object for the Energy Flow Card Plus, automatically detecting available energy entities in the Home Assistant instance.

```APIDOC
## getStubConfig

### Description
Provides a stub configuration when the user creates a new card. Calls `getDefaultConfig(hass)` to auto-detect available entities.

### Method
static getStubConfig

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Record<string, unknown>** - Default configuration object with available energy entities

### Response Example
None
```

--------------------------------

### navigate

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Navigates the user to a specified path within the Home Assistant frontend. This is useful for linking to different views or dashboards.

```APIDOC
## navigate

### Description
Navigate to Home Assistant path.

### Method
navigate(el: HTMLElement, path: string): void

### Parameters
#### Path Parameters
- **el** (HTMLElement) - Required - Element to navigate from
- **path** (string) - Required - Dashboard path (e.g., "/lovelace/1")

```

--------------------------------

### Action Configuration: Toggle

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Configures an action to toggle the state of an entity (e.g., light, switch). Provides haptic feedback upon execution.

```json
{
  action: "toggle"
}
```

--------------------------------

### Action Configuration: Confirmation Dialog

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Includes a confirmation dialog before executing an action. Allows specifying custom text and exemptions for certain users.

```json
{
  action: "toggle",
  confirmation: {
    text: "Really turn off the lights?",
    exemptions: [
      {
        user: "user_id"  // Skip confirmation for specific users
      }
    ]
  }
}
```

--------------------------------

### Disable Unnecessary Features for Minimal Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Use a minimal configuration by omitting features like secondary info, power outage detection, and animations to improve performance.

```yaml
type: custom:energy-flow-card-plus

# Minimal configuration for performance
entities:
  grid:
    entity: sensor.grid_consumption
    # No secondary info
    # No power outage detection
    # No animations on secondary
```

--------------------------------

### Configure Individual Device Entity

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/03-configuration-schema.md

Set up configuration for individual devices like EV chargers or pool pumps. Supports multiple entities for a single device and extensive customization for appearance and behavior.

```yaml
entities:
  individual1:
    entity: sensor.ev_charger_power
    # Or multiple to sum
    entity:
      - sensor.ev_charger_1
      - sensor.ev_charger_2

    name: EV Charger              # Display label
    icon: mdi:car-electric        # Icon path
    
    color: "#80b8ff"             # Hex color or [R,G,B]
    color_icon: false             # Color the icon
    color_value: false            # Color the value
    color_label: false            # Color the label
    
    unit_of_measurement: kWh      # Custom unit
    unit_white_space: true        # Space before unit
    decimals: 1                   # Decimal places
    
    display_zero: false           # Show even if zero
    display_zero_state: true      # Show value if zero
    display_zero_tolerance: 5     # Hide if below value
    
    inverted_animation: false     # Reverse flow direction
    show_direction: false         # Show direction indicator
    calculate_flow_rate: true     # Auto-animate or set to seconds: 2.5
    
    secondary_info:
      entity: sensor.ev_charger_status
      unit_of_measurement: ""     # Status string
      icon: mdi:information
      template: "{{ states('sensor.ev_charger_status') }}"
      display_zero: false
      decimals: 0
      energy_date_selection: false # Use instantaneous value
    
    use_metadata: false
    invert_state: false

  individual2:
    entity: sensor.pool_pump_power
    name: Pool Pump
    icon: mdi:water-pump
    color: "#4db6ac"
    # ... same options as individual1
```

--------------------------------

### Show Home Appliances Running Count

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Display the number of active home appliances as secondary information. The 'display_zero' option ensures that zero counts are shown.

```yaml
entities:
  home:
    entity: sensor.home_consumption
    
    # Show number of active appliances
    secondary_info:
      entity: sensor.active_appliances_count
      unit_of_measurement: devices
      icon: mdi:power-plug-multiple
      display_zero: true
      decimals: 0
```

--------------------------------

### Add Resource Reference in configuration.yaml

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/README.md

If you manage your Home Assistant dashboards via YAML, add this resource reference to your configuration.yaml file to include the energy-flow-card-plus.js module.

```yaml
resources:
  - url: /local/energy-flow-card-plus.js
    type: module
```

--------------------------------

### Entity State Conversion Flow

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/05-data-flow.md

Illustrates the process of converting entity state strings to numeric values, performing unit conversions to Watt-hours (Wh), and then formatting for display in various units (Wh, kWh, MWh).

```text
Entity State (string)
  ↓
coerceNumber()  [custom utility]
  ↓
numeric value (number)
  ↓
Unit Conversion:
  ├─ If unit_of_measurement = "kWh" → multiply by 1000 → Wh
  ├─ If unit_of_measurement = "MWh" → multiply by 1000000 → Wh
  └─ Otherwise → assume already in Wh
  ↓
Internal Representation (always Wh)
  ↓
displayValue() for rendering:
  ├─ If >= kwh_mwh_threshold * 1000 → MWh (divide by 1000000)
  ├─ If >= wh_kwh_threshold → kWh (divide by 1000)
  └─ Otherwise → Wh
  ↓
Formatted Display (e.g., "2.5 kWh")
```

--------------------------------

### MoreInfoActionConfig Interface

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/02-types.md

Configuration for triggering the 'more-info' action, which opens an entity's details modal. Optionally specify an entity.

```typescript
interface MoreInfoActionConfig extends BaseActionConfig {
  action: 'more-info'
  entity?: string
  data?: {
    entity_id?: string | [string]
  }
}
```

--------------------------------

### Power Outage Handling with Backup Generator

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Configure power outage handling to show a backup generator's power during an outage. This includes displaying generator status and animating its power flow.

```yaml
entities:
  grid:
    entity: sensor.grid_consumption
    power_outage:
      entity: binary_sensor.grid_status
      state_alert: "off"
      label_alert: "BACKUP POWER ACTIVE"
      icon_alert: mdi:power-plug-outline
      # Animate generator power during outage
      entity_generator: sensor.generator_power
      calculate_flow_rate: true

  individual1:
    entity: sensor.generator_power
    name: Generator
    icon: mdi:power-plant
    color: "#ff6f00"
    display_zero: true
    calculate_flow_rate: 1.5
```

--------------------------------

### Action Configuration: Call Service

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Configures an action to call a Home Assistant service. Requires the service to be specified in 'domain.service' format and supports optional data, target, repeat, and haptic feedback.

```json
{
  action: "call-service",
  service: "light.turn_on",
  data: {
    entity_id: "light.bedroom",
    brightness: 200
  },
  target: {
    entity_id: "light.bedroom"
  },
  repeat?: 1,
  haptic?: "light"
}
```

--------------------------------

### Navigate to Home Assistant Path

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/04-utility-modules.md

Navigates the user to a specified path within the Home Assistant dashboard. The path is typically a string like "/lovelace/1".

```typescript
navigate(el, "/lovelace/1")
```

--------------------------------

### Multi-Source Energy Flow Card Configuration

Source: https://github.com/flixlix/energy-flow-card-plus/blob/main/_autodocs/06-usage-examples.md

Configure the card to display energy flow from multiple sources like solar arrays, batteries, and home consumption points. Values from multiple entities within the same category (e.g., solar) are summed.

```yaml
type: custom:energy-flow-card-plus
title: Multi-Source Energy

entities:
  grid:
    entity:
      consumption: sensor.grid_consumption
      production: sensor.grid_return
    color_circle: color_dynamically

  # Multiple solar arrays - values are summed
  solar:
    entity:
      - sensor.solar_east_production
      - sensor.solar_west_production
      - sensor.solar_south_production
    name: Total Solar

  battery:
    entity:
      consumption: sensor.battery_discharge
      production: sensor.battery_charge
    state_of_charge: sensor.battery_soc

  # Multiple home consumption points
  home:
    entity:
      - sensor.main_house_consumption
      - sensor.guest_house_consumption
      - sensor.garage_consumption

  # Wind turbine as individual device
  individual1:
    entity: sensor.wind_turbine_power
    name: Wind Turbine
    icon: mdi:weather-wind
    color: "#00bcd4"
    display_zero: true

  # Low-carbon grid percentage
  fossil_fuel_percentage:
    entity: sensor.carbon_emission_percent
    name: Grid Carbon %
    icon: mdi:leaf
    color: "#4caf50"
    state_type: percentage
```