NextBus HACS Integration

Custom Home Assistant integration for fetching NextBus arrival predictions. This repository mirrors the upstream nextbus integration so it can be developed and fixed outside of Home Assistant core.

---

Features

• Fetches live predictions from the NextBus public API
• Simple configuration via the Home Assistant UI
• Optional Lovelace card for displaying upcoming departures
• Built-in request timeouts and error handling for improved reliability
• Automation blueprints for notifications and MQTT publishing
• Fully tested with pytest

Installation

Via HACS

1. Make sure HACS is installed and working in your Home Assistant instance.
2. In HACS, add this repository as a Custom Repository (integration category).
3. Install the NextBus integration from the list.
4. Restart Home Assistant.

Manual

1. Copy the custom_components/nextbus folder to <config>/custom_components/nextbus in your Home Assistant configuration directory.
2. (Optional) Copy next-bus-card.js into <config>/www and add it as a resource to your dashboard.
3. Restart Home Assistant.

Configuration

1. Navigate to Settings → Devices & services in Home Assistant.
2. Click Add Integration and search for NextBus.
3. Enter the agency and stop information when prompted.
4. Save to create the entity.

Automation Blueprints

Two blueprints are included to help you automate around bus arrivals:

• Publish NextBus predictions to MQTT – forwards sensor data to an MQTT topic.
• Notify when NextBus is approaching – sends a notification when a bus is within a configurable number of minutes.

Import the blueprints from the blueprints/automation/nextbus directory into Home Assistant to use them.

Lovelace Card

After copying next-bus-card.js into your dashboard resources, create a card using the next-bus-card type:

type: custom:next-bus-card
entity: sensor.my_bus_stop

Debugging

Enable debug logging either during configuration or through configuration.yaml:

logger:
  default: info
  logs:
    custom_components.nextbus: debug

Logs can then be viewed via Settings → System → Logs or the Home Assistant log file.

Development

Requirements

• Python 3.11+
• requests, pytest, flake8, black

Setup

./setup.sh
source .venv/bin/activate

Running Tests

pytest

Code Style

Format code with black and ensure linting passes with flake8 before committing.

Contributing

Issues and pull requests are welcome. If proposing a new feature, please open an issue first to discuss your idea.

License

Distributed under the MIT License. See LICENSE for details.