Skip to content
This repository was archived by the owner on Feb 26, 2022. It is now read-only.

info.md

Latest commit

 

History

History
117 lines (89 loc) · 10.2 KB

info.md

File metadata and controls

117 lines (89 loc) · 10.2 KB

Home Assistant SL Sensor (HASL) (v2.x)

⚠️ Please update to HASL 3.0.0 (search in HACS). This branch is no longer supported or recomended. Manual update is needed.
Please note that 3.x is in a new repository located at http://github.com/hasl-sensor/integration.
All previous version before 3.x, even for older installs, are not supported. HASL 3.0.0 can be found in default in HACS.

This is a platform for Home Assistant that can be used to create "Departure board" or "Traffic Situation" sensors for buses and trains in Stockholm, Sweden. You have to install it as a custom component and you need to get your own API keys from SL / Trafiklab. This is a fork of fredrikbaberg SL sensor (https://github.com/fredrikbaberg/ha-sensor-sl).

Automatic installation using HACS

First, visit https://www.trafiklab.se/api and create a free account. They provide multiple APIs, the ones you want are "SL Trafikinformation 4" and "SL Störningsinformation 2", optionally you can also register for "SL Trafikläget 2" to get status sensors. When you have your API keys, you're ready to add the component to your Home Assistant.

After you added the integration, add the desired configuration in configuration.yaml. Here is an example of a typical configuration:

sensor:
- platform: hasl
  ri4key: YOUR-RI4-KEY-HERE
  si2key: YOUR-SI2-KEY-HERE
  tl2key: YOUR-OPTIONAL-TI2-KEY-HERE
  sensors:
   - friendly_name: Mölnvik
     sensor_type: departures
     siteid: 4244
     lines: ['474', '480C']
     direction: 1
   - friendly_name: Trafikstatus
     sensor_type: status

Restart Home Assistant to make sure it loads and calls the integration!

Configuration variables

Name Required? Description Default
ri4key optional Your API key from Trafiklab for the Realtidsinformation 4 API (required for departures sensors)
si2key optional Your API key from Trafiklab for the Störningsinformation 2 API
tl2key optional Your API key from Trafiklab for the Trafikläget 2 API (required for status sensors)
version_sensor optional Add a sensor showing component versions false
api_minimization optional Use the api-call-minimization-strategy true
sensors A list of all the sensors to be created. Theese can be of sensor_type departures, status or trainlocation

Configuration variables for departure sensors

This sensor type creates a departure sensor for a specific stop. You can find the ID with some help from another API , "SL Platsuppslag). In the example above, site 4244 is Mölnvik. This sensor can be used with hasl-cards (departure-card, traffic-status-card) and outputs data as described in the sensor description.

Name Required? Description Default
sensor_type yes Mandatory configuration for departures sensor (must be set to departures)
friendly_name optional Used as display name
siteid yes The ID of the bus stop or station you want to monitor.
scan_interval optional Timespan between updates. You can specify 00:01:00 or 60 for update every minute.
sensor optional Specify the name of a binary_sensor to determine if this sensor should be updated. If sensor is ON, or if this option is not set, update will be done.
property optional Which property to report as sensor state. Can be one of: min minutes to departure (default), time next departure time, deviations number of active deviations, refresh if sensor is refreshing or not, updated when sensor data was last updated.
lines optional An array list of line numbers that you are interested in. Most likely, you only want info on the bus that you usually ride. If omitted, all lines at the specified site id will be included. In the example above, lines 474 and 480C will be included.
direction optional Unless your site id happens to be the end of the line, buses and trains go in both directions. You can enter 1 or 2 (0 represents both directions). 0
timewindow optional The number of minutes to look ahead when requesting the departure board from the api. Minimum is 5 and maximum is 60. 60

Configuration variables for status sensors

This sensor type creates a Traffic Situation sensor and shows the overall trafic situation in the public transportation system. This sensor can be used with hasl-cards (departure-card, traffic-status-card) and outputs data as described in the sensor description

Name Required? Description
sensor_type yes mandatory configuration for status sensor and must be set to status
friendly_name optional Used as display name
scan_interval optional Timespan between updates. You can specify 00:01:00 or 60 for update every minute.
sensor optional Specify the name of a binary_sensor to determine if this sensor should be updated. If sensor is 'on', or if this option is not set, update will be done.
traffic_class optional A comma separated list of the types to present in the sensor if not all (metro,train,local,tram,bus,fer)

Display of sensor data

The sensors can be used with multiple cards in hasl-cards (departure-card, traffic-status-card) . There are several cards for different sensors and presentation options for each sensor type.

card

API-call restrictions and optimizations

The Bronze level API is limited to 30 API calls per minute, 10.000 per month. With 10.000 calls per month, that allows for fewer than one calls every 4 minutes but if you are using multiple sensors, this is split between them and each config sensor section can contain a separate pair of api-keys. The calls have been optimized and are locally cached for the specified freshness. If multiple sensors use the same siteid there will still only be one call. Caching is done in a file (haslcache.json) that is automatically created in the configuration directory. You can also specify a binary_sensor that perhaps is false when no-one is at home or similar to reduce the number of calls. Optimizations can be turned off if needed in very specific situations or if you have a high level API-key.

Experimental and upcoming features

So far there is very limited support for other api-functions except those listed above. There is some ongoing experimentation with future functionalities of the platform and this code, however. Nothing that is decided or ready, but the features may be used as-is for now to experiment and see what can be done. Also, if you extend the code please submit a PR to improve this project.

If you have any suggestions, remember to add them to the issue tracker to be included in HASL 3.0, with the enhancement label on your request. Go do it now!.

To use this stuff you should know your way around advanced customization of your Home Assistant enviroment, but for now three parts exist:

Train location sensor

This sensor type creates a train location sensor and shows the train locations for subway, and surface trains. This sensor is EXPERIMENTAL and NOT SUPPORTED yet. Outputs json objects to be parsed by the frontend, but no specific card exists yet. Subject to change.

Name Required? Description
sensor_type yes mandatory configuration for train location sensor and must be set to trainlocation
friendly_name optional Used as display name
train_type yes Which train type should this sensor monitor. Choose one of PT (pendeltåg),RB (roslagsbanan),TVB (tvärbanan),SB (saltsjöbanan),LB (lidingöbanan),SpvC (spårväg city),TB1 (gröna linjen),TB2 (röda linjen),TB3 (blåa linjen)
scan_interval optional Timespan between updates. You can specify 00:01:00 or 60 for update every minute.
sensor optional Specify the name of a binary_sensor to determine if this sensor should be updated. If sensor is 'on', or if this option is not set, update will be done.

Platsuppslag

(Requires PU1-API-Key) The PU1 or Platsuppslag API can be used to get the codes for stops needed for configuration as described above. It may also be used to do advanced type-ahead searches. There is no GUI provided but there is a service exposed under services: hasl.find_location. It requires one argument as a string search_string that contains the place to be looked up. Returns the raw API response for now.

Configuration.yaml

hasl:
  pu1key: YOUR-PU1-KEY-HERE

Reseplaneraren 3.1

(Requires TP3-API-Key) The TP3 or Reseplaneraren3.1 lets you search for routes, prices and current times in the real-time and planned schedule for Stockholm traffic. This can be used to have a dashboard for the current route to your workplace or something similar. There is no GUI provided but there are two services exposed under services: hasl.find_trip_id which accepts a stop id from SL as integers orig and dest which then returns a raw API response. The second service hasl.find_trip_loc instead accepts a logitude and latitude in orig_lat, orig_lon, dest_lat and dest_lon and also returns a raw API response.

Configuration.yaml

hasl:
  tp3key: YOUR-TP3-KEY-HERE