Skip to content

Radar View#

mwp supports the display of "radar" contacts. This provides a view of adjacent aircraft obtained from a number of sources:

  • Tracked Telemetry. Secondary models tracked by telemetry (CRSF, LTM, MAVLink, Smartport, MPM(Flysky, Smaprtport)). Provided by RX Telemetry Mirroring or dedicated telemetry radios.

  • INAV-radar. INAV radar works in conjunction with INAV flight controllers to broadcast the location of UAS fitted with an ESP32 LoRa module. mwp can listen to one of these modems in ground station mode to display the positions of the rest of the 'swarm' (up to 4 UAS); technical / MSP details.

  • General Aviation from internet provider using a REST service delivering the dump1090/readsb JSON schema. This schema is used by a number of both free and subscription web services.

  • General Aviation typically reported using SDR (Software Defined Radios) using SBS streaming TCP protocol. This is generated by the open source dump1090 and readsb open source applications with a SDR receiver, as well as commercial products.
  • General Aviation typically reported using SDR (Software Defined Radios) using the dump1090-fa JSON format.
  • General Aviation typically reported using SDR (Software Defined Radios) using the readsb "protobuf" format. This is the preferred way to access SDR ADSB / Mode-S data.
  • General Aviation reported by the MAVLink 'Traffic Report' / 'ADSB Vehicle' message. Examples of available hardware include:
    • uAvionix PingRX, a compact device that receives ADS-B location data from full sized aircraft and publishes the locations as MAVLink. For a ground based installation, this device has around a 40Km detection radius. MAVLink ICD.
    • Aerobits TT-SC1. Untested, but supports the same MAVLink API as the PingRX. Product documentation.

  • General Aviation reported using the MSP2_ADSB_VEHICLE_LIST message. This is generated by INAV later than 7.1.0 when a PingRX or TT-SC1 device is attached to the flight controller. This is received by the main mwp MSP port without user configuration (no need to set up a radar-device). Due to the size of MSP2_ADSB_VEHICLE_LIST message, mwp does not poll for MSP2_ADSB_VEHICLE_LIST by default, see the setting key msp2-adsb, below.

  • Proximity alerts (visual and audible) for General Aviation (ADS-B / sbs-1 / dump1090 / readsb / Internet REST) aircraft, based on planned or actual home location or vehicle location.

For SDR (Software Defined Radios) using the readsb or dump1090 where the SDR host has a web server configured to supply the generated "protobuf" or JSON output, then mwp can obtain the data from the web server. Otherwise, it will be necessary to set up a small daemon on SDR host, see the src/samples/adsb-extra directory for further details.

Note that the SDR protocols may also be used with network services that provide ADS-B reports (usually for a fee or for provided local data).

mwp Configuration#

mwp can receive the 'radar' data over one or more connections, anyof which may be active, and mwp can receive and display 'own vehicle' telemetry (MSP, LTM, CRSF, Smartpost), Tracked Telemetry, 'INAV-radar', 'MAVlink Traffic' and General Aviation data simultaneously. Radar data may be received over:

  • The main serial port device (see caveat for INAV-radar) and MSP2_ADSB_VEHICLE_LIST.
  • device(s) defined by the radar-device CLI or configuration parameter (MAVLink Traffic, INAV-radar, SDR protocols)

The radar-device option is defined by the standard mwp naming scheme:

  • A serial device node, with optional baud rate, e.g.:
    • /dev/ttyACM0, /dev/ttyUSB4@567600, /dev/rfcomm3
    • Serial defaults to 115200 baud, but may be set in the device name (@baudrate)
  • A Bluetooth address (for BT bridges)
    • 00:0B:0D:87:13:A2
  • A UDP address, e.g. for simulation, recording replays or serial multiplexer (INAV, mavlink).
    • udp://:30001 local UDP listener.
  • An online REST service providing the readsb JSON format. For now, mwp supports services that offer and end point of the form https://host/v2/point/lat/lon/. These are defined using the adsbx:// pseudo URI, and require the host, range in nautical miles (NM) and the refresh interval (milliseconds). Some suppliers limit the maximum range to 250NM and minimum update rate of 1 second.
    • adsbx://api.adsb.one?range=40&interval=1000 Please see below for the mwp implementation details.
  • A readsb protobuf source or dump1090 JSON source over http/https, for example, using hosts woozle (protobuf) and jagular (JSON):
    • http://woozle/readsb/data/aircraft.pb
    • http://jagular/dump1090/data/aircraft.json
  • A readsb protobuf source, defined by a special URI:
    • pba://[[host][:port]] (requires adsbpbsrv on the SDR host). Host and port are optional, defaulting to localhost and 38008. So the minimal "URI" is pba://.
  • A dump1090 JSON source, defined by a special URI:
    • jsa://[[host][:port]] (requires jsacsrv on the SDR host). Host and port are optional, defaulting to localhost and 37007. So the minimal "URI" is jsa://.
  • A SBS protocol source, defined by a special URI:
    • sbs://[[host][:port]] Host and port are optional, defaulting to localhost and 30003. So the minimal "URI" is sbs://.

