Skip to main content

​
Service Architecture

FreeTAKServer implements a modular service architecture where each service runs independently and communicates through a central integration manager. All services extend the DigitalPyService base class from the DigitalPy framework.

​
Available Services

​
TCP CoT Service

The TCP CoT Service handles unencrypted Cursor on Target traffic over TCP connections. Implementation: FreeTAKServer/services/tcp_cot_service/
Main Class: TCPCoTServiceMain
# FreeTAKServer/services/tcp_cot_service/tcp_cot_service_main.py:73
class TCPCoTServiceMain(DigitalPyService):
    """Service responsible for handling CoT listener for XML"""
    
    def __init__(
        self,
        service_id,
        subject_address,
        subject_port,
        subject_protocol,
        integration_manager_address,
        integration_manager_port,
        integration_manager_protocol,
        formatter: Formatter,
    ):
        super().__init__(
            service_id,
            subject_address,
            subject_port,
            subject_protocol,
            integration_manager_address,
            integration_manager_port,
            integration_manager_protocol,
            formatter
        )
  • Protocol: TCP/IP without encryption
  • Port: Default 8087
  • Format: XML-based CoT messages
  • Use Case: Development, testing, local networks
  • Multi-threaded: Concurrent client handling via thread pools
Located in FreeTAKServer/services/tcp_cot_service/controllers/:
  • TCPSocketController: Manages TCP socket creation and binding
  • ReceiveConnections: Accepts incoming client connections
  • ClientConnectionController: Handles new client setup
  • ClientReceptionHandler: Receives data from connected clients
  • SendDataController: Sends CoT messages to clients
  • ClientDisconnectionController: Handles client disconnection cleanup
  • SendComponentDataController: Sends data from component processing

​
SSL CoT Service

The SSL CoT Service provides encrypted CoT traffic using SSL/TLS certificates. Implementation: FreeTAKServer/services/ssl_cot_service/
Main Class: SSLCoTServiceControllerFeatures:
  • SSL/TLS encrypted connections
  • X.509 certificate authentication
  • Default port: 8089
  • Client certificate validation
FTS uses the AtakOfTheCerts utility for certificate generation:
from FreeTAKServer.core.util.certificate_generation import AtakOfTheCerts

# Certificate operations:
# - Generate CA certificates
# - Create server certificates
# - Generate client certificates
# - Sign certificates with CA
Certificate Locations:
  • CA Certificate: certs/ca.pem
  • Server Certificate: certs/server.pem
  • Client Certificates: certs/clients/{username}.pem
  • Mutual TLS: Both server and client authentication
  • Certificate Validation: Verify client certificates against CA
  • Encrypted Transport: All CoT data encrypted in transit
  • Certificate Revocation: Support for certificate blacklisting

​
REST API Service

The REST API Service provides a web-based interface for CoT manipulation, system management, and integration. Implementation: FreeTAKServer/services/rest_api_service/
Main Class: RestAPIServiceMainFramework: Flask with SocketIO
# FreeTAKServer/services/rest_api_service/rest_api_service_main.py
app = Flask(__name__)
CORS(app)
socketio = SocketIO(app, async_handlers=True, async_mode="eventlet")
socketio.init_app(app, cors_allowed_origins="*")
Ports:
  • HTTP: Default 19023
  • WebSocket: Same port as HTTP
The REST API is organized into blueprints:Core Endpoints:
  • /ManagePresence - Position/presence management
  • /ManageEmergency - Emergency alerts
  • /ManageGeoObject - Geographic objects (markers, shapes)
  • /ManageRoute - Route planning
  • /ManageChat - Chat messages
  • /VideoStream - Video stream management
  • /Sensor - Sensor data
  • /ExCheck - Checklist management
System Endpoints:
  • /APIUser - User authentication
  • /ManageConnection - Connection management
  • /Health - Health checks
Real-time updates via Socket.IO:
// Client connection
const socket = io('http://server:19023');

// Subscribe to CoT events
socket.emit('subscribe', {type: 'presence'});

// Receive updates
socket.on('cotEvent', (data) => {
    console.log('New CoT:', data);
});
Event Types:
  • cotEvent - New CoT message
  • presence - Position updates
  • chat - Chat messages
  • emergency - Emergency alerts
Methods:
  • Session-based: Flask-Login sessions
  • Token-based: API key authentication
  • Certificate-based: Client certificate validation
# FreeTAKServer/services/rest_api_service/controllers/authentication.py
from flask_login import LoginManager, login_required

@app.route('/protected')
@login_required
def protected_endpoint():
    return jsonify({'status': 'authenticated'})

​
HTTP TAK API Service

Implements the TAK server HTTP API for compatibility with TAK clients. Implementation: FreeTAKServer/services/http_tak_api_service/
Main Class: HTTPTakAPIPurpose: Provides TAK-compatible HTTP endpoints for:
  • Mission package synchronization
  • Data package upload/download
  • Video stream metadata
  • CoT query API
Port: Default 8080
Marti API Compatibility:
  • GET /Marti/api/sync/metadata/{hash} - Get package metadata
  • GET /Marti/api/sync/content - Download package
  • PUT /Marti/api/sync/upload - Upload data package
  • GET /Marti/api/missions - List missions
  • GET /Marti/api/missions/{name} - Get mission details
  • POST /Marti/api/missions/{name}/changes - Submit mission changes
# Upload data package
PUT /Marti/api/sync/upload
Content-Type: multipart/form-data

