evcc-io/docs/agents/hardware-integrations.md

Hardware Integrations: Chargers, Meters, Vehicles

Integration Pattern

All device types use a registry-based factory pattern:

// Self-registration in init()
func init() {
    registry.AddCtx("typename", NewFromConfig)
}

func NewFromConfig(ctx context.Context, other map[string]interface{}) (api.Charger, error) {
    // Parse config, create client, return implementation
}

Optional interfaces are added via the decorator pattern:

//go:generate decorate -f decorateXxx -b *Xxx -t "api.PhaseSwitcher,Phases1p3p,func(int) error"

Charger Implementations

By Protocol

Protocol	Examples
HTTP/REST	Easee (REST+SignalR), Wallbox, go-e, OpenWB, Shelly
Modbus RTU/TCP	KEBA, Wallbe, CFOS, Bender, Delta, Mennekes
OCPP 1.6	Generic charge point server
EEBus/ISO 15118	EEBus SPINE protocol
UDP/Custom	KEBA UDP, OpenEVSE, Wattpilot, NRGKick
MQTT	OpenWB, Tasmota, Shelly
Smart Socket	Shelly, Tapo, TP-Link, FritzDECT

Required Charger Interface

type Charger interface {
    ChargeState
    Enabled() (bool, error)
    Enable(enable bool) error
    CurrentController
}

Where ChargeState provides Status() (ChargeStatus, error) (A/B/C) and CurrentController provides MaxCurrent(current int64) error.

Optional Charger Interfaces

• ChargerEx — MaxCurrentMillis(float64) for milliamp precision
• PhaseSwitcher — Phases1p3p(int) to switch 1p/3p
• Meter / MeterEnergy — built-in power/energy measurement
• PhaseCurrents / PhaseVoltages — per-phase readings
• ChargeRater — ChargedEnergy() for session energy
• ChargeTimer — ChargeDuration() for session time
• Identifier — Identify() for RFID/vehicle identification

Key Implementations

• Easee — REST + async SignalR; see docs/agents/easee-architecture.md for full detail
• OCPP (charger/ocpp.go) — Full 1.6 with charge point management
• go-e — Dual API (v1 local HTTP, v2 cloud); phase switching on v2
• EEBus — Complex SPINE protocol with USE cases (CEM, EV, EVCC)
• Generic configurable (charger/charger.go) — plugin-driven via YAML template

Adding a New Charger

1. Create charger/xxx.go (or YAML template in templates/definition/charger/)
2. Implement NewXxxFromConfig() returning api.Charger
3. Required: Status(), Enabled(), Enable(), MaxCurrent()
4. Register: registry.AddCtx("xxx", factory) in init()
5. Optional: add decorator for PhaseSwitcher, Meter, etc.
6. Add template: templates/definition/charger/xxx.yaml for UI metadata

Meter Implementations

By Category

Category	Examples
Modbus/SunSpec	SDM630, SMA, Fronius, Victron
HTTP/REST	Homewizard, Shelly Gen3, E3DC
Smart Home	HomeAssistant entities, Homematic
Battery/Storage	Tesla Powerwall, LG ESS, Zendure

Required Meter Interface

type Meter interface {
    CurrentPower() (float64, error)  // watts
}

Optional: MeterEnergy, PhaseCurrents/Voltages/Powers, Battery, BatteryCapacity

Key Implementations

• mbmd (meter/mbmd.go) — RS485 device library with auto-detection
• SunSpec (plugin/sunspec.go) — Modbus model-based point queries
• Generic — plugin-driven (HTTP, Modbus, MQTT sources)

Vehicle Integrations

Manufacturer	API Type
Tesla	Fleet API + vehicle-command proxy
VW Group	WeConnect (VW, Audi, Skoda, Seat, Cupra)
Hyundai/Kia	BlueLink (regional variants)
BMW/Mini	ConnectedDrive v2
Mercedes	Official API
Renault/Nissan	Renault API + Carwings
Ford	FordConnect (US/EU)
Porsche	Porsche Connect
PSA Group	Peugeot, Citroen, DS, Opel
Generic	OVMS, Tronity

Required Vehicle Interface

type Vehicle interface {
    Battery          // Soc() (float64, error)
    BatteryCapacity  // Capacity() float64
    IconDescriber    // Icon() string
    FeatureDescriber // Features() []Feature
    PhaseDescriber   // Phases() int
    TitleDescriber   // GetTitle() string
    SetTitle(string)
    Identifiers() []string
    OnIdentified() ActionConfig
}

Optional: SocLimiter, ChargeState, VehicleRange, VehicleOdometer, VehicleClimater, VehicleFinishTimer, VehiclePosition, CurrentLimiter, CurrentController, ChargeController, Resurrector

Polling Strategy

Configurable: always / while charging / while connected. Interval-based caching to avoid excessive cloud API calls. OAuth2 token handling built into each provider.

Auto-Detection (cmd/detect/)

Task-based parallel IP scanning: ping -> tcp_http -> tcp_modbus -> sunspec -> device-specific probes

Detects: OpenWB, SMA, KEBA, E3DC, Sonnen, Tesla Powerwall, Wallbe, Fronius, Tasmota, Shelly, Phoenix, and many more.