Škoda in Home Assistant: handleiding

Met deze handleiding lees je je Škoda uit in Home Assistant (HA) via de officiële MyŠkoda Public API. Je ziet de locatie, kilometerstand, het slot, de accu en meldingen, en je kunt de airco aan- en uitzetten. De handleiding bevat geen persoonlijke gegevens. Overal waar je iets van jezelf moet invullen staat een invulveld in hoofdletters, zoals JOUW_API_KEY.

Wat je nodig hebt

Een Škoda met MyŠkoda-account en connected services
Home Assistant met toegang tot configuration.yaml en secrets.yaml (bijvoorbeeld via de ingebouwde File editor)
Een API-key uit de MyŠkoda-app: ga naar https://go.skoda.eu/api-keys en kies de auto’s waarvoor de key moet gelden
Het VIN (chassisnummer) van je auto

Goed om te weten

Authenticatie: een statische key in de header X-API-Key. Er is geen OAuth of token-refresh.
Verlooptijd: de key verloopt. Elke response bevat de verlooptijd in de header X-API-Key-Expires-At. Zet een herinnering in je agenda of gebruik stap 6.
Limieten: volgens Škoda maximaal 5 keys per auto en 20 verzoeken per uur. Dat kan in de toekomst wijzigen. Elke poll van HA en elke druk op een knop telt als een verzoek.
Wat er niet in zit: onderhoud, inspectie, banden en storingslampjes zitten niet in de publieke API.
Voorbeeldwaarden: de veldnamen hieronder komen uit de API-specificatie (/docs/myskoda-public-api.yaml). Wat je auto levert, hangt af van het model. Een benzineauto heeft bijvoorbeeld geen charging.

Stap 1: secrets

Zet in secrets.yaml:

skoda_api_key: JOUW_API_KEY
skoda_vehicle_url: https://public.api.connect.skoda-auto.cz/api/v1/vehicles/JOUW_VIN?include=status,odometer,parkingPosition,charging,airConditioning
skoda_airco_start_url: https://public.api.connect.skoda-auto.cz/api/v1/vehicles/JOUW_VIN/air-conditioning/start
skoda_airco_stop_url: https://public.api.connect.skoda-auto.cz/api/v1/vehicles/JOUW_VIN/air-conditioning/stop

Met include= vraag je alleen op wat je nodig hebt. Zo blijft de response klein.

Stap 2: sensoren

