Skip to content

Commit 0893bd3

Browse files
robmarkcolefabaff
robmarkcole
authored and
fabaff
committed
Adds uk_transport component documentation (home-assistant#3037)
* Adds uk_transport documentation * Update ha_release
1 parent 327f323 commit 0893bd3

File tree

1 file changed

+122
-0
lines changed

1 file changed

+122
-0
lines changed

‎source/_components/sensor.uk_transport.markdown

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
layout: page
3+
title: "UK transport"
4+
description: "Display the current status of UK train and bus departures."
5+
date: 2017-07-07 18:00
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
logo: train.png
11+
ha_category: Transport
12+
ha_iot_class: "Cloud Polling"
13+
ha_release: "0.50"
14+
---
15+
16+
17+
The `uk_transport` sensor will display the time in minutes until the next departure in a specified direction from of a configured train station or bus stop. The sensor uses [transportAPI](http://www.transportapi.com/) to query live departure data and requires a developer application ID and key which can be obtained [here](https://developer.transportapi.com/). The [free tier](http://www.transportapi.com/plans/) allows 1000 requests daily, which is sufficient for a single sensor refreshing every 87 seconds.
18+
19+
<p class='note warning'>
20+
Additional sensors can be added but at the expense of a reduced refresh rate. 2 sensors can be updated every 2*87 = 174 seconds, and so on.
21+
</p>
22+
23+
Queries are entered as a list, with the two transport modes available being `bus` and `train`.
24+
25+
Train departure sensors require three character long `origin` and `destination` station codes which are searchable on the [National Rail enquiries](http://www.nationalrail.co.uk/times_fares/ldb.aspx) website (e.g. `WAT` is London Waterloo). The validity of a route can be checked by performing a GET request to `/uk/train/station/{station_code}/live.json` in the [API reference webpage](https://developer.transportapi.com/docs?raml=https://transportapi.com/v3/raml/transportapi.raml##request_uk_train_station_station_code_live_json).
26+
27+
To add a single train departure sensor add the following to your `configuration.yaml` file:
28+
29+
30+
```yaml
31+
# Example configuration.yaml entry for a single sensor
32+
sensor:
33+
- platform: uk_transport
34+
app_id: abc123
35+
app_key: efg456
36+
queries:
37+
- mode: train
38+
origin: MAL
39+
destination: WAT
40+
```
41+
42+
Configuration variables:
43+
44+
- **app_id** (*Required*): Your application id
45+
- **app_key** (*Required*): Your application key
46+
- **queries** array (*Required*): At least one entry required.
47+
- **mode** (*Required*): One of `bus` or `train`.
48+
- **origin** (*Required*): Specify the three character long origin station code.
49+
- **destination** (*Required*): Specify the three character long destination station code.
50+
51+
A large amount of information about upcoming departures is available within the attributes of the sensor. The example above creates a sensor with ID `sensor.next_train_to_wat` with the attribute `next_trains` which is a list of the next 25 departing trains. The status of the next departing train is accessed using the [template sensor](https://home-assistant.io/components/sensor.template/) below, as are the train origin, estimated and scheduled departure times, and the departure platform.
52+
53+
```yaml
54+
# Example configuration.yaml entry for a template sensor to access the attributes of the next departing train.
55+
- platform: template
56+
sensors:
57+
next_train_status:
58+
friendly_name: 'Next train status'
59+
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].status}}'
60+
next_trains_origin:
61+
friendly_name: 'Next train origin'
62+
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].origin_name}}'
63+
next_trains_estimated:
64+
friendly_name: 'Next train estimated'
65+
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].estimated}}'
66+
next_trains_scheduled:
67+
friendly_name: 'Next train scheduled'
68+
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].scheduled}}'
69+
next_trains_platform:
70+
friendly_name: 'Next train platform'
71+
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].platform}}'
72+
73+
```
74+
75+
Bus sensors require as their `origin` a bus stop ATCO code which can be found by browsing OpenStreetMap data as
76+
follows:
77+
78+
1. On [OpenStreetMap.org](http://www.openstreetmap.org/) zoom right in on a bus
79+
stop you're interested in
80+
2. Click the layers picker button on the right hand side
81+
3. Tick the 'map data' layer, and wait for clickable objects to load
82+
4. Click the bus stop node to reveal its tags on the left
83+
84+
The `destination` must be a valid location returned by the transportAPI query. Valid destinations can be checked by performing a GET query to `/uk/bus/stop/{atcocode}/live.json` in the [API reference webpage](https://developer.transportapi.com/docs?raml=https://transportapi.com/v3/raml/transportapi.raml##bus_information). A bus sensor is added in the following `configuration.yaml` file entry:
85+
86+
```yaml
87+
# Example configuration.yaml entry for multiple sensors
88+
sensor:
89+
- platform: uk_transport
90+
app_id: abc123
91+
app_key: efg456
92+
queries:
93+
- mode: bus
94+
origin: 340000368SHE
95+
destination: Wantage
96+
- mode: train
97+
origin: MAL
98+
destination: WAT
99+
```
100+
101+
And the template sensor for viewing the next bus attributes.
102+
103+
```yaml
104+
# Example configuration.yaml entry for a template sensor to access the attributes of the next departing bus.
105+
- platform: template
106+
sensors:
107+
next_bus_route:
108+
friendly_name: 'Next bus route'
109+
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].route}}'
110+
next_bus_direction:
111+
friendly_name: 'Next bus direction'
112+
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].direction}}'
113+
next_bus_scheduled:
114+
friendly_name: 'Next bus scheduled'
115+
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].scheduled}}'
116+
next_bus_estimated:
117+
friendly_name: 'Next bus estimated'
118+
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].estimated}}'
119+
120+
```
121+
122+
Powered by [transportAPI](http://www.transportapi.com/)

0 commit comments

Comments
 (0)