audiconnect/audi_connect_ha
GitHub: audiconnect/audi_connect_ha
Stars: 338 | Forks: 120
# Audi Connect Integration for Home Assistant
[][commits]
[](LICENSE.md)
[][black]
[](hacs)
## Notices
Due to API changes, **currently not all functionality is available**. Please open a issue to report the topics you are missing.
## Maintainers Wanted
- Looking for maintainers for Translation documents.
- Always looking for more help from the community. If you can resolve an issue, please submit a PR or reach out to the maintainers with the working code.
## Description
The `audiconnect` component provides an integration with the Audi Connect cloud service. It adds presence detection, sensors such as range, mileage, and fuel level, and provides car actions such as locking/unlocking and setting the pre-heater.
**Note:** Certain functions require special permissions from Audi, such as position update via GPS.
Credit for initial API discovery go to the guys at the ioBroker VW-Connect forum, who were able to figure out how the API and the PIN hashing works. Also some implementation credit to davidgiga1993 of the original [AudiAPI](https://github.com/davidgiga1993/AudiAPI) Python package, on which some of this code is loosely based.
Full credit for this integration goes to @arjenvrh for their outstanding work in putting it all together. We wouldn’t have this without their contributions.
## Installation
There are two ways this integration can be installed into [Home Assistant](https://www.home-assistant.io).
The easiest and recommended way is to install the integration using [HACS](https://hacs.xyz), which makes future updates easy to track and install.
Alternatively, installation can be done manually by copying the files in this repository into the `custom_components` directory in the Home Assistant configuration directory:
1. Open the configuration directory of your Home Assistant installation.
2. If you do not have a `custom_components` directory, create it.
3. In the `custom_components` directory, create a new directory called `audiconnect`.
4. Copy all files from the `custom_components/audiconnect/` directory in this repository into the `audiconnect` directory.
5. Restart Home Assistant.
6. Add the integration to Home Assistant (see **Configuration**).
## Configuration
Configuration is done through the Home Assistant UI.
To add the integration, go to **Settings ➤ Devices & Services ➤ Integrations**, click **➕ Add Integration**, and search for "Audi Connect".
### Configuration Variables
| Name | Type | Default | Description |
| --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Username` | `string` | – | The username associated with your Audi Connect account. |
| `Password` | `string` | – | The password for your Audi Connect account. |
| `S-PIN` | `string` | – | The S-PIN for your Audi Connect account to perform certain service actions.
(**Optional**) | | `Region` | `string` | `DE` | The region where your Audi Connect account is registered:
• `DE` – Europe
• `US` – United States
• `CA` – Canada
• `CN` – China | | `Scan Interval` | `int` | `15` | Frequency (in minutes) to fetch status data from Audi Connect.
Minimum allowed is 15 minutes.
\* _Can be updated later via the CONFIGURE menu._ | | `API Level` | `int` | `0` | Determines the API structure used for service action calls:
• `0` – _Typically_ Gas vehicles (legacy format)
• `1` – _Typically_ e-tron (electric vehicles, newer format)
\* _Can be updated later via the CONFIGURE menu._ | ## Options Find configuration options under **Settings ➤ Devices & Services ➤ Integrations ➤ Audi Connect ➤ Configure**: | Name | Type | Default | Description | | ----------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Cloud Update at Startup` | `bool` | `True` | Toggle the initial cloud update when the integration starts. Useful for development or frequent Home Assistant restarts. | | `Refresh Vehicle Data After Action` | `bool` | `False` | Send a vehicle refresh command after every service action (e.g. climate, lock). This is typically not required as the vehicle will check in with the cloud on its own after a command. Each vehicle refresh counts against the API rate limit. To improve responsiveness, increase the Cloud Refresh Delay instead. | | `Cloud Refresh Delay` | `int` | `5` | Seconds to wait after a service action before refreshing cloud data. A longer delay gives the vehicle more time to report its updated state to the cloud. | | `Scan Interval` | `int` | `15` | Defines polling frequency in minutes (minimum 15). | | `Excluded VINs` | `str` | – | Comma-separated VIN list to exclude from setup and updates. | _Note: The integration will reload automatically upon clicking `Submit`, but a Home Assistant restart is suggested._ ## Service Actions ### Audi Connect: Refresh Vehicle Data `audiconnect.refresh_vehicle_data` Normal updates retrieve data from the Audi Connect cloud service, and don't interact directly with the vehicle. _This_ service action triggers an update request from the vehicle itself. When data is retrieved successfully, Home Assistant is automatically updated. The service action requires a vehicle identification number (VIN) as a parameter. #### Parameters - **`vehicle`**: The Audi vehicle to perform the action on. ### Audi Connect: Refresh Cloud Data `audiconnect.refresh_cloud_data` _This_ service action triggers an update request from the cloud. - Functionality: Updates data for all vehicles from the online source, mirroring the action performed at integration startup or during scheduled refresh intervals. - Behavior: Does not force a vehicle-side data refresh. Consequently, if vehicles haven't recently pushed updates, retrieved data might be outdated. - Note: This service action replicates the function of active polling without scheduling, offering a more granular control over data refresh moments. - **IMPORTANT:** This service action has no built in usage limits. Excessive use may result in a temporary suspension of your account. #### Parameters - `none` ### Audi Connect: Execute Vehicle Action `audiconnect.execute_vehicle_action` This service action allows you to perform actions on your Audi vehicle, specified by the vehicle identification number (VIN) and the desired action. #### Service Parameters - **`vehicle`**: The Audi vehicle to perform the action on. - **`action`**: The specific action to perform on the vehicle. Available actions include: - **`lock`**: Lock the vehicle. - **`unlock`**: Unlock the vehicle. - **`start_climatisation`**: Start the vehicle's climatisation system. (Legacy) -- Deprecated - **`stop_climatisation`**: Stop the vehicle's climatisation system. - **`start_charger`**: Start charging the vehicle. - **`start_timed_charger`**: Start the vehicle's charger with a timer. - **`stop_charger`**: Stop charging the vehicle. - **`start_preheater`**: Start the vehicle's preheater system. (Legacy) -- Deprecated - **`stop_preheater`**: Stop the vehicle's preheater system. - **`start_window_heating`**: Start heating the vehicle's windows. - **`stop_window_heating`**: Stop heating the vehicle's windows. #### Usage Example To initiate the lock action for a vehicle with VIN `WAUZZZ4G7EN123456`, use the following service call: service: audiconnect.execute_vehicle_action data: device_id: 034986de941a1f824b3f06c0a1d9333f action: "lock" #### Notes - Certain service actions require the S-PIN to be set in the configuration. - After a successful action, the integration waits for the configured **Cloud Refresh Delay** and then performs a cloud data refresh. If **Refresh Vehicle Data After Action** is enabled, a vehicle refresh is also sent before the delay. ### Audi Connect: Start Climate Control `audiconnect.start_climate_control` This service action allows you to start the climate control with options for temperature, glass surface heating, and auto seat comfort. #### Parameters - **`vehicle`**: The Audi vehicle to perform the action on. - **`temp_f`** (_optional_): Desired temperature in Fahrenheit. Default is `70`. - **`temp_c`** (_optional_): Desired temperature in Celsius. Default is `21`. - **`glass_heating`** (_optional_): Enable (`True`) or disable (`False`) glass heating. Default is `False`. - **`seat_fl`** (_optional_): Enable (`True`) or disable (`False`) the front-left seat heater. Default is `False`. - **`seat_fr`** (_optional_): Enable (`True`) or disable (`False`) the front-right seat heater. Default is `False`. - **`seat_rl`** (_optional_): Enable (`True`) or disable (`False`) the rear-left seat heater. Default is `False`. - **`seat_rr`** (_optional_): Enable (`True`) or disable (`False`) the rear-right seat heater. Default is `False`. #### Usage Example To start the climate control for a vehicle with VIN `WAUZZZ4G7EN123456` with a temperature of 72°F, enable glass heating, and activate both front seat heaters, use the following service call: service: audiconnect.start_climate_control data: device_id: 034986de941a1f824b3f06c0a1d9333f temp_f: 72 glass_heating: True seat_fl: True seat_fr: True #### Notes - The `temp_f` and `temp_c` parameters are mutually exclusive. If both are provided, `temp_f` takes precedence. - If neither `temp_f` nor `temp_c` is provided, the system defaults to 70°F or 21°C. - After a successful action, the integration waits for the configured **Cloud Refresh Delay** and then performs a cloud data refresh. If **Refresh Vehicle Data After Action** is enabled, a vehicle refresh is also sent before the delay. ### Audi Connect: Start Auxiliary Heating `audiconnect.start_auxiliary_heating` This service action allows you to start auxiliary heating the vehicle, with option for duration. #### Parameters - **`vehicle`**: The Audi vehicle to perform the action on. - **`duration`** (_optional_): The number of minutes the auxiliary heater should run before turning off. Default is `20` minutes if not provided. #### Usage Example To start the auxiliary heater for a vehicle with VIN `WAUZZZ4G7EN123456`, and a duration of 40 minutes, use the following service call action: service: audiconnect.start_auxiliary_heating data: device_id: 034986de941a1f824b3f06c0a1d9333f duration: 40 #### Notes - Requires the S-PIN to be set in the configuration. - After a successful action, the integration waits for the configured **Cloud Refresh Delay** and then performs a cloud data refresh. If **Refresh Vehicle Data After Action** is enabled, a vehicle refresh is also sent before the delay. ## Example Dashboard Card Below is an example Dashboard (Lovelace) card illustrating some of the sensors this Home Assistant addon provides.  The card requires the following front end mods: - https://github.com/thomasloven/lovelace-card-mod - https://github.com/custom-cards/circle-sensor-card These mods can (like this integration) be installed using HACS. The card uses the following code in `ui-lovelace.yaml` (or wherever your Dashboard is configured). - type: picture-elements image: /local/pictures/audi_sq7.jpeg style: | ha-card { border-radius: 10px; border: solid 1px rgba(100,100,100,0.3); box-shadow: 3px 3px rgba(0,0,0,0.4); overflow: hidden; } elements: - type: image image: /local/pictures/cardbackK.png style: left: 50% top: 90% width: 100% height: 60px - type: icon icon: mdi:car-door entity: sensor.doors_trunk_sq7 tap_action: more_info style: {color: white, left: 10%, top: 86%} - type: state-label entity: sensor.doors_trunk_sq7 style: {color: white, left: 10%, top: 95%} - type: state-icon entity: sensor.windows_sq7 tap_action: more_info style: {color: white, left: 30%, top: 86%} - type: state-label entity: sensor.windows_sq7 style: {color: white, left: 30%, top: 95%} - type: icon icon: mdi:oil entity: sensor.audi_sq7_oil_level tap_action: more_info style: {color: white, left: 50%, top: 86%} - type: state-label entity: sensor.audi_sq7_oil_level style: {color: white, left: 50%, top: 95%} - type: icon icon: mdi:room-service-outline entity: sensor.audi_sq7_service_inspection_time tap_action: more_info style: {color: white, left: 70%, top: 86%} - type: state-label entity: sensor.audi_sq7_service_inspection_time style: {color: white, left: 70%, top: 95%} - type: icon icon: mdi:speedometer entity: sensor.audi_sq7_mileage tap_action: more_info style: {color: white, left: 90%, top: 86%} - type: state-label entity: sensor.audi_sq7_mileage style: {color: white, left: 90%, top: 95%} - type: custom:circle-sensor-card entity: sensor.audi_sq7_tank_level max: 100 min: 0 stroke_width: 15 gradient: true fill: '#aaaaaabb' name: tank units: ' ' font_style: font-size: 1.0em font-color: white text-shadow: '1px 1px black' style: top: 5% left: 80% width: 4em height: 4em transform: none - type: custom:circle-sensor-card entity: sensor.audi_sq7_range max: 630 min: 0 stroke_width: 15 gradient: true fill: '#aaaaaabb' name: range units: ' ' font_style: font-size: 1.0em font-color: white text-shadow: '1px 1px black' style: top: 5% left: 5% width: 4em height: 4em transform: none
(**Optional**) | | `Region` | `string` | `DE` | The region where your Audi Connect account is registered:
• `DE` – Europe
• `US` – United States
• `CA` – Canada
• `CN` – China | | `Scan Interval` | `int` | `15` | Frequency (in minutes) to fetch status data from Audi Connect.
Minimum allowed is 15 minutes.
\* _Can be updated later via the CONFIGURE menu._ | | `API Level` | `int` | `0` | Determines the API structure used for service action calls:
• `0` – _Typically_ Gas vehicles (legacy format)
• `1` – _Typically_ e-tron (electric vehicles, newer format)
\* _Can be updated later via the CONFIGURE menu._ | ## Options Find configuration options under **Settings ➤ Devices & Services ➤ Integrations ➤ Audi Connect ➤ Configure**: | Name | Type | Default | Description | | ----------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Cloud Update at Startup` | `bool` | `True` | Toggle the initial cloud update when the integration starts. Useful for development or frequent Home Assistant restarts. | | `Refresh Vehicle Data After Action` | `bool` | `False` | Send a vehicle refresh command after every service action (e.g. climate, lock). This is typically not required as the vehicle will check in with the cloud on its own after a command. Each vehicle refresh counts against the API rate limit. To improve responsiveness, increase the Cloud Refresh Delay instead. | | `Cloud Refresh Delay` | `int` | `5` | Seconds to wait after a service action before refreshing cloud data. A longer delay gives the vehicle more time to report its updated state to the cloud. | | `Scan Interval` | `int` | `15` | Defines polling frequency in minutes (minimum 15). | | `Excluded VINs` | `str` | – | Comma-separated VIN list to exclude from setup and updates. | _Note: The integration will reload automatically upon clicking `Submit`, but a Home Assistant restart is suggested._ ## Service Actions ### Audi Connect: Refresh Vehicle Data `audiconnect.refresh_vehicle_data` Normal updates retrieve data from the Audi Connect cloud service, and don't interact directly with the vehicle. _This_ service action triggers an update request from the vehicle itself. When data is retrieved successfully, Home Assistant is automatically updated. The service action requires a vehicle identification number (VIN) as a parameter. #### Parameters - **`vehicle`**: The Audi vehicle to perform the action on. ### Audi Connect: Refresh Cloud Data `audiconnect.refresh_cloud_data` _This_ service action triggers an update request from the cloud. - Functionality: Updates data for all vehicles from the online source, mirroring the action performed at integration startup or during scheduled refresh intervals. - Behavior: Does not force a vehicle-side data refresh. Consequently, if vehicles haven't recently pushed updates, retrieved data might be outdated. - Note: This service action replicates the function of active polling without scheduling, offering a more granular control over data refresh moments. - **IMPORTANT:** This service action has no built in usage limits. Excessive use may result in a temporary suspension of your account. #### Parameters - `none` ### Audi Connect: Execute Vehicle Action `audiconnect.execute_vehicle_action` This service action allows you to perform actions on your Audi vehicle, specified by the vehicle identification number (VIN) and the desired action. #### Service Parameters - **`vehicle`**: The Audi vehicle to perform the action on. - **`action`**: The specific action to perform on the vehicle. Available actions include: - **`lock`**: Lock the vehicle. - **`unlock`**: Unlock the vehicle. - **`start_climatisation`**: Start the vehicle's climatisation system. (Legacy) -- Deprecated - **`stop_climatisation`**: Stop the vehicle's climatisation system. - **`start_charger`**: Start charging the vehicle. - **`start_timed_charger`**: Start the vehicle's charger with a timer. - **`stop_charger`**: Stop charging the vehicle. - **`start_preheater`**: Start the vehicle's preheater system. (Legacy) -- Deprecated - **`stop_preheater`**: Stop the vehicle's preheater system. - **`start_window_heating`**: Start heating the vehicle's windows. - **`stop_window_heating`**: Stop heating the vehicle's windows. #### Usage Example To initiate the lock action for a vehicle with VIN `WAUZZZ4G7EN123456`, use the following service call: service: audiconnect.execute_vehicle_action data: device_id: 034986de941a1f824b3f06c0a1d9333f action: "lock" #### Notes - Certain service actions require the S-PIN to be set in the configuration. - After a successful action, the integration waits for the configured **Cloud Refresh Delay** and then performs a cloud data refresh. If **Refresh Vehicle Data After Action** is enabled, a vehicle refresh is also sent before the delay. ### Audi Connect: Start Climate Control `audiconnect.start_climate_control` This service action allows you to start the climate control with options for temperature, glass surface heating, and auto seat comfort. #### Parameters - **`vehicle`**: The Audi vehicle to perform the action on. - **`temp_f`** (_optional_): Desired temperature in Fahrenheit. Default is `70`. - **`temp_c`** (_optional_): Desired temperature in Celsius. Default is `21`. - **`glass_heating`** (_optional_): Enable (`True`) or disable (`False`) glass heating. Default is `False`. - **`seat_fl`** (_optional_): Enable (`True`) or disable (`False`) the front-left seat heater. Default is `False`. - **`seat_fr`** (_optional_): Enable (`True`) or disable (`False`) the front-right seat heater. Default is `False`. - **`seat_rl`** (_optional_): Enable (`True`) or disable (`False`) the rear-left seat heater. Default is `False`. - **`seat_rr`** (_optional_): Enable (`True`) or disable (`False`) the rear-right seat heater. Default is `False`. #### Usage Example To start the climate control for a vehicle with VIN `WAUZZZ4G7EN123456` with a temperature of 72°F, enable glass heating, and activate both front seat heaters, use the following service call: service: audiconnect.start_climate_control data: device_id: 034986de941a1f824b3f06c0a1d9333f temp_f: 72 glass_heating: True seat_fl: True seat_fr: True #### Notes - The `temp_f` and `temp_c` parameters are mutually exclusive. If both are provided, `temp_f` takes precedence. - If neither `temp_f` nor `temp_c` is provided, the system defaults to 70°F or 21°C. - After a successful action, the integration waits for the configured **Cloud Refresh Delay** and then performs a cloud data refresh. If **Refresh Vehicle Data After Action** is enabled, a vehicle refresh is also sent before the delay. ### Audi Connect: Start Auxiliary Heating `audiconnect.start_auxiliary_heating` This service action allows you to start auxiliary heating the vehicle, with option for duration. #### Parameters - **`vehicle`**: The Audi vehicle to perform the action on. - **`duration`** (_optional_): The number of minutes the auxiliary heater should run before turning off. Default is `20` minutes if not provided. #### Usage Example To start the auxiliary heater for a vehicle with VIN `WAUZZZ4G7EN123456`, and a duration of 40 minutes, use the following service call action: service: audiconnect.start_auxiliary_heating data: device_id: 034986de941a1f824b3f06c0a1d9333f duration: 40 #### Notes - Requires the S-PIN to be set in the configuration. - After a successful action, the integration waits for the configured **Cloud Refresh Delay** and then performs a cloud data refresh. If **Refresh Vehicle Data After Action** is enabled, a vehicle refresh is also sent before the delay. ## Example Dashboard Card Below is an example Dashboard (Lovelace) card illustrating some of the sensors this Home Assistant addon provides.  The card requires the following front end mods: - https://github.com/thomasloven/lovelace-card-mod - https://github.com/custom-cards/circle-sensor-card These mods can (like this integration) be installed using HACS. The card uses the following code in `ui-lovelace.yaml` (or wherever your Dashboard is configured). - type: picture-elements image: /local/pictures/audi_sq7.jpeg style: | ha-card { border-radius: 10px; border: solid 1px rgba(100,100,100,0.3); box-shadow: 3px 3px rgba(0,0,0,0.4); overflow: hidden; } elements: - type: image image: /local/pictures/cardbackK.png style: left: 50% top: 90% width: 100% height: 60px - type: icon icon: mdi:car-door entity: sensor.doors_trunk_sq7 tap_action: more_info style: {color: white, left: 10%, top: 86%} - type: state-label entity: sensor.doors_trunk_sq7 style: {color: white, left: 10%, top: 95%} - type: state-icon entity: sensor.windows_sq7 tap_action: more_info style: {color: white, left: 30%, top: 86%} - type: state-label entity: sensor.windows_sq7 style: {color: white, left: 30%, top: 95%} - type: icon icon: mdi:oil entity: sensor.audi_sq7_oil_level tap_action: more_info style: {color: white, left: 50%, top: 86%} - type: state-label entity: sensor.audi_sq7_oil_level style: {color: white, left: 50%, top: 95%} - type: icon icon: mdi:room-service-outline entity: sensor.audi_sq7_service_inspection_time tap_action: more_info style: {color: white, left: 70%, top: 86%} - type: state-label entity: sensor.audi_sq7_service_inspection_time style: {color: white, left: 70%, top: 95%} - type: icon icon: mdi:speedometer entity: sensor.audi_sq7_mileage tap_action: more_info style: {color: white, left: 90%, top: 86%} - type: state-label entity: sensor.audi_sq7_mileage style: {color: white, left: 90%, top: 95%} - type: custom:circle-sensor-card entity: sensor.audi_sq7_tank_level max: 100 min: 0 stroke_width: 15 gradient: true fill: '#aaaaaabb' name: tank units: ' ' font_style: font-size: 1.0em font-color: white text-shadow: '1px 1px black' style: top: 5% left: 80% width: 4em height: 4em transform: none - type: custom:circle-sensor-card entity: sensor.audi_sq7_range max: 630 min: 0 stroke_width: 15 gradient: true fill: '#aaaaaabb' name: range units: ' ' font_style: font-size: 1.0em font-color: white text-shadow: '1px 1px black' style: top: 5% left: 5% width: 4em height: 4em transform: none