ATAK plugin

Android Team Awareness Kit (TAK) is a US Government situational awareness application, available for free on Android (ATAK). The civilian version is available for free on the Google Play store.

ATAK-CIV https://play.google.com/store/apps/details?id=com.atakmap.app.civ

ATAK plugin

Supported versions

  • ATAK-CIV 4.10

  • ATAK-CIV 4.8

Requirements

  • ATAK-CIV

  • A CloudRF account or SOOTHSAYER server

  • A network connection

Release and debug builds

Due to the byzantine plugin signing process and compatibility matrix, there are a bewildering number of ATAK versions. Our plugin is signed by the TAK Product Center (TPC) which at the time of writing means it should work on CIV and MIL flavours.

A debug release is offered to work with the Github version which allows developers to demo capabilities without the need for plugin signing. A debug plugin build will only work with a debug build of ATAK. You can recognise this by the red letters DEVELOPER BUILD across the screen.

APK installation

Install ATAK-CIV on your phone first and then download the latest APK file from https://cloudrf.com/atak

You can download it directly from the device with a browser, send the file to the device via email/IM or copy it over via USB.

Before you attempt installation of the APK, ensure ATAK is running. If it is not running, installation will fail which is expected behaviour

Installing the APK

Plugin installation

Within ATAK, open the plugin manager (jigsaw icon) and you should see the SOOTHSAYER plugin listed as available but not loaded. At this point you need to check the central status box to load the plugin. This is also where ATAK will check compatibility.

Installing the plugin Installing the plugin

Validating the plugin version

To see details about the plugin version, click the report icon to the right. It should specify the required Android OS (10 in our case) and ATAK version (4.8.1.CIV) as well as the signature validity which for a TPC signed plugin should be valid: ATAK plugin details

Adding a shortcut in ATAK

Once installed the plugin will be available within ATAK. To add it to the quick menu, click the pencil marker adjacent to the “Tools” label above the icons. This opens up the navigation bar to editing so you can drag your new plugin up there. ATAK plugin shortcut

Using the plugin

Press the icon to open the plugin. You should have a list select and at least two buttons. To add a radio to the map, choose the system from the list, then click the SOOTHSAYER button above it. A marker will be added to the middle of the map. ATAK plugin start

You must drag this marker to the desired location using a long press. Once released, the coverage will be calculated. A network connection is required to communicate with the server at this point.

ATAK plugin drag

Single site mode

The default mode for calculations is to consider each site separately, as a separate layer. This allows different equipment to be placed upon the map, with different colour schemas, and site layers to be managed individually.

The downside to this mode is you may end up with many overlapping layers which you will need to manage through the ATAK layer menu to focus on what you need. These layers are available under the “SOOTHSAYER” category in the layers menu and can be hidden or deleted to suit.

ATAK plugin single mode

In this image, two different templates are used. One is a LOS coverage with green colours and the other is a VHF repeater with a rainbow heatmap.

ATAK plugin single mode

Multisite mode

The multisite mode is a more powerful network planning capability which models all radios together to show the entire network coverage. Designed for MANET networks, it will model changes to the network as soon as you reposition a node.

Multisite requires a server with a GPU or a CloudRF Gold subscription.

ATAK plugin multisite mode

A multisite layer is a single layer which is available in the ATAK layers menu under the “SOOTHSAYER” category. It can be hidden or deleted to suit.

ATAK MANET network

KMZ coverage export

Layers generated with the plugin are saved as KMZ on the SD card in the atak/SOOTHSAYER/KMZ/ folder. You can load them into ATAK as standard KMZ overlays using the “Local import” dialog or export them to another viewer such as WinTAK or TAK-X. When prompted for a choice of the import method, choose “Image Overlay File”.

ATAK file import ATAK file import KMZ list ATAK file import choice ATAK file KMZ layer

To send a KMZ to another TAK user, load it onto your map to validate it’s the right one, then using ATAK’s native send functionality, click the 3 bars to the right of the selected layer to open the send dialog. From here you can choose to send it to a contact, server or third party app eg. Bluetooth or Google Drive.

ATAK file KMZ export

Radio Templates

To add more radio systems, place your CloudRF/SOOTHSAYER JSON templates in the atak/SOOTHSAYER/templates folder. You can download templates from the top left corner in the CloudRF/SOOTHSAYER web interface. Templates in the plugin will refresh when you open it.

A template can be edited within any text editor and must conform to the CloudRF API specification detailed at https://cloudrf.com/documentation/developer/

At the time of writing both the old environment variables (cll,clm,clt) and the new ones (elevation,landcover,clutter,profile) are accepted.

ATAK SOOTHSAYER templates

Example DMR template

This template is for a 700MHz handheld radio with 2W of RF power, a CPU engine (engine: 2) with the ITM model, 3km radius and 5m resolution.