For "Telemetry Tracking", please see its separate article.

The specific (not shared with the main serial port) radar device(s) may be defined on the command line, or in the static command options file (~/.config/mwp/cmdopts):

  • mwp --radar-device udp://:30001
  • $ cat ~/.config/mwp/cmdopts
    # Default options for mwp
# using udev rule to associate a specifc USB-TTL adaptor to a name
--radar-device=/dev/pingRX@57600

Multiple devices may be defined, e.g.

  • As separate options, --radar-device=/dev/pingRX@57600 --radar-device /dev/inavradar@115200
  • As a comma separated list: --radar-device=/dev/pingRX@57600,/dev/inavradar@115200

Any bespoke radar-device is started automatically on startup (or when it shows up). It is not managed via the serial Connect button.

ADSBX REST Providers#

For many users using a (free) online REST service will be a simple option compared to using their own hardware devices.

Supported providers#

The intention is to support any provider that offers the readsb JSON response (sometimes called the ADSBExchange V2 API response). The query to get such a response may differ between providers, so for now the following providers are supported:

  • adsb.lol
  • adsb.one

These sources have the benefits of:

  • Using the same REST API endpoint (https://host/v2/point/lat/lon/range)
  • Are free to use
  • Do not require registration
  • Have few usage limits

Configuration#

Using (one of) the above providers requires that the user defines a --radar-device option using the adsbx:// URI schema. It is necessary to supply the host name, the range (in nautical miles) and a refresh interval in milliseconds, in the format: 

adsbx://host?range=R&interval=T
where

  • host is the provider host (assumed available via https)
  • range defines the range (R) in nautical miles
  • interval defines the refresh interval (T) in milliseconds

--radar-device may be given on the command line, or more conveniently in ~/.config/mwp/cmdopts, for example:

--radar-device adsbx://api.adsb.lol?range=40&interval=1000
## or
--radar-device adsbx://api.adsb.one?range=40&interval=1000

Adsbx Notes#

  • It is pointless to define both providers as they have much the same data
  • The providers permit a maximum range of 250NM
  • The providers have a minimum query interval of 1s (1000ms)
  • As the APIs return the data as JSON, the results are verbose. Requesting a range of 250NM may seem like a good idea; however it is not useful for our purposes and will return a large volume of data, which may be sub-optimal using mobile internet in the field.
  • mwp will use select a centre location based on user choice and vehicle state.

Where the data is provided by 3rd party volunteers, there may be limited coverage in remote areas (or areas with little air traffic).

Using the main serial port#

The main mwp serial port may be used for MavLink Traffic and MSP2_ADSB_VEHICLE_LIST messages without any further configuration. For INAV-radar, to use the main MSP port for INAV-radar (vice using --radar-device), it is still necessary to add a command option to mwp; it needs to told to relax the default inbound MSP direction check.

This is enabled as

mwp --relaxed-msp

which should be 'mainly harmless' for normal operations. It's entirely acceptable to put this in ~/config/mwp/cmdopts to make it the default, as the protocol check dilution is slight.

Settings#

The following dconf setting affect the radar function:

Setting Usage
radar-list-max-altitude Maximum altitude (metres) to show targets in the radar list view; targets higher than this value will show only in the map view. Setting to 0 disables. Note that ADS-B altitudes are AMSL (or geoid) and SDR altitudes are "Flight Level" (standard atmosphere).
radar-alert-altitude Target altitude (metres) below which ADS-B / SDR proximity alerts may be generated. Requires that 'radar-alert-range' is also set (none zero). Setting to 0 disables. Note that the above altitude datum.
radar-alert-range Target range (metres) below which ADS-B / SDR proximity alerts may be generated. Requires that 'radar-alert-altitude' is also set (none zero). Setting to 0 disables.
ga-alt Units for GA Altiude, enumerated as 0=m, 1=ft, 2=FL
ga-range Units for GA Range, enumerated as 0=m, 1=km, 2=miles, 3=nautical miles
ga-speed Units for GA Speed, enumerated as 0=m/s, 1=kph, 2=mph, 3=knots
msp2-adsb Options for requesting MSP2_ADSB_VEHICLE_LIST. "off": never request, "on:" always request, "auto:" heuristic based on serial settings / bandwidth

Note that proximity alerts require that both the radar-alert-altitude and radar-alert-range values are set.

Location and Alerts#

mwp selects a location for alerts based on the user choice and vehicle state. The same location will also be used for adsbx:// (internet REST) services.

The following table defines how the location is selected, and the range check alert visualisation for that state.

No location GCS Home Connection/GPS
Sound x Y x Y
Toast x Y x Y
Item Colour x Y Y Y
Base Position View centre / SDR location GCS Home Vehicle

Location Types#

  • No location: There is no home or vehicle location known.
  • GCS: The user has enabled the GCS location icon, either from the View -> GCS Location menu item or a local GPS (via gpsd).
  • Home: A home position is available, either from the vehicle GPS or a "fake" / "planned" home via Ctrl-Shift-H / creating a mission / loading a mission with stored home position.
  • Connection: The vehicle is connected to mwp and is supplying a valid GPS location.

Visualisation#

  • Sound: A beep is emitted every two seconds
  • Toast: A transient, non-blocking notification at the base of the screem
  • Item Colour: The aircraft icon will show in red, and the aircraft detail will be shown in the Gtk4 "error" style in the radar list.

Usage#

Legacy Images

The images this section are from legacy mwp, however the capability is the same.

Once the radar interface is open, radar tracks are displayed on the map and in a list available from the "View -> Radar View' menu option.

  • The list view is sort-able on the Id, Status, Last (time) and Range columns.
  • The map visualisation may be toggled by the Hide Tracks (Show Tracks) button. This will also supress alerts.
  • List and map views are updated in (near) real time.
  • Settings for display units are used for positions, altitude and speed.

Name#

Type Usage
INAV-radar Node Id (typically 'A' - 'D')
Traffic Report Callsign if reported, otherwise [ICAO number]
SDR Callsign if reported, otherwise [Mode S hexadecimal code]
Telemetry User defined for automatically allocated, prefixed by TTRK-
General Aviation Callsign if reported, otherwise [ICAO number]

Status#

Radar contacts have one of the following status values:

Status Explanation
Undefined ADS-B: Not shown in list or on the map, INAV-Radar not armed / updated
Stale The last contact was more that 120s previous. Displayed in the list and shown on the map with reduced intensity or an INAV-radar node has 'lost' status
Armed An active INAV-radar contact
Hidden A MAVLink Traffic /SDR contact is between 5 and 10 minutes old. It remains in the list but is not displayed in the map. MAVLink Traffic Report / SDR tracks are removed from the list (and internal storage) after 10 minutes inactivity. INAV-radar ground station. Stale / 'Lost' INAV-radar contacts do not expire, as they may relate to a lost model.
ADS-B A live MAVLink Traffic report
SDR SDR radio report (sbs, json, protobuf)
ADSBX General Aviation internet REST service

The number displayed after the status text is:

Type Usage
INAV-radar The link quality
Traffic Report Time since last communication in seconds
SDR reports Time since last communication in seconds
General Aviation Time since last communication in seconds

Columns#

The columns are sortable. Note that since the introduction of Telemetry Tracking, a new column "*" has been added, this contains a single character indicating the source:

Indicator Source
A ADS-B via MAVLink or MSP
I INAV Radar
S ADS-B via SDR protocol
T Telemetry Tracker
X General Aviation internet REST service

Telemetry Tracker

Examples#

  • Proximity Alerts
  • Live and stale aircraft
  • Aircraft tooltip
  • Mission Plan
  • List view

Live ADS-B and simulated INAV targets, with proximity alerts (range < 3000m).#

radar-alerts

Local manned aircraft view over Florida (May 2020).#

Florida-may-2020

Simulated INAV radar view#

inav-radar-sim

Simulators#

There are simulators for both INAV-radar and MAVLink 'Traffic Report' (e.g. uAvionix PingRX) in the mwptools/src/samples/radar directory.

There is a replay tool for SBS CSV logs mwptools/src/samples/sbs-test/sbs-player.rb.

Changing the Radar Symbols#

Many map symbols used by mwp can be changed by the user; in the image above, the INAV radar node symbol has been changed from the default stylised INAV multirotor to a smaller version of the mission replay "paper plane" symbol as described in creating your own icon.

Protocol documentation#

The MAVLink implementation is comprehensively documented by the vendor.

INAV radar#

The following is required by a device wishing to act as a ground node (it either masquerades as an INAV FC, or declares itself a GCS)

  • Receive and respond to the following MSP data requests:
    • MSP_FC_VARIANT (responding as INAV or (from 2021/05/06) GCS for generic ground control stations).
    • MSP_FC_VERSION (in INAV and GCS modes)
    • MSP_NAME (in INAV and GCS modes)
    • MSP_STATUS (in INAV mode)
    • MSP_ANALOG (in INAV mode)
    • MSP_BOXIDS (in INAV mode)
    • MSP_RAW_GPS (in INAV mode)
  • Receive unsolicited
    • MSP2_COMMON_SET_RADAR_POS

Note that the device firmware assumes that MSP buffer sizes are "as specification"; exceeding the expected message buffer size may crash the device (mea culpa).

In GCS mode, the node is passive; it does not use a LoRa slot and does not attempt to broadcast a location. In INAV mode, the node takes up a LoRa slot and is expected to reply to the additional MSP queries.

mwp's behaviour is defined by the GCS Location

  • If the GCS Location is defined (when the radar device is initialised, then mwp will respond as INAV and return the GCS Location, which may be driven by gpsd if required.
  • Otherwise, mwp will respond as a passive GCS.

SBS CSV protocol#

Protocol description.