Skip to content

README_EN.md

Latest commit

 

History

History
353 lines (268 loc) · 9.37 KB

README_EN.md

File metadata and controls

353 lines (268 loc) · 9.37 KB

HA EVCC Scheduler

Home Assistant integration for managing EV charging schedules via EVCC API.

Features

  • 🚗 Automatic Vehicle Detection: Syncs with selected vehicle in EVCC
  • ⚙️ Dynamic Plan Management: Create/update/delete repeating charging schedules
  • 🔄 Real-time Updates: WebSocket support with polling fallback
  • 🎛️ Switch Entities: Toggle plans directly from Home Assistant UI
  • 🌍 Multi-Language: German & English support
  • 📱 Custom Card Ready: WebSocket API for advanced UI integration
  • 🧪 Experimental Custom Card WS API: Disabled by default, opt-in via config checkbox (untested)
  • ✅ HACS Compatible: Install via Home Assistant Community Store

Quick Start

Installation (HACS)

  1. Open HACS → Integrations
  2. Click ⋮ → Custom Repositories
  3. Add: https://github.com/diestrohs/ha-evcc-scheduler
  4. Select Integration category
  5. Search "EVCC Scheduler" → Install
  6. Restart Home Assistant ⭐

Configuration

  1. Settings → Devices and Services
  2. Click + Create Integration
  3. Search "EVCC Scheduler"
  4. Enter:
    • Host: 192.168.1.100 (EVCC IP)
    • Port: 7070 (default)
    • Token: (if required)
    • SSL: Enable for HTTPS
    • WebSocket: Enable for real-time updates (default: enabled)
    • Polling Interval: seconds (default: 30, only if WebSocket disabled)
  5. Click Submit ✅

Usage

  • Switch entities appear as switch.evcc_repeating_plan_01, switch.evcc_repeating_plan_02, etc. (vehicle-agnostic)
  • Toggle plans directly in Home Assistant UI
  • Plan attributes include vehicle_title and vehicle_id to verify current vehicle
  • Use services to create/update/delete plans (toggle via set_repeating_plan + active field)
  • Entity IDs remain stable across vehicle changes - automations don't break!

Documentation

Requirements

  • Home Assistant 2025.12.0+
  • EVCC 0.210.2+
  • Python 3.11+
  • Network access to EVCC instance

Services

evcc_scheduler.set_repeating_plan

Create or update a repeating charging plan.

Parameters:

  • vehicle_id (required): Vehicle ID from EVCC (e.g., db:1)
  • plan_index (optional): Plan number (1-based). Omit to create new plan
  • time (optional): Start time in HH:MM format (24h)
  • weekdays (optional): Weekdays [1=Mon, 2=Tue, ..., 7=Sun]
  • soc (optional): Target state of charge (1-100%)
  • active (optional): Plan is active (true/false, default: true)
  • tz (optional): IANA timezone (defaults to Home Assistant timezone)
  • precondition (optional): Enum — 0=no precondition, 1=PV surplus only, 2=cheap prices only (defaults to 0)

Create new plan:

service: evcc_scheduler.set_repeating_plan
data:
  vehicle_id: "db:1"
  time: "07:00"
  tz: "Europe/Berlin"
  weekdays: [1, 2, 3, 4, 5]
  soc: 80
  precondition: 1
  active: true

Update existing plan:

service: evcc_scheduler.set_repeating_plan
data:
  vehicle_id: "db:1"
  plan_index: 1
  soc: 90

Toggle plan active status:

service: evcc_scheduler.set_repeating_plan
data:
  vehicle_id: "db:1"
  plan_index: 1
  active: false

evcc_scheduler.del_repeating_plan

Delete a repeating charging plan.

Parameters:

  • vehicle_id (required): Vehicle ID from EVCC (e.g., db:1)
  • plan_index (required): Plan number to delete (1-based)
service: evcc_scheduler.del_repeating_plan
data:
  vehicle_id: "db:1"
  plan_index: 1

Input Validation

  • Time must be HH:MM (00:00–23:59)
  • Weekdays must be a non-empty list of integers 1–7
  • SOC must be an integer in range 0–100
  • Active must be boolean
  • Precondition must be 0, 1 or 2 (enum)

Architecture

config_flow.py ──→ __init__.py ──→ coordinator.py ──→ api.py
    ↓                  ↓
websocket_client.py    entity_manager.py ←→ switch.py
    ↓
websocket_api.py (Custom Card API)
  • DataUpdateCoordinator: 30-second polling interval
  • WebSocket: Real-time updates with auto-reconnect
  • Entity Manager: Automatic creation/deletion based on vehicle
  • Entity Registry: Cleanup on restart and unload

Troubleshooting

Connection Issues

# Test EVCC connectivity
curl http://192.168.1.100:7070/api/state | jq '.vehicles'

# Test WebSocket
wscat -c ws://192.168.1.100:7070/ws

Enable Debug Logging

Add to configuration.yaml:

logger:
  logs:
    evcc_scheduler: debug
    evcc_scheduler.api: debug
    evcc_scheduler.coordinator: debug

Support

License

