CoT Messages

Understanding Cursor on Target (CoT) message format, structure, and processing in FreeTAKServer

What is Cursor on Target (CoT)?

Cursor on Target (CoT) is an XML-based data format used for real-time situational awareness and command-and-control applications. It provides a standardized way to represent position, status, and other tactical information.

CoT Message Structure

Basic XML Format

A CoT message consists of three main elements: event, point, and detail.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<event version="2.0" 
       uid="Linux-ABC.server-ping" 
       type="b-t-f" 
       time="2020-02-14T20:32:31.444Z" 
       start="2020-02-14T20:32:31.444Z" 
       stale="2020-02-15T20:32:31.444Z" 
       how="h-g-i-g-o">
    <point lat="34.5" lon="-117.2" hae="100.0" ce="10.0" le="5.0"/>
    <detail>
        <contact callsign="ALPHA-1"/>
        <remarks>This is a sample CoT message</remarks>
    </detail>
</event>

Event Element

The root element containing metadata about the tactical event.

version · string · required

Schema version of the CoT message (typically “2.0”)

uid · string · required

Globally unique identifier for this event. Format varies by event type.

type · string · required

Hierarchical CoT type string (e.g., “a-f-G-E-S” for friendly ground equipment)

Format: a-{attitude}-{dimension}-{function}-{specific}

• a: Atom (basic entity)
• attitude: f (friendly), h (hostile), n (neutral), u (unknown)
• dimension: G (ground), A (air), S (surface), U (subsurface), P (space)
• function: E (equipment), U (unit), I (installation), etc.

time · datetime · required

Timestamp when the event was generated (ISO 8601 format with Zulu time)

Format: YYYY-MM-DDTHH:MM:SS.fffZ

start · datetime · required

Timestamp when the event becomes valid

stale · datetime · required

Timestamp when the event should be considered expired

Default: 60 seconds after generation time

how · string · required

How the coordinates were generated

Common values:

• h-g-i-g-o: Human-generated, GPS, observed
• m-g: Machine-generated, GPS
• h-e: Human-entered

access · string

Access control restrictions for this event

Point Element

Defines the geographic location of the event.

<point lat="34.5" lon="-117.2" hae="100.0" ce="10.0" le="5.0"/>

lat · float · required

Latitude in decimal degrees (WGS 84 ellipsoid)

Range: -90.0 to 90.0

lon · float · required

Longitude in decimal degrees (WGS 84 ellipsoid)

Range: -180.0 to 180.0

hae · float · required

Height Above Ellipsoid in meters

ce · float · required

Circular Error (horizontal accuracy) in meters

95% confidence that position is within CE radius

le · float · required

Linear Error (vertical accuracy) in meters

95% confidence that altitude is within LE range

Detail Element

Contains additional information about the event. The detail element is extensible and can contain various sub-elements based on the event type.

<detail>
    <contact callsign="ALPHA-1" endpoint="*:-1:stcp"/>
    <__group name="Red" role="Team Member"/>
    <takv platform="ATAK-CIV" version="4.5.1.13"/>
    <track speed="5.5" course="270.0"/>
    <remarks>Additional information</remarks>
</detail>

Common Detail Sub-elements

contact

Contact information for the entity

Attributes:

• callsign: Display name
• endpoint: Network endpoint information

__group

Group/team membership information

Attributes:

• name: Group/team name
• role: Role within the group

takv

TAK client version information

Attributes:

• platform: Platform type (ATAK-CIV, WinTAK, iTAK)
• version: Client version number

track

Movement information

Attributes:

• speed: Speed in meters per second
• course: Direction of travel in degrees (0-360)

link

Relationship to other CoT entities

Attributes:

• uid: UID of linked entity
• relation: Relationship type
• type: CoT type of linked entity

remarks

Free-form text remarks or notes

marti

Data package and file transfer information

Sub-elements:

• dest: Destination callsigns for the package

emergency

Emergency alert information

Attributes:

• type: Emergency type (911 Alert, Ring The Bell, etc.)

CoT Type Hierarchy

Type String Format

CoT types use a hierarchical dot-separated format:

atom-attitude-dimension-function-specific-[...]

Common CoT Types

Positions

Type	Description
a-f-G-E-S	Friendly ground equipment (static)
a-f-G-E-V-C	Friendly ground vehicle - combat
a-f-A-C	Friendly aircraft - civilian
a-f-A-M-F	Friendly aircraft - military fixed wing
a-h-G-U-C	Hostile ground unit - combat
a-n-G	Neutral ground entity

