| Name | jtak JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | TAK client |
| upload_time | 2025-01-04 23:57:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.10 |
| 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 |
| keywords |
atak
cot
cursor on target
tak
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "jtak",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": "ATAK, CoT, Cursor on Target, TAK",
"author": null,
"author_email": "Jeff Mattson <jmattson@sei.cmu.edu>",
"download_url": "https://files.pythonhosted.org/packages/b6/6d/4f17d56f1e01867d468d386de15a1406ba749e769914866b83fa45cab4da/jtak-1.0.0.tar.gz",
"platform": null,
"description": "# JTAK\nA [TAK](https://tak.gov) client.\n\nJTAK provides a full-featured TAK client with multiple\ninput/outputs, Tak Protocol negotiation, state persistence\nof discovered atoms and chat groups, and concise configuration.\n\nWritten in Python, it serves well for quick experimentation\nand integration in a variety of environments.\n\n> Note: You probably don't need to clone this repo. See [Integration](#integration)\n\n## Install\n\n```\npip install jtak\n```\n\n## Run\n\n```\njtak_example\n```\n\n## Configuration\n\nThe example runs \"out-of-the-box\", but you'll likely want to\ncustomize the configuration. A single configuration object holds\nuser and worker information.\n\nBy default you'll get a random `uid` each time, so setting that\nis important if you plan to send cot messages. A `callsign` is\nhelpful as well.\n\nIf you don't specify any workers, you'll get the default set:\n```py\n[\n WorkerConf(\"udp://239.2.3.1:6969\"),\n WorkerConf(\"udp://224.10.10.1:17012\"),\n WorkerConf(\"tcp://0.0.0.0:4242\")\n]\n```\n\nIf you do specify any workers, you'll need to specify *all* the\ndesired workers; consider adding the default workers in\naddition to your others. Also note the `enabled` flag so you don't\nhave to delete them to make changes...you can\nmaintain a list of workers and disable any with that flag.\n\n```py\nClientConf(\n user=UserConf(\n uid=\"some-unique-id-1234567890\",\n callsign=\"ENDER\"\n ),\n workers=[\n WorkerConf(\n url=\"tls://192.168.1.99:8089\",\n tls_hostname=\"tak.local\",\n tls_p12_path=\"cyan.p12\",\n tls_p12_password=\"atakatak\"\n ),\n WorkerConf(\"stcp://192.168.1.99:8088\", enabled=False)\n ],\n sa_interval=30\n)\n```\n\n### ClientConf\nField | Default | Notes\n----- | ------- | -----\nuser | default | see UserConf\nworkers | default | see WorkerConf\nsa_interval | 30.0 | send device beacon at this interval (0 for no beacon)\n\n### UserConf\nField | Default | Notes\n----- | ------- | -----\nuid | \"jtak-{random}\" | unique and persistent user id\ncallsign | \"\" | ATAK display name\ncot_type | \"a-f-G\" | ATAK marker type\nteam | \"Cyan\" |\nrole | \"Team Member\" |\nlat | 0.0 | initial latitude\nlon | 0.0 | initial longitude\nhae | 0.0 | initial altitude\n\n### WorkerConf\nField | Default | Notes\n----- | ------- | -----\nurl | \"\" | scheme://host:port\nenabled | True | ignore if False\nlegacy | False | force tak proto 0 (legacy)\nusername | \"\" | tak server creds\npassword | \"\" | tak server creds\nlocal_ip | \"\" | local ip or adapter name; if blank, uses first of wifi, eth, lo\ntx_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))\nmesh_ttl | 1 | time-to-live for multicast transmissions\nmesh_mode | \"rw\" | A mesh worker can be read, write or both\ntls | default | see TLSConfig\n\n### TLSConf\nField | Default | Notes\n----- | ------- | -----\nhostname | \"\" | tls server hostname for certificate verification (helpful when url specifies ip address or different name than in server certificate)\nciphers | \"ALL\" | use to filter tls ciphers\np12_path | \"\" | path to client certificate p12 file\np12_password | \"atakatak\" | password to client certificate p12 file (Hopefully you have to specify this! :joy:)\nskip_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:)\n\n## Integration\n\n`jtak` implements the core messaging protocol, but unless you just\nwant to watch message traffic in a terminal, you will want to write\na wrapper for it.\n\nIn your own project, inherit `TakClient` and implement the desired abstract methods.\n\n```py\nimport jtak\n\nclass MyTakClient(jtak.TakClient):\n\n def sa_cot(self, endpoint: str):\n # Override this if you want a custom SA message.\n # Otherwise just keep self.me updated and SA messages are sent.\n # see `jtak.cot.default_sa_cot` as an example\n cot = ...\n return cot\n\n async def _inbound_handler(cot: CotEvent):\n # Override this if your inbound consumer wants something\n # other than a protobuf CotEvent message.\n\n # do something with cot\n # state is available in self.state if needed\n # returned objects are enqueued for an inbound bridge consumer\n return model\n\n async def outbound(self, model):\n # Override this if your outbound provider doesn't\n # produce COT messages.\n\n # convert the model into cot message(s)\n # or process model (ie. update self.me) and return None\n # returned cot messages are enqueued for outbound transmission\n return super().outbound(messages)\n```\n\n## Runner\n\n```\n TakClient\n \u250c --------------- \u2510\n ----> | outbound(model) | tx ----->\nRunner/Bridge | | Network\n <---- | inbound() | rx <-----\n \u2514 --------------- \u2518\n```\n\nA Runner is an application you write that instantiates a TakClient\nand runs it, as well as provides some means of pushing and pulling\nmessages.\n\nSee `jtak_example.py` for a simple runner. It simply runs the TakClient\nwith a logging level to see activity; it doesn't process messages.\n\nIf your data generation or processing integrates nicely with asyncio\ntasks, you can likely simply extend `jtak_example.py`.\n\nHowever, if data generation or processing is more complex or running in\na different process or application, you may need to implement a\nbridge. A bridge might itself send and receive messages\nbetween it and another application or process by various means\nlike message queues.\n\n## Contributing\nWe are happy to support any community of interest that grows around jtak.\nHowever, we are (overly) opinionated, so it's a good idea to run an idea by us before putting significant effort into a PR.\n\nAnd really, jtak shouldn't change too much. Specific use cases can inherit from jtak to add cool custom functionality.\n\n## Development\n\nAs 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.\n\nInternally, `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.\n\nOutbound 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).\n\nIn short `jtak` prefers to construct messages as XML and process messages as protobuf.\n\n## Acknowledgements\n\nInspired by the great work at https://github.com/snstac.\n",
"bugtrack_url": null,
"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",
"summary": "TAK client",
"version": "1.0.0",
"project_urls": {
"Issues": "https://github.com/cmu-sei/jtak/issues",
"Repository": "https://github.com/cmu-sei/jtak"
},
"split_keywords": [
"atak",
" cot",
" cursor on target",
" tak"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0545738c663dd7653a4e71c547e45a4ad46abd80f8e541ff567fad36ae87f6b3",
"md5": "cb240ee2960232b7bb950ba8b393129a",
"sha256": "7774ea2bdca8d37a82f2c3a020577755759c243153a6d9cbc0b3aed645df8ee7"
},
"downloads": -1,
"filename": "jtak-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cb240ee2960232b7bb950ba8b393129a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 48096,
"upload_time": "2025-01-04T23:57:22",
"upload_time_iso_8601": "2025-01-04T23:57:22.877572Z",
"url": "https://files.pythonhosted.org/packages/05/45/738c663dd7653a4e71c547e45a4ad46abd80f8e541ff567fad36ae87f6b3/jtak-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b66d4f17d56f1e01867d468d386de15a1406ba749e769914866b83fa45cab4da",
"md5": "3dee29968d84c5dbcff06515e281dcf0",
"sha256": "77e864031923fe35f2c58127e63b719b89ca01634ab1df8058a66f80193cfc95"
},
"downloads": -1,
"filename": "jtak-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3dee29968d84c5dbcff06515e281dcf0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 28728,
"upload_time": "2025-01-04T23:57:24",
"upload_time_iso_8601": "2025-01-04T23:57:24.328413Z",
"url": "https://files.pythonhosted.org/packages/b6/6d/4f17d56f1e01867d468d386de15a1406ba749e769914866b83fa45cab4da/jtak-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-04 23:57:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cmu-sei",
"github_project": "jtak",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jtak"
}
