EV Trip Planner Integration — Multi-Trip Deferrable Load Management

[informatico-madrid]

EV Trip Planner Integration — Multi-Trip Deferrable Load Management

Status: MVP Experimental — Seeking Contributors
Repository: informatico-madrid/ha-ev-trip-planner
Version: 0.5.24

---

Overview

This is an experimental Home Assistant custom component that manages EV charging schedules through EMHASS deferrable loads. It's currently an MVP — functional but with known technical debt and areas needing improvement.

The component transforms EV trip data (distance, departure/return times, charging power) into EMHASS-compatible deferrable load profiles, supporting multiple simultaneous trips with independent optimization per trip.

---

What Works

Window Calculation Algorithm (Core Contribution)

This is where the real innovation lies. The component implements a multi-dimensional charging window calculation that solves the EV charging scheduling problem across multiple trips with constrained time windows — a significantly more complex challenge than simple charging calculations.

The Algorithm Pipeline

Trip Data → Energy Calculation → Multi-Trip Windows → Hours Deficit Propagation → Power Profile
   │              │                    │                      │                      │
   │              │                    │                      │                      └─ 168h matrix (Watts per timestep)
   │              │                    │                      └─ Backward pass: redistribute unmet hours
   │              │                    └─ Chained windows across trips
   │              └─ kWh per trip (distance × efficiency + safety margin)
   └─ distance, kwh/100km, type, departure, return, deadlines

Step 1: Energy Calculation per Trip

def calculate_energy_needed(trip: Dict, vehicle: Dict) -> float:
    """Calculate energy needed for a single trip with safety margin."""
    base_energy = trip['distance'] * vehicle['efficiency_kwh_km']
    soc_margin = calculate_safety_margin(trip['target_soc'], vehicle['current_soc'])
    return base_energy + soc_margin

Step 2: Multi-Trip Window Calculation

The core function calculate_multi_trip_charging_windows() chains charging windows across multiple trips:

def calculate_multi_trip_charging_windows(trips: List[Dict]) -> List[Window]:
    """
    Calculate coordinated charging windows across multiple journeys.
    
    Each trip produces a window defined by:
    - start: latest(departure_time, current_time)
    - end: earliest(return_time, deadline)
    - hours_needed: energy / charging_power
    
    Windows are chained considering:
    - Vehicle presence (home/away states)
    - Return times between trips (rest periods)
    - Departure times for next trip
    - Hard deadlines that cannot be moved
    """

The algorithm considers:

• Vehicle presence: Charging can only happen when vehicle is present (detected via presence sensors or coordinates)
• Return times: Between trips, the vehicle returns home — this creates rest periods
• Departure times: Each trip has a latest departure that must be met
• Hard deadlines: Punctual trips (e.g., airport) have fixed time windows

Step 3: Backward Pass — Hours Deficit Propagation

When the total available time across all windows is insufficient for the required charging hours, the algorithm performs a backward pass to redistribute the deficit:

def calculate_hours_deficit_propagation(windows: List[Window]) -> List[Window]:
    """
    Backward pass: redistribute unmet charging hours across trips.
    
    If trip N needs 10 hours but only has 6 available:
    - The 4-hour deficit is propagated backward to trips N-1, N-2, etc.
    - Each preceding trip gets additional charging headroom
    - Priority is given to trips with higher SOC targets
    
    This ensures you NEVER run out of charge before a critical trip.
    """

Example:

Trip A (home→work):  needs 6h, has 8h available → surplus 2h
Trip B (work→home): needs 10h, has 6h available → deficit 4h
Trip C (home→airport): needs 8h, has 8h available → exactly enough

