Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/audiconnect/audi_connect_ha

Adds an audi connect integration to home assistant
https://github.com/audiconnect/audi_connect_ha

audi audi-connect hacs-integration homeassistant integration sensors

Last synced: 13 days ago
JSON representation

Adds an audi connect integration to home assistant

Awesome Lists containing this project

README 

        
# Audi Connect Integration for Home Assistant



[![GitHub Activity][commits-shield]][commits]

[![License][license-shield]](LICENSE.md)

[![Code Style][blackbadge]][black]

[![hacs][hacsbadge]](hacs)



## Notices



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



⚠️ Warning: 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](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   | Description                                                                                                                                                                     |

| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| `Cloud Update at Startup`         | `bool` | Toggle the initial cloud update when the integration starts. Useful for development or frequent Home Assistant restarts.                                                        |

| `Active Polling at Scan Interval` | `bool` | Enable or disable active polling.                                                                                                                                               |

| `Scan Interval`                   | `int`  | Defines polling frequency in minutes (minimum 15). Only effective if **Active Polling** is enabled.                                                                             |

| `API Level`                       | `int`  | Determines the API structure used for service action calls:
• `0` – _Typically_ Gas vehicles (legacy format)
• `1` – _Typically_ e-tron (electric vehicles, newer format) |



_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



- **`vin`**: The Vehicle Identification Number (VIN) of the Audi you want to control.



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



- **`vin`**: The Vehicle Identification Number (VIN) of the Audi you want to control.

- **`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:



```yaml

service: audiconnect.execute_vehicle_action

data:

  vin: "WAUZZZ4G7EN123456"

  action: "lock"

```



#### Notes



- Certain service actions require the S-PIN to be set in the configuration.

- When the service action is successfully performed, an update request is automatically triggered.



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



- **`vin`**: The Vehicle Identification Number (VIN) of the Audi you want to control.

- **`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:



```yaml

service: audiconnect.start_climate_control

data:

  vin: "WAUZZZ4G7EN123456"

  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.

- When the service action is successfully performed, an update request is automatically triggered.



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



- **`vin`**: The Vehicle Identification Number (VIN) of the Audi you want to control.

- **`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:



```yaml

service: audiconnect.start_auxiliary_heating

data:

  vin: "WAUZZZ4G7EN123456"

  duration: 40

```



#### Notes



- Requires the S-PIN to be set in the configuration.

- When the service action is successfully performed, an update request is automatically triggered.



## Example Dashboard Card



Below is an example Dashboard (Lovelace) card illustrating some of the sensors this Home Assistant addon provides.



![Example Dashboard Card](card_example.png)



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



```yaml

     - 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

```



[commits-shield]: https://img.shields.io/github/commit-activity/y/audiconnect/audi_connect_ha?style=for-the-badge

[commits]: https://github.com/audiconnect/audi_connect_ha/commits/master

[hacs]: https://github.com/custom-components/hacs

[hacsbadge]: https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge

[license-shield]: https://img.shields.io/github/license/audiconnect/audi_connect_ha?style=for-the-badge

[maintenance-shield]: https://img.shields.io/badge/maintainer-audiconnect-blue.svg?style=for-the-badge

[blackbadge]: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge

[black]: https://github.com/ambv/black