Repository files navigation

Display what is currently flying above your location

MMM-FlightsAbove is aMagicMirror module for displaying what iscurrently flying around in the airspace above some location. Thelocation is defined by thelatitude andlongitude of your location, and a radius inkilometers, which determine the maximum distance to which youwant to detect aircraft.

However, because maps you see and use are flat and squared, internally the application is using aboundary box (BB) to determine the area of interest. The BB sides are just the latitutes and longitudes of the map.So to easily calculate the BB values given a geographical location, we have included a tool that does the calculation for you.Use this to copy/paste your BB into your configuration file.

The flight data is provided byFlightRadar24, but could be easily extendedto use other sources as well.

The specific flight data items available from the API that you can display are:

Module Screenshot:

(From theMMM-Tabulator Demo.)

Here is a screenshot when using the config option:homeIata: "VNO" andcompassHeading: true tohighlight flights with the origin or destination airport given by the IATA code "VNO", and show thecompass heading in text form and not in degrees.

Using the config optionfooterLegend: true will enable a footer with the color legend.

TheMagicRadarBB.htmlBoundary Box Calculator Screenshot:

This module depend on the followingnpm packages:

• jquery - is a fast, small, and feature-rich JavaScript library
• jquery-ui - for user interface interactions, effects, widgets, and themes
• tabulator - for an overkill use of JSON to HTML table generation
• flightradar24-client - the API used to get FR24 flight data

These are also listed in thepackage.json file and should be installed automatically when usingnpm.However, those may require other packages.

This module is compatible with otherremote control modules such as:

• Hello-Lucy (This is a plug-in to MMM-voice.)
• MMM-voice

Those allow you to control this module by Voice commands.For example, in Hello-Lucy you can say: "SHOW FLIGHTS" or "HIDE FLIGHTS" to show or hide this module.

Manual Installation:

cd~/MagicMirror/modulesgit clone https://github.com/E3V3A/MMM-FlightsAbove.gitcd MMM-Tabulator

To install the depdendencies:jquery,jquery-ui andtabulator, do:

npm install jquery --savenpm install jquery-ui-dist --savenpm install jquery.tabulator --save

To install theflightradar24-client (API), use:

npm install flightradar24-client

Alternatively, on a *unix based distribution, you can try to install all the dependencies with the Bash script:

chmod 755 install_deps.sh./install_deps.sh

npm install mmm-flightsabove

To configure the FlightsAbove, you need to do the following:

1. Add the Module to the global MMconfig.js
2. Edit the global config to add the 4 lat/lon values for the Boundary Box of your location
3. [optional] EditMMM-FlightsAbove.js Tabulator settings to:
   • select & configure the table rows you want to show
   • edit the column formatting to be used
   • select the default Tabulator CSS
4. [optional] EditMMM-FlightsAbove.css for your own CSS taste

Add the module to the modules array in theconfig/config.js file by adding the following section.

