diff --git a/README.rst b/README.rst index c377b5f..b72977b 100644 --- a/README.rst +++ b/README.rst @@ -1,16 +1,11 @@ -.. image:: ./docs/pytak_logo-256x264.png - :alt: PyTAK Logo +![ATAK Screenshot with PyTAK Logo.](atak_screenshot_with_pytak_logo-x25.jpg) -takproto: TAK Protocol Python Module +TAKProto: TAK Protocol Python Module ************************************ -``takproto`` is a Python module to encode & decode TAK Protocol Cursor on Target (CoT) messages. +TAKProto is a Python module for encoding & decoding TAK Protocol Payloads, for use with `TAK Products `_ including ATAK, WinTAK, iTAK, TAKX, TAK Tracker & TAK Server. `takproto` includes functions for converting TAK Protocol Protobuf messages as Python objects, and serializing CoT XML messages as Protobuf. -Documentation -============= - -See `PyTAK documentation `_ for instructions on getting -started with PyTAK, examples, configuration & troubleshooting options. +`Documentation is available here. `_ License ======= @@ -35,22 +30,3 @@ 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. - -Origin -====== - -``takproto`` is a fork & complete re-write of @dB-SPL's -`takprotobuf `_. - -Notable differences between the original ``takprotobuf`` & this module ``takproto``: - -1. Rebuild proto files using `Protocol Buffers v21 `_. -2. Added support for encoding & decoding plain XML, Mesh & Stream TAK Protocol formats. -3. Remove dependency on ``untangle`` module, allowing compatibility with Python 3.6 - through 3.10. Unfortunately many single-board computers (i.e. Raspberry Pi) still - ship with Python 3.6, this change allows ``takproto`` to run on those systems. -4. Added ``xmlDetails`` detection for supporting undefined Protobuf elements in XML. -5. > 90% test coverage with **new** Unit Tests. -6. PEP-8 & Black style, linting, documentation & formatting of code. - -As much as possible @db-SPL's licensing terms were honored in this fork. diff --git a/docs/index.md b/docs/index.md index 35f4bcf..3751f1a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,5 +3,7 @@ # TAKProto - Python TAK Protocol Module -TAKProto is a Python module for encoding & decoding TAK Protocol Protobuf packets. +TAKProto is a Python module for encoding & decoding TAK Protocol Payloads, for use with [TAK Products](https://tak.gov) including ATAK, WinTAK, iTAK, TAKX, TAK Tracker & TAK Server. `takproto` includes functions for converting TAK Protocol Protobuf messages as Python objects, and serializing CoT XML messages as Protobuf. + +[Documentation is available here.](https://takproto.rtfd.io). diff --git a/docs/origin.md b/docs/origin.md new file mode 100644 index 0000000..09e0bce --- /dev/null +++ b/docs/origin.md @@ -0,0 +1,17 @@ + + +``takproto`` is a fork & complete re-write of @dB-SPL's +`takprotobuf `_. + +Notable differences between the original ``takprotobuf`` & this module ``takproto``: + +1. Rebuild proto files using `Protocol Buffers v21 `_. +2. Added support for encoding & decoding plain XML, Mesh & Stream TAK Protocol formats. +3. Remove dependency on ``untangle`` module, allowing compatibility with Python 3.6 + through 3.10. Unfortunately many single-board computers (i.e. Raspberry Pi) still + ship with Python 3.6, this change allows ``takproto`` to run on those systems. +4. Added ``xmlDetails`` detection for supporting undefined Protobuf elements in XML. +5. > 90% test coverage with **new** Unit Tests. +6. PEP-8 & Black style, linting, documentation & formatting of code. + +As much as possible @db-SPL's licensing terms were honored in this fork. diff --git a/docs/usage.md b/docs/usage.md index 527bb40..0f97a1b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -11,7 +11,7 @@ Given a `bytes` CoT XML message (or the path to an file containing a CoT XML mes ## UDP Multicast (Mesh SA) -``` py +```py linenums="1" hl_lines="16" title="cot2mesh.py" import takproto cot = """ @@ -37,11 +37,11 @@ By default, `xml2proto()` returns data as TAK Protocol - Version 1 Protobuf in M bytearray(b'\xbf\x01\xbf\x12\xff\x01\n\x0ba-f-G-E-V-C*$aa0b0312-b5cd-4c2c-bbbc-9c4c702162610\xa0\xa2\xc7\xb8\x82.8\xa0\xa2\xc7\xb8\x82.@\x98\xf5\xc8\xb8\x82.J\x03h-eQ3\x98T\xa7b\xfdE@Y}*~\xbe\xf3\x84P\xc0aW\\\x1c\x95\x9b\xc4:@i\x00\x00\x00\xe0\xcf\x12cAq\x00\x00\x00\xe0\xcf\x12cAz\x82\x01\x12$\n\x15192.168.1.10:4242:tcp\x12\x0bEliopoli HQ\x1a\x0c\n\x06Yellow\x12\x02HQ*\x02\x08d2F\n\x11LENOVO 20QV0007US\x12\nWinTAK-CIV\x1a\x19Microsoft Windows 10 Home"\n1.10.0.137:\x00') ``` -# TCP Unicast (TAK Server) +## TCP Unicast (TAK Server) Calling `xml2proto()` with the `takproto.TAKProtoVer.STREAM` ENUM parameter returns data as TAK Protocol - Version 1 Protobuf in Stream format (TCP Unicast): -```py +```py linenums="1" hl_lines="16" title="cot2stream.py" import takproto cot = """ @@ -71,7 +71,7 @@ bytearray(b'\xbf\x9f\x02\x12\xff\x01\n\x0ba-f-G-E-V-C*$aa0b0312-b5cd-4c2c-bbbc-9 Given a `bytearray` TAK Protocol - Version 1 Protobuf, `parse_proto()` returns an instance of the Protobuf class. You can then access the contents as an object: -```py +```py linenums="1" hl_lines="5" title="decode_tak.py" import takproto pb = bytearray(b'\xbf\x01\xbf\x12\xff\x01\n\x0ba-f-G-E-V-C*$aa0b0312-b5cd-4c2c-bbbc-9c4c702162610\xa0\xa2\xc7\xb8\x82.8\xa0\xa2\xc7\xb8\x82.@\x98\xf5\xc8\xb8\x82.J\x03h-eQ3\x98T\xa7b\xfdE@Y}*~\xbe\xf3\x84P\xc0aW\\\x1c\x95\x9b\xc4:@i\x00\x00\x00\xe0\xcf\x12cAq\x00\x00\x00\xe0\xcf\x12cAz\x82\x01\x12$\n\x15192.168.1.10:4242:tcp\x12\x0bEliopoli HQ\x1a\x0c\n\x06Yellow\x12\x02HQ*\x02\x08d2F\n\x11LENOVO 20QV0007US\x12\nWinTAK-CIV\x1a\x19Microsoft Windows 10 Home"\n1.10.0.137:\x00') @@ -83,7 +83,7 @@ This method of calling `parse_proto` would return an object containing the data If you were to `print(cot)`, you would see: -```json +```json linenums="1" cotEvent { type: "a-f-G-E-V-C" uid: "aa0b0312-b5cd-4c2c-bbbc-9c4c70216261" diff --git a/mkdocs.yml b/mkdocs.yml index c50da62..e643e74 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,11 @@ copyright: Copyright Sensors & Signals LLC https://www.snstac.com theme: name: material highlightjs: true - + features: + - content.code.copy + - content.code.select + - content.code.annotate + plugins: - include-markdown: opening_tag: "{!"