Support

TABLE OF CONTENTS

• Quick Start
• Data Input
• Main Window
  • Map Controls
• Playback Window
• Map Options
  • Accuracy Points
  • Tail
  • Protection Levels
  • HUD
  • Marker
• Map Overlays
• Logging
  • Logging to Standard Output
  • Logging to File
  • Logging to TCP Client
  • Logging to TCP Server
• Command Line Options

Drongo Maps uses the Google Maps API to display a moving map which can be used to monitor the output from a GNSS receiver in real-time. It supports the following features:

• Interactive map
• Live visualisation of TCP and serial data streams
• Playback visualisation of pre-recorded data streams
• Support for data streams in SBP, SBP-JSON, UBX, Novatel ASCII, Novatel binary, CSV, RTKLIB Positioning Solution files and NMEA 0183 formats
• Support for displaying accuracy points, protection levels and status information
• Logging to standard output, file, TCP client and TCP server in SBP, SBP-JSON, decoded SBP message and NMEA 0183 formats
• Support for map overlays in KML, KMZ, GPX or GeoJSON format

Drongo Maps is available for Windows, macOS and Linux.  It requires an active internet connection in order to function. 

Quick Start

Drongo Maps is distributed as a single executable, meaning that no installation process is necessary. 

Note for Windows users: Windows Defender may incorrectly flag Drongo Maps as a potential virus. Please follow these instructions to work around the issue.

Basic usage of Drongo Maps is intended to be self-explanatory:

• Use File → Open TCP or File → Open Serial to connect to a GNSS receiver
• Enable desired visualisations in the Map Menu (Show Accuracy Points and Show HUD are the recommended minimum) 
• To specify a log file, select: Logging → File → Configure 
• To start logging to the file specified in the preceding step: Logging → File → Enable

Data Input

Drongo Maps can process incoming data from one of three different sources:

1. Use File → Open TCP to receive live data from a TCP connection
2. Use File → Open Serial to receive live data from a serial port
3. Use File → Open File to load pre-recorded data from a file

The format of the incoming data will be automatically detected.  Drongo Maps supports a variety of input data formats, including, but not limited to:

• SBP binary
• SBP-JSON
• UBX binary
• Novatel ASCII
• Novatel binary
• CSV
• NMEA 0183

Main Window

The screenshot below shows an example of Drongo Maps in operation (note the elements shown in this window may differ depending upon user configuration):

Some key elements are as follows:

• The marker (circled in red) represents the current position.
• The accuracy points and tails (circled in green) represent the current and past positions. See the Accuracy Points and Tail sections below for more details.
• The HUD (circled in blue) shows selected metadata relating to the current position. In this case, the HUD has been configured to show estimated accuracy, age of corrections, velocity and position type.  See the HUD section below for more details.  
• The status bar (circled in yellow) shows status, warning and error messages.

Map Controls

Users may interact with the map in the main window using the Map Controls.  These controls are only displayed when the Map → Show Map Controls setting is enabled. The location of the main controls are highlighted in the screenshot below:

• Map Type (circled in blue): switches the main window between displaying street maps or satellite imagery (default). For Map mode, the display of 3D terrain may be toggled on and off.  For Satellite mode, the display of labels showing street map information may be toggled on and off.
• Zoom (circled in red): allows zooming in and out of the map. Note that it is also possible to change the zoom level of the map using the mouse scroll wheel, or by performing a "pinch-zoom" action on a touchpad.
• Tilt (circled in green): allows the view to be toggled between a top-down and 45° camera angle. When the 45° tilt mode is selected, two additional buttons are displayed, which allow the camera to be rotated in a clockwise or anti-clockwise direction. Note that the tilt control is only displayed when using the Satellite map type with higher zoom levels.
• Pan: it is possible to move around in the map by performing a mouse drag action. Note however that the position of the map will be reset whenever a new point is received if the Map → Auto-centre Map setting is enabled.

Note that the map controls remain active when they are overlaid with the HUD.

Playback Window

An existing log file can be loaded for playback by selecting File → Open File. Drongo Maps will parse the selected file to determine events of interest and then show a window similar to the following:

The Playback Window includes the following regions:

1. Metadata (circled in blue): this region displays a high-level summary of the currently loaded file
2. Playback Controls (circled in green): The centre button pauses and unpauses playback. The buttons to the left and right allow the playback speed to be controlled - repeated clicking on the right-hand button will increase playback speed by 100%, whereas repeated clicking on the left-hand button will decrease playback speed by 100%. This allows the user to perform real-time or faster-than-real-time playback in either the forwards or reverse direction. The progress bar above these buttons can be dragged to an arbitrary position to force playback to immediately jump to the specified epoch.
3. Playback Status (circled in red): this region shows the current status of the playback. The left-hand side of this region indicates whether playback is playing or paused, as well as displaying the playback speed. The right-hand side of this area shows the time of last epoch update in different representations, namely, the time since start of log, epoch number, UTC time, and GPS Time of Week.
   

Map Options

The Options dialog can be opened by navigating to Map → Options (or Drongo Maps → Preferences under macOS).  It displays five tabs which allow for customisation of various aspects of Drongo Maps.

Accuracy Points

The options in this tab allow the appearance of accuracy points to be customised.  An accuracy point is a single dot which represents the location and estimated accuracy of a GNSS position. Up to 1000 accuracy points may be displayed at a time - if a new position is received when 1000 points have already been received, then the oldest accuracy point will be removed. 

Accuracy points are only displayed when the Show Accuracy Points option is enabled in the Map menu.

Tail

The options in this tab allow the appearance of the tail to be customised. A tail is a line segment which connects a newly received GNSS position to the previous one, and so on. The length of the tail is limited to 1000 points - if a new point is received when the tail already contains 1000 points, then the oldest point will be removed. 

Tails are only displayed when the Show Tail option is enabled in the Map menu.

Protection Levels

The options in this tab allow the appearance and operation mode of Protection Levels to be customised.  Protection Levels are a feature of the Starling Positioning Engine which represent a bound on position error with a given degree of certainty. Up to 1000 Protection Level points may be displayed at a time - if a new position is received when 1000 points have already been received, then the oldest Protection Level point will be removed. 

Protection Levels are only displayed when the Show Protection Levels option is enabled in the Map menu.

HUD

The options in this tab allow the Heads-Up Display (HUD) overlay to be customised. In addition to allowing for customisation of the foreground and background colours, it is also possible to configure the data fields which will be displayed.  The ordering of the widgets displayed in the HUD will correspond to the ordering of the items enabled in this list. Note that it is possible to reorder the list by long-pressing on an item and then dragging the item to the desired position.

The HUD is only displayed when the Show HUD option is enabled in the Map menu.

Marker

The options in this tab allow for customisation of the marker icon displayed when the Show Marker option is enabled in the Map menu. A custom icon (in SVG format) may be selected by clicking on the Select Icon button. The size of the displayed icon can be controlled using the Scale value.

Map Overlays

The Map Overlays dialog can be opened by navigating to Map → Configure Overlays (or Drongo Maps → Configure Overlays under macOS). This dialog allows an arbitrary number of overlays to be displayed on the map. Overlays can be added to the list using the Add button and then selecting the desired file.  Overlays can be removed from the list by selecting an overlay and then pressing the Remove button. 

The draw order of the overlays will correspond to the ordering of the items enabled in this list (with the top-most item being rendered first). Note that it is possible to reorder the list by long-pressing on an item and then dragging the item to the desired position.

Overlays in KML, KMZ, GPX and GeoJSON format are supported.  Each overlay is successively imported to the Google Maps Data Layer, which means that styling support is limited to that supported by the Google Maps API for point, line and polygon types. KML, KMZ and GPX formats are internally converted into GeoJSON before being rendered with Google Maps, meaning that style information which has no corresponding counterpart in GeoJSON will not be displayed.

The following element types are supported:

• GeoJSON: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection
• KML/KMZ: Point, LineString, MultiLineString, Polygon, MultiPolygon, MultiGeometry, LinearRing, Track, MultiTrack, ExtendedData, SimpleData, name and description (only with CDATA content)
• GPX: trk, rte, wpt, plus various extensions and metadata 

Any folder structure present in a KML/KMZ file will be flattened. GeoJSON Point objects with a description property (or corresponding type from a converted file) can be interacted with in the map view, as demonstrated in the following screenshot:

Logging

Drongo Maps supports four possible destinations for data logging:

• Standard Output
• File
• TCP Client
• TCP Server

Additionally, one of four different output formats may be selected.  The logged data depends upon the format of the input data, as well as the selected output type, as follows:

