Skip to content
HomeAssistant SL Sensor (HASL)
Python
Branch: hasl
Clone or download
Pull request Compare This branch is 186 commits ahead, 2 commits behind fredrikbaberg:master.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
custom_components/hasl
CHANGELOG.md
DEPARTURES_OBJECT.md
LICENSE Initial commit May 7, 2017
README.md Update readme for new and upcomming features Jul 20, 2019
STATUS_OBJECT.md Updated status object May 16, 2019
custom_updater.json Fix of stupid typo Jul 15, 2019

README.md

hacs_badge ha_version stability-stable version maintained maintainer

Home Assistant SL Sensor (HASL)

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).

NOTE: If you are using pre 0.92 version of Home Assistant you will need to use release 1.0.3 or older from here and follow the instructions in the release files there instead (and there is some known issues with that release). The below information is for 0.92 or later versions of Home Assistant only.

Automatic installation using HACS

First, visit https://www.trafiklab.se/api and create a free account. They provide multiple APIs, the ones you want is "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.

This is a custom component so not installed by default in your Home Assistant install. However it can be easily installed and updated using HACS where this integration is included by default under the integration headline. By using HACS you will also make sure that any new versions are installed by default and as simple as the install itself.

After you added the integration then add the desired configuration in config. 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!

Manual installation (not advised)

The integration can be installed manually by copying some files from this repo to your install. Also you will need to create API key and config as outlined in the previous section. Note that HASL will not automatically update as newer versions are released so you need to keep track of that yourself. We recomend using HACS as outlined above in the previous section.

Please copy files:

hasl/__init__.py to <config>/custom_components/hasl/__init__.py
hasl/sensor.py to <config>/custom_components/hasl/sensor.py
hasl/manifest.json to <config>/custom_components/hasl/manifest.json

where <config> is your Home Assistant configuration directory.

Configuration variables

  • 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 (default False)

  • api_minimization (Optional): Use the api-call-minimization-strategy (default 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 departuresined 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. and outputs data as described in the sensor description.

  • sensor_type: departures: Mandatory configuration for departures sensor (must be set to departures)

  • friendly_name: Used as display name

  • siteid: 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 goes in both directions. You can enter 1 or 2 (default is 0 which represents both directions).

  • timewindow (Optional): The number of minutes to look ahead when requesting the departure board from the api. Default 60, minimum is 5 and maximum is 60.

Configuration variables for status sensors

This sensor type creates a Traffic Situation sensor and shows the all-up trafic situation in the public transportation system. This sensor can be used with hasl-cards. and outputs data as described in the sensor description

  • sensor_type: status: mandatory configuration for status sensor and must be set to status

  • friendly_name: 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. 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 less than one call every 4 minute 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 beeing locally cached for the specified freshness, if multiple sensors are using the same siteid there will still only be one call. Caching is done in a file (haslcache.json) that will be automatically created in the configuration directory. You can also specify a binary_sensor that perhaps is turned of when no-one is at home or similar to reduce the number of calls. Optimizations can be turned of if needed in very specific situation or if you have a high level API-key.

Experimental and upcomming features

So far there is very limited support for other api-functions except what is listed above. However there are some experimentation going on with future functionalities of the platform and this code. 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 so it can be furthered.

If you have any suggestions do not forget to add them to the issue tracker to be included in HASL 3.0, please use the enhancement label to add 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 exists:

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 object to be parsed by frontend, but no specific card exists yet. Subject to change.

  • sensor_type: trainlocation: mandatory configuration for train location sensor and must be set to trainlocation

  • friendly_name: Used as display name

  • train_type: 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 typeahead searches. There is no GUI provided but there is a services 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 the stockholm traffic. This could be used to have a dashboard for the current route to work or something similar. There is no GUI provided but there is two services exposed under services: hasl.find_trip_id which accepts a stop id from SL as integers orig and dest and then returns the 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 raw response.

Configuration.yaml

hasl:
  tp3key: YOUR-TP3-KEY-HERE
You can’t perform that action at this time.