Domotica & IoT

Home Assistant

GPS Tracker Map: La tua Dashboard di Viaggio in Home Assistant

25 Apr 2026

Un'integrazione personalizzata per monitorare i percorsi del tuo smartphone, rilevare soste automatiche e analizzare statistiche di viaggio direttamente nella tua dashboard.

View on GitHub

🌍 Perché un'integrazione GPS personalizzata?

Molti utenti di Home Assistant utilizzano l'app Companion per il monitoraggio della posizione, ma visualizzare lo storico dei percorsi in modo fluido e intuitivo non è sempre semplice con le card standard.

GPS Tracker Map nasce per colmare questo vuoto, offrendo una mappa interattiva basata su Leaflet che trasforma i dati di geolocalizzazione in informazioni visive chiare e professionali.

✨ Funzionalità Principali

Mappa Dark: Un'estetica curata che si integra perfettamente con i temi scuri di Home Assistant.
Percorso Dinamico: La linea del percorso cambia colore in base alla velocità (verde per camminate, rosso per l'auto).
Rilevamento Soste: Algoritmo automatico che identifica dove ti sei fermato per più di 10 minuti, segnandolo con marker gialli.
Timeline Cliccabile: Una barra laterale cronologica per saltare istantaneamente a un momento specifico della giornata.
Statistiche di Viaggio: Calcolo automatico di distanza totale, velocità massima e tempo di percorrenza.

📦 Requisito: È necessario che l'App Home Assistant Companion sia installata sul telefono e che il sensore di posizione sia attivo.

🛠️ Sotto il Cofano: Tecnologie e Architettura

Dal punto di vista tecnico, il progetto è una Single Page Application (SPA) integrata come Custom Panel in Home Assistant. Ecco le scelte architetturali principali:

Leaflet.js & OSM: Ho scelto Leaflet per la sua leggerezza e flessibilità. A differenza di Google Maps, l'uso di OpenStreetMap garantisce che l'estensione rimanga gratuita al 100% e priva di chiavi API complesse da gestire.
Colorazione Polyline in base alla velocità: Il percorso non è un'unica linea, ma una serie di segmenti collegati. Ogni segmento viene renderizzato con un colore calcolato dinamicamente: Verde (< 5km/h) -> Giallo (< 25km/h) -> Arancione (< 50km/h) -> Rosso (> 80km/h).
Algoritmo di Clustering per le Soste: Per evitare di affollare la mappa, l'integrazione analizza i timestamp dei punti GPS. Se la distanza tra punti consecutivi rimane sotto una certa soglia per più di 10 minuti, il sistema aggrega i punti e genera un marker "Sosta", calcolandone automaticamente la durata.
Integrazione API HA: Il frontend comunica con il backend di Home Assistant tramite Websocket API e REST API per recuperare lo storico degli stati dell'entità device_tracker, minimizzando il carico sul database SQL di HA.

🚀 Installazione via HACS (Consigliato)

Il modo più rapido per installare l'integrazione è tramite il Home Assistant Community Store (HACS):

Apri HACS nel tuo Home Assistant.
Clicca sui tre puntini in alto a destra e seleziona "Custom repositories".
Incolla l'URL del repository: https://github.com/genzo76/ha-gps-tracker
Seleziona "Integration" come categoria e clicca "Add".
Cerca ora "GPS Tracker Map" nell'elenco di HACS e clicca su Download.
Riavvia Home Assistant.

🛠️ Configurazione Post-Installazione

Una volta riavviato, vai su Impostazioni -> Dispositivi e Servizi -> Aggiungi Integrazione e cerca "GPS Tracker Map". Segui i passaggi della configurazione guidata selezionando l'entità device_tracker del tuo smartphone.

Generazione del Token di Accesso

Per funzionare correttamente nel pannello laterale, l'integrazione richiede un Long-Lived Access Token:

Clicca sul tuo nome profilo in HA (in basso a sinistra).
Scorri fino in fondo a "Token di accesso di lunga durata".
Crea un nuovo token chiamato "GPS Tracker" e copialo.
Incolla il token nelle impostazioni del pannello GPS Tracker quando richiesto.

                        Esempio Struttura YAML (Auto-generata)
                        YAML
                    

panel_custom:
  - name: gps_tracker_map
    sidebar_title: GPS Tracker
    sidebar_icon: mdi:map-marker-path
    url_path: gps_tracker_map
    module_url: /local/custom_components/gps_tracker_map/panel/index.html
                    

🎯 Conclusione

Con questa integrazione, Home Assistant smette di essere solo uno strumento di controllo e diventa un potente diario di viaggio privato. Tutti i dati rimangono all'interno del tuo server, garantendo la massima privacy rispetto a servizi cloud di terze parti.

🌍 Why a Custom GPS Integration?

Many Home Assistant users use the Companion app for location tracking, but visualizing **path history** in a fluid and intuitive way is not always easy with standard cards.

**GPS Tracker Map** was created to fill this gap, offering an interactive Leaflet-based map that transforms geolocation data into clear and professional visual information.

✨ Key Features

**Dark Map:** A refined aesthetic that perfectly integrates with Home Assistant dark themes.
**Dynamic Path:** The path line changes color based on speed (green for walking, red for driving).
**Stop Detection:** An automatic algorithm that identifies where you stopped for more than 10 minutes, marking it with yellow markers.
**Clickable Timeline:** A chronological sidebar to instantly jump to a specific moment of the day.
**Travel Statistics:** Automatic calculation of total distance, maximum speed, and travel time.

**📦 Requirement:** The Home Assistant Companion App must be installed on your phone and the location sensor must be active.

🛠️ Under the Hood: Technologies and Architecture

From a technical standpoint, the project is a Single Page Application (SPA) integrated as a Custom Panel in Home Assistant. Here are the main architectural choices:

Leaflet.js & OSM: I chose Leaflet for its lightness and flexibility. Unlike Google Maps, using OpenStreetMap ensures that the extension remains 100% free and without complex API keys to manage.
Speed-based Polyline Coloring: The path is not a single line but a series of connected segments. Each segment is rendered with a dynamically calculated color: Green (< 5km/h) -> Yellow (< 25km/h) -> Orange (< 50km/h) -> Red (> 80km/h).
Clustering Algorithm for Stops: To avoid cluttering the map, the integration analyzes the timestamps of GPS points. If the distance between consecutive points remains below a certain threshold for more than 10 minutes, the system aggregates the points and generates a "Stop" marker, automatically calculating its duration.
HA API Integration: The frontend communicates with the Home Assistant backend via Websocket API and REST API to retrieve the state history of the device_tracker entity, minimizing the load on HA's SQL database.

🚀 Installation via HACS (Recommended)

The fastest way to install the integration is via the **Home Assistant Community Store (HACS)**:

Open **HACS** in your Home Assistant.
Click the three dots in the top right and select **"Custom repositories"**.
Paste the repository URL: https://github.com/genzo76/ha-gps-tracker
Select **"Integration"** as the category and click **"Add"**.
Now search for "GPS Tracker Map" in the HACS list and click **Download**.
Restart Home Assistant.

🛠️ Post-Installation Configuration

Once restarted, go to **Settings -> Devices & Services -> Add Integration** and search for "GPS Tracker Map". Follow the wizard steps by selecting your smartphone's device_tracker entity.

Generating the Access Token

To function correctly in the side panel, the integration requires a **Long-Lived Access Token**:

Click on your profile name in HA (bottom left).
Scroll to the bottom to "Long-lived access tokens".
Create a new token named "GPS Tracker" and copy it.
Paste the token in the GPS Tracker panel settings when prompted.

🎯 Conclusion

With this integration, Home Assistant stops being just a control tool and becomes a powerful private travel diary. All data remains within your server, ensuring maximum privacy compared to third-party cloud services.