diff --git a/.gitignore b/.gitignore index 5d31ffd..332a268 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,5 @@ redis-server.log redis-server/ __pycache__ .ipynb_checkpoints/ +.python-version +config.ini diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..e941dac --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,17 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +mkdocs: + configuration: mkdocs.yml + +python: + install: + - requirements: docs/requirements.txt diff --git a/Makefile b/Makefile index bb123db..32cfa85 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ # -# Copyright 2022 Greg Albrecht +# Copyright Sensors & Signals LLC https://www.snstac.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,10 +13,6 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Author:: Greg Albrecht W2GMD -# Copyright:: Copyright 2022 Greg Albrecht -# License:: Apache License, Version 2.0 -# this_app = adsbxcot .DEFAULT_GOAL := all @@ -76,3 +72,7 @@ test_cov: black: black . + +mkdocs: + pip install -r docs/requirements.txt + mkdocs serve \ No newline at end of file diff --git a/README.rst b/README.rst index e4feb0d..c045cac 100644 --- a/README.rst +++ b/README.rst @@ -1,123 +1,25 @@ -ADSBExchange.com ADS-B to Cursor-On-Target Gateway. -*************************************************** - .. image:: https://raw.githubusercontent.com/ampledata/adsbxcot/main/docs/Screenshot_20201026-142037_ATAK-25p.jpg :alt: Screenshot of ADS-B PLI in ATAK. :target: https://github.com/ampledata/adsbxcot/blob/main/docs/Screenshot_20201026-142037_ATAK.jpg +Display Aircraft in TAK +*********************** -The ADSBXCOT ADS-B to Cursor-On-Target Gateway transforms Automatic -Dependent Surveillance-Broadcast (ADS-B) aircraft position information into -Cursor-On-Target (COT) Position Location Information for display on -Situational Awareness applications such as the Android Team Awareness Kit -(ATAK), WinTAK, RaptorX, TAKX, iTAK, et al. ADS-B data is provided by -ADSBExchange.com and requires an `API key `_ from that service. - -For more information on the TAK suite of tools, see: https://www.tak.gov/ - -.. image:: https://raw.githubusercontent.com/ampledata/adsbxcot/main/docs/adsbxcot_concept.png - :alt: ADSBXCOT Concept. - :target: https://github.com/ampledata/adsbxcot/blob/main/docs/adsbxcot_concept.png - - -Support Development -=================== - -**Tech Support**: Email support@undef.net or Signal/WhatsApp: +1-310-621-9598 - -This tool has been developed for the Disaster Response, Public Safety and -Frontline Healthcare community. This software is currently provided at no-cost -to users. Any contribution you can make to further this project's development -efforts is greatly appreciated. - -.. image:: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png - :target: https://www.buymeacoffee.com/ampledata - :alt: Support Development: Buy me a coffee! - - -Installation -============ - -ADSBXCOT's functionality provided by a command-line program called `adsbxcot`. - -Installing as a Debian / Ubuntu Package [Recommended]:: - - $ sudo apt update - $ wget https://github.com/ampledata/aircot/releases/latest/download/python3-aircot_latest_all.deb - $ sudo apt install -f ./python3-aircot_latest_all.deb - $ wget https://github.com/ampledata/pytak/releases/latest/download/python3-pytak_latest_all.deb - $ sudo apt install -f ./python3-pytak_latest_all.deb - $ wget https://github.com/ampledata/adsbxcot/releases/latest/download/python3-adsbxcot_latest_all.deb - $ sudo apt install -f ./python3-adsbxcot_latest_all.deb - - -Install from the Python Package Index (PyPI) [Advanced Users]:: - - $ pip install adsbxcot - - -Install from this source tree [Developers]:: - - $ git clone https://github.com/ampledata/adsbxcot.git - $ cd adsbxcot/ - $ python setup.py install - - -Usage -===== - -The `adsbxcot` command-line program has 2 runtime arguments:: - - usage: adsbxcot [-h] [-c CONFIG_FILE] - - optional arguments: - -h, --help show this help message and exit - -c CONFIG_FILE, --CONFIG_FILE CONFIG_FILE. Default: config.ini - - -Configuration -============= -Configuration parameters can be specified either via environment variables or in -a INI-stile configuration file. - -Parameters: - -* **ADSBX_URL**: ADSBExchange.com API or Rapid API URL. -* **COT_URL**: (*optional*) Destination for Cursor-On-Target messages. See `PyTAK `_ for options. -* **POLL_INTERVAL**: (*optional*) Period in seconds to poll API. Default: 30 -* **KNOWN_CRAFT**: (*optional*) CSV-style aircraft hints file for overriding callsign, icon, COT Type, etc. -* **INCLUDE_TISB**: (*optional*) If set, will also including TIS-B identified aircraft. -* **INCLUDE_ALL_CRAFT**: (*optional*) If set & KNOWN_CRAFT is set, will include aircraft not in KNOWN_CRAFT. - -There are other configuration parameters available via `PyTAK `_. - -Configuration parameters are imported in the following priority order: - -1. ``config.ini`` (if exists) or ``-c `` (if specified). -2. Environment Variables (if set). -3. Defaults. - - -Source -====== -ADSBXCOT source can be found on Github: https://github.com/ampledata/adsbxcot - +ADSBXCOT is a PyTAK gateway for displaying aircraft tracks from ADS-B Aggregators (ADSBExchange, adsb.fi, et al.) in `TAK Products `_ (ATAK, WinTAK, iTAK, TAK Server, TAKX). -Author -====== -ADSBXCOT is written and maintained by Greg Albrecht W2GMD oss@undef.net +ADSBXCOT converts ADS-B messages from aircraft into Cursor on Target (CoT), as spoken by TAK Products like ATAK. ADS-B messages are read from global ADS-B data aggregators, such as ADSBExchange.com or adsb.fi. ADS-B data sent to TAK Products retains many of the aircraft's track, course & speed parameters, but also metadata about the aircraft, including Flight, Tail, Category, and more. -https://ampledata.org/ +ADSBXCOT runs in any Python 3.6+ environment, on both Windows & Linux. +N.B.: Almost all ADS-B Aggreators require pre-authorization before allowing access to ADS-B data. This pre-authorization is often in the form of an API key. Many of these services provide these API keys for free, provided you feed data from your local ADS-B receiver into their cloud-service. Otherwise, they charge a fee for access to ADS-B data. Your organization should reach out to these ADS-B data aggregator services directly to negotiate terms for your use. -Copyright -========= -ADSBXCOT is Copyright 2022 Greg Albrecht +`Documentation is available here. `_ +Have your own ADS-B receiver? Check out `ADSBCOT `_. License ======= -Copyright 2022 Greg Albrecht +Copyright Sensors & Signals LLC https://www.snstac.com Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/adsbxcot/__init__.py b/adsbxcot/__init__.py index 28f8748..8fd0137 100644 --- a/adsbxcot/__init__.py +++ b/adsbxcot/__init__.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Copyright 2022 Greg Albrecht +# Copyright Sensors & Signals LLC https://www.snstac.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,17 +13,14 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Author:: Greg Albrecht W2GMD -# """ -ADS-B Exchange Cursor-on-Target Gateway. -~~~~ +Display Aircraft in TAK. -:author: Greg Albrecht W2GMD -:copyright: Copyright 2022 Greg Albrecht +:author: Greg Albrecht +:copyright: Copyright Sensors & Signals LLC https://www.snstac.com :license: Apache License, Version 2.0 -:source: +:source: """ from .constants import DEFAULT_POLL_INTERVAL, DEFAULT_LIGHT_COT # NOQA @@ -32,6 +29,6 @@ from .classes import ADSBXWorker # NOQA -__author__ = "Greg Albrecht W2GMD " -__copyright__ = "Copyright 2022 Greg Albrecht" +__author__ = "Greg Albrecht " +__copyright__ = "Copyright Sensors & Signals LLC https://www.snstac.com" __license__ = "Apache License, Version 2.0" diff --git a/adsbxcot/classes.py b/adsbxcot/classes.py index cee6146..4097c5c 100644 --- a/adsbxcot/classes.py +++ b/adsbxcot/classes.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Copyright 2022 Greg Albrecht +# Copyright Sensors & Signals LLC https://www.snstac.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,8 +13,6 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Author:: Greg Albrecht W2GMD -# """ADSBXCOT Class Definitions.""" @@ -30,14 +28,14 @@ import adsbxcot -__author__ = "Greg Albrecht W2GMD " -__copyright__ = "Copyright 2022 Greg Albrecht" +__author__ = "Greg Albrecht " +__copyright__ = "Copyright Sensors & Signals LLC https://www.snstac.com" __license__ = "Apache License, Version 2.0" class ADSBXWorker(pytak.QueueWorker): - """Reads ADSBExchange.com ADS-B Data, renders to COT, and puts on Queue.""" + """Reads ADS-B Aggregator Data, renders to COT, and puts on Queue.""" def __init__(self, queue: asyncio.Queue, config: SectionProxy) -> None: super().__init__(queue, config) @@ -96,8 +94,8 @@ async def handle_data(self, data: list) -> None: async def get_adsbx_feed(self, url: str) -> None: """ - ADSBExchange.com ADS-B Feed API Client wrapper. - Connects to ADSBX API and passes messages to `self.handle_message()`. + ADS-B Aggregator API Client wrapper. + Connects to API and passes messages to `self.handle_message()`. """ api_key: str = self.config.get("API_KEY") @@ -132,7 +130,7 @@ async def run(self, number_of_iterations=-1) -> None: """Runs this Thread, Reads from Pollers.""" self._logger.info("Running %s", self.__class__) - url: str = self.config.get("ADSBX_URL") + url: str = self.config.get("FEED_URL", self.config.get("ADSBX_URL")) poll_interval: str = self.config.get( "POLL_INTERVAL", adsbxcot.DEFAULT_POLL_INTERVAL ) diff --git a/adsbxcot/commands.py b/adsbxcot/commands.py index 2f1c06c..d41fa2a 100644 --- a/adsbxcot/commands.py +++ b/adsbxcot/commands.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Copyright 2022 Greg Albrecht +# Copyright Sensors & Signals LLC https://www.snstac.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,15 +13,13 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Author:: Greg Albrecht W2GMD -# -"""PyTAK Command Line.""" +"""ADSBXCOT Command Line.""" import pytak -__author__ = "Greg Albrecht W2GMD " -__copyright__ = "Copyright 2022 Greg Albrecht" +__author__ = "Greg Albrecht " +__copyright__ = "Copyright Sensors & Signals LLC https://www.snstac.com" __license__ = "Apache License, Version 2.0" diff --git a/adsbxcot/constants.py b/adsbxcot/constants.py index e81f81b..aa0d25b 100644 --- a/adsbxcot/constants.py +++ b/adsbxcot/constants.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Copyright 2022 Greg Albrecht +# Copyright Sensors & Signals LLC https://www.snstac.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,13 +13,11 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Author:: Greg Albrecht W2GMD -# """ADSBXCOT Constants.""" -__author__ = "Greg Albrecht W2GMD " -__copyright__ = "Copyright 2022 Greg Albrecht" +__author__ = "Greg Albrecht " +__copyright__ = "Copyright Sensors & Signals LLC https://www.snstac.com" __license__ = "Apache License, Version 2.0" diff --git a/adsbxcot/functions.py b/adsbxcot/functions.py index 94d9e63..073eb59 100644 --- a/adsbxcot/functions.py +++ b/adsbxcot/functions.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Copyright 2022 Greg Albrecht +# Copyright Sensors & Signals LLC https://www.snstac.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,8 +13,6 @@ # See the License for the specific language governing permissions and # limitations under the License. # -# Author:: Greg Albrecht W2GMD -# """ADSBXCOT Functions.""" @@ -27,8 +25,8 @@ import aircot import adsbxcot # pylint: disable=cyclic-import -__author__ = "Greg Albrecht W2GMD " -__copyright__ = "Copyright 2022 Greg Albrecht" +__author__ = "Greg Albrecht " +__copyright__ = "Copyright Sensors & Signals LLC https://www.snstac.com" __license__ = "Apache License, Version 2.0" diff --git a/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP.png b/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP.png new file mode 100644 index 0000000..82bf1b4 Binary files /dev/null and b/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP.png differ diff --git a/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png b/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png new file mode 100644 index 0000000..bb073b0 Binary files /dev/null and b/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png differ diff --git a/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP@2z.png b/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP@2z.png new file mode 100644 index 0000000..0a3301c Binary files /dev/null and b/docs/ADSBXCOT_CONOP/ADSBXCOT_CONOP@2z.png differ diff --git a/docs/adsbxcot concept.graffle b/docs/adsbxcot concept.graffle deleted file mode 100644 index 948a468..0000000 Binary files a/docs/adsbxcot concept.graffle and /dev/null differ diff --git a/docs/adsbxcot-conop.png b/docs/adsbxcot-conop.png deleted file mode 100644 index efc3551..0000000 Binary files a/docs/adsbxcot-conop.png and /dev/null differ diff --git a/docs/adsbxcot_concept.png b/docs/adsbxcot_concept.png deleted file mode 100644 index a2382df..0000000 Binary files a/docs/adsbxcot_concept.png and /dev/null differ diff --git a/docs/atak_screenshot_with_pytak_logo-x25.jpg b/docs/atak_screenshot_with_pytak_logo-x25.jpg new file mode 100644 index 0000000..4ae5f1d Binary files /dev/null and b/docs/atak_screenshot_with_pytak_logo-x25.jpg differ diff --git a/docs/atak_screenshot_with_pytak_logo.jpg b/docs/atak_screenshot_with_pytak_logo.jpg new file mode 100755 index 0000000..0dbe23d Binary files /dev/null and b/docs/atak_screenshot_with_pytak_logo.jpg differ diff --git a/docs/conop.md b/docs/conop.md new file mode 100644 index 0000000..09c273c --- /dev/null +++ b/docs/conop.md @@ -0,0 +1,3 @@ +# Concept of Operations (CONOP) + +[![ADSBXCOT Concept of Operations (CONOP)](ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png)](ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5905079 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +![ATAK Screenshot with ADSBXCOT aircraft tracks.](atak_screenshot_with_pytak_logo-x25.jpg) + +# Display Aircraft in TAK + +ADSBXCOT is a PyTAK gateway for displaying aircraft tracks from ADS-B Aggregators (ADSBExchange, adsb.fi, et al.) in [TAK Products](https://tak.gov>) (ATAK, WinTAK, iTAK, TAK Server, TAKX). + +ADSBXCOT converts ADS-B messages from aircraft into Cursor on Target (CoT), as spoken by TAK Products like ATAK. ADS-B messages are read from global ADS-B data aggregators, such as ADSBExchange.com or adsb.fi. ADS-B data sent to TAK Products retains many of the aircraft's track, course & speed parameters, but also metadata about the aircraft, including Flight, Tail, Category, and more. + +ADSBXCOT runs in any Python 3.6+ environment, on both Windows & Linux. + +N.B.: Almost all ADS-B Aggreators require pre-authorization before allowing access to ADS-B data. This pre-authorization is often in the form of an API key. Many of these services provide these API keys for free, provided you feed data from your local ADS-B receiver into their cloud-service. Otherwise, they charge a fee for access to ADS-B data. Your organization should reach out to these ADS-B data aggregator services directly to negotiate terms for your use. + +[Documentation is available here.](https://adsbxcot.rtfd.io) + +Have your own ADS-B receiver? Check out [ADSBCOT](https://adsbcot.rtfd.io). diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..6268374 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,35 @@ +ADSBXCOT's functionality provided by a command-line program called `adsbxcot`. + +There are several methods of installing ADSBXCOT. They are listed below, in order of complexity. + +# Debian, Ubuntu, Raspberry Pi + +Install ADSBXCOT, and prerequisite packages of [PyTAK](https://pytak.rtfd.io) & [AIRCOT](https://aircot.rtfd.io). + +```sh linenums="1" +sudo apt update +wget https://github.com/ampledata/aircot/releases/latest/download/python3-aircot_latest_all.deb +sudo apt install -f ./python3-aircot_latest_all.deb +wget https://github.com/ampledata/pytak/releases/latest/download/python3-pytak_latest_all.deb +sudo apt install -f ./python3-pytak_latest_all.deb +wget https://github.com/ampledata/adsbxcot/releases/latest/download/python3-adsbxcot_latest_all.deb +sudo apt install -f ./python3-adsbxcot_latest_all.deb +``` + +# Windows, Linux + +Install from the Python Package Index (PyPI) [Advanced Users]:: + +```sh +python3 -m pip install adsbxcot +``` + +# Developers + +PRs welcome! + +```sh linenums="1" +git clone https://github.com/snstac/adsbxcot.git +cd adsbxcot/ +python3 setup.py install +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b00f781 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,23 @@ +click +ghp-import +griffe +importlib-metadata +jinja2 +markdown +markdown-include +markupsafe +mergedeep +mkdocs +mkdocs-autorefs +mkdocs-include-markdown-plugin +mkdocs-material +mkdocstrings-python +mkdocstrings[python] +packaging +pymdown-extensions +pyparsing +python-dateutil +pyyaml +pyyaml-env-tag +six +zipp diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..019d0c9 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,58 @@ +# Command-line + +Command-line usage is available by running ``adsbxcot -h``. + +``` +usage: adsbxcot [-h] [-c CONFIG_FILE] [-p PREF_PACKAGE] + +options: + -h, --help show this help message and exit + -c CONFIG_FILE, --CONFIG_FILE CONFIG_FILE + Optional configuration file. Default: config.ini + -p PREF_PACKAGE, --PREF_PACKAGE PREF_PACKAGE + Optional connection preferences package zip file (aka data package). +``` + +## Configuration + +ADSBXCOT's configuration parameters can be set two ways: + +1. In an INI-style configuration file. ``adsbxcot -c config.ini`` +2. As environment variables. ``export DEBUG=1;adsbcot`` + +ADSBXCOT has the following built-in configuration parameters: + + +* **`FEED_URL`** + * Default: TK + + ADS-B Aggregator API URL. + + +* **`POLL_INTERVAL`** + * Default: ``30`` + + Period, in seconds, to poll API URL. + +* **`KNOWN_CRAFT`**: + * Default: unset + + CSV-style aircraft hints file for overriding callsign, icon, COT Type, etc. + +* **`INCLUDE_TISB`**: + * Default: ``False`` + + If ``True``, includes TIS-B tracks. + +* **`INCLUDE_ALL_CRAFT`**: + * Default: ``False`` + + If ``True`` and ``KNOWN_CRAFT`` is set, will forward all aircraft, including those transformed by the ``KNOWN_CRAFT`` database. + +* **`TISB_ONLY`**: + * Default: ``False`` + + If ``True``, only passes TIS-B tracks. + +Additional configuration parameters, including TAK Server configuration, are included in the [PyTAK Configuration](https://pytak.readthedocs.io/en/latest/configuration/) documentation. + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..2b1de61 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,40 @@ +site_name: ADSBXCOT - Display Aircraft in TAK +site_url: https://adsbxcot.rtfd.io/ +repo_url: https://github.com/snstac/adsbxcot/ +site_description: ADSBXCOT is a gateway for displaying aircraft tracks from ADS-B Aggregators (ADSBExchange, adsb.fi, et al.) in TAK Products (ATAK, WinTAK, iTAK, TAK Server, TAKX). +site_author: Greg Albrecht +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: "{!" + closing_tag: "!}" + - search + - mkdocstrings: + handlers: + # See: https://mkdocstrings.github.io/python/usage/ + python: + options: + docstring_style: sphinx + +markdown_extensions: + - markdown_include.include: + base_path: . + - admonition + - toc: + permalink: True + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences \ No newline at end of file diff --git a/setup.py b/setup.py index 7510aad..0b81424 100644 --- a/setup.py +++ b/setup.py @@ -50,7 +50,7 @@ def publish(): package_dir={__title__: __title__}, url=f"https://github.com/ampledata/{__title__}", entry_points={"console_scripts": [f"{__title__} = {__title__}.commands:main"]}, - description="ADSBExchange.com ADS-B to Cursor-On-Target Gateway.", + description="PyTAK gateway for displaying aircraft tracks from ADS-B Aggregators (ADSBExchange, adsb.fi, et al.) in TAK Products (ATAK, WinTAK, iTAK, TAK Server, TAKX).", author="Greg Albrecht", author_email="oss@undef.net", package_data={"": ["LICENSE"]},