After backward propagation:
Trip A: 8h (absorbs 2h from Trip B's deficit)
Trip B: 6h (unchanged — can't get more)
Trip C: 10h (gets 2h from Trip A's surplus)

Step 4: SOC Milestone Deficit Propagation

A parallel backward pass handles SOC milestones:

def calculate_deficit_propagation(windows: List[Window]) -> List[Window]:
    """
    Backward pass for SOC milestone deficits.
    
    Ensures that safety margins at specific SOC levels are maintained.
    For example, if SOC drops below 20%, additional charging headroom
    is allocated from preceding windows.
    """

Step 5: Power Profile Generation

The final step generates the 168-hour power profile matrix:

def calculate_power_profile_from_trips(trips: List[Dict], windows: List[Window]) -> List[int]:
    """
    Generate 168h power profile (Watts per timestep, 1h resolution).
    
    Returns array of 168 values where each value is:
    - 0: no charging scheduled
    - P_nom: charging at nominal power (e.g., 2200W)
    - Partial values: for fractional power control (future)
    """

Dynamic Index Management

Each trip gets an EMHASS index (0-49) with persistence across restarts:

• Soft-delete with cooldown: Released indices have a configurable cooldown period before reuse
• Index mapping: Stored in config entry storage, survives HA restarts
• Vehicle cleanup: When a vehicle is removed, all associated indices are cleaned up

EMHASS Integration

The component creates a template sensor with 6 attributes that map directly to EMHASS parameters:

HA Sensor Attribute	EMHASS Parameter	Description
number_of_deferrable_loads	number_of_deferrable_loads	Count of active trips
def_total_hours_array	def_total_hours	Hours needed per trip
p_deferrable_nom_array	P_deferrable_nom	Nominal power (W) per trip
def_start_timestep_array	def_start_timestep	Earliest start per trip
def_end_timestep_array	def_end_timestep	Deadline per trip
p_deferrable_matrix	P_deferrable	168h power profile matrix

Jinja2 Template Integration

Users configure EMHASS via Jinja2 templates in optimize.yaml:

number_of_deferrable_loads: {{ state_attr('sensor.ev_trip_planner_vehicle_emhass_aggregated', 'number_of_deferrable_loads') | default(0) }}
def_total_hours: {{ state_attr('sensor.ev_trip_planner_vehicle_emhass_aggregated', 'def_total_hours_array') | default([], true) | tojson }}
p_deferrable_nom: {{ state_attr('sensor.ev_trip_planner_vehicle_emhass_aggregated', 'p_deferrable_nom_array') | default([], true) | tojson }}
def_start_timestep: {{ state_attr('sensor.ev_trip_planner_vehicle_emhass_aggregated', 'def_start_timestep_array') | default([], true) | tojson }}
def_end_timestep: {{ state_attr('sensor.ev_trip_planner_vehicle_emhass_aggregated', 'def_end_timestep_array') | default([], true) | tojson }}
P_deferrable: {{ state_attr('sensor.ev_trip_planner_vehicle_emhass_aggregated', 'p_deferrable_matrix') | default([], true) | tojson }}

---

Known Issues and Areas for Improvement

1. Control Panel UX (Technical Debt)

The current control panel has inherited technical debt from an earlier development phase. It uses hardcoded CSS gradients and lacks proper theming integration. The panel works functionally but the code quality is below the project's current standards.

What needs improvement:

• Remove hardcoded CSS gradients, use HA theme variables
• Consider migrating to the native panel (Lit web components) which is already partially implemented
• Better responsive design for mobile

2. SOC-Based Charging Start/Stop Automation

The component does not currently include automations for starting/stopping charging based on SOC thresholds. This is a planned feature but currently requires manual configuration.

What's needed:

• Automation template for "start charging when SOC < X%"
• Automation template for "stop charging when SOC >= Y%"
• Integration with vehicle integration (Renault, Tesla, etc.)
• Configurable SOC thresholds per vehicle

3. Single Optimizer Dependency

Currently, the component only supports EMHASS as the optimization backend. The architecture uses emhass_adapter.py as an adapter pattern, prepared to add other optimizers (Tibber, custom) in the future, but this is not implemented.

What's needed:

• DeferrableLoadOptimizer protocol/interface
• Concrete implementations for different optimizers
• Configuration option to select optimizer per vehicle

4. Planning Horizon is Static

The planning horizon is fixed at 7 days by default and configurable but static. It does not dynamically adapt to EMHASS's actual planning horizon.

What's needed:

• Auto-detect EMHASS planning horizon from its configuration
• Dynamic adjustment of trip scheduling windows

---

Planned Improvements and Welcome Contributions

The following features are planned and contributions are welcome. If any of these interest you, please open an issue or PR.

High Priority

1. SOH (State of Health) Integration

   • Account for battery degradation when calculating charging needs
   • Adjust energy targets based on actual battery capacity vs. nominal
   • Integrate with vehicle APIs that expose SOH (e.g., Tesla, Renault)
   • Why it matters: As battery degrades, the same kWh input delivers less range. SOH-aware charging ensures you still reach your target range.

2. Dynamic Charging Power

   • Add a boolean field to the config flow to enable/disable dynamic charging power control
   • When enabled, emhass handles power limiting dynamically based on real-time conditions (TOU tariffs, grid consumption, battery health)
   • Why it matters: A single toggle gives you all the benefits: slower charging for battery longevity, cost optimization via TOU-aware limits, and grid-aware consumption management — all powered by emhass.

3. SOC-Based Charging Start/Stop Automations

   • Automation templates for "start charging when SOC < X%"
   • Automation templates for "stop charging when SOC >= Y%"
   • Integration with vehicle integration (Renault, Tesla, etc.)
   • Configurable SOC thresholds per vehicle

Medium Priority

4. Multi-Vehicle Support

   • Current design assumes one vehicle per config entry
   • EMHASS supports up to 50 simultaneous deferrable loads
   • Challenge: Window calculation across multiple vehicles with different schedules

5. Optimizer Abstraction

   • Currently EMHASS-only, but architecture prepared for pluggable optimizers
   • Define DeferrableLoadOptimizer protocol/interface
   • Concrete implementations for different optimizers (Tibber, custom)

Low Priority

6. Smart Learning

   • Learn from historical charging patterns
   • Predict trips automatically from GPS history
   • Adjust efficiency estimates based on actual consumption

7. Dynamic Planning Horizon

   • Auto-detect EMHASS planning horizon from its configuration
   • Dynamic adjustment of trip scheduling windows

---

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Home Assistant                        │
│                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────┐ │
│  │ Trip Manager │───▶│ Coordinator  │───▶│ Sensors   │ │
│  │ (business    │    │ (update cycle│    │ (EMHASS   │ │
│  │  logic)      │    │  every 30s)  │    │  attrs)   │ │
│  └──────────────┘    └──────────────┘    └───────────┘ │
│         │                                      │        │
│         │                                      ▼        │
│         │                            ┌──────────────────┐│
│         │                            │ EMHASS Adapter   ││
│         │                            │ (Jinja2 → YAML)  ││
│         │                            └──────────────────┘│
│         │                                      │        │
│         └──────────────────────────────────────┘        │
│                                                          │
│  User Config (optimize.yaml) ◀── Jinja2 Templates        │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│         EMHASS Server           │
│  (dayahead-optim / action)      │
└─────────────────────────────────┘

Key Components

Component	File	Lines	Purpose
Trip Manager	trip_manager.py	~2244	Core business logic
EMHASS Adapter	emhass_adapter.py	~2407	Deferrable load mapping
Calculations	calculations.py	~1395	Charging algorithms
Coordinator	coordinator.py	Data update cycle
Sensor	sensor.py	~961	Entity definitions
Config Flow	config_flow.py	~949	UI configuration
Services	services.py	~1592	Service handlers

Total: ~12,432 lines of Python code, 18 modules, 85+ unit tests, 8 E2E specs.

---

Development Methodology (Optional Context)

This project was developed using an AI-assisted spec-driven development methodology with:

• 6 methodological phases documented
• Phase 5: Agentic Verification Loop (unique contribution)
• 23 AI skills (12 domain-specific + 11 framework)
• Parallel QA review during implementation

This context is provided because it explains the architectural decisions and documentation quality. If you're interested in the development approach, see the _ai/ directory in the repository.

---

How to Contribute

High Priority Contributions (Most Needed)

1. SOH (State of Health) Integration — Medium/Complex

   • Account for battery degradation in energy calculations
   • Integrate with vehicle APIs exposing SOH data

2. Dynamic Charging Power — Trivial

   • Add a boolean field to the config flow to enable/disable dynamic charging power control
   • When enabled, emhass handles the power limiting dynamically based on real-time conditions

3. SOC-Based Automations — Quick Win

   • Create automation templates for start/stop charging based on vehicle SOC

Quick Wins (Good for First-Time Contributors)

1. Panel UX improvements: Replace hardcoded CSS with HA theme variables
2. Documentation: Add examples for specific vehicle integrations (Renault, Tesla, etc.)
3. Testing: Increase coverage on edge cases (empty trips, overlapping schedules)

Medium Complexity

1. Dynamic planning horizon: Auto-detect EMHASS horizon
2. Optimizer protocol: Define interface for pluggable optimizers
3. Multi-vehicle support: Current design assumes one vehicle per config entry

Complex

1. Full optimizer abstraction: Replace EMHASS-specific code with protocol-based design
2. Smart learning: Learn from historical charging patterns

---

Getting Started

Prerequisites

• Home Assistant 2024.x or later
• EMHASS installed and configured
• EV with known energy consumption (kWh/100km)

Installation

1. Install via HACS (preferred) or manually
2. Configure your vehicle in Home Assistant UI
3. Copy the Jinja2 template to your EMHASS optimize.yaml
4. Create trips and verify EMHASS sensors

Testing

# Run unit tests
pytest tests/ -v

# Run E2E tests
npx playwright test tests/e2e/

---

Questions I'd Like Community Input On

1. SOH integration: What vehicle APIs expose SOH data reliably? Should SOH be a separate integration layer or built into the component?

2. Maximum charging power: How do others manage max charging power limits? Is time-of-use aware limiting common?

3. SOC integration: What's the best approach for vehicle SOC integration and start/stop automations?

4. Optimizer abstraction: Has anyone implemented a similar pattern for pluggable optimization backends? What's the cleanest interface?

5. Multi-vehicle: How do others handle multiple EVs with EMHASS? Is the current single-vehicle-per-entry design a limitation?

6. Window calculation: Has anyone implemented a similar backward deficit propagation algorithm for other deferrable load types (thermal batteries, home batteries)?

---

License

MIT License — See LICENSE file for details.

---

This is an experimental MVP. Use at your own risk. The author is actively seeking contributors and collaborators.

[davidusb-geek]

Hi and wow!
That's a lot of work and what seems a very nice tool for EV planning using EMHASS.
Do you have any results examples (tables, graphs) showing the output of your tool in action?
Do you plan to keep it as a custom component for HA?
What is MVP?

[informatico-madrid]

Thank you for the kind words! Let me address each question:

What is MVP?

You're right, I should have been clearer. MVP = Minimum Viable Product — the minimum set of features that delivers real value to users. In our case, that means the core charging window calculation and EMHASS sensor integration work correctly, but there are known areas that need polish (panel UX, automations, etc.).

Do you have results examples?

Honestly — not yet anything visually impressive to show. The current functional output is the sensor attributes that get passed in the optimization request to EMHASS via the shell command. Here's what I can share:

What the sensors produce right now:

The component creates per-trip sensors with these attributes that map directly to EMHASS deferrable load parameters:

• def_total_hours — hours of charging needed per trip
• P_deferrable_nom — nominal charging power (W)
• def_start_timestep / def_end_timestep — time window for each trip
• power_profile_watts — power profile matrix per trip

These are passed to EMHASS via Jinja2 templates in the shell command that triggers the optimization.

Real-world usage:

I'm currently testing it in my own home with my daily driver. I've set up all my weekly trips and the component is correctly sending the planning data to EMHASS. EMHASS then optimizes when to charge based on my trip schedule.

In my case, I have a large home battery so I use weekly planning in EMHASS — which means I pass a 168-hour profile. This is where the multi-trip window calculation really shines: coordinating charging across a full week of trips. For users with standard 24-hour planning horizons, the component still works but the value proposition is more limited — a daily schedule with one or two trips is a simpler problem to solve manually.

One thing I've noticed that would be nice to expose: the soc_target for each trip departure is calculated internally but not currently visible in the sensor output. It would be useful to show this so users can verify the planned SOC before each trip.

If it would be helpful, I could share:

After running it for a full week in production, I could put together a table showing:

• How the sensor values evolved across different trip configurations
• SOC variation over the week vs. the planned charging windows
• Before/after comparison: EMHASS optimization with and without the trip planner data

This would be more meaningful than a screenshot of sensor attributes — but let me know if that level of detail is useful or if the technical description above is sufficient.

An improvement I'm already seeing the need for:

When EMHASS detects that energy is very cheap and abundant, it may schedule charging well in advance, leaving the car sitting at a high SOC for many hours. This is not ideal for battery health — and for some vehicles like my Nissan Leaf (30kWh), it's particularly bad. I'm planning to add a configurable dynamic SOC limit that caps the maximum SOC based on how many hours remain until the next trip departure. For example, if the car won't be used for 3 days, there's no reason to charge it to 100% even if energy is practically free. This parameter would be vehicle-specific since battery degradation sensitivity varies significantly between models.

Do you plan to keep it as a custom component for HA?

Yes, absolutely. The plan is:

1. Short term — Stay as a HACS custom component, stabilize the core functionality, fix the known issues mentioned in the post
2. Medium term — Improve the UX, add SOH support, wire up the automatic charging control (the code exists but isn't connected yet)

The custom component approach gives us flexibility to iterate quickly without being tied to HA core release cycles. And the Jinja2 template bridge to EMHASS means users can adopt it incrementally without changing their existing EMHASS setup.

---

Thanks again for the interest!. And if anyone wants to test it with their own vehicle/EMHASS setup, I'm happy to help with configuration.

[davidusb-geek]

• Before/after comparison: EMHASS optimization with and without the trip planner data

This will be the graal ;-)
Have a look at discussion #824, what would be nice is to add your tool as a part of your own cookbook, so that we can document a real tutorial on how to use your tool and link it to EMHASS with the jinja2 templating. Also it would be the place to showcase your results and tempt people to use it!

[informatico-madrid]

Before/after comparison

Agreed — that comparison is the goal. I plan to run a full week of production data and document the difference between EMHASS optimization with and without trip planner data. I'll try to create a visual diagram showing how the charging profile changes when the optimizer has trip schedule information vs. when it doesn't — to make it clear and easy to understand at a glance.

Cookbook contribution

The idea of contributing EV Trip Planner as an official EMHASS cookbook example is great. The real value case is: multi-trip deferrable load management with temporal dependencies and backward deficit propagation — which is exactly the pattern described in discussion #824.

EMHASS has been a huge help in my daily life, so I'm happy to contribute back. I'll submit a PR for the EMHASS cookbook documenting this use case: how to manage multiple EV charging trips with different schedules, recurring patterns, and cascading hour-deficit constraints — all driven through Home Assistant.