{module:'MMM-FlightsAbove',header:'Flights Above',position:'top_left',config:{header:"Flights Above",// The module header text, if any. Use: "" to remove.compassHeading:true,// Use a compass direction (NSWE) for the of heading indicator ("45" vs "NE")updateInterval:180,// [s] Radar scan/ping/update period in secodns [default 3 min]maxItems:10,// MAX Number of planes to display [default is 10]// The geographical (map) Boundary-Box (BB), from within planes will be shown are given by:// the maximim Lat/Lon edges of: [N-lat, W-lon, S-lat, E-lon] - all in decimal degrees.radarBBox:[-8.20917,114.62177,-9.28715,115.71243],// "DPS" (Bali Airport) [default]//radarLocation: "23.2,54.2",     // [Lat,Lon] - The location of radar center in decimal degrees//radarRadius: 60,                // [km] - The maximum distance of planes shown.//watchList: "",                  // Alert or Highlight planes/flights/types on this watch list}},...

You can change this configuration later when you see that it works.

Unfortunately, the API is operating with a geographical boundary-box (BB), rather than a sphercial radius froma given location. So you need to convert your locations Lat/Lon (in decimal degrees) to the 4 coordinatesrepresenting the sides of the BB. These are given by:MaxLat, MinLon, MinLat, MaxLon, or in other words,thenorth, west, south, east edges.

However, I have provided a simple GoogleMap based tool that make this calculation trivial.Look at the picture above, to see what to expect. To use the tool the first time, do the following:

1. Have yourGoogle Maps API Key handy. You can get oneHERE.
2. Edit the file:./tools/MagicRadarBB.html and replacing the text "YOUR_GOOGLE_MAPS_API_KEY" with your key.
3. Simply point your browser to one of the following URLs:
   • from a local browser, open the file:./tools/MagicRadarBB.html in the module directory.
   • from a local or remote browser, go to:http://192.168.xx.yy:8080/modules/MMM-FlightsAbove/tools/MagicRadarBB.html
4. Enter theLatitude andLongitude in decimal degrees, for your location.
5. Enter theradius in kilometer, out to which you want to see flights.
6. [optional] You can also drag the central marker to any point on the map. (Use+/- to zoom in/out.)
7. HitCalculate and copy the resulting coordinate text from theFR24 BB textbox into your MM config file.
8. If you get a blank map, your API key is probaly expired, invalid or over-used.

Eventually, we would like to calculate this automatically in thenode_helper.js script. (See issues)

Q: What radius should I use?

A: Since there is little use in displaying planes you cannot see, what you really should beasking is, how far can I see an airplane? The answer obviously depend on where you are, and especiallyhow high you are. If you are down in a valley surrounded by mountains, you can use your trigonometryskills to figure that its probably not much more than 30 km,line of sight (LOS). But if you are ontop of a mountain with free horizon, we could be talking about 120 km, at which point the aircraft wouldjust present itself as a tiny spot in the sky. This module is preset at a moderate 60 km LOS.

For an interesting London discussion, seethis.

* -not yet implemented - ToDo!

The default table columns shown, are:[flight,callsig,to,from,alt,speed,bearing,alt,model,squawk]But there are also:[id,registration,model,modes,radar] available.

-▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃

⚠️ Please do not use anupdateInterval shorter than ~2 minutes (120 seconds). A too shortsetting is useless as planes do not move across the visible sky that fast, and no, you will not beable to see F16's or MIG's, as they are not tracked by F24. So please respect the free servicesprovided by the Flightradar24 API. You also risk getting blocked by their servers if you rapid-firerequests. Finally, the services provided by them could break at any time, there are no service guarantees.⚠️

-▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃

The main part to configure is found under theloadTabulator() function:

...flightTable.tabulator({height:flightTableHeight,// [px] Set MAX height of table, this enables the Virtual DOM and improves render speedlayout:"fitDataFill",// Resize columns to fit thier data and ensure rows takeup the full table width//layout:"fitColumns",              // Resize columns so that they fit perfectly inside the width of the containerlayoutColumnsOnNewData:true,// Adjust the column width to the data each time you load it into the table//headerSort:false,                 // Disable header sorterresizableColumns:false,// Disable manual column resizeresponsiveLayout:true,// Enable responsive layoutsplaceholder:"Waiting for data...",// Display message to user on empty tableinitialSort:[// Define the sort order:{column:"altitude",dir:"asc"},// 1'st//{column:"flight",     dir:"desc"},    // 2'nd//{column:"bearing",    dir:"asc"},     // 3'rd],columns:[            ...{title:"Time",field:"timestamp",headerSort:false,sortable:false,visible:false,responsive:1,formatter:"ep2time"},...

For further details about configuring the many Tabulator options, seeMMM-Tabulator and references therein.

ℹ️ The data provided by theflightradar24-client, is not JSON, even if it resembles it. It isactually anArray of JavaScript objects. For an example of the raw data, look at thedemo.json file.

For other bugs, issues, details and updates, please refer to theissue tracker.

Feel free to post issues and PR's related to this module.
For all other or general questions, please refer to theMagicMirror Forum.

Most grateful thanks to:

• raywo - for clarifying and fixing the API response mechanism
• tbbear - for helping and clarifying JS Promises
• fewieden - for helping out in forums and fixing issues

(MIT)