# Response includes:
{
    "hash": "abc123...",
    "sizeInBytes": 524288,
    "submissionTime": "2024-03-04T12:00:00.000Z"
}

# Download via hash
GET /Marti/api/sync/content?hash=abc123...

​
HTTPS TAK API Service

Secure version of the HTTP TAK API Service with SSL/TLS encryption. Implementation: FreeTAKServer/services/https_tak_api_service/
Main Class: HTTPSTakAPIFeatures:
  • All HTTP TAK API endpoints over HTTPS
  • Certificate-based client authentication
  • Encrypted data package transfers
Port: Default 8443
# SSL context configuration
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ssl_context.load_cert_chain(
    certfile='certs/server.pem',
    keyfile='certs/server.key'
)
ssl_context.load_verify_locations('certs/ca.pem')
ssl_context.verify_mode = ssl.CERT_REQUIRED

​
Service Communication

​
Integration Manager Pattern

Services communicate through a central integration manager using ZeroMQ:

​
Message Flow

# Service sends to integration manager
request = ObjectFactory.get_new_instance("request")
request.set_value("cot_event", event)
request.set_action("ProcessCoT")

# Integration manager routes to components
self.integration_manager.send(request)

# Components process and respond
response = self.integration_manager.receive()

# Service receives processed result
processed_event = response.get_value("processed_cot")

​
Service Lifecycle

​
Initialization

# FreeTAKServer/controllers/services/FTS.py
class FTS(DigitalPy):
    def __init__(self):
        super().__init__()
        
        # Initialize services
        self.SSLCoTService = None
        self.CoTService = None
        self.TCPDataPackageService = None
        self.RestAPIService = None
        
    def start_services(self):
        # Start TCP CoT Service
        self.CoTService = TCPCoTServiceMain(
            service_id="tcp_cot_service",
            subject_address=config.CoTIPAddress,
            subject_port=config.CoTServicePort,
            ...
        )
        self.CoTService.start()
        
        # Start SSL CoT Service
        self.SSLCoTService = SSLCoTServiceController(
            service_id="ssl_cot_service",
            ...
        )
        self.SSLCoTService.start()
        
        # Start REST API
        self.RestAPIService.start()

​
Shutdown

def stop_services(self):
    # Graceful shutdown
    self.CoTService.stop()
    self.SSLCoTService.stop()
    self.RestAPIService.stop()
    
    # Wait for threads to finish
    self.CoTService.join()
    self.SSLCoTService.join()
    self.RestAPIService.join()

​
Service Configuration

​
Configuration File

Services are configured via config.ini: 
[CoTService]
ip = 0.0.0.0
port = 8087

[SSLCoTService]
ip = 0.0.0.0
port = 8089
certfile = /opt/fts/certs/server.pem
keyfile = /opt/fts/certs/server.key
cafile = /opt/fts/certs/ca.pem

[RestAPI]
ip = 0.0.0.0
port = 19023
secret_key = your-secret-key-here

[HTTPTakAPI]
ip = 0.0.0.0
http_port = 8080
https_port = 8443

​
Environment Variables

Override configuration with environment variables: 
export FTS_COT_PORT=8087
export FTS_SSL_COT_PORT=8089
export FTS_API_PORT=19023
export FTS_MAINPATH=/opt/fts

​
Performance Considerations

​
Thread Pool Configuration

# Adjust thread pool sizes based on load
from multiprocessing.pool import ThreadPool

# Connection handling pool
connection_pool = ThreadPool(processes=50)

# Message processing pool
processing_pool = ThreadPool(processes=20)

​
Connection Limits

Monitor concurrent connections and adjust system limits:
# Increase file descriptor limit
ulimit -n 4096

# Configure in systemd service
[Service]
LimitNOFILE=4096

​
Database Connection Pooling

# SQLAlchemy connection pool
from sqlalchemy import create_engine

engine = create_engine(
    connection_string,
    pool_size=20,
    max_overflow=40,
    pool_recycle=3600
)

​
Monitoring and Health Checks

​
Health Check Endpoint

# REST API health check
GET /Health

Response:
{
    "status": "healthy",
    "services": {
        "tcp_cot": "running",
        "ssl_cot": "running",
        "rest_api": "running"
    },
    "connections": 42,
    "uptime": 86400
}

​
Telemetry

from opentelemetry.trace import Status, StatusCode
from digitalpy.core.telemetry.tracer import Tracer

# Service metrics
tracer = Tracer("tcp_cot_service")

with tracer.start_span("process_cot") as span:
    span.set_attribute("cot.type", cot_type)
    span.set_attribute("client.id", client_id)
    # Process message
    span.set_status(Status(StatusCode.OK))

​
Troubleshooting

​
Common Issues

# Find process using port
sudo lsof -i :8087

# Kill process
sudo kill -9 <PID>

# Or change port in config.ini

# Regenerate certificates
cd /opt/fts
python -m FreeTAKServer.controllers.certificate_generation

# Verify certificate validity
openssl x509 -in certs/server.pem -text -noout

# Check database connectivity
from FreeTAKServer.core.persistence.DatabaseController import DatabaseController

db = DatabaseController()
if db.test_connection():
    print("Database OK")
else:
    print("Database connection failed")
  • Reduce thread pool sizes
  • Enable database connection pooling
  • Implement message rate limiting
  • Monitor for memory leaks in custom components

Architecture

Understand FTS architecture

Components

Explore the component system

Configuration

Configure FTS services

API Reference

REST API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us