DOCSEARCHbyAlgolia
Submit Docs

PyTAK

repository·main·Indexed 42 days ago

https://github.com/snstac/pytak

A Python library and CLI tool for building Team Awareness Kit (TAK) clients, servers, and gateways. It enables sending and receiving Cursor on Target (CoT) data across various transports including TCP, TLS, UDP, WebSockets, MQTT, and the Marti REST API. PyTAK supports TAK Protocol v0 (XML) and v1 (Protobuf), automatic enrollment via tak:// URLs, and provides a QueueWorker pattern for implementing custom CoT senders.

Tokens
23.8K
Snippets
84
Records
106
Agent score
51%

What's inside PyTAK

  1. PyTAK Features and Protocol Support

    main

    PyTAK provides several core capabilities for TAK integration:

    Protocol Support

    • TAK Protocol v0: XML-based.
    • TAK Protocol v1: Protobuf-based (requires takproto extra).

    Transport Options

    Supports multiple transport layers including:

    • TCP and TLS
    • UDP (unicast, multicast/Mesh SA, and broadcast)
    • File and stdout
    • WebSockets

    Connectivity and Enrollment

    • TAK Enrollment: Automatic certificate enrollment via tak:// URLs.
    • Marti REST API: Send/receive CoT via marti:// URL schemes.
    • Data Packages: Import .zip preference packages containing server settings and certificates.
    • TLS Authentication: Supports PEM certificates, PKCS#12 (.p12), and password-protected keys.

  2. PyTAK Gateway Clients and Integrations

    main

    PyTAK serves as the core engine for various CoT (Cursor on Target) and TAK (Team Awareness Kit) gateways. It is used to transform diverse data streams into TAK-compatible messages. Common integrations include:

    • ADS-B (Aircraft Tracking):
      • airtak: A purpose-built field-deployable device for ADS-B to TAK.
      • adsbcot: Transforms over-the-air ADS-B position messages to TAK.
      • adsbxcot: Transforms ADS-B Exchange (Internet aggregator) position messages to TAK.
      • stratuxcot: Transforms Stratux receiver ADS-B position messages to TAK.
    • Marine (AIS):
      • aiscot: Transforms marine AIS position messages to TAK.
    • Radio & Satellite (Positioning):
      • aprscot: Transforms amateur radio APRS position messages to TAK.
      • spotcot: Transforms Globalstar SPOT satellite position messages to TAK.
      • inrcot: Transforms Garmin inReach satellite position messages to TAK.
    • Communication Apps:
      • zellocot: Transforms ZelloWork user locations to TAK.

  3. Understand the output layout of `pytak dp`

    main

    When running pytak dp for a user named myuser, the default output structure in the data-packages/myuser/ directory is:

    • certs/myuser.p12: Client identity (key + cert + CA chain)
    • certs/myuser.pem: Client certificate PEM
    • certs/myuser-key.pem: Private key PEM
    • certs/myuser-ca.pem: CA chain PEM
    • certs/myuser-trust.p12: CA-only trust store
    • myuser-atak-connection.zip: Connection package for ATAK/CivTAK
    • myuser-itak-connection.zip: Connection package for iTAK

    Usage: Import the ATAK ZIP into ATAK (or CivTAK) and the iTAK ZIP into iTAK. The PKCS#12 passwords for the bundles inside the ZIPs are identical; use the -v flag during enrollment to see the generated password.

  4. Install the 'cryptography' dependency for PyTAK

    main

    PyTAK requires the cryptography package for certificate and PEM file handling. If it is not installed, you will receive a warning and cryptographic functions will fail. Install it using the following command:

    python3 -m pip install pytak[with-crypto]
    python3 -m pip install pytak[with-crypto]

  5. Automatically enroll a client certificate from TAK Server

    main

    PyTAK can automatically handle the full CSR → PKCS#12 enrollment flow using your TAK account credentials. This is useful for automated deployments.

    Requirements: Install the necessary extras: pip install pytak[with_aiohttp,with_crypto]

    Behavior: After the first successful enrollment, the certificate is cached in ~/.pytak/certs/. PyTAK will automatically re-enroll when the certificate is within 7 days of expiry.

  6. Troubleshoot CoT events not appearing in TAK

    main

    If your Cursor on Target (CoT) events are not showing up in your TAK client, follow these steps in order:

    1. Verify CoT generation: Ensure PyTAK is actually producing XML. Set COT_URL=log://stdout to print CoT XML to the console. If it prints, the issue is network/configuration related.
    2. Bypass TAK Server: Test connectivity by connecting directly to an EUD (ATAK/iTAK/WinTAK) on the same network using a tcp:// URL.
    3. Check Multicast: If using udp:// (Mesh SA), ensure your network hardware supports multicast. If in doubt, switch to tcp:// or udp+wo:// to rule out multicast issues.
    4. Enable Debugging: Run with DEBUG=1 to see connection errors or dropped packets.
    # Verify CoT is being generated
