Posted on

How not to write a TAK plugin

ATAK

Team Awareness Kit (TAK) has become the poster-child for defence innovation, transforming mapping, command and control and situational awareness with a relatively lightweight smartphone app. Never in the history of defence procurement have so many forces, nations and equipment vendors achieved tactical interoperability with impressive results.

Key to it’s success is a permissive software license, APIs and a design focused on information standards.

TL;DR Just give me the interface

Login to your CloudRF account and click the green “TAK server” button. Watch this video for the setup.

Documentation is here.

Background: Too many maps

Historically defence procurement has failed to differentiate between standards (eg. KML) and software (eg. Google Earth) resulting in many duplicate apps, especially multi-source maps solving the shortcomings of the previous multi-source map, which is the military implementation of the famous too-many-standards XKCD sketch. The revolving door of senior officers into defence companies didn’t help the situation. This reached a fever pitch during operations in Afghanistan 2006-2014 where at one point, every service, nation and prime contractor were plugging their own “multi-source” map, all of which were trying to solve the same problem, and all of which compounded it. Analysts were motivated to write glue-ware to achieve interoperability, typically with visual basic due to the locked down environment.

In our experience, the enduring military map was none of the above, it was good old Google Earth which could be found at all command levels due to its simplicity and assured interoperability via KML and HTML standards.

ATAK has disrupted a long established pattern of short sighted procurement of incompatible point solutions – which was long overdue and best of all, the IPR is not owned and controlled by a single contractor.

The TAK plugin industry

Some plugins are better than others

TAK is produced and owned by the US Government. Despite most of the client source code being available on the Play store and elsewhere a documented SDK for plugin developers, plugins require US Government approval. This approval is more than a bureaucratic hurdle, it is a security, technical and cryptographic approval which requires a code-review and a code signing certificate. There are a limited number of public domain signed plugins and a greater number of private plugins.

Given the cultural change of not just using open source in defence, but publishing and maintaining it, on public app stores it was inevitable there would be a catch to appease committees.

To get US Government approval requires a sponsor aka a contract. There are many firms large and small developing TAK plugins (typically with Java or Kotlin) under contract, including foreign nations under trade agreements. Whilst Android app development might sound a little 2010 (CloudRF started as a Android app in 2011) it’s made lucrative by the exclusivity of needing a Government sponsor – to publish at least.

2010 called, they want Java back..

RFSignal for Android (2011)

Java has had its day in our opinion. It created a generation of software developers who exist in a (JVM) bubble of abstraction far away from the processor for whom an opcode is an alien concept and writing a Hello world! demo on a vanilla machine requires a disproportionate amount of IDE massaging and preparation. The effort used to be justifiable because of the security the Java sandbox brings. The recent log4j CVE undid that argument pretty well.

We used Java 10 years ago to make our debut app “RFSignal” during the app gold rush of 2011 along with the Android SDK. It worked well for the first few releases whilst the app was under active development but the cracks showed when the app transitioned to maintenance. We found the “Eclipse” dev environment itself to be a substantial burden and even small one-line changes required an inordinate amount of effort in many places compared with other languages like Python, PHP or C++. Back then Android was evolving rapidly and keeping up with the latest SDK was a task in itself so we were glad to retire the app in 2015 and move to a SaaS model (and not give Google 30% of our sales).

We vowed no more Java, and to date have kept our promise except we did reference 1 line from the old app relating to a PNG hack to achieve Android bitmap opacity which was funny – ten years later.

To be clear we’re not criticising ATAK plugins written in Java – there is a clear need or them, especially interfaces to hardware which is a great value-add for manufacturers. We are proposing a more agile plugin architecture based around standard and network APIs which doesn’t prescribe a programming language – or even an OS.

ATAK source code: https://github.com/deptofdefense/AndroidTacticalAssaultKit-CIV

Standards to the rescue

Standards > software

We came late to ATAK in late 2020 but were no strangers to information standards, reverse engineering and joining distinct systems, at no extra cost, which our founder had previously won a national award for in 2012.

We already had a Google Earth layer (written in PHP) which relied heavily on the KML standard to connect CloudRF to Google Earth. We attempted the same on ATAK 4.1 without success due to limited KML GroundOverlay support back then. We could load on some layer types with a 10 second minimum refresh but advanced network features such as KML’s view based Link were not implemented. We use this feature to fetch the viewer’s bounding box, and center point, in our Google Earth KML interface.

