Included link to https://github.com/JosephBlock/fordapp-handler in docs & setup dialog

Author: marq24

README.md

@@ -1,4 +1,4 @@
-# FordPass Home Assistant Integration 2025 (EV/PHEV/Petrol/Diesel)
+# FordPass Home Assistant Integration +2025 (EV/PHEV/Petrol/Diesel)
 ## Supporting all Ford vehicles with FordPass™ & Lincoln vehicles with The Lincoln Way™ connectivity
 
 <!--
@@ -38,7 +38,7 @@ If you currently have your integration configured, then you might be lucky and t
 >
 > ## FordPass™/The Lincoln Way™ Account Disclaimer 
 > **The use of this HA integration could lead to a (temporary) lock of your FordPass™/The Lincoln Way™ account.**
-> Since this integration is not officially supported by Ford, using it could result in your being locked out! from your account.
+> Since Ford does not officially support this integration, using it could result that you being **locked out** from your FordPass™/The Lincoln Way™ account.
 >
 > **It's recommended** to use/create a **separate FordPass™/The Lincoln Way™ account** for this integration ([see the 'step-by-step' procedure further below](https://github.com/marq24/ha-fordpass?tab=readme-ov-file#use-of-a-separate-fordpassthe-lincoln-way-account-is-recommended)).
 
@@ -75,7 +75,7 @@ If you currently have your integration configured, then you might be lucky and t
 
 > [!IMPORTANT]
 > ## Unusual Integration Setup 
-> Status Quo in spring/summer/end 2025: This integration requires an unusual setup process to be able to access the data of your vehicle. This is because Ford has changed (once again) the access policies to the required backend APIs (and revoked the access to the APIs for individual developers).
+> Status Quo in summer 2026: This integration requires an unusual setup process to be able to access the data of your vehicle. This is because Ford has changed (once again) the access policies to the required backend APIs (and revoked the access to the APIs for individual developers).
 > 
 > The current implementation is based on API calls the original FordPass™/The Lincoln Way™ App (for Android & iOS) performs, and it's some sort of reverse engineered.
 > 
@@ -86,9 +86,11 @@ If you currently have your integration configured, then you might be lucky and t
 > ## Fetch & Store FordPass™/The Lincoln Way™ Access Token
 > During the integration setup, you will be guided through the process to obtain an access token for your vehicle in the context of your FordPass™/The Lincoln Way™ account.
 > 
-> This should be a _one-time process_, and the access token will be stored in a file outside the custom integration directory (This is to prevent the access token from being deleted during updates of the integration itself). As already explaind, I can't give any guarantee that process will work in the future.
+> This should be a _one-time process_, and the access token will be stored in a file outside the custom integration directory (This is to prevent the access token from being deleted during updates of the integration itself). As already explained, I can't give any guarantee that this process will work in the future.
 > 
