Building and Running Live Data Demo

NOTE 12/2023 Building and running demos is going to become significantly more simple in the upcoming Rust version of ODIN (see Why is ODIN ported to Rust)

The live-data demo from config/odin-live.conf shows the following input sources

(optional) aircraft (ADS-B) tracking

fire detection from GOES-R (geostationary) satellites

fire tracking with JPSS (polar orbiting) satellites

To run the demo please follow these steps:

Check Prerequisites for Building and Running RACE-ODIN

Create Common Root Directory for RACE/ODIN components

Obtain and Build RACE

Obtain and Build RACE-ODIN

Obtain and Configure Live Data Prerequisites

Start ODIN Live Data Demo

Obtain and Configure Live Data Prerequisites

The live data demo currently requires access configuration for the following external servers and executables:

(optional) ADS-B host

https://space-track.org - to obtain orbit parameters for JPSS satellites

https://firms.modaps.eosdis.nasa.gov - to obtain active fire data products from JPSS satellites

In addition the Orekit library needs ephemeris data to compute orbits of JPSS satellites.

If you have access to the required hardware (see PiAware) you can also build and run your own dump1090 edge server. Please refer to respective documentation of how to build on your platform (this requires make and a working C compiler for your platform).

The current ODIN demos make use of a specialized version of the WindNinja micro-grid wind simulator and associated data post-processors. Please see How to build WindNinja.

Configuring ADS-B (flight tracking) host

The demo optionally reads flight tracking information from a host that runs the open source dump1090 demodulator/decoder, which currently builds on Linux and macOS. This decoder requires an antenna and an SDR (software defined radio) dongle.

While there are several options of how to build such a system details are outside the scope of this documentation. Please refer to these instructions for details.

If you don't have access or don't want to track aircraft you can skip this configuration step. Please note that in this case you have to use the config/odin-livesat-demo.conf configuration to run the live ODIN demo.

Once you have access to such a system, configuring RACE-ODIN is just a matter of adding hostname and port to the 'Private Configuration' vault file :

secret {
  ...
  adsb {
    host="<your-adsb-host-url>"
    port = 30003
  }
  ...
}

Since this data source requires more effort the demo considers it optional. If there is no valid adsb.host ODIN will product the following warnings on startup but will otherwise run showing the satellite data.

[ERR]  trackImporter: failed to initialize: java.net.ConnectException: Connection refused
...
[WARN] odin-live: initialization of trackImporter failed: rejected

Obtaining a space-track.org Account

This website provides access to orbital parameters in form of two line elements. Accounts are free and can be obtained from this page.

Once you have the account information add the following to your Private Configuration

secret {
  ...
   spacetrack {
    authentication="identity=<your-email>&password=<your-password>"
  }
  ...
}

Obtaining a Map Key from FIRMS

In order to retrieve active fire data from polar orbiting satellites you have to obtain a map key from this page (scroll to the bottom of the page and click the "Get MAP_KEY" button). Keys are free. Once you have otained the key add the following to your Private Configuration

secret {
  ...
  firms {
    map-key="<your-map-key>"
  }
  ...
}

Download Orekit Ephemeris Data

race-odin uses the Orekit library to compute orbits for the JPSS satellites. This library requires ephemeris that needs to be downloaded and updated. Follow these steps to get the data:

switch to the race-odin parent directory

clone the orekit-data repository by executing git clone https://gitlab.orekit.org/orekit/orekit-data.git

Please note this directory needs to be updated periodically. You can either use the update.sh script that is part of the repository or execute git pull from within it.

If you keep the name (orekit-data) and location (parent directory of race-odin) no further configuration is required.

Start ODIN Live Data Demo

There are two versions of the live data demo: with and without live local air traffic monitoring. Which one to run should depend on whether you have access to an ads-b host or not.

If you have aceess to (and have configured) an ads-b host, please execute the following from within the race-odin directory:

./odin --vault ../<my-vault> config/odin-live-demo.conf

You can still run this if you don't have access to live ads-b data but the system startup will be slower and you will get warnings about import actor timeout. In this case it is therefore recommended to run with just the publicly available satellite data by executing

./odin --vault ../<my-vault> config/odin-livesat-demo.conf

Once the server is running, switch to a browser (Chromium based browsers have the best support for WebGL as of this writing) and go to http://localhost:9000/odin.

For more details see Running RACE-ODIN Applications.