Smartcar Integration for Home Assistant

Connect your compatible vehicle to Home Assistant using the Smartcar API.

This integration provides various sensors and controls for vehicles linked through the Smartcar platform, allowing you to monitor and interact with your car directly within Home Assistant.

Note: This integration relies on the Smartcar service. Availability of specific features depends on your vehicle's make, model, year, your Smartcar account plan (especially API rate limits), and the permissions granted during authentication.

Example showing entities for a Volkswagen ID.4

Prerequisites

1. Compatible Vehicle: Your car must be compatible with Smartcar and the API must also be supported in your country.
2. Smartcar Developer Account: You need a free developer account from Smartcar.
   • Go to developer.smartcar.com and sign up.
   • Log in to your Developer Dashboard.
3. Ensure a Smartcar Application exists:
   • In the dashboard, go to "Applications" and ensure an application was automatically created for you.
   • Rename your application if you want to (e.g., "Home Assistant Connect").

Installation

HACS

Installation through HACS is the preferred installation method.

1. Click the button above or go to HACS → Integrations → search for "Smartcar" → select it.
2. Press DOWNLOAD.
3. Select the version (it will auto select the latest) → press DOWNLOAD.
4. Restart Home Assistant then continue to the setup section.

Manual Download

1. Go to the release page and download the smartcar.zip attached to the latest release.
2. Unpack the zip file and move custom_components/smartcar to the following directory of your Home Assistant configuration: /config/custom_components/.
3. Restart Home Assistant then continue to the setup section.

Setup

Configuration is done via the Home Assistant UI after installation.

1. Navigate to "Settings" → "Devices & Services"
2. Click "+ Add Integration"
3. Search for and select → "Smartcar"

Or you can use the My Home Assistant Button below.

Follow the instructions to configure the integration.

Configuration Flow

Authorization Data Entry

1. Choose a name for your credentials and enter the Client ID and Client Secret which can be found in the Smartcar dashboard.

2. Crucially, set the "Redirect URIs" in the Smartcar settings for your application. You need to add exactly the URI your Home Assistant instance uses for OAuth callbacks.

   • Most users will simply use the My Home Assistant URI: https://my.home-assistant.io/redirect/oauth

     Note: This is not a placeholder. It is the URI that must be used unless you’ve disabled or removed the default_config: line from your configuration and disabled the My Home Assistant Integration.

   • Add only the correct URI for your setup.

3. Continue to the next step.

4. Select the Permissions you want Home Assistant to be able to access. To enable all entities in this integration, select all relevant permissions:

   • Get total distance traveled
   • Get the vehicle's location
   • Get EV/PHEV battery level, capacity & current range
   • Get details on whether the car is plugged in and charging
   • Get details on whether doors, windows & more are enabled
   • Get engine oil health
   • Get tire pressure details
   • Get fuel tank level
   • Control charging (start/stop & target charge)
   • Lock or unlock vehicle

   * Functionality for all permissions depends on car support

5. Continue to the next section which explains the steps to authorize your vehicle via Smartcar connect.

Authorization via Smartcar Connect

1. You will be redirected to the Smartcar website (or a new tab will open).
2. Log in using the credentials for your vehicle's connected services account (e.g., your Volkswagen ID, FordPass account, Tesla account), NOT your Smartcar developer account credentials.
3. Review the permissions requested by Home Assistant (these should match the scopes you selected when creating the Smartcar application).
4. Grant access to allow Home Assistant to connect to your vehicle(s) via Smartcar.
5. You should be redirected back to Home Assistant.

Setup Complete

If successful, the integration will be added, and Home Assistant will create devices and entities for your connected vehicle(s). From here:

• Enable entities you want access after understanding the impact on rate limits.
• Consider creating a customized polling setup via automations.

Entities

Several entities are created for for each connected vehicle (subject to vehicle compatibility and granted permissions) across the device tracker, sensor, binary sensor, number, switch, and lock platforms:

• device_tracker.<make_model>_location
• sensor.<make_model>_battery_capacity
• sensor.<make_model>_battery
• sensor.<make_model>_charging_status
• sensor.<make_model>_engine_oil_life
• sensor.<make_model>_fuel
• sensor.<make_model>_odometer
• sensor.<make_model>_range
• sensor.<make_model>_tire_pressure_back_left
• sensor.<make_model>_tire_pressure_back_right
• sensor.<make_model>_tire_pressure_front_left
• sensor.<make_model>_tire_pressure_front_right
• binary_sensor.<make_model>_charging_cable_plugged_in
• number.<make_model>_charge_limit
• switch.<make_model>_charging
• lock.<make_model>_door_lock

All entities have the following attributes:

• age The date at which the data was recorded by the vehicle*; corresponds to sc-data-age
• fetched_at The date at which Smartcar fetched the data*; corresponds to sc-data-fetched-at

* These will only be present when included in the API response.

Links to relevant API documentation are provided for each entity described below as well as the permissions each entity requires. When the required permissions are not requested during setup, those entities will not be created.

device_tracker.<make_model>_location

The GPS location of the vehicle.

Enabled by default: ✅
Requires permissions: read_location

sensor.<make_model>_battery_capacity

The battery capacity of this vehicle in kWh.

Enabled by default: ❌
Requires permissions: read_battery

sensor.<make_model>_battery

The state of charge of the vehicle as a percentage.

