TCP CoT Service

The TCP CoT Service provides unencrypted TCP connections for receiving Cursor-on-Target (CoT) messages from ATAK clients and other TAK devices.

Overview

The TCP CoT Service (TCPCoTServiceMain) is responsible for handling CoT communications over standard TCP connections. It listens for incoming connections, processes CoT XML messages, and distributes them to connected clients. Default Port: 8087 Protocol: TCP (unencrypted) Message Format: XML (CoT)

Service Architecture

Main Class

FreeTAKServer.services.tcp_cot_service.tcp_cot_service_main.TCPCoTServiceMain The TCP CoT service extends DigitalPyService and manages:

Socket creation and binding
Connection reception
Client data handling
Message serialization and routing
Component response broadcasting

Key Components

Socket Controller

Class: TCPSocketController (tcp_cot_service_main.py:167) Creates and configures TCP sockets:

self.TCPSocketController = TCPSocketController()
self.TCPSocketController.changeIP(IP)
self.TCPSocketController.changePort(CoTPort)
sock = self.TCPSocketController.createSocket()

Connection Model

Class: TCPCoTConnection (model/tcp_cot_connection.py:12)

class TCPCoTConnection(Connection):
    def __init__(self, oid=None) -> None:
        super().__init__("tcp_cot_connection", oid)
        self._service_id = SERVICE_NAME
        self._protocol = XML
        self._model_object: Event = None
        self._sock: socket = None

Properties:

service_id: “tcp_cot_service”
protocol: “XML”
model_object: Event domain object
sock: TCP socket instance

Connection Handling

Receiving Connections

The service uses ReceiveConnections controller to accept new TCP connections (tcp_cot_service_main.py:178):

receiveConnection = pool.apply_async(ReceiveConnections().listen, (sock,))

Client Reception

Class: ClientReceptionHandler (tcp_cot_service_main.py:175) Handles data reception from connected clients:

clientData = pool.apply_async(
    ClientReceptionHandler().startup, (self.client_information_queue,)
)

Buffer Size: 1024 bytes (tcp_cot_service_constants.py:3)

Connection Flow

Socket Creation - TCP socket bound to configured IP and port
Listen for Connections - Service accepts incoming connections
Handle Connection - New connection processed via handle_connection() (tcp_cot_service_main.py:761)
Client Registration - Client information stored in client_information_queue
Data Reception - Messages received via ClientReceptionHandler
Message Processing - CoT XML parsed and routed to components

Message Processing

Main Run Function

Method: mainRunFunction() (tcp_cot_service_main.py:476) Central loop that:

Receives new connections
Handles client data
Processes shared data from other services
Broadcasts component responses

Data Handling

Regular Data

Method: handle_regular_data() (tcp_cot_service_main.py:705) Processes CoT messages from clients:

def handle_regular_data(self, clientDataOutput: List[RawCoT]):
    for data_object in clientDataOutput:
        if data_object.xmlString == b"":
            self.handle_disconnection(data_object.clientInformation)
            continue
        # Process the raw CoT data and serialize it
        self.component_handler(data_object.xmlString)

Component Handler

Method: component_handler() (tcp_cot_service_main.py:276) Routes CoT data to appropriate components:

Convert XML to dictionary: convert_xml_to_dict() (tcp_cot_service_main.py:416)
Get human-readable type: get_human_readable_type() (tcp_cot_service_main.py:438)
Create request with CoT data
Send to subject for component processing

Disconnection Handling

Method: handle_disconnection() (tcp_cot_service_main.py:742) Handles client disconnections:

def handle_disconnection(self, client_information):
    sock = self.client_disconnection_controller.get_sock(client_information)
    self.client_disconnection_controller.delete_client_connection(client_information)
    self.client_disconnection_controller.disconnect_socket(sock)
    connection_id = self.client_disconnection_controller.get_connection_id(client_information)
    iam_disconnect_request = self.client_disconnection_controller.create_iam_disconnect_request(connection_id)
    self.subject_send_request(iam_disconnect_request, APPLICATION_PROTOCOL)
    self.client_disconnection_controller.send_disconnect_cot(client_information)

