| Name | cotdantic JSON |
| Version |
2.1.0
JSON |
| download |
| home_page | None |
| Summary | Pythonic coursor-on-target xml/protobuf generation using pydantic |
| upload_time | 2024-12-08 02:06:24 |
| maintainer | Raub Camaioni |
| docs_url | None |
| author | Raub Camaioni |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 Raub Camaioni 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. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
cot
coursor
target
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# COT(PY)DANTIC
Pythonic generation of Coursor-On-Target (COT) messages (xml/protobuf).
Provides pydantic_xml models with type completion and verification.
Easy transformation between xml and protobuf.
Human readable cot type construction.
## COT/TAK Resources
[takproto](https://takproto.readthedocs.io/en/latest): Encoding of XML to protobuf
[pydantic_xml](https://pydantic-xml.readthedocs.io/en/latest/): Python pydantic models to XML
[pytak](https://pytak.readthedocs.io/en/latest/examples/): Wealth of COT/TAK format information
[cot_types](https://github.com/dB-SPL/cot-types): Cot type to human readable mapping
[MIL STD 2525](http://everyspec.com/MIL-STD/MIL-STD-2000-2999/MIL-STD-2525B_CHG-2_20725/#:~:text=These%20symbols%20are%20designed%20to%20enhance%20DOD%60s%20joint%20warfighting%20interoperability): cot type symbols
[tak.gov](https://tak.gov/): Governing body of ATAK, Wintak, and other TAK based protocols
[dev_guide](https://nps.edu/documents/104517539/109705106/COT+Developer+Guide.pdf/cb125ac8-1ed1-477b-a914-7557c356a303#:~:text=What%20is%20Cursor-on-Target?%20In%20a%20nutshell,): developer outline of COT messages
[tak_miter](https://www.mitre.org/sites/default/files/pdf/09_4937.pdf): in-depth cot descriptions
## COTDANTIC CLI Tool
This package includes a curses cli tool.
Situational Awareness (SA) messages are printed in the main window.
Contacts are listed in the contacts window.
Chat messages are listed in the chat window, messages are automatically echoed back to sender.
Select window with left, right, arrow keys.
Scroll window with up, down, arrow keys.
Scroll to end with backspace key.
Default gateway interface used by default.
```
cotdantic --help
usage: cotdantic [-h] [--maddress MADDRESS] [--mport MPORT] [--minterface MINTERFACE] [--gaddress GADDRESS] [--gport GPORT] [--ginterface GINTERFACE] [--address ADDRESS] [--interface INTERFACE] [--uport UPORT]
[--tport TPORT] [--debug DEBUG] [--unicast {tcp,udp}]
options:
-h, --help show this help message and exit
--maddress MADDRESS SA address (default: 239.2.3.1)
--mport MPORT SA port (default: 6969)
--minterface MINTERFACE
SA interface (default: default-gateway)
--gaddress GADDRESS Chat address (default: 224.10.10.1)
--gport GPORT Chat port (default: 17012)
--ginterface GINTERFACE
Chat interface (default: default-gateway)
--address ADDRESS default TCP/UDP send address (default: default-gateway)
--interface INTERFACE
TCP/UDP bind interface (default: default-gateway)
--uport UPORT TCP port (default: 17012)
--tport TPORT UDP port (default: 4242)
--debug DEBUG Print debug information (default: False)
--unicast {tcp,udp} Endpoint protocol (default: tcp)
```
A docker build is included for multicast docker testing.
For multicast to reach inside a docker network=host must be set.
## COT Construction
Object based creation of COT.
Common fields have default values.
Optional fields are excluded from XML/Protobuf.
Creation of COT python model
```python
from cotdantic import *
from uuid import uuid4
uid = str(uuid4())
cot_type = str(atom.friend.ground.unit.combat.infantry)
point = Point(lat=38.711, lon=-77.147, hae=10, ce=5.0, le=10.0)
contact = Contact(callsign='Delta1', endpoint='192.168.0.100:4242:tcp')
group = Group(name='Cyan', role='Team Member')
detail = Detail(contact=contact, group=group)
cot_model = Event(
uid=uid,
type=cot_type,
point=point,
detail=detail,
)
```
COT Model
```python
type='a-f-G-U-C-I' point=Point(lat=38.711, lon=-77.147, hae=10.0, le=10.0, ce=5.0) version=2.0 uid='c56af374-52f6-4c8a-bd1d-8f48e7ebb21b' how='m-g' time='2024-10-12T20:42:31.12Z' start='2024-10-12T20:42:31.12Z' stale='2024-10-12T20:47:31.12Z' qos=None opex=None access=None detail=Detail(contact=Contact(callsign='Delta1', endpoint='192.168.0.100:4242:tcp', phone=None), takv=None, group=Group(name='Cyan', role='Team Member'), status=None, track=None, precision_location=None, link=[], alias=None, image=None, video=None)
```
## COT Conversion
COT XML
```python
# pretty print requires lxml dependency
xml_b: bytes = cot_model.to_xml(pretty_print=True)
xml_s: str = xml_b.decode()
```
```xml
<event type="a-f-G-U-C-I" version="2.0" uid="c56af374-52f6-4c8a-bd1d-8f48e7ebb21b" how="m-g" time="2024-10-12T20:42:31.12Z" start="2024-10-12T20:42:31.12Z" stale="2024-10-12T20:47:31.12Z">
<point lat="38.711" lon="-77.147" hae="10.0" le="10.0" ce="5.0"/>
<detail>
<contact callsign="Delta1" endpoint="192.168.0.100:4242:tcp"/>
<__group name="Cyan" role="Team Member"/>
</detail>
</event>
```
COT PROTOBUF
```python
proto = bytes(cot_model)
```
```python
b'\xbf\x01\xbf\x12\xb3\x01\n\x0ba-f-G-U-C-I*$c56af374-52f6-4c8a-bd1d-8f48e7ebb21b0\xd0\xde\xdf\x93\xa828\xd0\xde\xdf\x93\xa82@\xb0\x86\xf2\x93\xa82J\x03m-gQ^\xbaI\x0c\x02[C@Y\xc5 \xb0rhIS\xc0a\x00\x00\x00\x00\x00\x00$@i\x00\x00\x00\x00\x00\x00\x14@q\x00\x00\x00\x00\x00\x00$@z7\x12 \n\x16192.168.0.100:4242:tcp\x12\x06Delta1\x1a\x13\n\x04Cyan\x12\x0bTeam Member'
```
## Custom Detail Extension
The below handles custom detail tags.
```python
from pydantic_xml import attr, element
from typing import Optional
from cotdantic import *
class CustomElement(CotBase, tag='target_description'):
hair_color: str = attr()
eye_color: str = attr()
class CustomDetail(Detail):
description: Optional[CustomElement] = element(default=None)
class CustomEvent(EventBase[CustomDetail]):
pass
```
Same usage schema for xml and protobuf.
See tests for more details.
```python
custom_event = CustomEvent(...)
xml = custom_event.to_xml()
proto = bytes(custom_event)
CustomEvent.from_bytes(proto)
```
Alternativly, if the extention is simplistic, the following can be used to add custom detail elements.
The below raw_xml will be added to the protobuf and XML.
```
detail = Detail()
detail.raw_xml = b"<target_description hair_color="red" eye_color="brown"/>"
```
## Raw XML
The protobuf xml detail string is stored in Detail.raw_xml.
The raw_xml field contains all the XML tags not defined by the model.
These tags are added back when encoded to protobuf or XML.
## Cot Types
Development of the available cot types is not comprehensive.
Eventually all cot types should be accessable from the following type-completing syntax.
```python
from cotdantic import atom
print(atom.friend.ground.unit.combat.infantry)
```
```
a-f-G-U-C-I
```
Raw data
{
"_id": null,
"home_page": null,
"name": "cotdantic",
"maintainer": "Raub Camaioni",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cot, coursor, target",
"author": "Raub Camaioni",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a4/dc/d1c38753ab53859afb476708eebc55571c92942904d3c59d3aca6da5b4ca/cotdantic-2.1.0.tar.gz",
"platform": null,
"description": "# COT(PY)DANTIC\n\nPythonic generation of Coursor-On-Target (COT) messages (xml/protobuf). \nProvides pydantic_xml models with type completion and verification. \nEasy transformation between xml and protobuf. \nHuman readable cot type construction. \n\n## COT/TAK Resources\n\n[takproto](https://takproto.readthedocs.io/en/latest): Encoding of XML to protobuf \n[pydantic_xml](https://pydantic-xml.readthedocs.io/en/latest/): Python pydantic models to XML \n[pytak](https://pytak.readthedocs.io/en/latest/examples/): Wealth of COT/TAK format information \n[cot_types](https://github.com/dB-SPL/cot-types): Cot type to human readable mapping \n[MIL STD 2525](http://everyspec.com/MIL-STD/MIL-STD-2000-2999/MIL-STD-2525B_CHG-2_20725/#:~:text=These%20symbols%20are%20designed%20to%20enhance%20DOD%60s%20joint%20warfighting%20interoperability): cot type symbols \n[tak.gov](https://tak.gov/): Governing body of ATAK, Wintak, and other TAK based protocols \n[dev_guide](https://nps.edu/documents/104517539/109705106/COT+Developer+Guide.pdf/cb125ac8-1ed1-477b-a914-7557c356a303#:~:text=What%20is%20Cursor-on-Target?%20In%20a%20nutshell,): developer outline of COT messages \n[tak_miter](https://www.mitre.org/sites/default/files/pdf/09_4937.pdf): in-depth cot descriptions \n\n## COTDANTIC CLI Tool\n\nThis package includes a curses cli tool. \nSituational Awareness (SA) messages are printed in the main window. \nContacts are listed in the contacts window. \nChat messages are listed in the chat window, messages are automatically echoed back to sender. \nSelect window with left, right, arrow keys. \nScroll window with up, down, arrow keys. \nScroll to end with backspace key. \nDefault gateway interface used by default. \n```\ncotdantic --help\nusage: cotdantic [-h] [--maddress MADDRESS] [--mport MPORT] [--minterface MINTERFACE] [--gaddress GADDRESS] [--gport GPORT] [--ginterface GINTERFACE] [--address ADDRESS] [--interface INTERFACE] [--uport UPORT]\n [--tport TPORT] [--debug DEBUG] [--unicast {tcp,udp}]\n\noptions:\n -h, --help show this help message and exit\n --maddress MADDRESS SA address (default: 239.2.3.1)\n --mport MPORT SA port (default: 6969)\n --minterface MINTERFACE\n SA interface (default: default-gateway)\n --gaddress GADDRESS Chat address (default: 224.10.10.1)\n --gport GPORT Chat port (default: 17012)\n --ginterface GINTERFACE\n Chat interface (default: default-gateway)\n --address ADDRESS default TCP/UDP send address (default: default-gateway)\n --interface INTERFACE\n TCP/UDP bind interface (default: default-gateway)\n --uport UPORT TCP port (default: 17012)\n --tport TPORT UDP port (default: 4242)\n --debug DEBUG Print debug information (default: False)\n --unicast {tcp,udp} Endpoint protocol (default: tcp)\n```\n\n\n\nA docker build is included for multicast docker testing. \nFor multicast to reach inside a docker network=host must be set. \n\n## COT Construction\n\nObject based creation of COT. \nCommon fields have default values. \nOptional fields are excluded from XML/Protobuf. \n\nCreation of COT python model \n```python\nfrom cotdantic import *\nfrom uuid import uuid4\n\nuid = str(uuid4())\ncot_type = str(atom.friend.ground.unit.combat.infantry)\n\npoint = Point(lat=38.711, lon=-77.147, hae=10, ce=5.0, le=10.0)\ncontact = Contact(callsign='Delta1', endpoint='192.168.0.100:4242:tcp')\ngroup = Group(name='Cyan', role='Team Member')\ndetail = Detail(contact=contact, group=group)\ncot_model = Event(\n\tuid=uid,\n\ttype=cot_type,\n\tpoint=point,\n\tdetail=detail,\n)\n```\nCOT Model \n```python\ntype='a-f-G-U-C-I' point=Point(lat=38.711, lon=-77.147, hae=10.0, le=10.0, ce=5.0) version=2.0 uid='c56af374-52f6-4c8a-bd1d-8f48e7ebb21b' how='m-g' time='2024-10-12T20:42:31.12Z' start='2024-10-12T20:42:31.12Z' stale='2024-10-12T20:47:31.12Z' qos=None opex=None access=None detail=Detail(contact=Contact(callsign='Delta1', endpoint='192.168.0.100:4242:tcp', phone=None), takv=None, group=Group(name='Cyan', role='Team Member'), status=None, track=None, precision_location=None, link=[], alias=None, image=None, video=None)\n```\n\n## COT Conversion\nCOT XML \n```python\n# pretty print requires lxml dependency\nxml_b: bytes = cot_model.to_xml(pretty_print=True)\nxml_s: str = xml_b.decode()\n```\n```xml\n<event type=\"a-f-G-U-C-I\" version=\"2.0\" uid=\"c56af374-52f6-4c8a-bd1d-8f48e7ebb21b\" how=\"m-g\" time=\"2024-10-12T20:42:31.12Z\" start=\"2024-10-12T20:42:31.12Z\" stale=\"2024-10-12T20:47:31.12Z\">\n <point lat=\"38.711\" lon=\"-77.147\" hae=\"10.0\" le=\"10.0\" ce=\"5.0\"/>\n <detail>\n <contact callsign=\"Delta1\" endpoint=\"192.168.0.100:4242:tcp\"/>\n <__group name=\"Cyan\" role=\"Team Member\"/>\n </detail>\n</event>\n```\nCOT PROTOBUF \n```python\nproto = bytes(cot_model)\n```\n```python\nb'\\xbf\\x01\\xbf\\x12\\xb3\\x01\\n\\x0ba-f-G-U-C-I*$c56af374-52f6-4c8a-bd1d-8f48e7ebb21b0\\xd0\\xde\\xdf\\x93\\xa828\\xd0\\xde\\xdf\\x93\\xa82@\\xb0\\x86\\xf2\\x93\\xa82J\\x03m-gQ^\\xbaI\\x0c\\x02[C@Y\\xc5 \\xb0rhIS\\xc0a\\x00\\x00\\x00\\x00\\x00\\x00$@i\\x00\\x00\\x00\\x00\\x00\\x00\\x14@q\\x00\\x00\\x00\\x00\\x00\\x00$@z7\\x12 \\n\\x16192.168.0.100:4242:tcp\\x12\\x06Delta1\\x1a\\x13\\n\\x04Cyan\\x12\\x0bTeam Member'\n```\n\n## Custom Detail Extension\n\nThe below handles custom detail tags. \n```python\nfrom pydantic_xml import attr, element\nfrom typing import Optional\nfrom cotdantic import *\n\n\nclass CustomElement(CotBase, tag='target_description'):\n\thair_color: str = attr()\n\teye_color: str = attr()\n\n\nclass CustomDetail(Detail):\n\tdescription: Optional[CustomElement] = element(default=None)\n\n\nclass CustomEvent(EventBase[CustomDetail]):\n\tpass\n\n```\nSame usage schema for xml and protobuf. \nSee tests for more details. \n```python\ncustom_event = CustomEvent(...)\nxml = custom_event.to_xml()\nproto = bytes(custom_event)\nCustomEvent.from_bytes(proto)\n```\n\nAlternativly, if the extention is simplistic, the following can be used to add custom detail elements. \nThe below raw_xml will be added to the protobuf and XML. \n```\ndetail = Detail()\ndetail.raw_xml = b\"<target_description hair_color=\"red\" eye_color=\"brown\"/>\"\n```\n\n## Raw XML\nThe protobuf xml detail string is stored in Detail.raw_xml. \nThe raw_xml field contains all the XML tags not defined by the model. \nThese tags are added back when encoded to protobuf or XML. \n\n\n## Cot Types\n\nDevelopment of the available cot types is not comprehensive. \nEventually all cot types should be accessable from the following type-completing syntax. \n```python\nfrom cotdantic import atom\nprint(atom.friend.ground.unit.combat.infantry)\n```\n```\na-f-G-U-C-I\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Raub Camaioni 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. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Pythonic coursor-on-target xml/protobuf generation using pydantic",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/RaubCamaioni/cotdantic"
},
"split_keywords": [
"cot",
" coursor",
" target"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1754cb3f06d99f5aa13757e8e4a0dab7909e00ee119ce8f92d29ef98feec0820",
"md5": "7c5661eb1c22f333f73a82d4bd1c9b39",
"sha256": "28a9c5518f511d48f94ec1382f8073ef6a2994d73dad53c8ea51b490b2b65d6c"
},
"downloads": -1,
"filename": "cotdantic-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c5661eb1c22f333f73a82d4bd1c9b39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22603,
"upload_time": "2024-12-08T02:06:22",
"upload_time_iso_8601": "2024-12-08T02:06:22.237712Z",
"url": "https://files.pythonhosted.org/packages/17/54/cb3f06d99f5aa13757e8e4a0dab7909e00ee119ce8f92d29ef98feec0820/cotdantic-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a4dcd1c38753ab53859afb476708eebc55571c92942904d3c59d3aca6da5b4ca",
"md5": "c35ed7cb134f2d28a30a68b602164668",
"sha256": "95ff78406b7a5540c6034e905a6fe4362c43034bd4cf6c3159d753c7c96684ef"
},
"downloads": -1,
"filename": "cotdantic-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c35ed7cb134f2d28a30a68b602164668",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24462,
"upload_time": "2024-12-08T02:06:24",
"upload_time_iso_8601": "2024-12-08T02:06:24.208738Z",
"url": "https://files.pythonhosted.org/packages/a4/dc/d1c38753ab53859afb476708eebc55571c92942904d3c59d3aca6da5b4ca/cotdantic-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 02:06:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RaubCamaioni",
"github_project": "cotdantic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cotdantic"
}
