TAK logo

TAK Interface

Team Awareness Kit (TAK) is a US Government situational awareness application, developed under contract and now open sourced. The TAK eco-system comprises mobile apps for Android (ATAK) and iOS (iTAK) which connect to a server (TAK server) and communicate with open XML standards like Cursor-on-Target (CoT) and Keyhole Markup Language (KML).

The CloudRF TAK Interface is a unique network chatbot which enables a powerful RF planning capability for every End User Device (EUD) on a TAK network, without a local plugin. It has been developed and tested against ATAK 4.3 to 4.7 and TAK Server 4.7.

The apps are available to download for free from app stores and the TAK product center.

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

TAK Server: https://tak.gov/products

Server setup

If your organisation does not yet have a TAK server, use these instructions to build the official server docker images from TAK product center.

https://github.com/Cloud-RF/tak-server

TAK server frequently asked questions

TAK server configuration

The bot connects to your TAK server using SSL certificates. Only SSL mode is supported. To add the bot to your server you must first open the user management form on TAK server and click “Add User” (1). Give the user a name/callsign eg. CHATBOT (2) then assign a group to it (3) so users can communicate with it and you can also control what network messages the bot has access to. Any user needing the bot will need to belong to the same group.

Adding a new user in TAK server

User certificate generation

Adding a user in TAK Server does not, by default, create SSL certificates so you must do this from a shell environment. If you are using the docker image, you will need to open the shell inside the TAK server container as follows:

    docker exec -it tak-server-tak-1 bash
    cd /opt/tak/certs/

From the /opt/tak/certs directory run the makeCert.sh script to generate a client certificate pair with the same name as the new user eg. CHATBOT.

    ./makeCert.sh client CHATBOT

The 6 files will be created in the /opt/tak/certs/files directory like this:

root@fc5490932d35:/opt/tak/certs# ls -lah files/CHATBOT*
-rw-r--r-- 1 root root 1.3K Aug 26 10:38 files/CHATBOT-trusted.pem
-rw-r--r-- 1 root root  989 Aug 26 10:38 files/CHATBOT.csr
-rw-r--r-- 1 root root 3.7K Aug 26 10:38 files/CHATBOT.jks
-rw------- 1 root root 1.9K Aug 26 10:38 files/CHATBOT.key
-rw------- 1 root root 3.4K Aug 26 10:38 files/CHATBOT.p12
-rw-r--r-- 1 root root 2.5K Aug 26 10:38 files/CHATBOT.pem

If using docker you will need to “exit” the container to return to the host environment.

For your Chatbot you require 3 files which are used later to securely authenticate the certificate, the server and the user respectively: ca.pem, CHATBOT.pem and CHATBOT.key. Copy these files securely to your computer ready for use with the chatbot.

Chatbot setup

A web based setup form is available for convenience on the CloudRF API at /API/bot/manager. Session based authentication is required so you should access this form from either the user inteface or the shop, for the public API.

For the public API this is located at:

https://api.cloudrf.com/API/bot/manager

For a private server this would be:

https://{server IP}/API/bot/manager

You will need to carefully enter your TAK server details as follows and the click “Submit” to validate the data. Validation will check if the certificates are related and cryptographically sound.

Field

Description

TAK Server address

The IP address OR domain name for your server. This must match your certificate’s Common Name (CN). You can check the CN value via the padlock in any web browser on port 8443 (default).

CoT SSL port

TCP port for secure sockets layer, Cursor-on-Target (CoT) XML. Default 8089

Marti API Port

TCP port for the REST API used for ‘Enterprise Sync’ on TAK server. Default 8443

TAK Server CA Certificate PEM

Your TAK Server’s ca.pem file. Need to authenticate certificates

TAK Client Certificate PEM

Your CHATBOT.pem certificate. Needed for the server to authenticate the bot

TAK Client Certificate key

Your CHATBOT.key file. Needed for mutual authentication of the server

TAK Client Certificate Key Passphrase

The .key file’s passphrase. The default is atakatak

Chatbot manager

Chatbot control

To start a bot, click “Start chatbot”. You can verify connectivity from both the Chatbot logs which has a 5 second refresh and the TAK Server Client Dashboard which will show a TAK client callled “SOOTHSAYER”. Adding a new user in TAK server

The bot can be stopped by clicking “Stop Chatbot”.

Debugging connectivity

If the bot does not connect it is either because the server cannot be reached OR there are authentication issues with the certificates and account. Assuming your CloudRF API is on the same network as your TAK Server in the case of a VPN for example:

  • Try accessing the server web interface from a web browser eg. https://{TAK SERVER}:8443

  • Review the TAK Server logs at /opt/tak/logs/

  • Review the chatbot logs in the form

  • Test TCP 8089 with a shell utility like netcat: nc -v takserver 8089

  • Check the user exists on the server and belongs to a group

Chatbot Commands

The bot can be found in the app’s chatroom as SOOTHSAYER-x where x is a number representing the instance. You can have multiple chatbots on a busy network server to increase planning capacity.

When you first communicate with the bot it will request authentication. This step locks the bot to your device until you either release it or it times out through inactivity (default 60 minutes) at which point it is free for another member to claim.

SOOTHSAYER on ATAK 4.7 SOOTHSAYER on ATAK 4.7

Commands for the bot are as follows:

auth

Before you can start RF planning you must authorise your device to the server. SOOTHSAYER private server users can just type auth to be given any available slot on the server. Public API users must request the instance number eg. auth 1. The number must match the number in the callsign

auth 1

A successful authorisation will generate a Registered OK response.

