ViaggiaTreno sensor documentation (home-assistant#3924)

fabfurnari · balloob · commit c38c00b00df1 · 2017-11-18T10:17:40.000-08:00
* ViaggiaTreno sensor documentation

* ✏️ Spelling, grammar, styling, and configuration fixes
diff --git a/source/_components/sensor.viaggiatreno.markdown b/source/_components/sensor.viaggiatreno.markdown
@@ -0,0 +1,62 @@
+---
+layout: page
+title: "ViaggiaTreno Italian Railroads"
+description: "Instructions on how to integrate Italian Railroads data (from ViaggiaTreno API) into Home Assistant."
+date: 2017-11-07 14:35
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: train.png
+ha_category: Transport
+ha_iot_class: "Cloud Polling"
+ha_release: 0.58
+---
+
+The `viaggiatreno` sensor will give you information about configured train ids and stations using the public [ViaggiaTreno](http://viaggiatreno.it) API.
+
+To activate the sensor you need at least two parameters: the `train_id` and the `station_id`. 
+
+The first is available just looking at the [ViaggiaTreno](http://viaggiatreno.it/) timetable, the latter can be obtained using the dedicated API endpoint:
+`http://www.viaggiatreno.it/viaggiatrenonew/resteasy/viaggiatreno/autocompletaStazione/<Station name>` 
+(e.g., `http://www.viaggiatreno.it/viaggiatrenonew/resteasy/viaggiatreno/autocompletaStazione/ROMA` will list all station names (with ids) that starts with *ROMA*).
+
+<p class='note'>
+Note that the `station_id` is referred to the train's **departing station**. If a train number does not match with the station id, no data will be returned to the sensor.
+</p>
+
+Then add the data to your `configuration.yaml` file as shown in the example:
+
+```yaml
+# Example configuration.yaml entry
+sensor:
+  - platform: viaggiatreno
+    train_id: 12279
+    station_id: S08409
+```
+
+{% configuration %}
+train_id:
+  description: The ID of the train.
+  required: true
+  type: int
+station_id:
+  description: The ID of the starting station.
+  required: true
+  type: int
+train_name:
+  description: The name of the sensor. Defaults to 'Train <train id> from <station id>'.
+  required: false
+  type: string
+{% endconfiguration %}
+
+<p class='note'>
+In a future implementation, the station name could be used to automatically search best-matching station id, without the need to specify it.
+</p>
+
+The public timetables are coming from [ViaggiaTreno](http://viaggiatreno.it).
+
+<p class='note'>
+Instructions (in Italian) for the API are available at:
+https://github.com/bluviolin/TrainMonitor/wiki/API-del-sistema-Viaggiatreno
+</p>
