Getting Started¶

This guide will walk you through setting up the AutoPi Home Assistant integration from start to finish.

Prerequisites¶

Before you begin, ensure you have:

AutoPi Requirements¶

• AutoPi Account: Active account at app.autopi.io
• AutoPi Device: At least one AutoPi device installed in your vehicle
• API Token: AutoPi API token with vehicle access permissions

Home Assistant Requirements¶

• Home Assistant: Version 2023.1.0 or later
• Administrator Access: Ability to install custom integrations
• Internet Connection: For communication with AutoPi cloud services

Step 1: Obtain AutoPi API Token¶

Method 1: AutoPi Dashboard (Recommended)¶

1. Log in to app.autopi.io
2. Navigate to Account Settings → API Tokens
3. Click Generate New Token
4. Give your token a descriptive name (e.g., "Home Assistant")
5. Select appropriate permissions (minimum: vehicle read access)
6. Copy and save the token securely

Method 2: API Documentation¶

1. Visit the AutoPi API documentation
2. Follow the authentication guide
3. Generate a token programmatically if needed

Step 2: Install the Integration¶

Choose your preferred installation method:

Option A: HACS Installation (Recommended)¶

1. Install HACS (if not already installed):
2. Visit HACS installation guide

3. Follow the installation instructions

4. Add Custom Repository:

   Repository: rknightion/autopi-ha
   Category: Integration
   

5. Install Integration:

6. Search for "AutoPi" in HACS
7. Click Install
8. Restart Home Assistant

Option B: Manual Installation¶

1. Download Latest Release:
2. Go to GitHub Releases

3. Download autopi.zip from the latest release

4. Extract Files:

   # Extract to your Home Assistant config directory
   unzip autopi.zip -d config/custom_components/
   

5. Restart Home Assistant:

6. Restart your Home Assistant instance
7. The integration will be available after restart

Step 3: Add Integration¶

1. Navigate to Integrations:
2. Go to Settings → Devices & Services

3. Click + Add Integration

4. Search for AutoPi:

5. Type "AutoPi" in the search box

6. Select AutoPi from the results

7. Configure Connection:

8. API Token: Enter your AutoPi API token
9. Base URL (optional): Use default unless you have a custom endpoint

10. Click Submit

11. Select Vehicles:

12. The integration will discover your vehicles
13. Select which vehicles you want to monitor
14. Click Submit

Step 4: Configure Options (Optional)¶

After adding the integration, you can configure update intervals:

1. Access Integration Options:
2. Go to Settings → Devices & Services
3. Find AutoPi integration

4. Click Configure

5. Set Update Interval:

6. Update Interval (1-10 min): All vehicle data including position, status, and metrics, default 1 minute

7. Save Configuration:

8. Click Submit
9. Integration will reload with new settings

Step 5: Verify Installation¶

After setup, you should see:

New Devices¶

• One device per monitored vehicle
• Named with vehicle's call name or license plate
• Located under Settings → Devices & Services → AutoPi

New Entities¶

For each vehicle: - Device Tracker: device_tracker.{vehicle_name} - Status Sensor: sensor.{vehicle_name}_status - Position Sensors: Speed, altitude, course, GPS satellites - Diagnostic Sensors: Latitude, longitude

Integration-wide: - Vehicle Count: sensor.autopi_vehicle_count - API Statistics: API calls, failures, success rate - Performance: Update duration

Dashboard Cards¶

The entities will automatically appear in: - Map card: Vehicle locations - Entity cards: Vehicle status and metrics - History graphs: Sensor data over time

Troubleshooting¶

Common Issues¶

"Invalid API Token"¶

• Verify your token is correct and hasn't expired
• Check token permissions include vehicle access
• Regenerate token if necessary

"No Vehicles Found"¶

• Ensure your AutoPi devices are online
• Check vehicle registration in AutoPi dashboard
• Verify API token has access to vehicles

"Connection Failed"¶

• Check internet connectivity
• Verify AutoPi service status
• Try again after a few minutes

"Integration Won't Load"¶

• Restart Home Assistant completely
• Check logs for detailed error messages
• Verify installation files are correct

Getting Help¶

If you encounter issues:

1. Check Logs:

   # Add to configuration.yaml for detailed logging
   logger:
     default: info
     logs:
       custom_components.autopi: debug
   

2. Search Issues: Check GitHub Issues

3. Report Bugs: Create a new issue with:

4. Home Assistant version
5. Integration version
6. Relevant log entries
7. Steps to reproduce

Next Steps¶

Once installation is complete:

• Configuration Guide: Detailed configuration options
• Entity Reference: Complete list of available entities
• API Optimization: Optimize API usage and performance
• Vehicle Data: Understanding vehicle data and attributes

Security Best Practices¶

API Token Management¶

• Store tokens securely
• Rotate tokens periodically
• Use minimal required permissions
• Monitor token usage in AutoPi dashboard

Network Security¶

• Use HTTPS for Home Assistant (recommended)
• Consider VPN for remote access
• Monitor integration logs for unusual activity

Data Privacy¶

• Vehicle location data is sensitive
• Review Home Assistant data retention policies
• Consider excluding location entities from recorder if desired