Audi Connect Integration for Home Assistant

[![GitHub Activity][commits-shield]][commits] ![License][license-shield] [![Code Style][blackbadge]][black] ![hacs][hacsbadge]

Notices

Due to API changes, currently not all functionality is available. Please open a issue to report the topics you are missing.

[!Caution] Excessive use of certain features in this integration may result in temporary or permanent suspension of your Audi Connect account. Please use responsibly — abuse or misuse could potentially impact access for the entire community. Use at your own risk.

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 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.

The easiest and recommended way is to install the integration using HACS, 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.

[!CAUTION] This service action counts against your daily API rate limit. Repeated use may exhaust your limit. Use sparingly and monitor your remaining API calls via the "API Requests Remaining" diagnostic sensor or Settings → System → Repairs & System Information.

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 illu