Zet dit in configuration.yaml. Heb je al een rest: op kolom 0 (zonder #), voeg het blok dan als extra item toe en maak geen tweede rest:. Gebruik je de oudere notatie sensor: – platform: rest, zet dit dan op een eigen plek op kolom 0.

rest:
  - resource: !secret skoda_vehicle_url
    scan_interval: 900
    headers:
      X-API-Key: !secret skoda_api_key
    sensor:
      - name: "Skoda kilometerstand"
        value_template: "{{ value_json.vehicle.odometer.mileageInKm | default(none) }}"
        unit_of_measurement: "km"
        device_class: distance
        state_class: total_increasing

      - name: "Skoda vergrendeling"
        value_template: >
          {{ value_json.vehicle.status.overall.reliableLockStatus
             | default(value_json.vehicle.status.overall.locked | default('unknown')) }}

      - name: "Skoda positie"
        value_template: "{{ value_json.vehicle.parkingPosition.state | default('unknown') }}"
        json_attributes_path: "$.vehicle.parkingPosition"
        json_attributes:
          - formattedAddress

      - name: "Skoda gps"
        value_template: "{{ value_json.vehicle.parkingPosition.state | default('unknown') }}"
        json_attributes_path: "$.vehicle.parkingPosition.gpsCoordinates"
        json_attributes:
          - latitude
          - longitude

      - name: "Skoda accu"
        value_template: "{{ value_json.vehicle.charging.status.battery.stateOfChargeInPercent | default(none) }}"
        unit_of_measurement: "%"
        device_class: battery
        state_class: measurement

      - name: "Skoda laadlimiet"
        value_template: "{{ value_json.vehicle.charging.settings.targetStateOfChargeInPercent | default(none) }}"
        unit_of_measurement: "%"

      - name: "Skoda laadstatus"
        value_template: "{{ value_json.vehicle.charging.status.state | default('unknown') }}"

      - name: "Skoda kabel"
        value_template: "{{ value_json.vehicle.charging.status.plugConnectionState | default('unknown') }}"

      - name: "Skoda airco"
        value_template: "{{ value_json.vehicle.airConditioning.state | default('unknown') }}"
        json_attributes_path: "$.vehicle.airConditioning.targetTemperature"
        json_attributes:
          - value

      - name: "Skoda laadvermogen"
        value_template: "{{ value_json.vehicle.charging.status.chargePowerInKw | default(0) }}"
        unit_of_measurement: "kW"
        device_class: power
        state_class: measurement

      - name: "Skoda tijd tot vol"
        value_template: "{{ value_json.vehicle.charging.status.remainingTimeToFullyChargedInMinutes | default(none) }}"
        unit_of_measurement: "min"
        device_class: duration

      - name: "Skoda fouten"
        value_template: "{{ value_json.errors | default([]) | length }}"
        json_attributes:
          - errors

    binary_sensor:
      - name: "Skoda deuren open"
        value_template: "{{ value_json.vehicle.status.overall.doors == 'OPEN' }}"
        device_class: door

      - name: "Skoda airco actief"
        value_template: "{{ value_json.vehicle.airConditioning.state not in ['OFF', 'unknown'] }}"
        device_class: running

Let op bij de plaatsing: unit_of_measurement, state_class en device_class: duration horen onder sensor:. Onder binary_sensor: geven ze een foutmelding. Controleer daarna Ontwikkelaarstools > YAML > Configuratie controleren en doe een volledige herstart

Stap 3: airco aan en uit

Zet dit op kolom 0 in configuration.yaml, maar maar één keer. Staat er al een rest_command:, voeg de twee commando’s dan daaronder toe.

rest_command:
  skoda_airco_start:
    url: !secret skoda_airco_start_url
    method: post
    headers:
      X-API-Key: !secret skoda_api_key
    content_type: "application/json"
    payload: '{"targetTemperature":{"value":21,"unit":"CELSIUS"},"airConditioningWithoutExternalPower":true}'
  skoda_airco_stop:
    url: !secret skoda_airco_stop_url
    method: post
    headers:
      X-API-Key: !secret skoda_api_key

De doeltemperatuur staat vast op 21 °C. airConditioningWithoutExternalPower: true laat de airco ook zonder stekker werken, wat accu kost. De auto voert het commando met enkele minuten vertraging uit. Controleer het resultaat met sensor.skoda_airco (status OFF of HEATING).

Stap 4: dashboard

Voeg via Dashboard > Bewerken > Kaart toevoegen > Handmatig toe:

type: vertical-stack
cards:
  - type: gauge
    entity: sensor.skoda_accu
    name: Accu
    min: 0
    max: 100
    needle: true
  - type: entities
    entities:
      - entity: sensor.skoda_laadlimiet
        name: Laadlimiet
      - entity: sensor.skoda_laadstatus
        name: Laadstatus
      - entity: sensor.skoda_kabel
        name: Kabel
      - entity: sensor.skoda_laadvermogen
        name: Laadvermogen
      - entity: sensor.skoda_tijd_tot_vol
        name: Tijd tot vol
      - entity: sensor.skoda_vergrendeling
        name: Slot
      - entity: binary_sensor.skoda_deuren_open
        name: Deuren
      - entity: sensor.skoda_kilometerstand
        name: Kilometerstand
      - entity: sensor.skoda_positie
        name: Status
      - type: attribute
        entity: sensor.skoda_positie
        attribute: formattedAddress
        name: Adres
      - entity: sensor.skoda_fouten
        name: API-meldingen

Airco-knoppen. De eerste knop toont de status en kleurt mee bij de volgende poll(max na 15 minuten):

type: horizontal-stack
cards:
  - type: button
    entity: binary_sensor.skoda_airco_actief
    name: Airco aan
    icon: mdi:air-conditioner
    show_state: true
    state_color: true
    tap_action:
      action: perform-action
      perform_action: rest_command.skoda_airco_start
  - type: button
    name: Airco uit
    icon: mdi:power
    tap_action:
      action: perform-action
      perform_action: rest_command.skoda_airco_stop

Stap 5: auto met een eigen plaatje op de hoofdmap

De hoofdmap toont zonder plaatje alleen de beginletters van de naam. Zet een plaatje (bijvoorbeeld een transparante PNG van ongeveer 200 pixels breed) in /config/www/ en voeg customize toe aan het bestaande homeassistant:-blok. Dat blok mag maar één keer in configuration.yaml staan.

homeassistant:
  customize:
    sensor.skoda_gps:
      entity_picture: /local/JOUW_BESTANDSNAAM.png

Controleer eerst of het plaatje bereikbaar is op http://JOUW_HA_ADRES:8123/local/JOUW_BESTANDSNAAM.png. Ververs daarna de kaart met Ctrl+F5.

Stap 6: meldingen

Zet dit in automations.yaml. Vervang notify.JOUW_NOTIFY_SERVICE door je eigen notify-service (zie Ontwikkelaarstools > Acties met filter notify) en geef elke automation een eigen, unieke id.

- id: 'JOUW_UNIEKE_ID_1'
  alias: "Skoda accu vol"
  description: ''
  triggers:
    - trigger: template
      value_template: >-
        {{ states('sensor.skoda_accu') | int(0) >= states('sensor.skoda_laadlimiet') | int(101)
           and is_state('sensor.skoda_kabel', 'CONNECTED') }}
  conditions: []
  actions:
    - action: notify.JOUW_NOTIFY_SERVICE
      data:
        title: "Skoda"
        message: "Accu is op {{ states('sensor.skoda_accu') }}% (limiet bereikt)."
  mode: single

- id: 'JOUW_UNIEKE_ID_2'
  alias: "Skoda API-key verloopt binnenkort"
  description: ''
  triggers:
    - trigger: time
      at: "09:00:00"
  conditions:
    - condition: template
      value_template: >-
        {{ now().date() >= (strptime('JJJJ-MM-DD', '%Y-%m-%d') - timedelta(days=14)).date() }}
  actions:
    - action: notify.JOUW_NOTIFY_SERVICE
      data:
        title: "Skoda API-key"
        message: "Je API-key verloopt binnenkort. Maak een nieuwe aan en update secrets.yaml."
  mode: single

Vervang JJJJ-MM-DD door de verloopdatum van je key. Die staat in de MyŠkoda-app, of in de header X-API-Key-Expires-At van een response:

curl -i -H “X-API-Key: JOUW_API_KEY” “https://public.api.connect.skoda-auto.cz/api/v1/vehicles/JOUW_VIN?include=info”

De automation “accu vol” meldt zodra de accu de ingestelde laadlimiet van de auto bereikt. Pas je de limiet in de auto aan, dan past de melding vanzelf mee. Omdat er maar elke 15 minuten gepolld wordt, kan de accu bij de melding iets boven de limiet zitten.

Werk de automations in automations.yaml bij via Ontwikkelaarstools > YAML > Automatiseringen herladen.

Tips en veelgemaakte fouten

Herstart in plaats van herladen. Gebruik na wijzigingen aan sensoren een volledige herstart. Met de herlaadknop voor REST-entiteiten ontstaan kopieën zoals sensor.skoda_gps_2, omdat de sensoren geen unique_id hebben. De kopieën verdwijnen bij de volgende herstart.
Inspringing. Een – resource: op de verkeerde kolom geeft de fout bad indentation of a sequence entry of required key ‘platform’ not provided. Het blok hoort onder een eigen rest: op kolom 0 te staan.
Dubbele sleutels. rest:, rest_command:, homeassistant: en automation: mogen elk maar één keer op kolom 0 staan.
Sensor zonder waarde. Staat een sensor op unknown, dan levert je auto dat onderdeel niet. Kijk op Statussen naar sensor.skoda_fouten, want de errors-lijst noemt welke onderdelen ontbreken.
Foutcodes in het logboek. 401 betekent een ongeldige of verlopen key, 403 een key die niet bij deze auto hoort, en 429 dat het limiet van verzoeken is bereikt.
Entiteiten zonder unique_id kun je niet in de interface hernoemen of verwijderen. Pas de naam daarom aan in de YAML of in customize.