⚠️	HASL version 3.0.0 is now recomended. Please upgrade, this integration is deprecated. Please see http://github.com/hasl-sensor/integration for more information.

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

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

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 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 (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 goes 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 all-up 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.

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.

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