Release v1.5.2: Add last-trip sensors and improve metadata

Syax89 · Syax89 · commit 39a11af28064 · 2026-03-18T11:36:51.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to this project are documented in this file.
 
+## [1.5.2] - 2026-03-18
+
+### Changed
+- **Repository Metadata**: Improved manifest, HACS metadata, and service descriptions for a cleaner Home Assistant and HACS experience.
+- **Trip Entities**: Added optional sensors for last trip average speed and last trip duration, and expanded last-trip attributes with average speed details.
+
+### Fixed
+- **Documentation**: Refined the README to better explain installation, available entities, and the built-in refresh service.
+- **Translations**: Added localized labels for the new last-trip sensors across the bundled translations.
+
 ## [1.5.1] - 2026-03-18
 
 ### Changed
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 ![GitHub Release](https://img.shields.io/github/v/release/Syax89/geotab-hacs-integration?style=for-the-badge)
 ![License](https://img.shields.io/github/license/Syax89/geotab-hacs-integration?style=for-the-badge)
 
-A professional-grade Home Assistant integration for the Geotab fleet management platform. This component facilitates the seamless synchronization of telematics data, providing comprehensive vehicle monitoring, diagnostic analysis, and real-time tracking directly within the Home Assistant ecosystem.
+A Home Assistant integration for the Geotab fleet management platform. It brings live vehicle position, driving state, diagnostics, active faults, and trip statistics into Home Assistant through the standard UI and HACS.
 
 ---
 
@@ -13,7 +13,7 @@ A professional-grade Home Assistant integration for the Geotab fleet management
 * **High-Precision Tracking**: Dedicated `device_tracker` entities providing real-time geographical coordinates for all fleet assets.
 * **Diagnostic Trouble Codes (DTC)**: Advanced monitoring of active engine faults with detailed reporting on fault codes, human-readable descriptions, and severity indicators (lamp status).
 * **Extended Telematics**: Access to over 30 distinct data points per vehicle, including fuel metrics, tire pressures, and engine health parameters.
-* **Historical Aggregation**: Built-in calculation of daily, weekly, and monthly trip statistics, including distance covered and idle time analysis.
+* **Historical Aggregation**: Built-in calculation of daily, weekly, and monthly trip statistics, including distance covered, average driving speed, last-trip metrics, and idle time analysis.
 * **Internationalization**: Full localization support for English, Italian, German, Spanish, French, Dutch, and Portuguese.
 
 ---
@@ -43,7 +43,7 @@ Entities are logically categorized to ensure a streamlined user interface and ef
 ### Trip Statistics
 * **Aggregated Metrics**: Daily, weekly, and monthly distance tracking.
 * **Operational Analysis**: Trip counts, average driving speed, and weekly idle time reports.
-* **Last Journey**: Comprehensive data on the most recently completed trip.
+* **Last Journey**: Dedicated last-trip distance, duration, and average-speed sensors.
 
 ---
 
@@ -77,6 +77,19 @@ Entities are logically categorized to ensure a streamlined user interface and ef
 
 *Note: Integration parameters can be modified post-installation via the **Configure** interface.*
 
+### Included Entities
+
+By default the integration creates, for each Geotab vehicle:
+
+* a `device_tracker` entity for live position
+* primary sensors such as odometer, fuel level, speed, and last update
+* binary sensors for ignition, driving state, and active faults
+* optional diagnostic and trip-analysis sensors that can be enabled from the entity registry
+
+### Built-In Service
+
+The integration registers the `geotab.refresh` service, which triggers an immediate refresh for all configured Geotab entries.
+
 ---
 
 ## 🛡️ Technical Integrity & Security
diff --git a/custom_components/geotab/manifest.json b/custom_components/geotab/manifest.json
@@ -4,8 +4,10 @@
   "codeowners": ["@simonerondina"],
   "config_flow": true,
   "documentation": "https://github.com/Syax89/geotab-hacs-integration",
+  "integration_type": "service",
   "iot_class": "cloud_polling",
   "issue_tracker": "https://github.com/Syax89/geotab-hacs-integration/issues",
+  "loggers": ["mygeotab"],
   "requirements": ["mygeotab>=0.9.1,<1.0.0"],
-  "version": "1.5.1"
+  "version": "1.5.2"
 }
diff --git a/custom_components/geotab/sensor.py b/custom_components/geotab/sensor.py
@@ -318,6 +318,29 @@ class GeotabSensorEntityDescription(SensorEntityDescription):
             else None
         ),
     ),
