diff --git a/.gitignore b/.gitignore index d3e46e7..e02d63a 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,4 @@ pylint.log redis-server.log redis-server/ __pycache__ +known_craft.csv diff --git a/adsbcot/__init__.py b/adsbcot/__init__.py index 91993f8..d905665 100644 --- a/adsbcot/__init__.py +++ b/adsbcot/__init__.py @@ -21,7 +21,7 @@ :source: """ -__version__ = "6.2.0-beta5" +__version__ = "6.2.0-beta7" __author__ = "Greg Albrecht " __copyright__ = "Copyright Sensors & Signals LLC https://www.snstac.com" __license__ = "Apache License, Version 2.0" diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..f4d16fd --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1 @@ +{!CHANGELOG.md!} diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..04821fb --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,64 @@ +ADSBCOT's configuration parameters can be set two ways: + +1. In an INI-style configuration file. (ex. ``adsbcot -c config.ini``) +2. As environment variables. (ex. ``export DEBUG=1;adsbcot``) + +ADSBCOT has the following built-in configuration parameters: + +* **`FEED_URL`** + * Default: ``file:///run/dump1090-fa/aircraft.json`` + + ADS-B data source URL. Supported URL types: + + - ``file://`` The absolute local folder path to an ADS-B data file in JSON format. + - ``http://`` The local piaware web server aircraft data JSON URL. (ex. ``http://piaware.local:8080/data/aircraft.json``) + - ``tcp://`` A dump1090 BaseStation (SBS-1, "raw") host & port URL (ex. ``tcp://sensor.example.com:30003``). + - ``tcp+raw://`` A dump1090 BaseStation (SBS-1, "raw") host & port URL (ex. ``tcp+raw://sensor.example.com:30003``). + - ``tcp+beast://`` A dump1090 Beast binary mode host & port URL (ex. ``tcp+beast://sensor.example.com:30005``). + +* **`POLL_INTERVAL`** + * Default: ``30``* + + Period, in seconds, to poll the FEED_URL, *if the FEED_URL is of the type ``http://``. + +* **`ALT_UPPER`** + * Default: unset + + Upper Altitude Limit, geometric (GNSS / INS) altitude in feet referenced to the WGS84 ellipsoid. + +* **`ALT_LOWER`** + * Default: unset + + Lower Altitude Limit, geometric (GNSS / INS) altitude in feet referenced to the WGS84 ellipsoid. + +Additional configuration parameters, including TAK Server configuration, are included in the [PyTAK Configuration](https://pytak.readthedocs.io/en/latest/configuration/) documentation. + + + + + + +TKT TK TTKTKTKTKT +TK TK TK + +* **`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. + + diff --git a/docs/conop.md b/docs/conop.md new file mode 100644 index 0000000..410ad3a --- /dev/null +++ b/docs/conop.md @@ -0,0 +1,7 @@ +# Concept of Operations (CONOP) + +[![ADSBXCOT Concept of Operations (CONOP)](ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png)](ADSBXCOT_CONOP/ADSBXCOT_CONOP@2x.png) + + + +![ADSBCOT Example Setup](adsbcot_example.png) diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..23712b7 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,65 @@ + +## Run on a Raspberry Pi + +This example configuration can run along-side the dump1090 software on the same computer, or on computers connected over an IP network (i.e. A remote Raspberry Pi running dump1090). + +ADS-B data is transformed into TAK data and forwarded to our TAK Server over TCP port ``8087``. + +```ini +[adsbcot] +COT_URL = tcp://takserver.example.com:8087 +FEED_URL = tcp+beast://sensor.example.com:30003 +``` + +### Usage + +1. Add the configuration text to a configuration file named: ``adsbcot.ini`` +2. Use the configuration file when starting ADSBCOT: ``adsbcot -c adsbcot.ini`` +> Ensure you know the full path to your configuration file. + +## Forward to ATAK + +This example configuration can run along-side the dump1090 software on the same computer, or on computers connected over an IP network (i.e. A remote Raspberry Pi running dump1090). + +ADS-B data is transformed into TAK data and forwarded to our ATAK Mesh SA Multicast Network. + +```ini +[adsbcot] +COT_URL = udp+wo://239.2.3.1:6969 +FEED_URL = tcp+beast://10.1.2.24:30003 +``` + +### Usage + +1. Add the configuration text to a configuration file named: ``adsbcot.ini`` +2. Use the configuration file when starting ADSBCOT: ``adsbcot -c adsbcot.ini`` +> Ensure you know the full path to your configuration file. + +## Use aircraft JSON API + +This example configuration can run along-side the dump1090 software on the same computer, or on computers connected over an IP network (i.e. A remote Raspberry Pi running dump1090). + +ADS-B data is read from the dump1090 aircraft JSON API URL every 10 seconds, and is transformed into TAK data. From there it is forwarded to our TAK Server over TLS port ``8089`` using client certificates. + +```ini +[adsbcot] +PYTAK_TLS_CLIENT_CERT = /etc/my_client_cert.pem +COT_URL = tls://takserver.example.com:8089 +FEED_URL = http://piaware.local:8080/data/aircraft.json +POLL_INTERVAL = 10 +``` + +### Usage + +1. Add the configuration text to a configuration file named: ``adsbcot.ini`` +2. Use the configuration file when starting ADSBCOT: ``adsbcot -c adsbcot.ini`` +> Ensure you know the full path to your configuration file. + + +## Using environment variables + +```bash linenums="1" +export COT_URL="udp://10.9.8.7:8087" +export FEED_URL="tcp+raw://127.0.0.1:30002" +adsbcot +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..24d694e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,16 @@ +![ATAK Screenshot with ADSBCOT aircraft tracks.](atak_screenshot_with_pytak_logo-x25.png) + +# Display Aircraft in TAK + +ADSBCOT is software for monitoring and analyzing aviation surveillance data via the Team Awareness Kit (TAK) ecosystem of products. + +ADSBCOT captures & reports real-time ADS-B data received from aircraft (or other airbrone vehicles and drones) into TAK products using native TAK protocols, including Cursor on Target (CoT). + +ADSBCOT has been evaluated with WinTAK, iTAK, ATAK & TAK Server. + +ADSBCOT is in active use today in a variety of missions. + +[Documentation is available here.](https://adsbcot.rtfd.io) + + Use ADS-B Aggregators? Check out my sister software `ADSBXCOT `_. + diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..d3e7c71 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,35 @@ +ADSBCOT's functionality provided by a command-line program called `adsbcot`. + +There are several methods of installing ADSBCOT. They are listed below, in order of complexity. + +# Debian, Ubuntu, Raspberry Pi + +Install ADSBCOT, 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/adsbcot/releases/latest/download/python3-adsbcot_latest_all.deb +sudo apt install -f ./python3-adsbcot_latest_all.deb +``` + +# Windows, Linux + +Install from the Python Package Index (PyPI) [Advanced Users]:: + +```sh +python3 -m pip install adsbcot +``` + +# Developers + +PRs welcome! + +```sh linenums="1" +git clone https://github.com/snstac/adsbcot.git +cd adsbcot/ +python3 setup.py install +``` diff --git a/docs/takproto_chart.png b/docs/takproto_chart.png new file mode 100644 index 0000000..c808643 Binary files /dev/null and b/docs/takproto_chart.png differ diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..84d053e --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,18 @@ +## 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). +``` + +## Run as a service / Run forever. + +TK diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..724f945 --- /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: A gateway for displaying aircraft tracks from ADS-B Aggregators in TAK Products, including ATAK. +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/tox.ini b/tox.ini deleted file mode 100644 index 73efa6b..0000000 --- a/tox.ini +++ /dev/null @@ -1,5 +0,0 @@ -[tox] - -[testenv] -deps = pytest -commands = pytest