From 10a44796047c7561934c120f4e9c5d155818918e Mon Sep 17 00:00:00 2001 From: Thomas D <11554546+thomasddn@users.noreply.github.com> Date: Tue, 15 Apr 2025 12:59:39 +0000 Subject: [PATCH 1/6] Add Volvo sensor documentation --- source/_integrations/volvo.markdown | 152 ++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 source/_integrations/volvo.markdown diff --git a/source/_integrations/volvo.markdown b/source/_integrations/volvo.markdown new file mode 100644 index 000000000000..9d6f4fd35d9c --- /dev/null +++ b/source/_integrations/volvo.markdown @@ -0,0 +1,152 @@ +--- +title: Volvo +description: Instructions on setting up Volvo within Home Assistant. +ha_release: 2025.6 +ha_iot_class: Cloud Polling +ha_codeowners: + - '@thomasddn' +ha_domain: volvo +ha_integration_type: integration +ha_config_flow: true +ha_category: + - Sensor +ha_platforms: + - sensor +ha_quality_scale: silver +related: + - url: https://developer.volvocars.com/ + title: Volvo developers portal +--- + +The **Volvo** {% term integration %} is used to integrate your [Volvo](https://www.volvocars.com/) vehicle. + +## Supported vehicles + +- All car models starting from model year 2015 (although some might have fewer features available). +- Cars located in Europe, Middle East, Africa, US, Canada, and Latin America regions. Or view the [full list of countries](https://developer.volvocars.com/terms-and-conditions/apis-supported-locations/). + +## Prerequisites + +1. Head over to [Volvo's developer portal](https://developer.volvocars.com/) +2. Make an account +3. Go to the [API applications page](https://developer.volvocars.com/account/#your-api-applications) +4. Create an "API application" and give it a meaningful name + +It's recommended to add an API application per vehicle you want to add. There is a maximum on the number of requests that can be made per API key per day. + +{% include integrations/config_flow.md %} + +{% configuration_basic %} +API key: + description: "Enter the API key obtained in the prerequisites steps." +VIN: + description: "If you have more than one car under this account then you can select the Vehicle Identification Number of the vehicle you wish to add." +{% endconfiguration_basic %} + +## Configuration options + +You have the following configuration options if your model has a combustion engine: + +{% configuration_basic %} +Fuel consumption unit: + description: You can specify in which unit (L/100 km, mpg (UK), or mpg (US)) the fuel consumption should be displayed. +{% endconfiguration_basic %} + +## Supported functionality + +The **Volvo** integration provides the following entities. + +### All engine types + +#### Sensors + +- **Car connection**: Connectivity of the car +- **Distance to service**: Remaining distance till the next service maintenance +- **Engine time to service**: Remaining engine-hours till the next service maintenance +- **Odometer**: Odometer +- **TA Avg. speed**: Average speed on the automatic trip meter +- **TA Distance**: Total distance on the automatic trip meter +- **Time to service**: Remaining time till the next service maintenance +- **TM Avg. speed**: Average speed on the manual trip meter +- **TM Distance**: Total distance on the manual trip meter + +### Battery only and Plug-in hybrid + +#### Sensors + +- **Avg. energy consumption since charge**: Average energy consumption since the last charge of the battery +- **Battery capacity**: Total capacity of the battery +- **Battery charge level**: Current state of charge of the battery +- **Distance to empty battery**: Electric range + +#### Sensors for specific models + +Go to Volvo's developer portal to view [the list of supported models](https://developer.volvocars.com/apis/energy/v1/overview/#availability). + +- **Charging connection status**: Charging connection status +- **Charging limit**: Charging limit configured in the car +- **Charging status**: Indication if the car is charging or not +- **Est. charging time**: Estimated charging time to reach the target battery charge level +- **TA Avg. energy consumption**: Average energy consumption on the automatic trip meter +- **Target battery charge level**: Target battery charge level configured in the car +- **TM Avg. energy consumption**: Average energy consumption on the manual trip meter + +### Fuel only and Plug-in hybrid + +- **Distance to empty tank**: Fuel range +- **Fuel amount**: Remaining fuel +- **TA Avg. fuel consumption**: Average fuel consumption on the manual automatic meter +- **TM Avg. fuel consumption**: Average fuel consumption on the manual trip meter + +## Examples + +### Estimated charging finish time + +The Volvo API only provides an estimated charging time (in minutes). To calculate the finish time, you can create a **Template sensor** helper with the template below. + +{% raw %} + +```jinja2 +{% set charging_time = states('sensor.volvo_YOUR_MODEL_estimated_charging_time') | int(0) %} +{% if charging_time > 0 -%} + {% set new_time = now() + timedelta(minutes=charging_time) %} + {{ new_time }} +{%- else -%} + {{ this.state }} +{%- endif %} +``` + +{% endraw %} + +Set the **Device class** to **Timestamp** and optionally choose your vehicle for **Device**. + +## Data updates + +The **Volvo** integration fetches data from the API every 135 seconds by default. +If you decide to define a custom polling interval, beware that there is a maximum of 10.000 requests per day. +Every poll operation accounts for about a dozen calls (depends on model). + +## Known limitations + +The official Volvo app has access to a more feature-rich API. As a result, this integration cannot provide live updates, display tyre pressure values, start air purifying, schedule climatization, show climatization status, and so on. + +## Troubleshooting + +### Recharge API + +#### Symptoms + +The **Volvo** {% term integration %} does not show recharge entities or they are unavailable. +This happens because sometimes the Volvo recharge API does not respond properly. + +#### Resolution + +The integration will automatically re-enable the recharge entities once the API becomes available again. + +## Removing the integration + +This integration follows standard integration removal. + +{% include integrations/remove_device_service.md %} + +After deleting the integration, go to the app of the manufacturer and remove the Home Assistant integration from there as well. From 2a48e7da55deba0ec95fe9de59976ff298e98f6e Mon Sep 17 00:00:00 2001 From: Thomas D <11554546+thomasddn@users.noreply.github.com> Date: Tue, 15 Apr 2025 13:45:56 +0000 Subject: [PATCH 2/6] Fix nitpick comments --- source/_integrations/volvo.markdown | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/_integrations/volvo.markdown b/source/_integrations/volvo.markdown index 9d6f4fd35d9c..5005fbf135fd 100644 --- a/source/_integrations/volvo.markdown +++ b/source/_integrations/volvo.markdown @@ -61,12 +61,12 @@ The **Volvo** integration provides the following entities. #### Sensors - **Car connection**: Connectivity of the car -- **Distance to service**: Remaining distance till the next service maintenance -- **Engine time to service**: Remaining engine-hours till the next service maintenance +- **Distance to service**: Remaining distance until the next service maintenance +- **Engine time to service**: Remaining engine-hours until the next service maintenance - **Odometer**: Odometer - **TA Avg. speed**: Average speed on the automatic trip meter - **TA Distance**: Total distance on the automatic trip meter -- **Time to service**: Remaining time till the next service maintenance +- **Time to service**: Remaining time until the next service maintenance - **TM Avg. speed**: Average speed on the manual trip meter - **TM Distance**: Total distance on the manual trip meter @@ -136,7 +136,7 @@ The official Volvo app has access to a more feature-rich API. As a result, this #### Symptoms -The **Volvo** {% term integration %} does not show recharge entities or they are unavailable. +The **Volvo** {% term integration %} does not show recharge entities, or they are unavailable. This happens because sometimes the Volvo recharge API does not respond properly. #### Resolution From 5bec70e9a8f2348c9dbb63d70ae74dc12d9fb595 Mon Sep 17 00:00:00 2001 From: Thomas D <11554546+thomasddn@users.noreply.github.com> Date: Tue, 15 Apr 2025 13:58:43 +0000 Subject: [PATCH 3/6] Fix nitpick comments --- source/_integrations/volvo.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/volvo.markdown b/source/_integrations/volvo.markdown index 5005fbf135fd..afc9bb4d986a 100644 --- a/source/_integrations/volvo.markdown +++ b/source/_integrations/volvo.markdown @@ -40,7 +40,7 @@ It's recommended to add an API application per vehicle you want to add. There is API key: description: "Enter the API key obtained in the prerequisites steps." VIN: - description: "If you have more than one car under this account then you can select the Vehicle Identification Number of the vehicle you wish to add." + description: "If you have more than one car under this account, then you can select the Vehicle Identification Number of the vehicle you wish to add." {% endconfiguration_basic %} ## Configuration options From 4c8dad93f4ff7c048733d664600700d10c90d476 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Wed, 16 Apr 2025 08:31:47 +0200 Subject: [PATCH 4/6] tiny style tweaks --- source/_integrations/volvo.markdown | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/_integrations/volvo.markdown b/source/_integrations/volvo.markdown index afc9bb4d986a..14002a709890 100644 --- a/source/_integrations/volvo.markdown +++ b/source/_integrations/volvo.markdown @@ -27,10 +27,10 @@ The **Volvo** {% term integration %} is used to integrate your [Volvo](https://w ## Prerequisites -1. Head over to [Volvo's developer portal](https://developer.volvocars.com/) -2. Make an account -3. Go to the [API applications page](https://developer.volvocars.com/account/#your-api-applications) -4. Create an "API application" and give it a meaningful name +1. Head over to [Volvo's developer portal](https://developer.volvocars.com/). +2. Make an account. +3. Go to the [API applications page](https://developer.volvocars.com/account/#your-api-applications). +4. Create an **API application** and give it a meaningful name. It's recommended to add an API application per vehicle you want to add. There is a maximum on the number of requests that can be made per API key per day. @@ -70,7 +70,7 @@ The **Volvo** integration provides the following entities. - **TM Avg. speed**: Average speed on the manual trip meter - **TM Distance**: Total distance on the manual trip meter -### Battery only and Plug-in hybrid +### Battery-only and plug-in hybrid #### Sensors @@ -91,7 +91,7 @@ Go to Volvo's developer portal to view [the list of supported models](https://de - **Target battery charge level**: Target battery charge level configured in the car - **TM Avg. energy consumption**: Average energy consumption on the manual trip meter -### Fuel only and Plug-in hybrid +### Fuel-only and plug-in hybrid - **Distance to empty tank**: Fuel range - **Fuel amount**: Remaining fuel From 263e7acfc17fe632173ddbb8ffe990a548123a22 Mon Sep 17 00:00:00 2001 From: Thomas D <11554546+thomasddn@users.noreply.github.com> Date: Thu, 24 Apr 2025 15:06:07 +0000 Subject: [PATCH 5/6] Update supported vehicles --- source/_integrations/volvo.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/volvo.markdown b/source/_integrations/volvo.markdown index 14002a709890..cd7c7599073d 100644 --- a/source/_integrations/volvo.markdown +++ b/source/_integrations/volvo.markdown @@ -22,7 +22,7 @@ The **Volvo** {% term integration %} is used to integrate your [Volvo](https://w ## Supported vehicles -- All car models starting from model year 2015 (although some might have fewer features available). +- Car models starting from model year 2010. Features available depend on model and year. - Cars located in Europe, Middle East, Africa, US, Canada, and Latin America regions. Or view the [full list of countries](https://developer.volvocars.com/terms-and-conditions/apis-supported-locations/). ## Prerequisites From d939b6b8ef2f4f95601a7ee40aafac0641dd21fa Mon Sep 17 00:00:00 2001 From: Thomas D <11554546+thomasddn@users.noreply.github.com> Date: Thu, 24 Apr 2025 15:18:43 +0000 Subject: [PATCH 6/6] Small grammar changes --- source/_integrations/volvo.markdown | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/source/_integrations/volvo.markdown b/source/_integrations/volvo.markdown index cd7c7599073d..ab4d9d66dbd0 100644 --- a/source/_integrations/volvo.markdown +++ b/source/_integrations/volvo.markdown @@ -64,11 +64,11 @@ The **Volvo** integration provides the following entities. - **Distance to service**: Remaining distance until the next service maintenance - **Engine time to service**: Remaining engine-hours until the next service maintenance - **Odometer**: Odometer -- **TA Avg. speed**: Average speed on the automatic trip meter -- **TA Distance**: Total distance on the automatic trip meter +- **TA avg. speed**: Average speed on the automatic trip meter +- **TA distance**: Total distance on the automatic trip meter - **Time to service**: Remaining time until the next service maintenance -- **TM Avg. speed**: Average speed on the manual trip meter -- **TM Distance**: Total distance on the manual trip meter +- **TM avg. speed**: Average speed on the manual trip meter +- **TM distance**: Total distance on the manual trip meter ### Battery-only and plug-in hybrid @@ -87,16 +87,18 @@ Go to Volvo's developer portal to view [the list of supported models](https://de - **Charging limit**: Charging limit configured in the car - **Charging status**: Indication if the car is charging or not - **Est. charging time**: Estimated charging time to reach the target battery charge level -- **TA Avg. energy consumption**: Average energy consumption on the automatic trip meter +- **TA avg. energy consumption**: Average energy consumption on the automatic trip meter - **Target battery charge level**: Target battery charge level configured in the car -- **TM Avg. energy consumption**: Average energy consumption on the manual trip meter +- **TM avg. energy consumption**: Average energy consumption on the manual trip meter ### Fuel-only and plug-in hybrid +#### Sensors + - **Distance to empty tank**: Fuel range - **Fuel amount**: Remaining fuel -- **TA Avg. fuel consumption**: Average fuel consumption on the manual automatic meter -- **TM Avg. fuel consumption**: Average fuel consumption on the manual trip meter +- **TA avg. fuel consumption**: Average fuel consumption on the automatic trip meter +- **TM avg. fuel consumption**: Average fuel consumption on the manual trip meter ## Examples