+    GeotabSensorEntityDescription(
+        key="last_trip_average_speed",
+        translation_key="last_trip_average_speed",
+        icon="mdi:speedometer-medium",
+        native_unit_of_measurement=UnitOfSpeed.KILOMETERS_PER_HOUR,
+        device_class=SensorDeviceClass.SPEED,
+        state_class=SensorStateClass.MEASUREMENT,
+        value_fn=lambda data: trip_stats.last_trip_average_speed(
+            data.get("last_trip")
+        ),
+        entity_registry_enabled_default=False,
+    ),
+    GeotabSensorEntityDescription(
+        key="last_trip_duration",
+        translation_key="last_trip_duration",
+        icon="mdi:timer-outline",
+        native_unit_of_measurement=UnitOfTime.HOURS,
+        state_class=SensorStateClass.MEASUREMENT,
+        value_fn=lambda data: trip_stats.last_trip_duration_hours(
+            data.get("last_trip")
+        ),
+        entity_registry_enabled_default=False,
+    ),
     GeotabSensorEntityDescription(
         key="daily_distance",
         translation_key="daily_distance",
@@ -474,6 +497,7 @@ def extra_state_attributes(self) -> dict[str, Any] | None:
                 return {
                     "start": trip.get("start"),
                     "stop": trip.get("stop"),
+                    "average_speed": trip.get("averageSpeed"),
                     "maximum_speed": trip.get("maximumSpeed"),
                     "driving_duration": trip.get("drivingDuration"),
                     "idling_duration": trip.get("idlingDuration"),
diff --git a/custom_components/geotab/services.yaml b/custom_components/geotab/services.yaml
@@ -1,3 +1,4 @@
 refresh:
   name: Refresh
   description: Force an immediate data refresh from the Geotab API for all configured entries.
+  fields: {}
diff --git a/custom_components/geotab/strings.json b/custom_components/geotab/strings.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Accelerator Position" },
       "throttle_pos": { "name": "Throttle Position" },
       "last_trip_distance": { "name": "Last Trip Distance" },
+      "last_trip_average_speed": { "name": "Last Trip Average Speed" },
+      "last_trip_duration": { "name": "Last Trip Duration" },
       "daily_distance": { "name": "Daily Distance" },
       "weekly_distance": { "name": "Weekly Distance" },
       "monthly_distance": { "name": "Monthly Distance" },
diff --git a/custom_components/geotab/translations/de.json b/custom_components/geotab/translations/de.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Gaspedalstellung" },
       "throttle_pos": { "name": "Drosselklappenstellung" },
       "last_trip_distance": { "name": "Letzte Fahrtstrecke" },
+      "last_trip_average_speed": { "name": "Letzte Fahrt: Durchschnittsgeschwindigkeit" },
+      "last_trip_duration": { "name": "Letzte Fahrt: Dauer" },
       "daily_distance": { "name": "Fahrten: Tägliche Strecke" },
       "weekly_distance": { "name": "Fahrten: Wöchentliche Strecke" },
       "monthly_distance": { "name": "Fahrten: Monatliche Strecke" },
diff --git a/custom_components/geotab/translations/en.json b/custom_components/geotab/translations/en.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Accelerator Position" },
       "throttle_pos": { "name": "Throttle Position" },
       "last_trip_distance": { "name": "Last Trip Distance" },
+      "last_trip_average_speed": { "name": "Last Trip Avg Speed" },
+      "last_trip_duration": { "name": "Last Trip Duration" },
       "daily_distance": { "name": "Trips: Daily Distance" },
       "weekly_distance": { "name": "Trips: Weekly Distance" },
       "monthly_distance": { "name": "Trips: Monthly Distance" },
diff --git a/custom_components/geotab/translations/es.json b/custom_components/geotab/translations/es.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Posición del acelerador" },
       "throttle_pos": { "name": "Posición de la mariposa" },
       "last_trip_distance": { "name": "Distancia del último viaje" },
+      "last_trip_average_speed": { "name": "Velocidad media del último viaje" },
+      "last_trip_duration": { "name": "Duración del último viaje" },
       "daily_distance": { "name": "Viajes: Distancia diaria" },
       "weekly_distance": { "name": "Viajes: Distancia semanal" },
       "monthly_distance": { "name": "Viajes: Distancia mensual" },
diff --git a/custom_components/geotab/translations/fr.json b/custom_components/geotab/translations/fr.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Position de l'accélérateur" },
       "throttle_pos": { "name": "Position du papillon" },
       "last_trip_distance": { "name": "Distance du dernier trajet" },
+      "last_trip_average_speed": { "name": "Vitesse moyenne du dernier trajet" },
+      "last_trip_duration": { "name": "Durée du dernier trajet" },
       "daily_distance": { "name": "Trajets : Distance quotidienne" },
       "weekly_distance": { "name": "Trajets : Distance hebdomadaire" },
       "monthly_distance": { "name": "Trajets : Distance mensuelle" },
diff --git a/custom_components/geotab/translations/it.json b/custom_components/geotab/translations/it.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Posizione Acceleratore" },
       "throttle_pos": { "name": "Posizione Farfalla" },
       "last_trip_distance": { "name": "Distanza Ultimo Viaggio" },
+      "last_trip_average_speed": { "name": "Velocità Media Ultimo Viaggio" },
+      "last_trip_duration": { "name": "Durata Ultimo Viaggio" },
       "daily_distance": { "name": "Viaggi: Distanza Giornaliera" },
       "weekly_distance": { "name": "Viaggi: Distanza Settimanale" },
       "monthly_distance": { "name": "Viaggi: Distanza Mensile" },
diff --git a/custom_components/geotab/translations/nl.json b/custom_components/geotab/translations/nl.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Gaspedaalpositie" },
       "throttle_pos": { "name": "Gaskleppositie" },
       "last_trip_distance": { "name": "Afstand laatste rit" },
+      "last_trip_average_speed": { "name": "Gemiddelde snelheid laatste rit" },
+      "last_trip_duration": { "name": "Duur laatste rit" },
       "daily_distance": { "name": "Ritten: Dagelijkse afstand" },
       "weekly_distance": { "name": "Ritten: Wekelijkse afstand" },
       "monthly_distance": { "name": "Ritten: Maandelijkse afstand" },
diff --git a/custom_components/geotab/translations/pt.json b/custom_components/geotab/translations/pt.json
@@ -47,6 +47,8 @@
       "accelerator_pos": { "name": "Posição do acelerador" },
       "throttle_pos": { "name": "Posição da borboleta" },
       "last_trip_distance": { "name": "Distância da última viagem" },
+      "last_trip_average_speed": { "name": "Velocidade média da última viagem" },
+      "last_trip_duration": { "name": "Duração da última viagem" },
       "daily_distance": { "name": "Viagens: Distância diária" },
       "weekly_distance": { "name": "Viagens: Distância semanal" },
       "monthly_distance": { "name": "Viagens: Distância mensal" },
diff --git a/custom_components/geotab/trip_stats.py b/custom_components/geotab/trip_stats.py
@@ -91,6 +91,36 @@ def average_trip_speed(trips: list[dict]) -> float | None:
     return round(sum(speeds) / len(speeds), 1)
 
 
+def last_trip_average_speed(trip: dict | None) -> float | None:
+    """Return the average speed of the most recent trip (km/h)."""
+    if not trip:
+        return None
+    average_speed = trip.get("averageSpeed")
+    if average_speed is None:
+        return None
+    return round(float(average_speed), 1)
+
+
+def last_trip_duration_hours(trip: dict | None) -> float | None:
+    """Return the total duration of the most recent trip in hours."""
+    if not trip:
+        return None
+
+    driving_seconds = _parse_iso8601_duration(str(trip.get("drivingDuration") or ""))
+    idle_seconds = _parse_iso8601_duration(str(trip.get("idlingDuration") or ""))
+    total_seconds = driving_seconds + idle_seconds
+
+    if total_seconds == 0:
+        start = _parse_datetime(str(trip.get("start") or ""))
+        stop = _parse_datetime(str(trip.get("stop") or ""))
+        if start and stop and stop >= start:
+            total_seconds = (stop - start).total_seconds()
+
+    if total_seconds == 0:
+        return None
+    return round(total_seconds / 3600, 2)
+
+
 def total_idle_time_weekly(trips: list[dict]) -> float | None:
     """Total idle time (hours) across trips in the last 7 days."""
     recent = _filter_trips_since(trips, 7 * 24)
diff --git a/hacs.json b/hacs.json
@@ -1,5 +1,6 @@
 {
   "name": "Geotab",
+  "content_in_root": false,
   "render_readme": true,
   "homepage": "https://github.com/Syax89/geotab-hacs-integration",
   "hacs": "1.32.0"
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -75,8 +75,8 @@ def _mock_get(type_name, *args, **kwargs):
             }],
             # 2. Trip Result for device1
             [
-                {"id": "trip1", "distance": 15.0, "start": "2026-03-08T10:00:00Z", "stop": "2026-03-08T10:30:00Z", "maximumSpeed": 80, "drivingDuration": "PT25M", "idlingDuration": "PT5M"},
-                {"id": "trip2", "distance": 22.5, "start": "2026-03-07T08:00:00Z", "stop": "2026-03-07T08:45:00Z", "maximumSpeed": 100, "drivingDuration": "PT40M", "idlingDuration": "PT3M"},
+                {"id": "trip1", "distance": 15.0, "start": "2026-03-08T10:00:00Z", "stop": "2026-03-08T10:30:00Z", "maximumSpeed": 80, "averageSpeed": 55, "drivingDuration": "PT25M", "idlingDuration": "PT5M"},
+                {"id": "trip2", "distance": 22.5, "start": "2026-03-07T08:00:00Z", "stop": "2026-03-07T08:45:00Z", "maximumSpeed": 100, "averageSpeed": 70, "drivingDuration": "PT40M", "idlingDuration": "PT3M"},
             ],
         ]
         yield instance
