CoT / TAK Bridge

Bidirectional Cursor on Target translation for ATAK/iTAK interoperability.

What is CoT?

Cursor on Target (CoT) is an XML message schema developed by MITRE and the U.S. Air Force for sharing tactical events between heterogeneous systems. It defines a lightweight, extensible envelope for geospatial events — primarily used to report the position and status of friendly forces, enemy contacts, map marks, and other mission-relevant items.

CoT is the native protocol of the Team Awareness Kit (TAK) product family:

• ATAK — Android Team Awareness Kit, the most widely deployed TAK client
• iTAK — the iOS version of the TAK client
• WinTAK — the Windows desktop TAK client
• TAK Server — the enterprise server that federates multiple TAK clients and external systems

A CoT message consists of a root <event> element with attributes describing the event type (a dot-notation type string such as a-f-G-U-C for a friendly ground unit), timing (time, start, stale), and an entity UID. The <point> child element carries coordinates (latitude, longitude, altitude, circular error, linear error). Optional <detail> children carry application-specific data.

Bridge Architecture

The CoT Bridge runs as a standalone Docker container (groundwave-bridge) alongside the main GroundWave stack. It acts as a protocol translation layer between the CoT TCP world and GroundWave's JSON/Socket.IO world, with two active communication channels at all times:

• TCP server on port 4242 — accepts inbound connections from ATAK, iTAK, WinTAK, and other CoT-capable clients. Each TAK client connects as if the bridge were a TAK Server. The bridge reads CoT XML from these connections and writes CoT XML back to them.
• Socket.IO client — maintains a persistent WebSocket connection to groundwave-app on the internal Docker network. The bridge subscribes to GroundWave events (positions, markers, chat) and emits translated versions to TAK clients, and vice versa.

The bridge process itself is stateless — it holds no persistent database connection and no local state beyond active TCP sockets. All data persistence is handled by groundwave-app through its normal REST and Socket.IO interfaces.

Echo Prevention

Without echo prevention, a position reported by a TAK client would be relayed to GroundWave, which would broadcast it back to the bridge, which would relay it back to all TAK clients — creating an infinite loop. The bridge attaches a source: "cot-bridge" tag to every event it injects into GroundWave. Any event carrying this tag is not re-emitted to TAK clients, breaking the loop.

Supported Data Types

The following table describes the mapping between GroundWave event types and their CoT equivalents. Translation is bidirectional unless noted.

CoT type strings use a dot-separated hierarchy (the table above shows the base type with hyphens as used in the type attribute). The bridge uses fast-xml-parser for XML parsing and generation, providing robust handling of malformed input without crashing the bridge process.

Enabling the Bridge

The CoT Bridge container is activated via Docker Compose profiles. It does not start as part of the default stack. To include it, pass --profile bridge to any Compose command:

# Start the full stack including the CoT Bridge
docker compose --profile bridge up -d

# Stop everything including the bridge
docker compose --profile bridge down

If you use the bundled setup script, you can enable the profile by exporting it before running setup:

export COMPOSE_PROFILES=bridge
./setup.sh

The bridge container is configured with restart: unless-stopped and will automatically reconnect to both the GroundWave app server and any TAK clients that re-establish TCP connections after a restart.

TAK Client Configuration

Any CoT-compatible client can connect to the bridge using a standard TAK Server network configuration. The steps below apply to ATAK, but iTAK and WinTAK follow the same pattern:

1. Open Network Preferences

   In ATAK, go to Settings → Network Preferences → Manage Server Connections.

2. Add a new connection

   Tap the + button and choose "TAK Server."

3. Enter the connection details
   • Description: GroundWave (or any label)
   • Address: the IP address of your GroundWave server on the local network
   • Port: 4242
   • Protocol: TCP
   • Use SSL/TLS: Off (for local network deployments; TLS is not required between TAK clients and the bridge on a trusted LAN)
4. Save and connect

   ATAK will establish the TCP connection. Within a few seconds, GroundWave users should appear on the ATAK map, and ATAK users should appear in the GroundWave User Roster with a "CoT" indicator.

Translation Library

The core of the bridge is a pure translation library located at server/src/utils/cot/. This library has no external dependencies beyond fast-xml-parser and is independently testable without a running server.

The library provides the following modules:

• mapper.js — the primary mapping layer. Exports functions for converting each GroundWave event type to a CoT XML string, and for parsing inbound CoT XML into GroundWave-format JSON objects. Handles edge cases such as missing optional CoT fields and coordinates that fall outside valid WGS 84 bounds.
• types.js — constants mapping GroundWave entity types to CoT type strings and vice versa. Centralizes the type mapping table so changes only need to be made in one place.
• xml.js — thin wrapper around fast-xml-parser providing consistent parse options (attribute name prefix, array coercion) and an XML serialization helper that produces standards-compliant CoT output.

Data Type Filtering

Each direction of translation — GroundWave to CoT, and CoT to GroundWave — can be filtered independently. The bridge reads a comma-separated BRIDGE_DATA_TYPES environment variable and only translates event types listed there. The default is all supported types. To relay only positions and chat:

BRIDGE_DATA_TYPES=positions,chat

Limitations

The CoT Bridge provides deep interoperability for the core TAK use case — shared situational awareness — but there are inherent limitations arising from the differences between the two protocols:

• Voice (PTT) has no CoT equivalent. GroundWave's real-time PCM audio streaming and WebM/Opus recording have no counterpart in the CoT specification. TAK clients connected via the bridge cannot participate in GroundWave voice channels.
• Map overlays and file sharing are not bridged. CoT does not define a mechanism for transferring raster image overlays, GeoJSON/GPX layer files, or arbitrary file attachments. These features remain GroundWave-native only.
• Direct messages are not relayed. CoT GeoChat supports targeted messages but the addressing model differs from GroundWave's channel-based DMs. Only public channel messages are translated.
• CoT bridge is one-hop only. Data that arrives at GroundWave via a federation link from another GroundWave server is not re-emitted to TAK clients. The bridge translates between locally-connected GroundWave clients and locally-connected TAK clients only. Chaining federation and CoT in a single event path is not supported.
• TAK Server advanced features are not emulated. Mission packages, data sync, certificate enrollment, and TAK Server administrative APIs are outside the scope of the bridge. It implements the minimum CoT event relay needed for common operational use.