new SoC module Cupra (#2553)

* add cupra connect soc

* add docu

Author: vuffiraa72

docs/SoC-Cupra-settings-1.png

@@ -0,0 +1,82 @@
+# SoC-Modul Cupra
+
+Das SoC-Modul Cupra gibt es in openWB 2.x.
+
+## Konfiguration
+
+Die Konfiguration erfolgt im Bereich Einstellungen - Konfiguration - Fahrzeuge:
+
+![Allgemeine Konfiguration](SoC-Cupra-settings-1.png)
+
+![Spezielle Konfiguration](SoC-Cupra-settings-2.png)
+
+## Hinweise
+
+Für nicht-Cupra Fahrzeuge (Audi, Skoda, VW, etc.) funktioniert das Modul nicht.
+
+Erfolgreich getestet u.a. für folgende Fahrzeuge: Cupra Born.
+
+**Wichtig für alle Fahrzeuge:**
+Es muss ein aktives Konto im Seat ID Portal vorhanden sein und die "My SEAT App" muss eingerichtet sein. Es muss explizit die "My SEAT App" eingerichtet werden und nicht die "My CUPRA App".
+
+**WICHTIG:**
+Seat/Cupra ändert gelegentlich die Bedingungen für die Nutzung der Online-Services.
+
+Diese müssen bestätigt werden. Wenn der SOC-Abruf plötzlich nicht mehr funktioniert, VOR dem Posten bitte Schritt 1 ausführen.
+
+Bei Problemen zunächst bitte diese Schritte durchführen:
+
+1. sicherstellen, dass auf dieser Seat-Seite alle Einverständnisse gegeben wurden.
+
+    <https://seatid.vwgroup.io/landing-page>
+
+    In einigen Fällen wurden die Einverständnisse gegeben und trotzdem funktionierte die Abfrage nicht.
+    Hier hat folgendes Vorgehen geholfen: Im Seat Konto das Land temporär umstellen, d.h.
+    - auf ein anderes Land als das eigene ändern
+    - sichern
+    - zurück auf das eigene Land ändern
+    - sichern.
+
+2. Nach einem manuellen SOC-Abruf (Kreispfeil hinter dem SOC klicken) auf der Status - Seite EV-SOC Log und Debug log auf Fehler kontrollieren
+
+3. Falls im Ev-Soc Log Fehler 303 (unknown redirect) gemeldet wird:
+    - Ursache 1: Bestimmte Sonderzeichen im Passwort funktionieren nicht mit dem Modul. Bitte das Passwort auf eines ohne Sonderzeichen ändern und testen.
+    - Ursache 2: Falsche Email, Passwort oder VIN eingegeben. Alle 3 löschen, speichern, neu eingeben, speichern und testen.
+
+4. Falls eine Firewall im Spiel ist: Es gab einzelne Probleme beim Internet-Zugriff der openWB auf Python Archive und Fahrzeug-Server wenn IPV6 aktiv ist.
+
+5. Nach Neustart bzw. Änderung der LP-Konfiguration werden im EV-Soc-Log Fehler ausgegeben (permission oder fehlende Datei).
+
+    Diese Fehler sind normal und können ignoriert werden. Leider wird im Debug Mode 0 keine Positiv-Meldung ausgegeben.
+    Empfehlung:
+    - In Einstellungen - System - Fehlersuche dies einstellen: Debug Level/Details
+    - dann einen manuellen SOC-Abruf durchführen (im Dashboard auf Kreispfeil klicken).
+    - danach sollte im EV-SOC-Log eine Zeile ähnlich dieser kommen:
+
+        `2023-02-12 11:57:14 INFO:soc_skoda:Lp1 SOC: 61%@2023-02-12T11:53:20`
+
+        Diese Zeile zeigt folgende Information:
+
+        `2023-02-12 11:57:14` *- Timestamp des SOC-Abrufs*
+
+        `INFO` *- Debug Level INFO*
+
+        `soc_skoda` *- SOC-Modul*
+
+        `Lp1` *- Ladepunkt*
+
+        `SOC: 61%` *- SOC Stand*
+
+        `@2025-02-12T11:53:20` *- Timestamp des Updates vom EV zum Seat Cloud-Server*
+
+6. Falls diese Schritte nicht zum Erfolg führen, das Problem im [Support Thema](https://forum.openwb.de/viewforum.php?f=12) mit Angabe relevanter Daten posten
+    - oWB SW Version
+    - oWB gekauft oder selbst installiert
+    - wenn selbst installiert: welches OS(Stretch/Buster)
+    - welches Fahrzeug
+    - falls vorhanden Angaben über Firewall, VPN, etc., also Appliances, die den Internetzugang limitieren könnten
+    - relevante Abschnitte der Logs, vor allem Fehlermeldungen, als CODE-blocks (</>).
+
+Das SoC-Log mit evtl. Fehlermeldungen kann wie folgt eingesehen werden:
+
+- Einstellungen - System - Fehlersuche

docs/SoC-Cupra-settings-2.png

@@ -6,6 +6,7 @@
 * [Fahrzeuge](https://github.com/openWB/core/wiki/Fahrzeuge)
   * [Manueller SoC](https://github.com/openWB/core/wiki/Manueller-SoC)
   * [SoC BMW & Mini](https://github.com/openWB/core/wiki/SoC-BMW-Mini)
+  * [SoC Cupra](https://github.com/openWB/core/wiki/SoC-Cupra)
   * [SoC OVMS](https://github.com/openWB/core/wiki/SoC-OVMS)
   * [SoC VWId](https://github.com/openWB/core/wiki/SoC-VWId)
   * [WiCAN OBD2-Dongle mit manuellem SoC](https://github.com/openWB/core/wiki/WiCAN)

docs/SoC-Cupra.md

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+
+import aiohttp
+from asyncio import new_event_loop, set_event_loop
+from typing import Union
+from modules.vehicles.cupra import libcupra
+from modules.vehicles.cupra.config import Cupra
+from modules.vehicles.vwgroup.vwgroup import VwGroup
+
+
+class api(VwGroup):
+
+    def __init__(self, conf: Cupra, vehicle: int):
+        super().__init__(conf, vehicle)
+
+    # async method, called from sync fetch_soc, required because libvwid/libskoda/libcupra expect async environment
+    async def _fetch_soc(self) -> Union[int, float, str]:
+        async with aiohttp.ClientSession() as self.session:
+            cupra = libcupra.cupra(self.session)
+            return await super().request_data(cupra)
+
+
+def fetch_soc(conf: Cupra, vehicle: int) -> Union[int, float, str]:
+
+    # prepare and call async method
+    loop = new_event_loop()
+    set_event_loop(loop)
+
+    # get soc, range from server
+    a = api(conf, vehicle)
+    soc, range, soc_ts, soc_tsX = loop.run_until_complete(a._fetch_soc())
+
+    return soc, range, soc_ts, soc_tsX

docs/_Sidebar.md

@@ -0,0 +1,28 @@
+from typing import Optional
+
+
+class CupraConfiguration:
+    def __init__(self,
+                 user_id: Optional[str] = None,        # show in UI
+                 password: Optional[str] = None,       # show in UI
+                 vin: Optional[str] = None,            # show in UI
+                 refreshToken: Optional[str] = None,   # DON'T show in UI!
+                 calculate_soc: bool = False           # show in UI
+                 ):
+        self.user_id = user_id
+        self.password = password
+        self.vin = vin
+        self.refreshToken = refreshToken
+        self.calculate_soc = calculate_soc
+
+
+class Cupra:
+    def __init__(self,
+                 name: str = "Cupra",
+                 type: str = "cupra",
+                 official: bool = False,
+                 configuration: CupraConfiguration = None) -> None:
+        self.name = name
+        self.type = type
+        self.official = official
+        self.configuration = configuration or CupraConfiguration()