-> The overall setup process is described in short in the [Installation section](https://github.com/marq24/ha-fordpass?tab=readme-ov-file#installation-instructions-3-steps) below, and in detail in the [linked documentation](./doc/OBTAINING_TOKEN.md).
+> **The overall setup process is described in short in the [Installation section](https://github.com/marq24/ha-fordpass?tab=readme-ov-file#installation-instructions-3-steps) below, and in detail in the [linked documentation](./doc/OBTAINING_TOKEN.md)**.
+>
+> Since the end of May 2026 [@JosephBlock](https://github.com/JosephBlock) is offering a tool to make the token acquire process much simpler. So if you are struggling with the documented details (and don't mind installing an additional _3rd party_ tool), then the free available [tool called 'fordapp-handler' from Joseph's GitHub repository](https://github.com/JosephBlock/fordapp-handler) can be an alternative.
 
 ---
 
@@ -108,7 +110,7 @@ There is another Home Assistant integration for Ford Vehicles called [ha-fordcon
 
 
 ## Installation Instructions (3 Steps)
-### Step 1. HACS add the Integration
+### Step 1. HACS: add the Integration
 
 [![Open your Home Assistant instance and adding repository to HACS.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=marq24&repository=ha-fordpass&category=integration)
 <!--
@@ -138,7 +140,9 @@ There is another Home Assistant integration for Ford Vehicles called [ha-fordcon
 > So if your country is not listed in the integration, and you follow the recommendation to register a sperate account to be used with the integration, then [__register this second account at the ford.com domain__](https://www.ford.com/#$userCreateAccount), since this ensures that you can use the Integration with the 'Rest of the World' Region setting.
 
 ### Step 3. The hard part — the **Token Setup**
-The actual token request requires an external browser to get finally the FordPass™/The Lincoln Way™ access token. [Yes this is for sure quite unusual process when setting up a HA integration, but it's the only way to get the token right now]
+The actual token request requires an external browser to finally get the FordPass™/The Lincoln Way™ access token. [Yes this is for sure quite an unusual process when setting up a HA integration, but it's the only way to get the token right now]
+
+**If you are struggling with this step (and don't mind installing an additional _3rd party_ tool), then [Joseph Block's fordapp-handler](https://github.com/JosephBlock/fordapp-handler) can be an alternative.**
 
 Please follow the steps:
 1. Copy the URL listed in the first input field

custom_components/fordpass/__init__.py

@@ -834,7 +834,7 @@ async def _async_update_data(self):
                             data = self.data
                         return data
 
-                except TimeoutError as ti_err:
+                except asyncio.TimeoutError as ti_err:
                     # Mark as unavailable - but let the coordinator deal with the rest...
                     self._available = False
                     raise ti_err

custom_components/fordpass/config_flow.py

@@ -290,7 +290,8 @@ async def async_step_user(self, user_input=None):
                         )
                 }),
                 description_placeholders={
-                    "repo": "https://github.com/marq24/ha-fordpass"
+                    "repo": "https://github.com/marq24/ha-fordpass",
+                    "github_root": "https://github.com"
                 },
                 errors=errors
             )
@@ -507,7 +508,8 @@ async def async_step_token(self, user_input=None):
                 ),
                 description_placeholders={
                     CONF_URL: the_url,
-                    "repo": "https://github.com/marq24/ha-fordpass"
+                    "repo": "https://github.com/marq24/ha-fordpass",
+                    "github_root": "https://github.com"
                 },
                 errors=errors
             )
@@ -725,7 +727,7 @@ async def async_step_reauth_confirm(self, user_input: dict[str, Any] | None = No
                             try:
                                 async with asyncio.timeout(30):
                                     await self.hass.config_entries.async_reload(reauth_entry.entry_id)
-                            except TimeoutError:
+                            except asyncio.TimeoutError:
                                 _LOGGER.warning(f"async_step_reauth_confirm(): Timeout reloading config entry {reauth_entry.entry_id} during reauth")
                                 return self.async_abort(reason="reauth_reload_failed")
 
@@ -771,7 +773,8 @@ async def async_step_reauth_confirm(self, user_input: dict[str, Any] | None = No
                 description_placeholders={
                     CONF_USERNAME: reauth_entry.data.get(CONF_USERNAME, "UNKNOWN-USER"),
                     CONF_URL: the_url,
-                    "repo": "https://github.com/marq24/ha-fordpass"
+                    "repo": "https://github.com/marq24/ha-fordpass",
+                    "github_root": "https://github.com"
                 },
                 errors=errors
             )

custom_components/fordpass/manifest.json

@@ -12,6 +12,6 @@
     "loggers": ["custom_components.fordpass"],
     "requirements": [],
     "ssdp": [],
-    "version": "2026.6.0",
+    "version": "2026.7.0",
     "zeroconf": []
   }

custom_components/fordpass/translations/da.json

@@ -110,15 +110,15 @@
             },
             "token": {
                 "title": "Opsætning af token",
-                "description": "Opsætningen af token kræver, at du åbner et ekstra browservindue (med udviklerværktøjer aktiveret – F12) for at fange det endelige adgangstoken.\r\rDet er en lidt usædvanlig fremgangsmåde for en Home Assistant-integration. Du kan læse detaljerne i [opsætningsvejledningen]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\r\rFølg disse trin:\r1. Kopiér linket nedenfor, eller klik på det følgende link (skal åbnes i en ny fane/vindue): [Start autoriseringsprocessen]({url})\r2. Åbn en browser (med udviklerværktøjer aktiveret), og indsæt linket i den anden browser\r3. Indtast dine FordPass™/The Lincoln Way™-loginoplysninger igen, og tryk på login-knappen\r4. Hold øje med fanen Network, indtil du ser anmodningen `?code=`\r5. Kopiér hele `Request-URL` fra anmodningen i browserens udviklerværktøjer, og indsæt det i token-feltet nedenfor\r6. Klik OK for at fortsætte",
+                "description": "Opsætningen af token kræver, at du åbner et ekstra browservindue (med udviklerværktøjer aktiveret – F12) for at fange det endelige adgangstoken.\r\rDet er en lidt usædvanlig fremgangsmåde for en Home Assistant-integration. Du kan læse detaljerne i [opsætningsvejledningen]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\r\rFølg disse trin:\r1. Kopiér linket nedenfor, eller klik på det følgende link (skal åbnes i en ny fane/vindue): [Start autoriseringsprocessen]({url})\r2. Åbn en browser (med udviklerværktøjer aktiveret), og indsæt linket i den anden browser\r3. Indtast dine FordPass™/The Lincoln Way™-loginoplysninger igen, og tryk på login-knappen\r4. Hold øje med fanen Network, indtil du ser anmodningen `?code=`\r5. Kopiér hele `Request-URL` fra anmodningen i browserens udviklerværktøjer, og indsæt det i token-feltet nedenfor\r6. Klik OK for at fortsætte\n\n> [!TIP]\n> JosephBlock has created a separate tool that supports you in the access-token-code-acquire-process, which makes the use of the browser developer tools obsolete. So if you don't mind installing a helper application on your local computer, you can get the tool from here: [{github_root}/JosephBlock/fordapp-handler]({github_root}/JosephBlock/fordapp-handler).",
                 "data": {
                     "url": "URL: kopiér denne ind i din browser",
                     "tokenstr": "Token Request-URL: indsæt hele `Request-URL`, når login er gennemført i browseren"
                 }
             },
             "reauth_confirm": {
                 "title": "Genautorisering kræves",
-                "description": "Dit tidligere token er ugyldigt – så du skal lave et nyt til kontoen {username}:\r\rDetaljer findes i [opsætningsvejledningen]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\r\rFølg disse trin:\r1. Kopiér linket nedenfor, eller klik på det følgende link (skal åbnes i en ny fane/vindue): [Start autoriseringsprocessen]({url})\r2. Åbn en browser (med udviklerværktøjer aktiveret), og indsæt linket i den anden browser\r3. Indtast dine FordPass™/The Lincoln Way™-loginoplysninger igen, og tryk på login-knappen (lad dig ikke narre af, at spinneren bliver ved med at snurre – det er 'normalt')\r4. Hold øje med fanen Network, indtil du ser anmodningen `?code=`\r5. Kopiér hele `Request-URL` fra anmodningen i browserens udviklerværktøjer, og indsæt det i token-feltet nedenfor\r6. Klik OK for at fortsætte",
+                "description": "Dit tidligere token er ugyldigt – så du skal lave et nyt til kontoen {username}:\r\rDetaljer findes i [opsætningsvejledningen]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\r\rFølg disse trin:\r1. Kopiér linket nedenfor, eller klik på det følgende link (skal åbnes i en ny fane/vindue): [Start autoriseringsprocessen]({url})\r2. Åbn en browser (med udviklerværktøjer aktiveret), og indsæt linket i den anden browser\r3. Indtast dine FordPass™/The Lincoln Way™-loginoplysninger igen, og tryk på login-knappen (lad dig ikke narre af, at spinneren bliver ved med at snurre – det er 'normalt')\r4. Hold øje med fanen Network, indtil du ser anmodningen `?code=`\r5. Kopiér hele `Request-URL` fra anmodningen i browserens udviklerværktøjer, og indsæt det i token-feltet nedenfor\r6. Klik OK for at fortsætte\n\n> [!TIP]\n> JosephBlock has created a separate tool that supports you in the access-token-code-acquire-process, which makes the use of the browser developer tools obsolete. So if you don't mind installing a helper application on your local computer, you can get the tool from here: [{github_root}/JosephBlock/fordapp-handler]({github_root}/JosephBlock/fordapp-handler).",
                 "data": {
                     "url": "URL: kopiér denne ind i din browser",
                     "tokenstr": "Token Request-URL: indsæt hele `Request-URL`, når login er gennemført i browseren"

custom_components/fordpass/translations/de.json

@@ -111,15 +111,15 @@
             },
             "token": {
                 "title": "Zugriffs-Token Einrichtung",
-                "description": "Die Token-Einrichtung erfordert einen zweites Browser Fenster (mit aktivierten Developer-Tools - F12), um den finalen Zugriffstoken von Ford zu erhalten.\r\rDies ist recht ungewöhnlich für eine Home Assistant Integration, details findest Du in der [Einrichtungsanleitung]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\r\rBitte befolge die Schritte:\r1. Kopiere die URL aus dem oberen Feld oder klicke auf den nachfolgenden Link (dieser muss in einem neuen Tab/Fenster geöffnet werden): [Mit dem Autorisierungsverfahren beginnen]({url})\r2. Öffne einen weiteren Browser (mit aktivierten Entwicklertools) und füge die kopierte URL in dieses zweiter Browserfenster ein\r3. Gibt Deine FordPass™/The Lincoln Way™-Anmeldeinformationen (erneut) ein und starte den Anmeldeforgang\r4. Beobachte die Registerkarte „Netzwerk“, bis der Request „?code=“ zu sehen ist\r5. Kopiere die vollständige „Request-URL“ dieser Anfrage aus den Browser Entwicklertools und fügen diese hier unten im Token-Feld ein\r6. Klicke auf „OK“ um fortzufahren",
+                "description": "Die Token-Einrichtung erfordert einen zweites Browser Fenster (mit aktivierten Developer-Tools - F12), um den finalen Zugriffstoken von Ford zu erhalten.\r\rDies ist recht ungewöhnlich für eine Home Assistant Integration, details findest Du in der [Einrichtungsanleitung]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\r\rBitte befolge die Schritte:\r1. Kopiere die URL aus dem oberen Feld oder klicke auf den nachfolgenden Link (dieser muss in einem neuen Tab/Fenster geöffnet werden): [Mit dem Autorisierungsverfahren beginnen]({url})\r2. Öffne einen weiteren Browser (mit aktivierten Entwicklertools) und füge die kopierte URL in dieses zweiter Browserfenster ein\r3. Gibt Deine FordPass™/The Lincoln Way™-Anmeldeinformationen (erneut) ein und starte den Anmeldeforgang\r4. Beobachte die Registerkarte „Netzwerk“, bis der Request „?code=“ zu sehen ist\r5. Kopiere die vollständige „Request-URL“ dieser Anfrage aus den Browser Entwicklertools und fügen diese hier unten im Token-Feld ein\r6. Klicke auf „OK“ um fortzufahren\n\n> [!TIP]\n> JosephBlock hat ein separates Tool entwickelt, das Dich beim Abruf des Access-Token-Codes unterstützt und die Verwendung der Entwicklertools des Browsers überflüssig macht. Wenn es für Dich OK ist, eine kleine Hilfsanwendung auf Deinem lokalen Computer zu installieren, kannst Du das Tool hier herunterladen: [{github_root}/JosephBlock/fordapp-handler]({github_root}/JosephBlock/fordapp-handler).",
                 "data": {
                     "url": "URL: Füge diese in Deinen Browser ein",
                     "tokenstr": "Token Request-URL: Nachdem der Anmeldevorgang im Browser abgeschlossen ist, füge die vollständige „Request-URL“ ein"
                 }
             },
             "reauth_confirm": {
                 "title": "Erneute Autorisierung erforderlich",
-                "description": "Dein bisheriges Token ist ungültig (geworden) - Du musst nun einen neuen für das Konto {username} erzeugen:\r\rDetails findest Du in der [Einrichtungsanleitung]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\n\nBitte befolge die Schritte:\n1. Kopiere die URL aus dem oberen Feld oder klicke auf den nachfolgenden Link (dieser muss in einem neuen Tab/Fenster geöffnet werden): [Mit dem Autorisierungsverfahren beginnen]({url})\n2. Öffnen einen weiteren Browser (mit aktivierten Entwicklertools) und füge die kopierte URL in dieses zweite Browserfenster ein\n3. Gibt Deine FordPass™/The Lincoln Way™-Anmeldeinformationen (erneut) ein und starte den Anmeldeforgang (lass Dich nicht davon verwirren, dass der Spinner sich nicht aufhört zu drehen, das ist 'normal')\n4. Beobachte die Registerkarte „Netzwerk“, bis der Request „?code=“ zu sehen ist\n5. Kopiere die vollständige „Request-URL“ dieser Anfrage aus den Browser Entwicklertools und fügen diese hier unten im Token-Feld ein\n6. Klicke auf „OK“ um fortzufahren",
+                "description": "Dein bisheriges Token ist ungültig (geworden) - Du musst nun einen neuen für das Konto {username} erzeugen:\r\rDetails findest Du in der [Einrichtungsanleitung]({repo}/blob/main/doc/OBTAINING_TOKEN.md)\n\nBitte befolge die Schritte:\n1. Kopiere die URL aus dem oberen Feld oder klicke auf den nachfolgenden Link (dieser muss in einem neuen Tab/Fenster geöffnet werden): [Mit dem Autorisierungsverfahren beginnen]({url})\n2. Öffnen einen weiteren Browser (mit aktivierten Entwicklertools) und füge die kopierte URL in dieses zweite Browserfenster ein\n3. Gibt Deine FordPass™/The Lincoln Way™-Anmeldeinformationen (erneut) ein und starte den Anmeldeforgang (lass Dich nicht davon verwirren, dass der Spinner sich nicht aufhört zu drehen, das ist 'normal')\n4. Beobachte die Registerkarte „Netzwerk“, bis der Request „?code=“ zu sehen ist\n5. Kopiere die vollständige „Request-URL“ dieser Anfrage aus den Browser Entwicklertools und fügen diese hier unten im Token-Feld ein\n6. Klicke auf „OK“ um fortzufahren\n\n> [!TIP]\n> JosephBlock hat ein separates Tool entwickelt, das Dich beim Abruf des Access-Token-Codes unterstützt und die Verwendung der Entwicklertools des Browsers überflüssig macht. Wenn es für Dich OK ist, eine kleine Hilfsanwendung auf Deinem lokalen Computer zu installieren, kannst Du das Tool hier herunterladen: [{github_root}/JosephBlock/fordapp-handler]({github_root}/JosephBlock/fordapp-handler).",
                 "data": {
                     "url": "URL: Füge diese in Deinen Browser ein",
                     "tokenstr": "Token Request-URL: Nachdem der Anmeldevorgang im Browser abgeschlossen ist, füge die vollständige „Request-URL“ ein"