OpenADSB Track Overrides

Forward

OpenADSB is an iOS air traffic visualizer that connects to a variety of air traffic servers. OpenADSB supports dump1090, tar1090 and Virtual Radar Server (VRS) as well as limited support for ModeSMixer2 and Radarcape. OpenADSB strives to be open in that it supports these various server protocols.

When installed from the App Store, it comes preconfigured to use ADS-B Exchange (ADSBx) as the default data source. OpenADSB is not affiliated with ADS-B Exchange but has an agreement with them to be the default data source. ADS-B Exchange is non-profit and is operated by volunteers. It takes considerable effort and cost to keep ADSBx running. Users, especially heavy users of ADSBx should consider making a donation.

Terminology

Within OpenADSB, the term “track” refers to a tracked object. This is usually an aircraft but in the future could be any tracked object such as a ground vehicle or ship.

Track Override

OpenADSB simply displays what is sent by the track source. If a track property is missing (such as operator, aircraft type), then it is not displayed and shown as an empty value.

For example, ADSBx tar1090 doesn’t contain any operator or owner information. As such the detailed operator property is missing for private, non-airline aircraft. OpenADSB attempts to infer the 3-letter ICAO operator code from the callsign (e.g. BAW123 is BAW). If there’s an operator code, it then looks up the full operator name from a list of known operators (e.g. BAW is British Airways).

OpenADSB has a Track Overrides feature which allows end users to supply their own set of overrides. These overrides supersedes anything sent by the server. This allows users to supply missing data and override any data sent by the server.

The overrides are loaded from a user supplied and hosted JSON file which is loaded by OpenADSB on app startup.

Instructions

There are three steps to overriding aircraft properties.

1. Create the overrides JSON file
2. Host the overrides JSON file
3. Configure OpenADSB to load the overrides JSON file

Create the overrides JSON file

The overrides are contained in a JSON file. The overrides are organized by track and are contained in the top level overrides array. Each array object is an aircraft’s overrides.

The available aircraft properties are:

Example:

{
  "overrides": [
    {
      "a": "ac82ec",
      "r": "N905NA",
      "t": "B741",
      "dt": "Boeing 747-123",
      "c": "A5",
      "o": "ZZZ",
      "do": "National Aeronautics and Space Administration",
      "co": "USA",
      "s": "20107",
      "m": false,
      "i": true
    },
    {
      "a": "AB248A",
      "dt": "DC-8-72",
      "i": true
    }
  ]
}

Each aircraft override must have the ICAO hex code (the a field), all other fields are optional. In the above example, ac82ec will have its registration (r), type (t), detailed type (dt), dump1090 category (c), operator (o), detailed operator (do), country (co), serial number (s), military (m) and interesting (i) overridden. For ab248a, only the detailed type and interesting are overridden.

Host the overrides JSON file

The overrides JSON file must be hosted in a place that is accessible by OpenADSB on startup. This usually means hosting on a publically accessible server such as GitHub, AWS S3, or any hosting service.

Configure OpenADSB to load the overrides JSON file

Within OpenADSB, go to Settings (gear ⚙) - Track Overrides (it’s under Track Fetching). Enter the URL and tap Load. The status indicator will show how many track overrides were loaded or any errors it encountered.

Once configured OpenADSB will load the overrides file on app startup. Tapping on Load will cause it to be reloaded (useful when actively editing the JSON file).

Other Considerations

The entire set of overrides are held in the app’s memory (RAM), it is not saved to the app’s disk storage. This is usually not an issue with modern iOS devices which has plenty of memory.

OpenADSB supports HTTP compression including gzip and br (content-encoding header). Consider enabling compression or gzipping the overrides file if it’s large.

Tapping Load will bypass all HTTP caching and load the overrides file immediately. On app startup OpenADSB will honor HTTP’s caching headers (cache-control).

The overrides JSON file is loaded on app startup without any retries. If it fails to load then go to Settings (gear ⚙) - Track Overrides and tap Load to reload it.

Sample Code

Using some simple scripting, it’s possible to programmatically construct an overrides JSON from various governmental aircraft registries.

FAA

1. Download the FAA’s Aircraft Registration Database and unzip.
2. Run this Python script which creates overrides.json from MASTER.txt

import csv, json

overrides = []

with open('MASTER.txt') as inFile:
    inCSV = csv.reader(inFile, delimiter=',')
    next(inCSV) # skip header
    for row in inCSV:
        owner = row[6].strip()

        # set the dump1090 category for helicopter (A7) and balloon (B2)
        aircraftType = row[18]
        if aircraftType == '6':
            dump1090Category = 'A7'
        elif aircraftType == '2':
            dump1090Category = 'B2'
        else:
            dump1090Category = False
        
        if owner or dump1090Category:
            override = {
                'a': row[33].strip(), # a = ICAO 24-bit hex address
            }

            if owner:
                override['do'] = owner # do = detailed operator

            if dump1090Category:
                override['c'] = dump1090Category # c = dump1090 category

            overrides.append(override)

with open('overrides.json', mode='w') as outFile:
    json.dump({ 'overrides': overrides }, outFile)

The resultant overrides JSON is about 13 megabytes.

Transport Canada

1. Download the Canadian Civil Aircraft Register and unzip.
2. Run this Python script which creates overrides.json from carsownr.txt and carscurr.txt

import csv, json

hexByRegistration = {}

with open('carscurr.txt') as inFile:
    inCSV = csv.reader(inFile, delimiter=',')
    for row in inCSV:
        if len(row) >= 47:
            binaryAddress = row[42]
            hexAddress = hex(int(binaryAddress, 2))[-6:]
            registration = row[0].strip()
            hexByRegistration[registration] = hexAddress

overrides = []

with open('carsownr.txt', 'rb') as inFile:
    # Remove any nulls in carsownr.txt
    inCSV = csv.reader((line.replace('\0','') for line in inFile), delimiter=',')
    for row in inCSV:
        if len(row) >= 20:
            registration = row[0].strip()
            hexAddress = hexByRegistration.get(registration)
            owner = row[1].decode('latin-1').strip()
            if hexAddress and owner:
                override = {
                    'a': hexAddress, # a = ICAO 24-bit hex address
                    'do': owner      # do = detailed operator
                }
                overrides.append(override)

with open('overrides.json', mode='w') as outFile:
    json.dump({ 'overrides': overrides }, outFile)

Copyright © 2020 Steve Kuo, all rights reserved.