Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bcpearce/homeassistant-gtfs-realtime

Home Assistant Custom Integration for GTFS Realtime Data
https://github.com/bcpearce/homeassistant-gtfs-realtime

custom-component gtfs gtfs-realtime hacs home-assistant

Last synced: 17 days ago
JSON representation

Home Assistant Custom Integration for GTFS Realtime Data

Awesome Lists containing this project

README 

        

![GTFS Realtime](resources/logo.svg)

# GTFS Realtime for Home Assistant



## Installation



This integration can be installed manually or through [HACS](https://hacs.xyz/) as a custom repository.



#### Manual



Copy files in [custom_components/gtfs_realtime](custom_components/gtfs_realtime/) to [/path/to/homeassistant/config/custom_components/gtfs_realtime](#).



#### HACS



1. Go to HACS in your Home Assistant Integration

2. Select "Integrations"

3. Click the "..." in the upper left corner.

4. Go to Custom Repositories

5. Add this repository's URL https://github.com/bcpearce/homeassistant-gtfs-realtime in "Repository", and set the category to "Integration"



## Configuration



Once the integration is installed, the configure the integration through Settings >> Devices and Services, and use "Add Integration".  Select GTFS Realtime and follow the instructions in the user interface.



You can select a supported provider or configure it manually. 



### Realtime Feed URLs



These are the URLs that will be queried for realtime updates. Using a preconfigured provider may include feeds you do not need, these can be deleted here to improve performance.



### Static Feed URLs



Less frequently updated data will be provided as one or more .zip files. Include the URL your provider supplies these files at. It will be updated daily. 



### API Key



If your provider requires an API Key. It must be included. Otherwise, leave this blank. The API Key will be supplied as a header under the "api_key" field.



### Route Icons



Optionally route icons can be included.  The integration will default to using MDI icons otherwise. For NYC Subway integrations, and other supported integrations, the resources folder may contain valid route icons to use.  



For custom use, a URL must be provided that includes up to three Python format braces for `{route_id}`, `{route_color}` and `{route_text_color}`. At minimum, `{route_id}` must be provided.  These braces should be placed in the input string and conform to the requirements in Python'a [str.format()](https://docs.python.org/3/library/stdtypes.html#str.format) method. 



See [Digital Ocean Route Icons](https://github.com/bcpearce/Digital-Ocean-Route-Icons) for a project using Digital Ocean functions to provide a dynamic icon using the GTFS provider's Route Color and Route Text Color. 



#### Resources



The [resources/NYCT_Bullets](resources/NYCT_Bullets/) folder contains ready-to-use SVG files for customizing arrival icons for the New York City Subway, provided by Wikimedia Commons.



### Other Transit Systems



This software may work for other GTFS realtime providers, but has not been tested. There is no guarantee that providers--even if included in this repository--will work--or that changes in provider APIs will not cause breakages. 



## Frontend



Example frontend card configs can be found in [example/frontend.yaml](example/frontend.yaml).



## Sensors



### Arrival Sensor



The number of sensors can be specified during setup. By default this is 4.  



Sensors will indicate the 1st, 2nd, 3rd, ... etc. arrivals for a given `stop_id` ordered by shortest time.  If no scheduled trips exist for a given arrival ordinal, it will take on the state "Unknown". That is to say, the first sensor will always have the shortest time to arrival, the second sensor will have the second shortest time to arrival, and so on. 



Raw sensor data is provided in seconds. Minutes are the recommended unit.



### Alert Sensor



Alert sensors can be setup for a `route_id`. The [example/frontend.yaml](example/frontend.yaml) file shows how to set up conditional cards that display only if an alert is active. The alert sensor will switch to the "Problem" state if an alert is active for a given station or route. This can be used in automations, such as turning on an indicator LED when an alert becomes active. 



## GTFS Station Stop



This package utilizes [GTFS Station Stop](https://pypi.org/project/gtfs-station-stop/) to provide updates to Home Assistant sensors. 



## Disclaimer



This software is not developed with or affiliated with Home Assistant or with any GTFS API provider. It is not guaranteed to work, use at your own risk.