The Deutsche Bahn Binding provides the latest timetable information for all trains that arrive or depart at a specific train station, including live information for delays and changes in timetable.
The information are requested from the timetable api of Deutsche Bahn developer portal, so you'll need a (free) developer account to use this binding.
## Supported Things
- **timetable** The timetable bridge connects to the timetable api and provides information for the next trains that will arrive or depart at the configured station.
1. Register new account or login with an existing one
1. If no application is configured yet (check Tab "Anwendungen" at top) create a new application. Only the name is required, for example openHAB, any other fields can be left blank.
1. Remember the shown **Client ID** and **Client Secret**.
1. Go to **Katalog** and search for **Timetables** api.
1. Within **Zugehörige APIs** select the Timetables api.
1. Select **Abonnieren** at top left of the page.
1. Select the Nutzungsplan **Free** by clicking **Abonnieren**.
1. Select the previously created application.
1. Click **Next**.
1. Click **Fertig**.
1. Now you have successfully registered the api within an application. The **Client ID** and **Client Secret** can now be used during bridge configuration.
For the selection of the station within openHAB you need the eva no. of the station, i.e. a 7-digit number starting with 80 for Germany.
The station ID is no longer available on the Open Data portal of Deutsche Bahn.
You can look up the number at [www.michaeldittrich.de](https://www.michaeldittrich.de/ibnr/) or [in the CSV file](https://github.com/ratopi/haltestellendaten).
| `evaNo` | | Yes | The eva nr. of the train station for which the timetable will be requested.|
| `trainFilter` | | Yes | Selects the trains that will be displayed in the timetable. Either only arrivals, only departures or all trains can be displayed. |
- specify a filter for the value of a given channel. Therefore, you must specify the channel name (with channel group) and specify a compare value like this:
`departure#line="RE60"` this will select all trains with line RE60
- use regular expressions for expected channel values, for example: `departure#line="RE.*"`, this will match all lines starting with "RE".
- combine multiple statements as "and" conjunction by using `&`. If used, both parts must match, for example: `departure#line="RE60" & trip#category="WFB"`
- combine multiple statements as "or" disjunction by using `|`. If used, one of the parts must match, for example: `departure#line="RE60" | departure#line="RE60"`
- use brackets to build more complex queries like `trip#category="RE" AND (departure#line="17" OR departure#line="57")`
Once you've created the timetable you can add train-things that represent the trains within this timetable.
Each train represents one position within the timetable. For example: If you configure a train with position 1 this will be
the next train that arrives / departs at the given station. Position 2 will be the second one, and so on. If you want to
show the next 4 trains for a station, create 4 things with positions 1 to 4.
**Attention:** The timetable api only provides data for the next 18 hours. If the timetable contains less train entries than you've created
train things, the channels of these trains will be undefined.
**train** parameters:
| Property | Default | Required | Description |
|-|-|-|-|
| `position` | | Yes | The position of the train within the timetable. |
## Channels
Each train has a set of channels, that provides access to any information served by the timetable API. A detailed description of the values and their meaning can be found within
(due it starts or ends at the given station). If you have configured your timetable to contain only departures (with property trainFilter) the departure channel values will always be defined
and if you have selected only arrivals the arrival channel values will always be defined.
Channels will have a 'NULL' channel value, when the corresponding attribute is not set.
Basically most information are available as planned and changed value. This allows to easy display changed values (for example the delay or changed platform).
| category | String | Provides the category of the trip, e.g. "ICE" or "RE". |
| number | String | Provides the trip/train number, e.g. "4523". |
| filter-flags | String | Provides the filter flags. |
| trip-type | String | Provides the type of the trip. |
| owner | String | Provides the owner of the train. A unique short-form and only intended to map a trip to specific evu (EisenbahnVerkehrsUnternehmen). |
| planned-path | String | Provides the planned path of a train. |
| changed-path | String | Provides the changed path of a train. |
| planned-platform | String | Provides the planned platform of a train. |
| changed-platform | String | Provides the changed platform of a train. |
| planned-time | DateTime | Provides the planned time of a train. |
| changed-time | DateTime | Provides the changed time of a train. |
| planned-status | String | Provides the planned status (planned, added, cancelled) of a train. |
| changed-status | String | Provides the changed status (planned, added, cancelled) of a train. |
| cancellation-time | DateTime | Time when the cancellation of this stop was created. |
| line | String | The line of the train. |
| messages | String | Messages for this train. Contains all translated codes from the messages of the selected train stop. Multiple messages will be separated with a single dash. |
| hidden | Switch | On if the event should not be shown because travellers are not supposed to enter or exit the train at this stop. |
| wings | String | A sequence of trip id separated by pipe symbols. |
| transition | String | Trip id of the next or previous train of a shared train. At the start stop this references the previous trip, at the last stop it references the next trip. |
| planned-distant-endpoint | String | Planned distant endpoint of a train. |
| changed-distant-endpoint | String | Changed distant endpoint of a train. |
| distant-change | Number | Distant change |
| planned-final-station | String | Planned final station of the train. For arrivals the starting station is returned, for departures the target station is returned. |
| planned-intermediate-stations | String | Returns the planned stations this train came from (for arrivals) or the stations this train will go to (for departures). Stations will be separated by single dash. |
| changed-final-station | String | Changed final station of the train. For arrivals the starting station is returned, for departures the target station is returned. |
| changed-intermediate-stations | String | Returns the changed stations this train came from (for arrivals) or the stations this train will go to (for departures). Stations will be separated by single dash. |
