Integration Guide - rogasp/evlink-backend GitHub Wiki

Follow these steps to connect your EV to EVLinkHA and Home Assistant.

1. Create an Account

  1. Go to [evlinkha.se/register](https://evlinkha.se/register)
  2. Log in using Magic Link or GitHub

2. Create API Key

  1. Go to your [Profile](https://evlinkha.se/profile)
  2. Click "Create API Key" and copy the key

3. Link Your Vehicle

  1. Go to the Dashboard
  2. Click "Link Vehicle" and follow the manufacturer’s login
  3. Currently, only XPENG is supported. More brands will follow.
  4. After linking, click "Copy ID" to get your Vehicle ID

4. Configure Home Assistant

secrets.yaml

# Add your API credentials and base URL
evlink_api_key: "Bearer <API_CODE>"
evlink_status_url: "https://evlinkha.se/api/status/<VEHICLE_ID>"
evlink_vehicle_id: "<YOUR_VEHICLE_ID>"

configuration.yaml

sensor:
  - platform: rest
    name: "EVLink Vehicle"
    unique_id: "evlink_vehicle_sensor"
    resource: !secret evlink_status_url
    method: GET
    headers:
      Authorization: !secret evlink_api_key
    value_template: "{{ value_json.vehicleName }}"
    scan_interval: 300
    json_attributes:
      - vendor
      - vehicleName
      - lastSeen
      - isReachable
      - chargingState
      - chargeState
      - information
      - location
      - odometer
      - smartChargingPolicy

⚠️ Rate limit recommendations:

  • Free tier (3 calls / 30 min): set scan_interval ≥ 600 s
  • Pro tier (60 calls / min; soon ~10 calls/minute/vehicle): set scan_interval ≥ 60 s
  • Exceeding these limits returns 429 Too Many Requests.

5. Verify in Home Assistant

  1. Go to Developer Tools → States
  2. Search for sensor.evlink_battery_level, sensor.evlink_is_charging etc.
  3. Ensure values update at your chosen interval

6. On-Demand Charging Control

6.1 REST Command

Add to your configuration.yaml:

rest_command:
  evlink_control_charging:
    url: "https://evlinkha.se/api/charging/{{ vehicle_id }}"
    method: POST
    headers:
      Authorization: !secret evlink_api_key
    content_type: application/json
    payload: >
      {
        "action": "{{ action }}"
      }

6.2 Input Boolean Toggle

input_boolean:
  evlink_charging_toggle:
    name: EVLink Charging Control
    icon: mdi:battery-charging-80

6.3 Template Switch

switch:
  - platform: template
    switches:
      evlink_charging_control:
        friendly_name: "EVLink Charging Control"
        value_template: >
          {{ state_attr('sensor.evlink_vehicle', 'chargeState').isCharging | default(false) }}
        turn_on:
          service: rest_command.evlink_control_charging
          data:
            vehicle_id: !secret evlink_vehicle_id
            action: "START"
        turn_off:
          service: rest_command.evlink_control_charging
          data:
            vehicle_id: !secret evlink_vehicle_id
            action: "STOP"

6.4 Automation (Rollback & Notify)

- id: 'evlink_toggle_handler'
  alias: EVLinkHA – Charging Toggle Handler
  description: >
    Calls the EVLinkHA API when the charging toggle flips,
    then rolls it back + notifies on failure.
  mode: single

  trigger:
    platform: state
    entity_id: input_boolean.evlink_charging_toggle

  action:
    - choose:
        - conditions:
            - "{{ trigger.to_state.state == 'on' }}"
          sequence:
            - service: rest_command.evlink_control_charging
              data:
                vehicle_id: !secret evlink_vehicle_id
                action: "START"
        - conditions:
            - "{{ trigger.to_state.state == 'off' }}"
          sequence:
            - service: rest_command.evlink_control_charging
              data:
                vehicle_id: !secret evlink_vehicle_id
                action: "STOP"

    - delay:
        seconds: 5

    - choose:
        - conditions:
            - "{{ trigger.to_state.state == 'on' }}"
            - "{{ not state_attr('sensor.evlink_vehicle', 'chargeState').isCharging }}"
          sequence:
            - service: input_boolean.turn_off
              target:
                entity_id: input_boolean.evlink_charging_toggle
            - service: persistent_notification.create
              data:
                title: "EVLinkHA Charging"
                message: "❌ Failed to start charging: invalid vehicle state."

        - conditions:
            - "{{ trigger.to_state.state == 'off' }}"
            - "{{ state_attr('sensor.evlink_vehicle', 'chargeState').isCharging }}"
          sequence:
            - service: input_boolean.turn_on
              target:
                entity_id: input_boolean.evlink_charging_toggle
            - service: persistent_notification.create
              data:
                title: "EVLinkHA Charging"
                message: "❌ Failed to stop charging: vehicle still charging."

6.5 Lovelace Grid Card

type: grid
columns: 2
square: false
cards:
  - type: gauge
    entity: sensor.evlink_battery_level
    name: Battery
    min: 0
    max: 100
    unit: "%"
    severity:
      green: 60
      yellow: 10
      red: 0
    needle: true

  - type: sensor
    entity: sensor.evlink_battery_range
    name: Range
    icon: mdi:map-marker-distance
    unit: km

  - type: entity
    entity: binary_sensor.evlink_is_plugged_in
    name: Plugged In
    icon: mdi:power-plug

  - type: entity
    entity: binary_sensor.evlink_is_charging
    name: Charging
    icon: mdi:battery-charging

  - type: sensor
    entity: sensor.evlink_charge_rate
    name: Charging rate
    icon: mdi:ev-station
    unit: kW

  - type: entity
    entity: switch.evlink_charging_control
    name: EVLink Charging
    icon: mdi:battery-charging-80

grid_options:
  columns: full
⚠️ **GitHub.com Fallback** ⚠️