Skip to content

hardware-integrations.md

Latest commit

 

History

History
148 lines (114 loc) · 4.76 KB

hardware-integrations.md

File metadata and controls

148 lines (114 loc) · 4.76 KB

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.