Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

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: 5 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)



## Notice



Due to API changes it might be that currently not all functionality is given. Please open a issue to report the topics you are missing.



## Maintainers Wanted



Due to time limitations this project is not actively maintained anymore. It will continue to work as long as Audi does not change the API again.

However, I'm open to someone else taking the lead. If you would like to become a maintainer, please contact me.



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



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



![image](https://github.com/user-attachments/assets/facff84e-f40f-4090-9e44-80f698385426)



### Configuration Variables



**username**



- (string)(Required) The username associated with your Audi Connect account.



**password**



- (string)(Required) The password for your Audi Connect account.



**S-PIN**



- (string)(Optional) The S-PIN for your Audi Connect account.



**region**



- (Required) The region where your Audi Connect account is registered.

  - 'DE' for Europe (or leave unset)

  - 'US' for United States of America

  - 'CA' for Canada

  - 'CN' for China



**scan_interval**



- (number)(Optional) The frequency in minutes for how often to fetch status data from Audi Connect. (Optional. Default is 15 minutes, can be no more frequent than 15 min.)



## Options



Find configuration options under **Settings ➤ Devices & Services ➤ Integrations ➤ Audi Connect ➤ Configure**:



- **Cloud Update at Startup (`bool`)**: Toggle cloud updates at integration startup. Ideal for development or frequent HA restarts.

- **Active Polling at Scan Interval (`bool`)**: Enable or disable active polling.

- **Scan Interval (`int`)**: Defines polling frequency in minutes (minimum 15). Effective only if "Active Polling at Scan Interval" is enabled.



_Note: A Home Assistant restart is required for changes to take effect._



## Services



### 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 triggers an update request from the vehicle itself. When data is retrieved successfully, Home Assistant is automatically updated. The service requires a vehicle identification number (VIN) as a parameter.



#### Service 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 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 replicates the function of active polling without scheduling, offering a more granular control over data refresh moments.

- **IMPORTANT:** This service has no built in usage limits. Excessive use may result in a temporary suspension of your account.



#### Service Parameters



- `none`



### Audi Connect: Execute Vehicle Action



`audiconnect.execute_vehicle_action`



This service 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)

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

  - **`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 action require the S-PIN to be set in the configuration.

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



### Audi Connect: Start Climate Control



`audiconnect.start_climate_control`



This service allows you to start the climate control with options for temperature, glass surface heating, and auto seat comfort.



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

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

- When the 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

```



[buymecoffee]: https://buymeacoff.ee/arjenvrh

[buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a%20beer-donate-yellow.svg?style=for-the-badge

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

[commits]: https://github.com/arjenvrh/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/arjenvrh/audi_connect_ha?style=for-the-badge

[maintenance-shield]: https://img.shields.io/badge/maintainer-Arjen%20van%20Rhijn%20%40arjenvrh-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