{
    "version": "CloudRF-API-v3.8.2",
    "reference": "https://cloudrf.com/documentation/developer/",
    "template": {
        "name": "Motorola DMR 2W",
        "service": "CloudRF https://api.cloudrf.com",
        "created_at": "2023-04-12T06:35:40+00:00",
        "owner": 1,
        "bom_value": 0
    },
    "site": "Site",
    "network": "MOTO",
    "engine": 2,
    "coordinates": 1,
    "transmitter": {
        "lat": 51.96403,
        "lon": -2.113952,
        "alt": 2,
        "frq": 700,
        "txw": 2,
        "bwi": 0.1,
        "powerUnit": "W"
    },
    "receiver": {
        "lat": 0,
        "lon": 0,
        "alt": 1,
        "rxg": 2,
        "rxs": -100
    },
    "feeder": {
        "flt": 1,
        "fll": 0,
        "fcc": 0
    },
    "antenna": {
        "mode": "template",
        "txg": 2.15,
        "txl": 0,
        "ant": 39,
        "azi": 0,
        "tlt": 0,
        "hbw": 1,
        "vbw": 1,
        "fbr": 2.15,
        "pol": "v"
    },
    "model": {
        "pm": 1,
        "pe": 2,
        "ked": 1,
        "rel": 95
    },
    "environment": {
        "clm": 0,
        "cll": 0,
        "clt": "Minimal.clt"
    },
    "output": {
        "units": "m",
        "col": "LTE.dBm",
        "out": 2,
        "ber": 1,
        "mod": 0,
        "nf": -124,
        "res": 5,
        "rad": 3
    }
}

Example GPU ‘line of sight’ template

This template uses the more powerful GPU engine (engine: 1) to model line of sight out to 3km at 2m resolution (if your area of interest has 2m LiDAR).

{
    "version": "CloudRF-API-v3.8.2",
    "reference": "https://cloudrf.com/documentation/developer/",
    "template": {
        "name": "LOS_3km_2m_GPU",
        "service": "SOOTHSAYER https://185.11.204.106",
        "created_at": "2023-05-05T15:43:42+00:00",
        "owner": 8,
        "bom_value": 0
    },
    "site": "Site",
    "network": "TALON",
    "engine": 1,
    "coordinates": 1,
    "transmitter": {
        "lat": 50.806335,
        "lon": -1.112032,
        "alt": 2,
        "frq": 1250,
        "txw": 2,
        "bwi": 0.1,
        "powerUnit": "W"
    },
    "receiver": {
        "lat": 38.913,
        "lon": 1.45,
        "alt": 1,
        "rxg": 2,
        "rxs": -90
    },
    "feeder": {
        "flt": 1,
        "fll": 0,
        "fcc": 0
    },
    "antenna": {
        "mode": "template",
        "txg": 2,
        "txl": 0,
        "ant": 39,
        "azi": 0,
        "tlt": 0,
        "hbw": 1,
        "vbw": 1,
        "fbr": 2,
        "pol": "v"
    },
    "model": {
        "pm": 7,
        "pe": 2,
        "ked": 0,
        "rel": 50
    },
    "environment": {
        "clm": 0,
        "cll": 0,
        "clt": "Temperate.clt"
    },
    "output": {
        "units": "m",
        "col": "GREEN.dBm",
        "out": 2,
        "ber": 1,
        "mod": 0,
        "nf": -124,
        "res": 2,
        "rad": 3
    }
}

Template limits

As a server based system, limits for APIs and accounts are set at the server. For premium users this means a 500km / 310Mi radius and a resolution between 1m / 3ft. The combination of these two will determine the resulting file size. The API will automatically reduce unreasonable parameters to fit within memory.

As well as memory, a large layer needs more bandwidth to communicate and is generally not recommended. You should be aiming for smaller layers which can be generated and communicated quickly. You can still do a large radius eg. > 100km, but will need to offset your resolution to keep the total size less than 1 mega pixels (1000 x 1000px).

As a rule of thumb, multiply the radius in km by 2 to get the resolution in metres

The following guide is recommend for practical 1MP ATAK templates:

Desired radius km

Recommended max resolution m

1

2

2

4

5

10

10

20

20

40

50

100

100

200

150

300

Giant airborne calculations

The API can model out to 500km radius for aircraft. If you set 500km as the radius with 100m resolution you are generating a 10k x 10k image measuring 100 mega pixels! This will take a long time to make, a long time to download and then will crash ATAK, and any other Android map for that matter. To do this scale of calculation, use a resolution of 300m which makes a more digestible 11MP image. Better still reduce the radius to the radio horizon which is 357km for an aircraft at 10,000m (33,000ft).

Custom icons

You can insert a custom icon into a JSON template as a 48x48px base64 encoded PNG. Examples are included on the Github repo. ATAK plugin