Service Metrics

The service tracks operational metrics (tcp_cot_service_main.py:97-106):

self.connection_received = 0      # Total connections received
self.sent_message_count = 0       # Messages sent to clients
self.received_message_count = 0   # Messages received from clients
self.messages_to_core_count = 0   # Messages sent to core
self.messages_from_core_count = 0 # Messages received from core
self.openSockets = 0              # Currently open sockets

Monitoring

Method: monitor() (tcp_cot_service_main.py:806) Logs metrics every 15 seconds:

self.logger.debug(f"messages sent to clients in {logging_interval} seconds: {self.sent_message_count}")
self.logger.debug(f"messages received from clients in {logging_interval} seconds: {self.received_message_count}")
self.logger.debug(f"number of connected client: {str(len(self.connections.keys()))}")

Configuration

Service Constants

File: configuration/tcp_cot_service_constants.py

SERVICE_NAME = 'tcp_cot_service'
XML = 'XML'
DATA_RECEPTION_BUFFER_SIZE = 1024

Port Configuration

Default Port: 8087 (MainConfig.py:70)

"CoTServicePort": {"default": 8087, "type": int}

Usage

Starting the Service

tcp_service.start(
    IP=server_ip,
    CoTPort=8087,
    Event=event,
    clientDataPipe=client_pipe,
    ReceiveConnectionKillSwitch=kill_switch,
    RestAPIPipe=rest_pipe,
    clientDataRecvPipe=recv_pipe,
    factory=object_factory,
    tracing_provider_instance=tracer
)

Client Connection

ATAK clients can connect using: Protocol: TCP Port: 8087 Host: FreeTAKServer IP address Example connection string:

tcp://<server-ip>:8087

Threading Model

The service uses a ThreadPool for concurrent operations (tcp_cot_service_main.py:171):

pool = ThreadPool(processes=2)

Two main async tasks:

Connection Reception - Accepts new client connections
Client Data Handler - Receives data from connected clients

SSL CoT Service - Secure SSL/TLS CoT connections
CoT Message Format - CoT XML message structure

Connection Type

Property: connection_type (tcp_cot_service_main.py:194)

@property
def connection_type(self):
    return ConnectionTypes.TCP

Overview

REST API

TAK API

CoT Services

Overview

Service Architecture

Main Class

Key Components

Socket Controller

Connection Model

Connection Handling

Receiving Connections

Client Reception

Connection Flow

Message Processing

Main Run Function

Data Handling

Regular Data

Component Handler

Disconnection Handling

Service Metrics

Monitoring

Configuration

Service Constants

Port Configuration

Usage

Starting the Service

Client Connection

Threading Model

Connection Type

Build docs developers (and LLMs) love

Overview

REST API

TAK API

CoT Services

​Overview

​Service Architecture

​Main Class

​Key Components

​Socket Controller

​Connection Model

​Connection Handling

​Receiving Connections

​Client Reception

​Connection Flow

​Message Processing

​Main Run Function

​Data Handling

​Regular Data

​Component Handler

​Disconnection Handling

​Service Metrics

​Monitoring

​Configuration

​Service Constants

​Port Configuration

​Usage

​Starting the Service

​Client Connection

​Threading Model

​Related Services

​Connection Type

Build docs developers (and LLMs) love

Overview

Service Architecture

Main Class

Key Components

Socket Controller

Connection Model

Connection Handling

Receiving Connections

Client Reception

Connection Flow

Message Processing

Main Run Function

Data Handling

Regular Data

Component Handler

Disconnection Handling

Service Metrics

Monitoring

Configuration

Service Constants

Port Configuration

Usage

Starting the Service

Client Connection

Threading Model

Related Services

Connection Type