MIT License - See LICENSE for details

Changelog

See CHANGELOG.md for version history.

Version: 0.1.4
Home Assistant: 2025.12.0+
EVCC: 0.210.2+
License: MIT

Last Updated: January 24, 2026

Deutsch / German cd /config/custom_components git clone https://github.com/diestrohs/ha-evcc-scheduler.git

Home Assistant neu starten


## Konfiguration

Nach der Installation:

1. Gehe zu **Einstellungen** → **Geräte und Services** → **Integrationen**
2. Klicke auf **"+ Integration erstellen"**
3. Suche nach **"EVCC Scheduler"**
4. Folge der Konfiguration:
   - **Host**: IP oder Hostname von EVCC (z.B. `192.168.1.100`)
   - **Port**: EVCC API Port (Default: `7070`)
   - **Token**: Optional (falls EVCC Token-Auth hat)
   - **SSL**: An/Aus je nach EVCC-Setup
   - **Timeout**: HTTP-Timeout in Sekunden (Default: `10`)

## Verwendung

### Services

Die Integration stellt folgende Services zur Verfügung:

#### `evcc_scheduler.set_repeating_plan`
Erstelle oder aktualisiere einen Ladeplan

```yaml
service: evcc_scheduler.set_repeating_plan
data:
  vehicle_id: "db:1"
  plan_index: 1              # Optional: null = neuer Plan
  time: "07:00"
  weekdays: [1, 2, 3, 4, 5]  # 1=Mo, 7=So
  soc: 80
  active: true

evcc_scheduler.del_repeating_plan

Lösche einen Ladeplan

service: evcc_scheduler.del_repeating_plan
data:
  vehicle_id: "db:1"
  plan_index: 1

Plan aktiv/inaktiv setzen

Nutze evcc_scheduler.set_repeating_plan mit dem Feld active:

service: evcc_scheduler.set_repeating_plan
data:
  vehicle_id: "db:1"
  plan_index: 1
  active: true

Entities

Per charging plan, 4 entities are created:

  • Switch: switch.evcc_elroq_repeating_plan_1_activ - Activate/deactivate plan
  • Time: time.evcc_elroq_repeating_plan_1_time - Start time of the plan
  • Icon: mdi:clock-digital
  • Text: text.evcc_elroq_repeating_plan_1_weekdays - Weekdays (comma-separated: 1,2,3,4,5)
  • Number: number.evcc_elroq_repeating_plan_1_soc - Target charge in % (0-100)
  • Icon: mdi:battery-charging (UI slider step: 10; services accept any integer 0–100)

Entity Attributes (available in all entities):

  • vehicle_id: Vehicle ID (e.g. db:1)
  • vehicle_title: Vehicle name (e.g. Elroq)
  • plan_index: Plan number (1-based)
  • time, weekdays, soc, active: Plan details (only in Switch entity)
  • weekdays_list: Weekdays as list (only in Text entity)

Note: Entity IDs remain stable across vehicle changes - automations continue working!

Architecture Notes

  • Entities share a common base: base_entity.py (BaseEvccPlanEntity)
  • Provides shared fields (vehicle_id, vehicle_title, plan_index), update_data(), and unique ID helper
  • Platform setup is unified via setup_platform() to reduce boilerplate

Dokumentation

Detaillierte Dokumentation:

Voraussetzungen

  • Home Assistant 2025.12 oder neuer
  • EVCC v0.210.2 oder neuer mit aktivierter REST API
  • EVCC und Home Assistant im gleichen Netzwerk (oder erreichbar)
  • Python 3.11+

Unterstützte Fahrzeuge

Alle Fahrzeuge, die in EVCC konfiguriert sind:

  • Tesla (Model S, 3, X, Y)
  • Volkswagen (ID.4, ID.5, ID. Buzz, ID.3, etc.)
  • Škoda (Enyaq, Superb iV, Citigo iV, etc.)
  • Audi (e-tron, Q4 e-tron, e-tron GT, etc.)
  • Cupra (Born, Leon, etc.)
  • BMW (i3, i4, iX, etc.)
  • Mercedes (EQA, EQC, EQE, EQS, etc.)
  • Hyundai (Ioniq, Kona, Tucson, etc.)
  • Kia (e-Niro, EV9, EV6, etc.)
  • Nissan (Leaf, Ariya, etc.)
  • Polestar (1, 2, 3, etc.)
  • Porsche (Taycan, etc.)
  • Und weitere...

Fehlerbehandlung

Wenn die Integration nicht funktioniert:

  1. Logs prüfen:

    logger:
  logs:
    evcc_scheduler: debug

  2. EVCC-Verbindung testen:

    curl http://192.168.1.100:7070/api/state | jq '.vehicles'

  3. WebSocket testen:

    wscat -c ws://192.168.1.100:7070/ws

Support

Lizenz

MIT License - Siehe LICENSE Datei

Beitragen

Beiträge sind willkommen! Bitte lese CONTRIBUTING.md für Details.

Getestet mit:

  • Home Assistant 2025.12 ✅
  • EVCC 0.210.2 ✅
  • Python 3.12 ✅