From c7665959e1d641f98b449f8f22655afa15ed8a1b Mon Sep 17 00:00:00 2001 From: Greg Albrecht Date: Thu, 20 Jun 2024 09:23:54 -0700 Subject: [PATCH] updated docs --- Makefile | 24 +++--------- README.md | 2 +- debian/aiscot.postinst | 8 ++-- debian/aiscot.service | 2 +- debian/install_pkg_build_deps.sh | 4 +- docs/configuration.md | 55 +++++++++++++++++++++++++++ docs/conop.md | 22 +++++++++++ docs/installation.md | 31 +++++++++++++++ docs/troubleshooting.md | 31 +++++++++++++++ docs/usage.md | 65 ++++++++++++++++++++++++++++++++ setup.cfg | 2 +- 11 files changed, 219 insertions(+), 27 deletions(-) mode change 100755 => 100644 debian/aiscot.postinst create mode 100644 docs/configuration.md create mode 100644 docs/conop.md create mode 100644 docs/installation.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/usage.md diff --git a/Makefile b/Makefile index 3b7d73f..994ffeb 100644 --- a/Makefile +++ b/Makefile @@ -47,7 +47,7 @@ clean: @rm -rf *.egg* build dist *.py[oc] */*.py[co] cover doctest_pypi.cfg \ nosetests.xml pylint.log output.xml flake8.log tests.log \ test-result.xml htmlcov fab.log .coverage __pycache__ \ - */__pycache__ deb_dist + */__pycache__ deb_dist .mypy_cache pep8: flake8 --max-line-length=88 --extend-ignore=E203 --exit-zero $(REPO_NAME)/*.py @@ -85,28 +85,16 @@ deb_dist: python3 setup.py --command-packages=stdeb.command sdist_dsc deb_custom: -# echo "# START Makefile customization " >> $(wildcard deb_dist/*/debian)/rules -# echo "override_dh_installsystemd:" >> $(wildcard deb_dist/*/debian)/rules -# echo " dh_installsystemd --name=$(REPO_NAME)" >> $(wildcard deb_dist/*/debian)/rules -# echo "override_dh_installinit:" >> $(wildcard deb_dist/*/debian)/rules -# echo " dh_installinit --name=$(REPO_NAME)" >> $(wildcard deb_dist/*/debian)/rules -# echo "# END Makefile customization" >> $(wildcard deb_dist/*/debian)/rules - cp debian/$(REPO_NAME).conf $(wildcard deb_dist/*/debian)/python3-$(REPO_NAME).default - cp debian/$(REPO_NAME).postinst $(wildcard deb_dist/*/debian)/python3-$(REPO_NAME).postinst - cp debian/$(REPO_NAME).service $(wildcard deb_dist/*/debian)/python3-$(REPO_NAME).service - -# ifneq ("$(postinst)", "") -# cp $(postinst) $(wildcard deb_dist/*/debian)/python3-$(REPO_NAME).postinst -# endif -# ifneq ("$(service)", "") -# cp $(service) $(wildcard deb_dist/*/debian)/python3-$(REPO_NAME).service -# endif + cp debian/$(REPO_NAME).conf $(wildcard deb_dist/*/debian)/$(REPO_NAME).default + cp debian/$(REPO_NAME).postinst $(wildcard deb_dist/*/debian)/$(REPO_NAME).postinst + cp debian/$(REPO_NAME).service $(wildcard deb_dist/*/debian)/$(REPO_NAME).service bdist_deb: deb_dist deb_custom cd deb_dist/$(REPO_NAME)-*/ && dpkg-buildpackage -rfakeroot -uc -us faux_latest: - cp deb_dist/python3-$(REPO_NAME)_*-1_all.deb deb_dist/python3-$(REPO_NAME)_latest_all.deb + cp deb_dist/$(REPO_NAME)_*-1_all.deb deb_dist/$(REPO_NAME)_latest_all.deb + cp deb_dist/$(REPO_NAME)_*-1_all.deb deb_dist/python3-$(REPO_NAME)_latest_all.deb package: bdist_deb faux_latest diff --git a/README.md b/README.md index 4f50200..6f17dda 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Pacific Ocean, as described in this article: http://ampledata.org/boat_race_supp > Want a turn-key AIS to TAK Gateway? Check out [AryaSEA](https://www.snstac.com/aryasea). -# License & Copyright +## License & Copyright Copyright Sensors & Signals LLC https://www.snstac.com diff --git a/debian/aiscot.postinst b/debian/aiscot.postinst old mode 100755 new mode 100644 index c23f824..0515f64 --- a/debian/aiscot.postinst +++ b/debian/aiscot.postinst @@ -19,7 +19,7 @@ echo "AISCOT Post Install" # shellcheck source=aiscot.conf -[ -f "/etc/default/python3-aiscot" ] && . /etc/default/python3-aiscot +[ -f "/etc/default/aiscot" ] && . /etc/default/aiscot # Sane defaults: [ -z "$SERVER_HOME" ] && SERVER_HOME=/run/aiscot @@ -70,10 +70,10 @@ then fi fi -systemctl enable python3-aiscot.service +systemctl enable aiscot.service echo "aiscot has been installed." -echo "Configure: sudo nano /etc/default/python3-aiscot" -echo "Start: sudo systemctl start python3-aiscot.service" +echo "Configure: sudo nano /etc/default/aiscot" +echo "Start: sudo systemctl start aiscot.service" exit 0 diff --git a/debian/aiscot.service b/debian/aiscot.service index 1cefb31..eef888f 100644 --- a/debian/aiscot.service +++ b/debian/aiscot.service @@ -26,7 +26,7 @@ User=aiscot ExecStart=/usr/local/bin/aiscot RuntimeDirectory=aiscot SyslogIdentifier=aiscot -EnvironmentFile=/etc/default/python3-aiscot +EnvironmentFile=/etc/default/aiscot Type=simple Restart=always RestartSec=20 diff --git a/debian/install_pkg_build_deps.sh b/debian/install_pkg_build_deps.sh index 6713a78..ac2e185 100644 --- a/debian/install_pkg_build_deps.sh +++ b/debian/install_pkg_build_deps.sh @@ -5,6 +5,6 @@ echo "Installing Debian package build dependencies" apt-get update -qq apt-get install -y \ - python3 python3-dev python3-pip python3-venv python3-all \ + python3 dev pip venv all \ dh-python debhelper devscripts dput software-properties-common \ - python3-distutils python3-setuptools python3-wheel python3-stdeb + distutils setuptools wheel stdeb diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..b63b6db --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,55 @@ +AISCOT supports multiple methods of configuration: + +1. INI-style config file, see `config.example.ini`. Usage: `aiscot -c config.ini`. +2. Environment variables. Usage: `export DEBUG=1 ; aiscot` +3. If using systemd, edit `/etc/default/aiscot` + +AISCOT has the following built-in configuration parameters: + +* **`COT_URL`** + * Default: ``udp+wo://239.2.3.1:6969`` (TAK Mesh SA, Multicast UDP, write-only) + + Destination for TAK Data (Cursor on Target Events). Supported values are: + + * TLS Unicast: ``tls://host:port`` + * TCP Unicast: ``tcp://host:port`` + * UDP Multicast: ``udp://group:port`` (aka **Mesh SA**) + * UDP Unicast: ``udp://host:port`` + * UDP Broadcast: ``udp+broadcast://network:port`` + * UDP Write-only: ``udp+wo://host:port`` + * stdout or stderr: ``log://stdout`` or ``log://stderr`` + + **N.B.** `+wo` modifier stands for 'write-only', and allows multiple PyTAK + applications to run on a single bound-interface without monopolizing a port. If you're getting a 'cannot bind to port' or 'port occupied error', try adding the `+wo` modifier. + +* **`AIS_PORT`**: + * Default: ``5050`` + + AIS UDP Listen Port, for use with Over-the-air (RF) AIS. + +* **`COT_STALE`**: + * Default: ``3600`` (seconds) + + CoT Stale period ("timeout"), in seconds. + +* **`COT_TYPE`**: + * Default: ``a-u-S-X-M`` + + Override COT Event Type ("marker type"). + +* **`KNOWN_CRAFT`**: + * Default: unset + + CSV-style hints file for overriding callsign, icon, COT Type, etc. + +* **`INCLUDE_ALL_CRAFT`**: + * Default: ``False`` + + If ``True`` and ``KNOWN_CRAFT`` is set, will forward all craft, including those transformed by the ``KNOWN_CRAFT`` database. + +* **`IGNORE_ATON`**: + * Default: ``False`` + + Ignore AIS from Aids to Naviation (buoys, etc). + +Additional configuration parameters, including TAK Server configuration, are included in the [PyTAK Configuration](https://pytak.readthedocs.io/en/stable/configuration/) documentation. diff --git a/docs/conop.md b/docs/conop.md new file mode 100644 index 0000000..71af5c0 --- /dev/null +++ b/docs/conop.md @@ -0,0 +1,22 @@ +# Concept of Operations + +AISCOT can operate in two different modes, as described in detail below: + +1. AIS Over-the-air (RF) +2. AIS Aggregator (AISHUB) + +## AIS Over-the-air Operation (RF) + +![AISCOT "AIS Over the Air" CONOP](aiscot_ota.png) + +Receive AIS data from a VHF AIS receiver, such as the +Megwatt `dAISy+ `_. From there +AIS can be decoded by `AIS Dispatcher `_ and +forwarded to AISCOT to be transformed to COT and transmitted to COT destinations. + +## AIS Aggregator Operation (AISHUB.com) + +![AISCOT "AIS Aggregator" CONOP](aiscot_agg.png) + +Receive AIS data from the `AISHUB `_ service. +Requires a subscription to AISHUB. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..853bb44 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,31 @@ +AISCOT's functionality provided by a command-line software program called `aiscot`. + +## Debian, Ubuntu, Raspberry Pi + +Install AISCOT, and prerequisite packages [PyTAK](https://pytak.rtfd.io). + +```sh linenums="1" +sudo apt update -qq +wget https://github.com/snstac/pytak/releases/latest/download/pytak_latest_all.deb +sudo apt install -f ./pytak_latest_all.deb +wget https://github.com/snstac/aiscot/releases/latest/download/aiscot_latest_all.deb +sudo apt install -f ./aiscot_latest_all.deb +``` + +## Windows, Linux + +Install from the Python Package Index (PyPI):: + +```sh +sudo python3 -m pip install aiscot +``` + +## Developers + +PRs welcome! + +```sh linenums="1" +git clone https://github.com/snstac/aiscot.git +cd aiscot/ +make editable +``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..5b57bcb --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,31 @@ +To report bugs, please set the DEBUG=1 environment variable to collect logs: + +```sh +DEBUG=1 aiscot +``` + +Or: + +```sh linenums="1" +export DEBUG=1 +aiscot +``` + +Or: + +```sh linenums="1" +echo 'DEBUG=1' >> aiscot.ini +aiscot -c aiscot.ini +``` + +You can view systemd/systemctl/service logs via: + +```journalctl -fu aiscot``` + +Please use GitHub issues for support requests. Please note that AISCOT is free open source software and comes with no warranty. See LICENSE. + +## Database Update + +Occasional updates to the YADD Ship Name database can be found at: http://www.yaddnet.org/pages/php/test/tmp/ + +Updates to the MID database can be found at: TK diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..b9eba1e --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,65 @@ +AISCOT can be configured with a INI-style configuration file, or using +environmental variables. + +Command-line options:: + + usage: aiscot [-h] [-c CONFIG_FILE] [-p PREF_PACKAGE] + + optional arguments: + -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). + +## AISHUB + +AISHUB.com requires registration. Once registered the site will provide you with a +Username that you'll use with their feed. You'll also need to specify a Bounding Box +when accessing the feed. + +The AISHUB_URL must be specified as follows: + +``https://data.aishub.net/ws.php?format=1&output=json&compress=0&username=AISHUB_USERNAME&latmin=BBOX_LAT_MIN&latmax=BBOX_LAT_MAX&lonmin=BBOX_LON_MON&lonmax=BBOX_LON_MAX`` + +Replacing ``AISHUB_USERNAME`` with your AISHUB.com username, and specifying the +Bounding Box is specified as follows: + +* **`latmin`** + * signed float + + The minimum latitude of the Bounding Box (degrees from Equator) as a signed float (use negative sign for East: ``-``). + +* **`latmax`** + * signed float + + The maximum latitude of the Bounding Box (degrees from Equator) as a signed float (use negative sign for East: ``-``). + +* **`lonmin`** + * signed float + + The minimum longitude of the Bound Box (degrees from Prime Meridian) as a signed float (use negative sign for North: ``-``). + +* **`lonmax`** + * signed float + + The maximum longitude of the Bound Box (degrees from Prime Meridian) as a signed float (use negative sign for North: ``-``). + +For example, the following Bound Box paints a large swath around Northern California: +``latmin=35&latmax=38&lonmin=-124&lonmax=-121``. This can be read as: +"Between 35° and 38° latitude & -121° and -124° longitude". + +## Run as a service / Run forever + +1. Add the text contents below a file named `/lib/systemd/system/aiscot.service` + You can use `nano` or `vi` editors: `sudo nano /lib/systemd/system/aiscot.service` +2. Reload systemctl: `sudo systemctl daemon-reload` +3. Enable AISCOT: `sudo systemctl enable aiscot` +4. Start AISCOT: `sudo systemctl start aiscot` + +```ini +{!debian/aiscot.service} +``` + + +> Pay special attention to the `ExecStart` line above. You'll need to provide the full local filesystem path to both your `aiscot` executable & AISCOT configuration files. \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index 2f95e9f..edeb454 100644 --- a/setup.cfg +++ b/setup.cfg @@ -78,7 +78,7 @@ console_scripts = [options] include_package_data = True -packages = aiscot +packages = aiscot, aiscot.data package_dir = aiscot = aiscot python_requires = >=3.6, <4