Metadata-Version: 2.4
Name: jtak
Version: 1.0.3
Summary: TAK client
Project-URL: Repository, https://github.com/cmu-sei/jtak
Project-URL: Issues, https://github.com/cmu-sei/jtak/issues
Author-email: Jeff Mattson <jmattson@sei.cmu.edu>
License: jtak
        
        Copyright 2025 Carnegie Mellon University.
        
        Licensed under a MIT (SEI)-style license, please see license.txt or contact permission@sei.cmu.edu for full terms.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        jtak includes and/or can make use of certain third party software ("Third Party Software"). The Third Party Software that is used by jtak is dependent upon your system configuration, but typically includes the software identified in this license.txt file, and/or described in the documentation and/or read me file. By using jtak, you agree to comply with any and all relevant Third Party Software terms and conditions contained in any such Third Party Software or separate license file distributed with such Third Party Software. The parties who own the Third Party Software ("Third Party Licensors") are intended third party beneficiaries to this License with respect to the terms applicable to their Third Party Software. Third Party Software licenses only apply to the Third Party Software and not any other portion of jtak or jtak as a whole.
        
        This material is based upon work funded and supported by the Department of Defense under Contract No. FA8702-15-D-0002 with Carnegie Mellon University for the operation of the Software Engineering Institute, a federally funded research and development center.
        
        The view, opinions, and/or findings contained in this material are those of the author(s) and should not be construed as an official Government position, policy, or decision, unless designated by other documentation.
        
        References herein to any specific entity, product, process, or service by trade name, trade mark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by Carnegie Mellon University or its Software Engineering Institute nor of Carnegie Mellon University - Software Engineering Institute by any such named or represented entity.
        
        NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING INSTITUTE MATERIAL IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT.
        
        [DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution.  Please see Copyright notice for non-US Government use and distribution.
        
        
        
        DM24-1629
License-File: LICENSE.md
Keywords: ATAK,CoT,Cursor on Target,TAK
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4,>=3.10
Requires-Dist: asyncio-dgram
Requires-Dist: cryptography
Requires-Dist: delimited-protobuf
Requires-Dist: protobuf>=5.29.0
Requires-Dist: psutil
Description-Content-Type: text/markdown

# JTAK
A [TAK](https://tak.gov) client.

JTAK provides a full-featured TAK client with multiple
input/outputs, Tak Protocol negotiation, state persistence
of discovered atoms and chat groups, and concise configuration.

Written in Python, it serves well for quick experimentation
and integration in a variety of environments.

> Note: You probably don't need to clone this repo. See [Integration](#integration)

## Install

```
pip install jtak
```

## Run

```
jtak_example
```

## Configuration

The example runs "out-of-the-box", but you'll likely want to
customize the configuration. A single configuration object holds
user and worker information.

By default you'll get a random `uid` each time, so setting that
is important if you plan to send cot messages. A `callsign` is
helpful as well.

If you don't specify any workers, you'll get the default set:
```py
[
    WorkerConf("udp://239.2.3.1:6969"),
    WorkerConf("udp://224.10.10.1:17012"),
    WorkerConf("tcp://0.0.0.0:4242")
]
```

If you do specify any workers, you'll need to specify *all* the
desired workers; consider adding the default workers in
addition to your others. Also note the `enabled` flag so you don't
have to delete them to make changes...you can
maintain a list of workers and disable any with that flag.

```py
ClientConf(
    user=UserConf(
        uid="some-unique-id-1234567890",
        callsign="ENDER"
    ),
    workers=[
        WorkerConf(
            url="tls://192.168.1.99:8089",
            tls_hostname="tak.local",
            tls_p12_path="cyan.p12",
            tls_p12_password="atakatak"
        ),
        WorkerConf("stcp://192.168.1.99:8088", enabled=False)
    ],
    sa_interval=30
)
```

### ClientConf
Field       | Default | Notes
-----       | ------- | -----
user        | default | see UserConf
workers     | default | see WorkerConf
sa_interval | 30.0    | send device beacon at this interval (0 for no beacon)

### UserConf
Field      | Default         | Notes
-----      | -------         | -----
uid        | "jtak-{random}" | unique and persistent user id
callsign   | ""              | ATAK display name
cot_type   | "a-f-G"         | ATAK marker type
team       | "Cyan"          |
role       | "Team Member"   |
lat        | 0.0             | initial latitude
lon        | 0.0             | initial longitude
hae        | 0.0             | initial altitude

### WorkerConf
Field     | Default | Notes
-----     | ------- | -----
url       | ""      | scheme://host:port (where scheme is "udp", "tcp", "tls")
enabled   | True    | ignore if False
legacy    | False   | force tak proto 0 (legacy)
username  | ""      | tak server creds
password  | ""      | tak server creds
local_ip  | ""      | local ip or adapter name; if blank, uses first of wifi, eth, lo
tx_delay  | 0.0     | some tak servers might require a slight delay between cot message (negative value produces random values between 0 and abs(tx_delay))
mesh_ttl  | 1       | time-to-live for multicast transmissions
mesh_mode | "rw"    | A mesh worker can be read, write or both
tls       | default | see TLSConfig

### TLSConf
Field             | Default    | Notes
-----             | -------    | -----
hostname          | ""         | tls server hostname for certificate verification (helpful when url specifies ip address or different name than in server certificate)
ciphers           | "ALL"      | use to filter tls ciphers
p12_path          | ""         | path to client certificate p12 file
p12_password      | "atakatak" | password to client certificate p12 file (Hopefully you have to specify this! :joy:)
skip_verification | False      | skip tak server certificate verification (Hopefully this is only enabled for testing! But you'll probably have to enable this because TakServer's certificate includes the CA certificate by default, which is frowned upon by verification tools. :grimace:)

## Integration

`jtak` implements the core messaging protocol, but unless you just
want to watch message traffic in a terminal, you will want to write
a wrapper for it.

In your own project, inherit `TakClient` and implement the desired abstract methods.

```py
import jtak

class MyTakClient(jtak.TakClient):

    def sa_cot(self, endpoint: str):
        # Override this if you want a custom SA message.
        # Otherwise just keep self.me updated and SA messages are sent.
        # see `jtak.cot.default_sa_cot` as an example
        cot = ...
        return cot

    async def _inbound_handler(cot: CotEvent):
        # Override this if your inbound consumer wants something
        # other than a protobuf CotEvent message.

        # do something with cot
        # state is available in self.state if needed
        # returned objects are enqueued for an inbound bridge consumer
        return model

    async def outbound(self, model):
        # Override this if your outbound provider doesn't
        # produce COT messages.

        # convert the model into cot message(s)
        # or process model (ie. update self.me) and return None
        # returned cot messages are enqueued for outbound transmission
        return super().outbound(messages)
```

## Runner

```
                    TakClient
                ┌ --------------- ┐
        ---->   | outbound(model) | tx ----->
Runner/Bridge   |                 |       Network
        <----   | inbound()       | rx <-----
                └ --------------- ┘
```

A Runner is an application you write that instantiates a TakClient
and runs it, as well as provides some means of pushing and pulling
messages.

See `jtak_example.py` for a simple runner. It simply runs the TakClient
with a logging level to see activity; it doesn't process messages.

If your data generation or processing integrates nicely with asyncio
tasks, you can likely simply extend `jtak_example.py`.

However, if data generation or processing is more complex or running in
a different process or application, you may need to implement a
bridge. A bridge might itself send and receive messages
between it and another application or process by various means
like message queues.

## Contributing
We are happy to support any community of interest that grows around jtak.
However, we are (overly) opinionated, so it's a good idea to run an idea by us before putting significant effort into a PR.

And really, jtak shouldn't change too much. Specific use cases can inherit from jtak to add cool custom functionality.

## Development

As mentioned earlier, COT messages can be structured as XML or Protobuf. Although XML is "legacy", it is required that all clients support XML for the time being.

Internally, `jtak` uses a mix of the two. Inbound messages are coverted to TakMessages (protobuf) regardless of how they are received. However, "non-standard" detail is included in an "xmlDetail" field, so even with TakMessage some xml processing may still be required.

Outbound messages are sent in accordance with the current tak protocol negotation; a client shouldn't send protobuf until its negotiation allows. However, `jtak` *generates* messages as XML (e.g. the default sa cot message).

In short `jtak` prefers to construct messages as XML and process messages as protobuf.

## Acknowledgements

Inspired by the great work at https://github.com/snstac.