COT_URL=log://stdout python3 send.py

# Enable debug logging
DEBUG=1 python3 send.py

# Connect directly to an EUD (example)
# COT_URL = tcp://192.168.1.50:4242

  7. Windows-specific PyTAK troubleshooting

    main

    UDP Multicast Issues

    Windows restricts how multicast sockets bind. If udp:// fails, try:

    • Using udp+wo:// (write-only) instead of udp://.
    • Using tcp:// or tls:// instead.

    Setting Environment Variables in PowerShell

    Use the $env: prefix to set variables in a PowerShell session:

    $env:COT_URL = "tcp://takserver.example.com:8087"
$env:DEBUG = "1"
$env:PYTAK_TLS_CLIENT_PASSWORD = "atakatak"

# To check a variable:
$env:COT_URL

  10. Handle `Enter PEM pass phrase:` prompt

    main

    This prompt occurs when your private key is password-protected. You can resolve this in three ways:

    1. Set the password in config (Recommended): Use the PYTAK_TLS_CLIENT_PASSWORD setting.
    2. Remove the passphrase from the key: Use OpenSSL to create a new key without a passphrase and point PYTAK_TLS_CLIENT_KEY to it.
    3. Manual entry: Accept the prompt and enter the password every time PyTAK starts.
    # Option 1: Set password in config
PYTAK_TLS_CLIENT_PASSWORD = atakatak
    # Option 2: Remove passphrase from key
openssl rsa -in pytak.key -out pytak.nopass.key

  11. Use TAK enrollment deep-link URLs (`tak://`)

    main

    PyTAK supports TAK enrollment deep-links (similar to ATAK QR-code onboarding). This requires pytak[with_aiohttp] and pytak[with_crypto].

    Format: tak://com.atakmap.app/enroll?host=<host>&username=<user>&token=<secret>

    Usage via COT_URL:

    COT_URL = tak://com.atakmap.app/enroll?host=takserver.example.com&username=myuser&token=mytoken

    Usage via CLI:

    pytak "tak://com.atakmap.app/enroll?host=takserver.example.com&username=myuser&token=mytoken"

    What PyTAK does:

    1. Parses host, username, and token.
    2. Checks ~/.pytak/certs/ for a valid cached certificate.
    3. If none exists, performs a full CSR → PKCS#12 enrollment against the TAK Server.
    4. Caches the certificate and passphrase to disk.
    5. Automatically sets COT_URL to wss://<host>:8443/takproto/1 (or a custom port if provided in host=) and configures TLS.

    Certificates are re-enrolled automatically when within 7 days of expiry.

    Export onboarding packages

    To enroll and write PKCS#12/PEM files and connection data packages without connecting to the server, use the dp subcommand:

    pytak dp 'tak://com.atakmap.app/enroll?host=takserver.example.com&username=myuser&token=mytoken'

  12. Pull PyTAK Docker images

    main

    PyTAK publishes two types of container images to GHCR based on the package format. Use the :latest tag for stable releases or specify a specific <tag> for version pinning.

    • ghcr.io/snstac/pytak-deb:<tag>: Installs PyTAK from the .deb package.
    • ghcr.io/snstac/pytak-rpm:<tag>: Installs PyTAK from the .rpm package.
    docker pull ghcr.io/snstac/pytak-deb:<tag>
docker pull ghcr.io/snstac/pytak-rpm:<tag>