SOOTHSAYER on ATAK 4.7

deauth

Detach this device from the bot to free it up for another user. You will be automatically removed after 60 minutes of inactivity.

clutter

Fetch your account’s custom clutter with the clutter command. The clutter items must exist in your account already. See the Clutter section in the Web Interface Map documentation for instructions. The clutter is used on the server API not the client EUD so this step is not needed to “use clutter” in your calculations, it is for visual reference only. To use clutter on the API, your radio template needs custom clutter enabled (clm=1).

Clutter can be uploaded to the web interface or API as GeoJSON or KML 

Custom clutter on ATAK

Custom clutter as seen on Web UI

eqpt

Type eqpt to list radio templates available to your account. To create a template see the saving templates function within the web interface. To use an item type use followed by the eqpt you wish to use, for example use pmr for example to select a pmr template.

TAK 'eqpt' command followed by 'use pmr' command

env

List environmental profiles. Use one with env {profile}, for example env minimal.clt.

Selecting an environmental profile

help

For more information on a command type the command followed by help, for example eqpt help to get information about the eqpt command.

You can also just send help on its own to get a list of available commands.

Response of help command

id

Returns useful information about your device and the chatbot with the id command. This includes configuration and associated/followed networks.

join

Associate this device with a radio network, for example join blue. For route analysis of points along a path back to the start use join self, for MANET analysis of many-to-many points use join {net} where net can be any word.

rc

Perform a radio check against your joined network, for example rc blue or rc firehq.

use

Use a radio template, for example use vhf. List the equipment with the eqpt command. Not case-sensitive. If you do not have any templates you must visit the web interface on a computer and define some. See the web interface templates section for more information.

Shape analysis

ATAK drawing toolbox

Point-to-Point

Using the ATAK drawing toolbox, select the polygon (#4) then press twice on the map to draw a line from one point to another. Select End Shape once done then click on the line to open up the radial menu.

Choose the details to open the right dialog and then click the Send button to open a list of contacts. Select the SOOTHSAYER contact and click Send. After a brief delay, SOOTHSAYER will return a 3D KMZ layer showing the point-to-point path and fresnel zone. To view a 2D profile chart and the metadata, click the layer to open the radial menu again, then view details.

Drawing a line in TAK then opening radial menu

Viewing a path profile KMZ

Point-to-many-Points

If you are not associated to a network or have requested to work alone (with join self) you will get coloured polylines showing the signal as seen from the start point. Using the ATAK draw tool, select polygon again then draw a line on the map from one point to several other points. Select End Shape then click on this line to open up the radial menu.

Send the line to SOOTHSAYER which will return the signal strength at all the points / vertices on the line. Each tested point will be simulated as the transmitter back to point 0 (receiver). Received power in dBm is visible as METADATA if you click the vertex.

Testing several points

MANET

If you are associated to a network (eg. send join blue) you will get links between all nodes. Using the ATAK draw tool, select polygon then draw points on the map representing network nodes. Select End Shape then click on this line to open up the radial menu.

Send the line to SOOTHSAYER which will return the links. Detail is available by clicking a link.

In this mode, each vertex/node is assumed to have the same radio equipment as your chosen template. If you have different power profiles, use the low power one.

Testing many MANET points

Route

Using the ATAK route OR telestration drawing tool, draw a freehand route on the map from a start position. Select end then click on this line to open up the radial menu.

Send the route to SOOTHSAYER which will return either coloured links (measured to point zero) OR coloured links between every node depending on your network. You can join another net any time with join {net}.

Drawing a route Drawing a route

Area

To create a point-to-multipoint heatmap aka area output. Use the circle drawing tool to create a circle with a radius representing your target RF coverage and send the shape to SOOTHSAYER.

Depending on the radius and template, a (CPU) multipoint prediction can take several seconds to complete. If you have GPU enabled and a template with a GPU engine these are significantly faster. Once complete a semi-opaque image overlay will appear on your map, styled according to the colour key in the radio template.

Point to Multipoint Signal metadata

Best Site

To analyse an area for the optimal site using GPU parallel processing, use the polygon tool again. Unlike previous shapes, the Best Site Analysis (BSA) capability is acivated by a closed polygon so you must complete the shape by clicking upon the first point.

A closed polygon Best Site Analysis on ATAK

BSA output is very different to a signal coverage heatmap: For starters it does not have a transmitter site. It reveals the site efficiency in % at each point within the shape, measured relative to the best site (red = +95%). The roof of a building will score higher but is not a guarantee of efficiency depending on the shape and heights of surrounding obstacles (Note the blue buildings towards the shape edges in the screenshot above). For example if there is a convex hill on the edge of the shape (see below), the best site will not be on the summit but far from it, looking towards the slope with enough perspective to see it all.

Best Site Analysis on ATAK

Layer management

On the TAK server the administrator can review and delete layers from the Enterprise Sync page.

If you create lots of area coverage plots and need to hide or share some, you can manage them on the EUD using the ATAK layers menu. The actual coverage layer is listed as an image overlay and the placemark is a File overlay.

Other TAK interfaces

WinTAK

Works OK with WinTAK 4.5 to 4.7 with the exception of embedded media in description balloons.

iTAK

Very limited functionality. Bot can be tasked but KML support is not ready for this.

WebTAK

Very limited functionality. Bot can be tasked but KML support is not ready for this.

Private server

SOOTHSAYER is available as a self-hosted server for offline and private networks. The server can be licensed for n users and includes the API, user interfaces and works with your own LiDAR and clutter. For more information email support@cloudrf.com