During our research we learnt about the Cursor-on-Target (CoT) XML schema and how it was implemented within ATAK’s Geochat functionality. This allowed us to close the loop and handle a chat message from a client at our own TAK server – without touching Java!! Being able to connect the client to our own server was significant, and exciting, as this is where we could house, and maintain, our code instead of a version-brittle plugin.

An open source TAK server….with a Python bot

Realising we needed a TAK server capable of talking CoT we headed to Github and found two open source projects, FreeTakServer and Taky, both written in Python. We tried both and selected the simpler Taky server which offered a minimal setup necessary for 2 way communication.

You can find an early ATAK capability we published for OSGB coordinates conversion bot over here.

One of the nice features about SaaS models is licensing. You can connect software modules via a common protocol with different licenses. This is why we open sourced our server modifications but kept our Python bot private. You can get a head-start for how to build a bot with our open source geobot.

TAKY setup

We forked Taky and added some features relating to client authentication, access control, anonymity and CoT. The CoT modification is notable as it extends the namespace (which is permitted in the XML standard) to tag anonymous messages with the originator’s unique ID. These modified messages are exchanged between the chatbot and the server when sharing shapes and are redundant for regular C2 use.

You can fetch our modifications from our branch: https://github.com/Cloud-RF/taky

‘Follow-me’ demo

This early demo was created with a GPS spoofer (visible in corner). When the position updates, ATAK sends a broadcast which our TAKY server receives. The python bot at the server forwards this to the API and a creates a KML layer – a standard feature in CloudRF. On ATAK, a network KML layer pulls back the KML on a periodic cycle which is why it is slow to catch up when the marker moves fast. We have since identified a mechanism to return a KMZ immediately using a data package.

SSL, HTTPS and Data packages

Achieving insecure communication was quick: We published a demo of a CoT + KML script which did this in Nov 2020. Achieving secure communication with TLS certificates, which worked on ATAK and for HTTPS was a different matter and required lots of debugging. A lot of time was spent resolving seemingly trivial issues but the key principle we found which unlocked a lot of happenings was adding the right SAN (SubjectAltName) to our web server certificates.

SAN is used as an optional field in SSL certificates to declare alternative names or IP addresses, and is checked by Android’s SSL client. The open source TAK servers would wrap a script called ROTC.py to generate certificates (without SAN) using a self-signed certificate authority (CA) which despite the manageable security risk involved works well for securing the ATAK server – and even mutual authentication which we have implemented.

When ATAK later makes a request to a HTTPS link to fetch a data package for example, it checks the certificate for a SAN which a third party certificate from a trusted CA typically has. This tiny little attribute is worth big money as they can add lots in an array and call it a “wildcard” certificate. Thankfully LetsEncrypt is disrupting this monopoly.

Data packages are zip archives used in TAK to share files. They require a manifest file and a simple folder structure. When a CoT message is delivered to a End User Device (EUD) describing a data package it will fetch it, unpack it and auto-parse the content. We return KMZ files but you can also return XML map files to add map sources for example.

The CloudRF ATAK interface: Setup

If you have a CloudRF account you can jump in and use the ATAK chatbot. You will need to fetch your data package, side-load it and then authenticate to the chatbot to associate your Android device with your account.

Documentation: https://cloudrf.com/documentation/atak_interface

This video walks you through the setup and comms test:

Using clutter profiles

For more advanced use, you might want to change the regional clutter profile to match your area. This video shows you to do that:

Self hosted solution?

We have a turnkey server with the CloudRF API, OSM tile server and ATAK interface called SOOTHSAYER. It’s ideal for rescue organisations and first responders who might otherwise be running multiple network services or working areas without internet access.

It works on VMware and as of 1.2 can use SMB shares for cloud hypervisors like Proxmox and ESXi.

Need help?

We’re not precious about attribution if your account is in credit. RF modelling can be incredibly difficult so if you’re a silver or gold customer who is having trouble integrating the API into your TAK project, do the smart thing and get in touch. It may cost you some pride but you’ll achieve your goal much quicker as we’ve been doing this for 10 years.

API documentation: https://api.cloudrf.com

OpenAPI spec: https://cloudrf.com/documentation/developer/swagger-ui/

Posted on

Hosting your own network map

If you’re a wireless internet service provider or an organisation who want to show an online coverage map there are different options available depending on your level of skill. The basic option is to do this with an arbitrary polygon on a free map like Google maps but if you want a beautiful and accurate physics based coverage map, at no extra cost read on…