Enabled by default: ✅
Requires permissions: read_battery
Obtained concurrently with: sensor.<make_model>_range

sensor.<make_model>_charging_status

The charging status of the vehicle.

Possible values:

• ​CHARGING
• FULLY_CHARGED
• NOT_CHARGING

Enabled by default: ✅
Requires permissions: read_charge
Obtained concurrently with: binary_sensor.<make_model>_charging_cable_plugged_in, switch.<make_model>_charging

sensor.<make_model>_engine_oil_life

The estimated engine oil life remaining for the vehicle.

Enabled by default: ❌
Requires permissions: read_engine_oil

sensor.<make_model>_fuel

The amount of fuel remaining for the vehicle.

Enabled by default: ❌
Requires permissions: read_fuel

sensor.<make_model>_odometer

The odometer reading of the vehicle.

Enabled by default: ❌
Requires permissions: read_odometer

sensor.<make_model>_range

The estimated range remaining for the vehicle.

Enabled by default: ✅
Requires permissions: read_battery
Obtained concurrently with: sensor.<make_model>_battery

sensor.<make_model>_tire_pressure_back_left

The back left tire pressure of the vehicle.

Enabled by default: ❌
Requires permissions: read_tires
Obtained concurrently with: sensor.<make_model>_tire_pressure_back_right, sensor.<make_model>_tire_pressure_front_left, sensor.<make_model>_tire_pressure_front_right

sensor.<make_model>_tire_pressure_back_right

The back right tire pressure of the vehicle.

Enabled by default: ❌
Requires permissions: read_tires
Obtained concurrently with: sensor.<make_model>_tire_pressure_back_left, sensor.<make_model>_tire_pressure_front_left, sensor.<make_model>_tire_pressure_front_right

sensor.<make_model>_tire_pressure_front_left

The front left tire pressure of the vehicle.

Enabled by default: ❌
Requires permissions: read_tires
Obtained concurrently with: sensor.<make_model>_tire_pressure_back_left, sensor.<make_model>_tire_pressure_back_right, sensor.<make_model>_tire_pressure_front_right

sensor.<make_model>_tire_pressure_front_right

The front right tire pressure of the vehicle.

Enabled by default: ❌
Requires permissions: read_tires
Obtained concurrently with: sensor.<make_model>_tire_pressure_back_left, sensor.<make_model>_tire_pressure_back_right, sensor.<make_model>_tire_pressure_front_left

binary_sensor.<make_model>_charging_cable_plugged_in

Whether the vehicle is currently plugged in.

Enabled by default: ✅
Requires permissions: read_charge
Obtained concurrently with: sensor.<make_model>_charging_status, switch.<make_model>_charging

number.<make_model>_charge_limit

Change the charge limit by setting it to a specific value.

Enabled by default: ❌
Requires permissions: read_charge, control_charge

switch.<make_model>_charging

Change whether the vehicle is currently charging by starting or stopping charging.

Enabled by default: ✅
Requires permissions: read_charge, control_charge
Obtained concurrently with: sensor.<make_model>_charging_status, binary_sensor.<make_model>_charging_cable_plugged_in

lock.<make_model>_door_lock

Change whether the vehicle is currently locked by locking or unlocking.

Enabled by default: ✅
Requires permissions: read_security, control_security

Note: some models, e.g., VW ID.4 2023+ do not have this functionality.

Rate Limits & Polling

• Smartcar's free developer tier typically has a limit of 500 API calls per vehicle per month. Exceeding this may incur costs or stop the integration from working.
• By default, it uses 6 hour polling interval and only fetches data required for enabled entities.
• Polling can be customized as well.

Customized Polling

To customize polling, you can disable polling on the integration and write your own automation.

• First, configure the integration as described above.
• Go to Settings → Integartions (under Devices & services) → Smartcar
• Click the three dots to the right of the integration.
• Choose System options.
• Disable Enable polling for changes and then click Save.
• Create an automation using homeassistant.update_entity to refresh the desired value(s).

Examples are provided:

• examples/poll-smartcar-simple.yaml
• examples/poll-smartcar-custom.yaml
• examples/poll-smartcar-excessive.yaml

When updating an entity via homeassistant.update_entity:

• A request to update an entity will also update related entities (see the Obtained concurrently with notes on each entity above).
• Requests to update several entities at once will be batched, reducing excessive network requests and potentially limiting the number of API calls counted against your account.

For instance:

• homeassistant.update_entity on sensor.<make_model>_battery and sensor.<make_model>_range will make a single batch request that counts as one API call because the entities are related.
• homeassistant.update_entity on sensor.<make_model>_battery and sensor.<make_model>_odometer will make a single batch request that counts as two API calls since they are unrelated.

Known Issues / Limitations

• Vehicle Compatibility: Not all features are supported by all vehicle makes/models/years via the Smartcar API. Entities for unsupported features (e.g., fuel status for EVs or lock control for VW ID.4 2023+) may or may still be created, but not function. Check the Smartcar compatibility details for your specific vehicle.
• API Latency: There can be significant delays (seconds to minutes) between sending a command (e.g., start charging) and the vehicle executing/reporting the change back through the API. The state in Home Assistant will update after the next successful data poll.
• Rate Limits: Be mindful of the 500 calls/vehicle/month limit on the free tier.

Support / Issues

Please report any issues you find with this integration by opening an issue on the GitHub Issues page.