🚗 HomeAssistant - Commute Helper

Home Assistant integration for real-time commute briefings with traffic, weather, and transport updates

Features • Installation • Configuration • Contributing

---

✨ Features

Feature	Description
🚦 Real-time Traffic	Live traffic conditions on your commute route
🌤️ Weather Briefing	Current conditions and forecast for departure
🚇 Transit Updates	Public transport delays and disruptions
🎙️ Voice Announcements	TTS briefings via smart speakers
⏰ Smart Scheduling	Briefings based on your work schedule
📊 Commute Stats	Track and analyze commute times
🔄 Scraper Microservice	Real-time data collection
🏠 HACS Compatible	Easy installation via HACS

---

📋 Prerequisites

Requirement	Version
Home Assistant	2023.1+
HACS	Latest
Python	3.11+ (for scraper)

Required Integrations

• Google Maps API (or alternative)
• Weather integration (e.g., Met Office, OpenWeatherMap)
• TTS service (optional, for voice briefings)

---

🚀 Installation

Option 1: HACS (Recommended)

1. Open HACS in Home Assistant
2. Click Integrations → + Explore & Download Repositories
3. Search for "HA Commute Helper"
4. Click Download
5. Restart Home Assistant

Option 2: Manual Installation

# Clone the repository
cd /config
git clone https://github.com/CaputoDavide93/ha-commute-helper.git

# Copy custom component
cp -r ha-commute-helper/custom_components/commute_helper custom_components/

# Copy packages
cp -r ha-commute-helper/packages/* packages/

# Restart Home Assistant

Option 3: With Scraper Microservice

# Deploy scraper
cd scraper-microservice
docker-compose up -d

---

⚙️ Configuration

1. Configure Secrets

Copy and edit the secrets template:

cp secrets_template.yaml secrets.yaml

# secrets.yaml
commute_origin: "Your Home Address"
commute_destination: "Your Work Address"
google_maps_api_key: "your-api-key"
weather_api_key: "your-weather-key"

2. Add to configuration.yaml

# configuration.yaml
homeassistant:
  packages: !include_dir_named packages/

commute_helper:
  origin: !secret commute_origin
  destination: !secret commute_destination
  arrival_time: "09:00"
  departure_sensor: sensor.commute_departure_time

3. Configure Automations

automation:
  - alias: "Morning Commute Briefing"
    trigger:
      - platform: time
        at: "07:00"
    condition:
      - condition: state
        entity_id: binary_sensor.workday_sensor
        state: "on"
    action:
      - service: tts.speak
        entity_id: media_player.kitchen_speaker
        data:
          message: "{{ state_attr('sensor.commute_briefing', 'full_text') }}"

---

📖 Usage

Available Entities

Entity	Description
sensor.commute_time	Current estimated commute (minutes)
sensor.commute_departure_time	Recommended departure time
sensor.commute_briefing	Full text briefing
binary_sensor.commute_delayed	True if delays detected
sensor.commute_traffic_level	Traffic severity (low/medium/high)

Lovelace Card Example

type: entities
title: Morning Commute
entities:
  - entity: sensor.commute_time
    name: Travel Time
  - entity: sensor.commute_departure_time
    name: Leave By
  - entity: sensor.commute_traffic_level
    name: Traffic
  - entity: sensor.weather_temperature
    name: Temperature

---

🔧 Architecture

graph TD
    A[Scraper Microservice] --> B[Home Assistant]
    C[Google Maps API] --> B
    D[Weather API] --> B
    E[Transit API] --> B
    B --> F[Sensor Entities]
    F --> G[Automations]
    G --> H[TTS / Notifications]

Loading

Project Structure

ha-commute-helper/
├── custom_components/
│   └── commute_helper/
│       ├── __init__.py
│       ├── manifest.json
│       └── sensor.py
├── packages/
│   └── commute_helper.yaml
├── scraper-microservice/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── main.py
├── hacs.json
└── secrets_template.yaml

---

🎙️ Voice Briefings

Example Briefing Output

"Good morning! Your commute to work is currently 35 minutes due to moderate traffic on the M25. The weather is partly cloudy at 12 degrees. Leave by 8:25 to arrive on time. Have a great day!"

Customizing Briefings

# In packages/commute_helper.yaml
template:
  - sensor:
      - name: "Commute Briefing"
        state: "{{ states('sensor.commute_time') }} min"
        attributes:
          full_text: >
            Good morning! Your commute is {{ states('sensor.commute_time') }} minutes.
            {% if states('sensor.commute_traffic_level') != 'low' %}
            There is {{ states('sensor.commute_traffic_level') }} traffic.
            {% endif %}
            Temperature is {{ states('sensor.weather_temperature') }}°.

---

🐛 Troubleshooting

Common Issues

❌ Entity Not Found

# Check if component loaded
ha core info

# Verify configuration
ha core check

❌ API Rate Limit

Reduce polling frequency in configuration:

commute_helper:
  scan_interval: 600  # 10 minutes

❌ Scraper Not Connecting

# Check scraper logs
docker-compose logs -f scraper

# Verify network connectivity
curl http://localhost:8080/health

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👤 Author

Davide Caputo

---

⭐ If this tool helped you, please give it a star! ⭐