Embed code

The easiest way to add a map to your website or blog is with the embed code function. This is a small code (HTML) snippet which you paste into your website, like WordPress, for example. It requires that your blog supports HTML content.

To use this first you must have a layer in your archive. This could be a single area calculation or a large network mesh created from lots of individual calculations. Select it and click the code icon.

You will then be shown your embed code and a notice.

Google Maps Key

The notice says “Replace ‘GOOGLEMAPSKEY’ with your Google Maps key“. This is necessary as you need a key to share an online map as it’s licensed, not a free-for-all. You can get a key at no cost from Google if you visit this link:

https://developers.google.com/maps/documentation/javascript/get-api-key

To test your key works visit a HTML online editor, paste in your embed code and replace GOOGLEMAPSKEY with your long random Google Maps key. If successful you will see your map and your embed code is ready to go on your website!

Self-hosted (Expert mode)

The downside to embed code is the layer must be fetched from a server from Europe. For most users this won’t be a problem but if you are in Australia and your layer is quite large this could result in a blank map for a second or two – not a great advert if you are a business.

To deliver a faster map to your local customers, host the layer yourself. To do this, take the previously described embed code and extract the long link starting https://api.cloudrf.com/…

Paste that into a browser to visit the page directly then view the source code. Here you will find a link to a .png image in your archive as well as the necessary Google Maps Javascript.

Copy that code to your own website and download the PNG image. Upload the PNG image to your server and edit the link so it points to the local copy eg. yourcompany.com/files/yourlayer.png

Copy the code between the html tags.

Terms and attribution

You can host as many of these maps as you like for no extra cost but unless you have written permission, attribution is required. This is already included as a small link on the map but we won’t object if you want to add your own label too.

We will host your data so long as your account is in credit. If your account is not in credit we will retain the data as per the plan limit which is two years in most cases.

If you need your image to be available for lots of website visitors or for longer than 2 years, we strongly recommend self-hosting your PNG layers.

Posted on

API 2.0

CloudRF API

We have a new API.

This long awaited update brings an OpenAPI 3.0 compliant REST implementation with a redesign of public facing architecture so all requests will go to https://api.cloudrf.com and documentation will be at https://docs.cloudrf.com

Human readable requests

The old API grew into an exhaustive list of +43 variables starting from only 10 when it was an Android app. That’s just the public ones. There’s more parameters relating to interfaces. We were adding about a dozen variables a year in the early years of the service and turned down many requests for protocol-specific parameters to keep the number manageable and keep the API signal and technology agnostic.

The new JSON body schema tidies these +40 variables into logical objects which not only align with the interface but can be dropped completely for example in the case of the optional environment object, and defaults used.

New endpoints

The CloudRF API is now at api.cloudrf.com

Documentation is at docs.cloudrf.com

We’ve got OpenAPI / Swagger documentation at https://api.cloudrf.com/swagger-ui/

Legacy ../API/ endpoints and old API documentation are still active and will be until October 2021.

OpenAPI

New functions

Some previously undocumented interface features are now in the new API. These are exporting user files into GIS formats and uploading GeoJSON features as private clutter. These are now documented in API2.0

New authentication

The days of sending your unique identifier ‘uid’ and your API key in the HTTP request as uid=…key=… and then scrubbing them out of presentations are thankfully finished!!!

Now you have one API key which you must put into a HTTP ‘key’ header. This keeps your sensitive credentials separate from your body which contains site parameters. This also means the path to offline JSON templates is now clear. We’ve offered templates for years but as rows in a private database, now that the private bits are out of the way you can confidently share an API request.

JSON site templates

A nice feature about this new API is because the sensitive authentication parameters have been removed, and the entire site/antenna/environment exists as a single JSON object, you can take this away and share it, save it, reuse it, publish it. We’re going to build on this concept to offer a new style of template system so as well as saving your settings for quick reuse as you can now, you can share your settings.

This will also enable novice API users to create valid requests by fetching a template eg. “VHF radio.json” from the library and dropping it into an API client, along with their ‘key’ to run that template through their account.

Legacy API sunset 1st October 2021

The legacy API will still run in parallel and will be retired on the 1st October 2021. Please move your projects over to the new API soon and see our documentation and client code examples on Postman to do this.

We are publishing more application specific examples to assist with this and will be on hand to help customers migrate.