Messages

Type	Description
b-t-f	TAK server ping/pong
b-m-p-s-p-loc	Geochat message
b-m-p-c	Chat message (point to point)
b-r-f-h-c	Route
b-i-v	Video stream

Special

Type	Description
t-x-c-t	Connection request
t-x-d-d	Disconnect
b-a-o-tbl	Drawing objects (polygon, line, etc)
b-m-r	Mission package

FTS CoT Domain Model

Event Class

The core CoT event implementation in FTS:

# FreeTAKServer/components/core/domain/domain/_event.py
class Event(CoTNode):
    """Root CoT event object"""
    
    @CoTProperty
    def uid(self):
        return self.cot_attributes.get("uid", None)
    
    @uid.setter
    def uid(self, uid):
        if uid == None:
            self.uid = str(uuid.uuid1())
        else:
            self.cot_attributes["uid"] = uid
    
    @CoTProperty
    def type(self):
        return self.cot_attributes.get("type", None)
    
    @CoTProperty
    def point(self):
        return self.cot_attributes.get("point", None)
    
    @CoTProperty
    def detail(self):
        return self.cot_attributes.get("detail", None)

Point Class

# FreeTAKServer/components/core/domain/domain/_point.py
class point(CoTNode):
    """Geographic point representation"""
    
    def __init__(self, configuration, model, le=None, ce=None, 
                 hae=None, lon=None, lat=None):
        super().__init__(self.__class__.__name__, configuration, model)
        self.cot_attributes["le"] = le    # Linear Error
        self.cot_attributes["ce"] = ce    # Circular Error
        self.cot_attributes["hae"] = hae  # Height Above Ellipsoid
        self.cot_attributes["lon"] = lon  # Longitude
        self.cot_attributes["lat"] = lat  # Latitude

Detail Class

# FreeTAKServer/components/core/domain/domain/_detail.py
class detail(CoTNode):
    """Optional element for CoT sub-schema"""
    
    @CoTProperty
    def contact(self):
        return self.cot_attributes.get("contact", None)
    
    @CoTProperty
    def marti(self):
        return self.cot_attributes.get("marti", None)
    
    @CoTProperty
    def link(self):
        return self.cot_attributes.get("link", None)
    
    @CoTProperty
    def mission(self):
        return self.cot_attributes.get("mission", None)

CoT Message Processing

Parsing Pipeline

XML to Domain Object

FTS converts XML to domain objects using a multi-step process:

# FreeTAKServer/core/parsers/XMLCoTController.py:64-100
def determineCoTGeneral(self, data, client_information_queue):
    # Parse XML string
    event = etree.fromstring(data.xmlString)
    
    # Convert XML to dictionary
    request.set_action("XMLToDict")
    request.set_value("message", data.xmlString)
    actionmapper.process_action(request, response)
    data_dict = response.get_value("dict")
    
    # Convert machine-readable type to human-readable
    request.set_action("ConvertMachineReadableToHumanReadable")
    request.set_value("machine_readable_type", data_dict["event"]["@type"])
    actionmapper.process_action(request, response)
    human_type = response.get_value("human_readable_type")
    
    # Route to appropriate handler based on type
    return (human_type, data)

Type Mapping

FTS maintains mappings between machine-readable and human-readable CoT types:

Machine-Readable → Human-Readable

• a-f-G-E-S → “FriendlyGroundEquipment”
• b-m-p-s-p-loc → “GeoChat”
• b-t-f → “Ping”
• a-f-G-E-V-C → “FriendlyGroundVehicle”

This allows routing to specific component handlers.

Serialization

Domain Object to XML

# FreeTAKServer/components/core/domain/controllers/serialization/xml_serialization/xml_serializer.py
class XmlSerializer(SerializerAbstract):
    def serialize_model_to_CoT(self, modelObject, tagName="event", level=0):
        # Convert type back to machine-readable
        if modelObject.__class__.__name__ == "Event":
            request.set_action("ConvertHumanReadableToMachineReadable")
            request.set_value("human_readable_type", modelObject.type)
            modelObject.type = response.get_value("machine_readable_type")
        
        # Create XML element
        xml = Element(tagName)
        
        # Add attributes from CoT properties
        for attribName in modelObject.get_properties():
            value = getattr(modelObject, attribName)
            if hasattr(value, "__dict__"):
                # Nested object - recurse
                tagElement = self.serialize_model_to_CoT(value, attribName)
                xml.append(tagElement)
            else:
                # Simple attribute
                xml.set(attribName, str(value))
        
        return xml