• SBP:
  • SBP inputs: output corresponds to input data in SBP binary format
  • Non-SBP inputs: output corresponds to input converted to MSG_GPS_TIME and MSG_POS_LLH messages in SBP binary format
• JSON: 
  • SBP inputs: output corresponds to input data in SBP-JSON format
  • Non-SBP inputs: output corresponds to input converted to MSG_GPS_TIME and MSG_POS_LLH messages in SBP-JSON format
• Decoded messages:
  • SBP inputs: output corresponds to input data in decoded SBP message format
  • Non-SBP inputs: output corresponds to input converted to MSG_GPS_TIME and MSG_POS_LLH messages in decoded SBP message format
• NMEA: 
  • Input data is converted to NMEA 0183 GGA and RMC sentences

Logging to Standard Output

When invoked from a terminal or command line interface (CLI), the Standard Output logging mode may be used to to log messages to the standard output. 

Note for macOS users: On macOS, the Drongo Maps executable is typically installed in /Volumes/Drongo Maps/Drongo Maps.app/Contents/MacOS/Drongo Maps. You will not see messages to the standard output if Drongo Maps is invoked through the Applications window of Finder.

Note for Windows users: Logging via Standard Output is not possible with Windows builds of Drongo Maps.

Usage:

1. Select Logging → Standard Output → Configure.  The following dialog will be displayed:
   
   
   
2. Select the desired output format (see Logging with Drongo Maps above for details)
3. Press OK
4. Select Logging → Standard Output → Enable

Output will then be printed to standard output in the requested format. The Logging → Standard Output → Enable menu item will also show a check-mark to indicate that standard output logging is active.

Logging to File

The File logging mode can be used to log data to a file. The recorded file can then be loaded into Drongo Maps to replay the drive in real-time (or in accelerated real-time, in reverse, etc). SBP logs may also be loaded into another tool (e.g. Woodpecker Log Utility) for further analysis.

Usage:

1. Select Logging → File → Configure. The following dialog will be displayed:
   
   
2. Select the desired output format (see Logging with Drongo Maps above for details)
3. Press Change to modify the name of the target output file
4. Press OK
5. Select Logging → File → Enable

Output will then be logged to the specified file in the requested format. The Logging → File → Enable menu item will also show a check-mark to indicate that file logging is active.

Note: If the file already exists, selecting Enable will overwrite the contents of the file without warning.

Logging to TCP Client

The TCP Client logging mode configures Drongo Maps to connect to a TCP port and log data to it. 

Usage:

1. Select Logging → TCP Client → Configure. The following dialog will be displayed:
   
   
2. Select the desired output format (see Logging with Drongo Maps above for details)
3. Specify the host IP address and port number to which Drongo Maps should connect
4. Press OK
5. Select Logging → TCP Client → Enable

Data will then be sent to the specified TCP host/port in the requested format. The Logging → TCP Client → Enable menu item will also show a check-mark to indicate that TCP client logging is active.

Logging to TCP Server

In the TCP Server logging mode, Drongo Maps acts as a TCP server, publishing data on the specified port. 

Usage:

1. Select Logging → TCP Server → Configure. The following dialog will be displayed:

   
   

   
   
2. Select the desired output format (see Logging with Drongo Maps above for details)
3. Specify the port number on which Drongo Maps should publish data
4. Press OK
5. Select Logging → TCP Server → Enable

Drongo Maps will then listen on the specified TCP port for incoming connections and write data to any clients which subsequently connect in the requested format. The Logging → TCP Server → Enable menu item will also show a check-mark to indicate that TCP server logging is active.

Command Line Options

In some advanced use cases it may be desirable to create scripts/batch files which execute one or more instances of Drongo Maps with a specific configuration. Drongo Maps supports a number of command line options which can be used to facilitate this:

• --file <filename>: Load the specified file at start-up
• --tcp <host:port>: Connect to the specified TCP host using the specified port at startup
• --serial <port:baud>: Connect to the specified serial port using the specified baud rate at startup
• --window-size <X,Y>: Desired dimensions of the main map window.  The default size is 800,600
• --window-pos <X,Y>:  Desired position of the upper left corner of the main map window
• --log <stdout,file,tcpcli,tcpsvr>: Start logging to specified target(s) at startup
• --app-name <name>: Application name to display (e.g. can be used to change the text shown in the title bar of the main window)