MMM-Futar

This is a module for the MagicMirror² to display Budapest public transport information using real-time data from the "Futár" service provided by the Centre for Budapest Transport (BKK).

Features

By default this module displays the departure times of the configured route in the configured stop:

Or, if you wish, you can display all departures from the configured stop:

If you wish, you can hide the complete head:

You can also configure whether you want the module to hide the symbol in the head, and/or show the symbol at every stop time:

You can even decide to display the symbols and route text with the color matching the route type (enabled by default from version 1.2.0, but can be optionally disabled):

The module by default displays operation alerts for the selected routes (available from version 1.3.0):

If you decide to put the module on the right column, you can set the module to right align its content:

This module is capable to display only a single stop and route data. If you would like to see the departure times of more stops and routes on your mirror, add this module multiple times.

For updates, please check the CHANGELOG.

Using the module

To use this module follow these steps:

1. Clone this repository to the modules folder of your MagicMirror:

git clone https://github.com/balassy/MMM-Futar.git

2. Step into the newly created folder:

cd MMM-Futar

3. Install third-party dependencies:

npm install

4. Add the following configuration block to the modules array in the config/config.js file:

var config = {
  modules: [
    {
      module: 'MMM-Futar',
      position: 'top_left',
      config: {
        apiKey: 'YOUR_API_KEY',
        stopId: 'BKK_F02285',
        routeId: 'BKK_1020',
        minutesAfter: 50,
        hideStopTimesInNextMinutes: 0,
        updateInterval: 60000, // 1 minute in milliseconds
        showHead: true, // true | false
        showSymbolInHead: true, // true | false
        showSymbolInStopTime: false, // true | false
        showRouteNameInStopTime: false, // true | false
        maxNumberOfItems: 3,
        align: 'left', // 'left' | 'right'
        fade: true,
        fadePoint: 0.25,
        coloredSymbolInHead: true, // true | false
        coloredTextInHead: true, // true | false
        coloredSymbolInStopTime: true, // true | false
        coloredRouteNameInStopTime: true, // true | false
        symbolColors: {
          tram: '#ffcf42', // yellow-ish
          bus: '#1a9fed', // blue-ish
          subway: '#b3090c', // red-ish
          trolleybus: '#931517', // dark red-ish
          rail: '#5cbc82', // green-ish
          ferry: '#1a52ed' // dark-blue-ish
        },
        alerts: {
          showHeaderInStopTime: true, // true | false
          showSymbolInStopTime: true, // true | false
          color: '#ffcf42', // 'auto' or any CSS color
          language: 'en' // 'en' or 'hu' supported only by the Futár API
        }
      }
    }
  ]
}

Configuration options

Alert options

The following properties are available for the alerts object of the configuration object:

How it works

This module periodically sends requests from the browser window of the MagicMirror Electron application to the BKK Futár Webservice. Although the service is free and public, its API is not publicly documented, so the module was created by understanding the current communication.

The API require a free API key which you can register here: https://opendata.bkk.hu/

You can see an example by visiting this URL (enter your API key in the URL): https://futar.bkk.hu/api/query/v1/ws/otp/api/where/arrivals-and-departures-for-stop.json?stopId=BKK_F02297&onlyDepartures=true&minutesBefore=0&minutesAfter=40&key=yourApiKey

How to obtain the stopId and routeId

To get the stop and route identifiers required by this module, follow these steps:

stopId

1. Navigate to https://futar.bkk.hu.

2. Zoom until your favorite stop is shown on the map.

3. Hover your mouse over your favorite stop and wait until a pop-up window appears.

4. Note that the pop-up window contains the ID of the stop in the format of #F02285.

5. Configure the stopId configuration value by removing the # sign and prepending BKK_, for example BKK_F02285.

routeId

1. Navigate to https://futar.bkk.hu.

2. Zoom until your favorite stop is shown on the map.

3. Click on your favorite stop icon until a pop-up window appears. On that window, click on the line which you reveal it's routeId (under the stopId, not on the arrivals list, this is important!!!)

4. On the left panel select the direction which needed.

5. Hover your mouse over your stop.

6. Right click, copy the link address and it should reveal the stopId and the routeId as well.

Localization

Currently this module supports English (en) and Hungarian (hu) languages. The language can be specified in the global language setting in the config.js file.

Want to see more languages? Please contribute!

Contribution

Although for operation this module does not depend on any other module, if you would like to contribute to the codebase, please use the preconfigured linters to analyze the source code before sending a pull request. To run the linters follow these steps:

1. Install developer dependencies:

npm ci

2. Run all linters:

npm run lint

Got feedback?

Your feedback is more than welcome, please send your suggestions, feature requests or bug reports as Github issues.

About the author

This project is created and maintaned by György Balássy.