Metadata-Version: 2.4
Name: aprsd-avwx-plugin
Version: 1.0.0
Summary: APRSD Plugins for the AVWX Api
Author-email: "Walter A. Boring IV" <waboring@hemna.com>
Maintainer-email: "Walter A. Boring IV" <waboring@hemna.com>
License: 
        The MIT License (MIT)
        
        Copyright (c) 2026 Walter A. Boring IV
        
        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: aprs,aprs-is,aprsd,aprsd-server,aprsd-client,aprsd-socket,aprsd-socket-server,aprsd-socket-client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Communications :: Ham Radio
Classifier: Topic :: Internet
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: aprsd>=4.2.0
Requires-Dist: oslo_config
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

AVWX Api based APRSD plugins
============================

|PyPI| |Status| |Python Version| |License|

|Read the Docs| |Tests| |Codecov|

|pre-commit|

.. |PyPI| image:: https://img.shields.io/pypi/v/aprsd-avwx-plugin.svg
   :target: https://pypi.org/project/aprsd-avwx-plugin/
   :alt: PyPI
.. |Status| image:: https://img.shields.io/pypi/status/aprsd-avwx-plugin.svg
   :target: https://pypi.org/project/aprsd-avwx-plugin/
   :alt: Status
.. |Python Version| image:: https://img.shields.io/pypi/pyversions/aprsd-avwx-plugin
   :target: https://pypi.org/project/aprsd-avwx-plugin
   :alt: Python Version
.. |License| image:: https://img.shields.io/pypi/l/aprsd-avwx-plugin
   :target: https://opensource.org/licenses/MIT
   :alt: License
.. |Read the Docs| image:: https://img.shields.io/readthedocs/aprsd-avwx-plugin/latest.svg?label=Read%20the%20Docs
   :target: https://aprsd-avwx-plugin.readthedocs.io/
   :alt: Read the documentation at https://aprsd-avwx-plugin.readthedocs.io/
.. |Tests| image:: https://github.com/hemna/aprsd-avwx-plugin/workflows/Tests/badge.svg
   :target: https://github.com/hemna/aprsd-avwx-plugin/actions?workflow=Tests
   :alt: Tests
.. |Codecov| image:: https://codecov.io/gh/hemna/aprsd-avwx-plugin/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/hemna/aprsd-avwx-plugin
   :alt: Codecov
.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
   :target: https://github.com/pre-commit/pre-commit
   :alt: pre-commit


Features
--------

* Fetch METAR weather reports for APRS callsigns
* Automatically finds the nearest weather station to a callsign's location
* Uses aprs.fi to get GPS coordinates for callsigns
* Returns raw METAR data for aviation weather information


Requirements
------------

* Python 3.11 or higher
* APRSD server (version 4.2.0 or higher)
* AVWX API access (either via subscription or self-hosted)
* aprs.fi API key (for location lookups)


Installation
------------

You can install *AVWX Api based APRSD plugins* via pip_ from PyPI_:

.. code:: console

   $ pip install aprsd-avwx-plugin


AVWX API Setup
--------------

This plugin requires access to an AVWX API instance. You have two options:

Official AVWX REST API (Subscription Required)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The official AVWX REST API is available at https://info.avwx.rest/_. This service provides:

* METAR - Current surface conditions
* TAF - 24-hour forecasts
* PIREP - Inflight observations
* AIRMET/SIGMET - Weather advisories
* NOTAM - Notices to airmen
* Station information and search

The official service requires a subscription (hobby, pro, or enterprise tiers). Basic METAR and TAF parsing services are free, but other features require paid plans.

For more information, visit the `AVWX REST API`_ website.

.. _AVWX REST API: https://info.avwx.rest/

Self-Hosted AVWX Engine
~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively, you can self-host your own AVWX API using the open-source `avwx-engine`_ project. This allows you to run your own aviation weather parsing service without subscription fees.

To self-host:

1. Clone the avwx-engine repository:

   .. code:: console

      $ git clone https://github.com/avwx-rest/avwx-engine
      $ cd avwx-engine

2. Follow the installation and setup instructions in the `avwx-engine`_ README

3. Configure the plugin to point to your self-hosted instance (see Configuration below)

The avwx-engine is a Python library that can be run as a service. You'll need to set up an API server wrapper around it to provide REST API endpoints that this plugin can consume.


Configuration
-------------

The plugin requires two configuration options in your APRSD configuration file:

* ``avwx_plugin.apiKey`` - Your AVWX API key (required)
* ``avwx_plugin.base_url`` - The base URL for the AVWX API (default: ``https://avwx.rest``)

Example configuration:

.. code:: ini

   [avwx_plugin]
   apiKey = your-api-key-here
   base_url = https://avwx.rest

If you're self-hosting, set ``base_url`` to your self-hosted instance URL:

.. code:: ini

   [avwx_plugin]
   apiKey = your-api-key-here
   base_url = http://localhost:8000

You also need an aprs.fi API key for location lookups:

.. code:: ini

   [aprs_fi]
   apiKey = your-aprs-fi-api-key-here


Usage
-----

Once installed and configured, the plugin can be triggered via APRS messages.

Command Format
~~~~~~~~~~~~~~

The plugin responds to messages starting with ``m`` or ``metar``:

* ``m`` - Get METAR for your own callsign's location
* ``metar`` - Get METAR for your own callsign's location
* ``m <CALLSIGN>`` - Get METAR for the specified callsign's location
* ``metar <CALLSIGN>`` - Get METAR for the specified callsign's location

How It Works
~~~~~~~~~~~~

1. When a user sends a ``metar`` command (with or without a callsign), the plugin:

   a. Determines the target callsign (either the sender or the specified callsign)

   b. Queries aprs.fi to get the GPS coordinates for that callsign

   c. Uses the AVWX API to find the nearest weather station to those coordinates

   d. Fetches the METAR report for that station

   e. Returns the raw METAR data to the user

2. The plugin requires the callsign to have recent GPS data in aprs.fi for location lookup.

Example Usage
~~~~~~~~~~~~~

Send an APRS message to your APRSD server:

.. code::

   m

   or

   metar

   or

   m N0CALL

   or

   metar N0CALL

The plugin will respond with the raw METAR report for the nearest weather station to the callsign's location, for example:

.. code::

   KJFK 251851Z 36010KT 10SM FEW250 12/03 A3012 RMK AO2 SLP201 T01220028

If the callsign doesn't have location data in aprs.fi, or if the AVWX API is unavailable, an error message will be returned.


Contributing
------------

Contributions are very welcome.
To learn more, see the `Contributor Guide`_.


License
-------

Distributed under the terms of the `MIT license`_,
*AVWX Api based APRSD plugins* is free and open source software.


Issues
------

If you encounter any problems,
please `file an issue`_ along with a detailed description.


Credits
-------

This project was generated from `@hemna`_'s `APRSD Plugin Python Cookiecutter`_ template.

.. _@hemna: https://github.com/hemna
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _MIT license: https://opensource.org/licenses/MIT
.. _PyPI: https://pypi.org/
.. _APRSD Plugin Python Cookiecutter: https://github.com/hemna/cookiecutter-aprsd-plugin
.. _file an issue: https://github.com/hemna/aprsd-avwx-plugin/issues
.. _pip: https://pip.pypa.io/
.. _avwx-engine: https://github.com/avwx-rest/avwx-engine
.. _https://info.avwx.rest/: https://info.avwx.rest/
.. github-only
.. _Contributor Guide: CONTRIBUTING.rst
.. _Usage: https://aprsd-avwx-plugin.readthedocs.io/en/latest/usage.html
