VigoBus Pro

Custom integration for Home Assistant that exposes Vigo urban bus arrival times from Vitrasa, nearest stop support, extra stops, and line alerts.

• Nearest stop sensor based on your home location
• Per-device nearest stop sensors: pick person/device_tracker entities in the config menu, or auto-create one for every GPS device (home stop is kept, never removed). Each of these sensors exposes an is_device_nearest attribute so dashboards (like the companion card) can reliably tell them apart from the home stop or a manually configured extra stop
• Every stop (home, extra, or per-device) is grouped as its own Home Assistant device, bundling its 4 sensors (state, line, route, upcoming) together in Settings → Devices & Services instead of a flat sensor list. Existing installs pick this up automatically on the next restart — no reconfiguration needed. A stop's device can be deleted from that page like any other device; if it's still configured (home nearest, an extra stop, a tracked person) it comes back automatically on the next reload, and if you removed it from the config it stays gone
• Additional configurable stops
• Arrival estimates with line, route, minutes, and bus distance
• Optional line filter per stop (nearest or extra) so a sensor only reports arrivals for one bus line
• Each upcoming bus is tagged with Vitrasa's own official line color (from their public line-geometry data), exposed as a color field per bus so dashboards can match the real livery instead of guessing
• Line alerts in Spanish and Galician with fallback
• Support for multiple route variants on the same line
• Local brand images included (custom_components/vigobus/brand) for Home Assistant 2026.3+
• Lovelace card support through the companion dashboard card repo
• Stop list, line colors, and alerts are cached in memory (not re-downloaded on every scan cycle) and independent devices/stops are refreshed concurrently, so scans stay fast even with several tracked people or configured stops
• Backs off automatically after repeated failures instead of retrying at full speed against a backend that's down, and resets to the configured interval as soon as it recovers
• Diagnostics support: Settings → Devices & Services → VigoBus Pro → Download diagnostics gives a redacted snapshot of coordinator/config state for bug reports, without needing to paste coordinates or custom stop names
• Optional "Notify when a new alert appears" toggle, with an optional list of notify services/devices to also send it to (in addition to the Home Assistant notifications panel)
• Trip planner: vigobus.geocode, vigobus.search_stops, and vigobus.plan_trip services plan a real bus trip (with transfers) from an origin to a destination — a free-text address or named place (a school, a shopping mall, a hospital), not just an exact stop — using Vigo's official static GTFS schedule for Vitrasa and OpenStreetMap's public Nominatim geocoder. Each bus leg carries its real as-driven street geometry (from the feed's shapes.txt, trimmed to the boarding/alighting stop), so the companion card can draw it following the actual route instead of a straight line. Passing an optional ors_api_key (a free OpenRouteService key) does the same for the first/last walk legs — no free, keyless walking-routing service exists that's safe for a distributed app, so this one part is opt-in. The companion card's "Plan a trip" section (its own on/off toggle) is built on these; it returns several ranked route options, not just one. Known limitations: only the itinerary's first bus leg is cross-checked against live arrival data; a query very late at night may miss a trip that started the previous service day

1. Open HACS.
2. Add a custom repository.
3. Use the repository URL for this integration.
4. Select the category Integration.
5. Install VigoBus Pro and restart Home Assistant.

Repository URL: https://github.com/MUbeira0/vigobus-integration

Add the integration from Home Assistant UI:

• Settings
• Devices & Services
• Add Integration
• Search for VigoBus Pro

First-time setup only asks what's needed for the home nearest-stop sensor — extra stops are added afterwards from Configure, which has a guided search-and-pick UI (and a paste-a-list option for anyone who already knows their stop IDs). Configure is also split into three focused sections instead of one long form: Location & nearest stop, Notifications, and Alerts.

• Real-time ETA for Vigo urban bus stops
• Line and route information for each next arrival
• Remaining bus distance (when available)
• Service alerts per line (Spanish and Galician, with fallback)

The vigobus.geocode service (used by the card's destination search) sends whatever text is typed there to OpenStreetMap's public Nominatim service — that's the only way to resolve a free-text address or place name into coordinates without adding a paid API key. Nothing else in this integration talks to a third party beyond Vigo's own open-data endpoints. Requests are capped at roughly one per second and cached for an hour, per Nominatim's usage policy; place results shown anywhere must be attributed to OpenStreetMap contributors (the companion card does this).

• If entities do not appear after install, restart Home Assistant.
• If icon/logo does not refresh, clear frontend cache and reload.
• If stop IDs changed upstream, open an issue with the affected stop and line.

• Documentation: https://github.com/MUbeira0/vigobus-integration
• Issues: https://github.com/MUbeira0/vigobus-integration/issues
• Releases: https://github.com/MUbeira0/vigobus-integration/releases

The integration creates sensors for each configured stop:

• Main stop sensor
• Line sensor
• Route sensor
• Upcoming buses sensor

The dashboard card is intended to be published as a separate HACS Dashboard repository.

Stateless lookup used by the companion card's "my location" mode: given a latitude/longitude it returns the closest stop(s) with their upcoming buses. It does not read or store any device tracker — callers (typically a dashboard card reading the viewing device's own live geolocation) pass coordinates on every call, so the result reflects whoever is looking at the dashboard at that moment rather than a fixed home or tracker location. When more than one stop is within tie_margin_m (default 60m) of the closest one, several candidates are returned instead of just one.

service: vigobus.nearest_stops
data:
  latitude: 42.2328
  longitude: -8.7226