Common CoT Message Examples

Presence/Position Update

<event version="2.0" uid="ANDROID-deadbeef" type="a-f-G-E-S" 
       time="2024-03-04T12:00:00.000Z" 
       start="2024-03-04T12:00:00.000Z" 
       stale="2024-03-04T12:01:00.000Z" 
       how="m-g">
    <point lat="34.5" lon="-117.2" hae="100.0" ce="10.0" le="5.0"/>
    <detail>
        <contact callsign="ALPHA-1" endpoint="*:-1:stcp"/>
        <__group name="Red" role="Team Member"/>
        <takv platform="ATAK-CIV" version="4.5.1.13"/>
        <track speed="5.5" course="270.0"/>
    </detail>
</event>

GeoChat Message

<event version="2.0" uid="GeoChat.ANDROID-deadbeef.All Chat Rooms.abc123" 
       type="b-t-f" 
       time="2024-03-04T12:00:00.000Z" 
       start="2024-03-04T12:00:00.000Z" 
       stale="2024-03-04T12:10:00.000Z" 
       how="h-e">
    <point lat="0.0" lon="0.0" hae="0.0" ce="9999999.0" le="9999999.0"/>
    <detail>
        <__chat id="All Chat Rooms" chatroom="All Chat Rooms" 
                groupOwner="false" messageId="abc123" 
                senderCallsign="ALPHA-1">
            <chatgrp uid0="ANDROID-deadbeef" uid1="All Chat Rooms" id="All Chat Rooms"/>
        </__chat>
        <link uid="ANDROID-deadbeef" type="a-f-G-E-S" relation="p-p"/>
        <remarks source="BAO.F.ATAK.ANDROID-deadbeef" 
                 time="2024-03-04T12:00:00.000Z">
            Hello from ALPHA-1
        </remarks>
    </detail>
</event>

Emergency Alert

<event version="2.0" uid="ANDROID-deadbeef" type="b-a-o-tbl" 
       time="2024-03-04T12:00:00.000Z" 
       start="2024-03-04T12:00:00.000Z" 
       stale="2024-03-04T12:10:00.000Z" 
       how="h-e">
    <point lat="34.5" lon="-117.2" hae="100.0" ce="10.0" le="5.0"/>
    <detail>
        <contact callsign="ALPHA-1"/>
        <emergency type="911 Alert" cancel="false"/>
        <link uid="ANDROID-deadbeef" type="a-f-G-E-S" relation="p-p"/>
    </detail>
</event>

Data Package

<event version="2.0" uid="package-abc123" type="b-m-r" 
       time="2024-03-04T12:00:00.000Z" 
       start="2024-03-04T12:00:00.000Z" 
       stale="2024-03-04T13:00:00.000Z" 
       how="h-e">
    <point lat="0.0" lon="0.0" hae="0.0" ce="9999999.0" le="9999999.0"/>
    <detail>
        <fileshare filename="image.jpg" senderUrl="https://server:8080/Marti/api/sync/content?hash=abc123" 
                   sizeInBytes="524288" sha256="abc123..." 
                   senderUid="ANDROID-deadbeef" senderCallsign="ALPHA-1" 
                   name="image.jpg"/>
        <ackrequest uid="package-abc123" ackrequested="true" tag="package-abc123"/>
        <marti>
            <dest callsign="BRAVO-1"/>
        </marti>
    </detail>
</event>

Special Considerations

Time Handling

All timestamps must be in ISO 8601 format with Zulu (UTC) time: YYYY-MM-DDTHH:MM:SS.fffZ

Default stale time is 60 seconds after generation.

UID Format

UIDs should be globally unique. Common patterns:

• Position updates: {platform}-{device-id} (e.g., ANDROID-deadbeef)
• GeoChat: GeoChat.{sender-uid}.{chatroom}.{message-id}
• Server events: {hostname}.server-ping

Coordinate System

All coordinates use WGS 84 ellipsoid:

• Latitude: -90° to 90° (negative = south)
• Longitude: -180° to 180° (negative = west)
• HAE: Height above WGS 84 ellipsoid in meters

Related Documentation

Architecture

Understand FTS architecture

Services

Learn about FTS services

Components

Explore the component system

API Reference

REST API documentation