diff --git a/tests/test_trip_stats.py b/tests/test_trip_stats.py
@@ -25,6 +25,8 @@
 daily_trip_count = trip_stats.daily_trip_count
 weekly_trip_count = trip_stats.weekly_trip_count
 average_trip_speed = trip_stats.average_trip_speed
+last_trip_average_speed = trip_stats.last_trip_average_speed
+last_trip_duration_hours = trip_stats.last_trip_duration_hours
 total_idle_time_weekly = trip_stats.total_idle_time_weekly
 
 
@@ -33,6 +35,7 @@ def _make_trip(
     hours_ago: float = 1.0,
     max_speed: float = 80.0,
     avg_speed: float = 60.0,
+    driving_duration: str = "PT30M",
     idle_duration: str = "PT5M",
 ) -> dict:
     """Create a trip dict with a start time N hours ago."""
@@ -43,6 +46,7 @@ def _make_trip(
         "stop": (start + timedelta(minutes=30)).isoformat(),
         "maximumSpeed": max_speed,
         "averageSpeed": avg_speed,
+        "drivingDuration": driving_duration,
         "idlingDuration": idle_duration,
     }
 
@@ -140,6 +144,29 @@ def test_empty(self):
         assert average_trip_speed([]) is None
 
 
+class TestLastTripHelpers:
+    """Tests for latest-trip helper functions."""
+
+    def test_last_trip_average_speed(self):
+        trip = _make_trip(avg_speed=63.4)
+        assert last_trip_average_speed(trip) == 63.4
+
+    def test_last_trip_duration_prefers_durations(self):
+        trip = _make_trip(driving_duration="PT30M", idle_duration="PT15M")
+        assert last_trip_duration_hours(trip) == 0.75
+
+    def test_last_trip_duration_falls_back_to_timestamps(self):
+        start = datetime.now(timezone.utc) - timedelta(minutes=42)
+        trip = {
+            "start": start.isoformat(),
+            "stop": (start + timedelta(minutes=42)).isoformat(),
+        }
+        assert last_trip_duration_hours(trip) == 0.7
+
+    def test_last_trip_duration_empty(self):
+        assert last_trip_duration_hours(None) is None
+
+
 class TestTotalIdleTimeWeekly:
     """Tests for total_idle_time_weekly."""
 
