#.`Current list extensions <#current-list-extensions>`_
#.`send-message <#send-message>`_
#.`Development <#development>`_
#.`Release <#release>`_
#.`Building your own APRSD plugins <#building-your-own-aprsd-plugins>`_
#.`Docker Container <#docker-container>`_
#.`Running the container <#running-the-container>`_
#.`Activity <#activity>`_
#.`Star History <#star-history>`_
----
..
[!WARNING]
Legal operation of this software requires an amateur radio license and a valid call sign.
[!NOTE]
Star this repo to follow our progress! This code is under active development, and contributions are both welcomed and appreciated. See `CONTRIBUTING.md <https://github.com/craigerl/aprsd/blob/master/CONTRIBUTING.md>`_ for details.
What is APRSD
-------------
APRSD is a python application for interacting with the APRS network and Ham radios with KISS interfaces and
providing APRS services for HAM radio operators.
APRSD currently has the following commands to use.
* server - Start the aprsd server gateway process.
* listen - Listen to packets on the APRS-IS Network based on FILTER.
* send-message - Send a message to a callsign via APRS_IS.
* check-version - Check this version against the latest in pypi.org.
* completion - Show the shell completion code
* dev - Development type subcommands
* dump-stats - Dump the current stats from the running APRSD instance.
* fetch-stats - Fetch stats from a APRSD admin web interface.
* healthcheck - Check the health of the running aprsd server.
* list-extensions - List the built in extensions available to APRSD.
* list-plugins - List the built in plugins available to APRSD.
* passcode - Generate an APRS passcode for a callsign.
* sample-config - Generate a sample Config file from aprsd and all...
* version - Show the APRSD version.
Each of those commands can connect to the APRS-IS network if internet
connectivity is available. If internet is not available, then APRS can
be configured to talk to a TCP KISS TNC for radio connectivity directly.
APRSD Has the ability to add plugins and extensions. Plugins add new message filters that can look for specific messages and respond. For example, the aprsd-email-plugin adds the ability to send/recieve email to/from an APRS callsign. Extensions add new unique capabilities to APRSD itself. For example the aprsd-admin-extension adds a web interface command that shows the running status of the aprsd server command. aprsd-webchat-extension is a new web based APRS 'chat' command.
You can see the `available plugins/extensions on pypi here: <https://pypi.org/search/?q=aprsd>`_`https://pypi.org/search/?q=aprsd <https://pypi.org/search/?q=aprsd>`_
..
[!NOTE]
aprsd admin and webchat commands have been extracted into separate extensions.
APRSD\'s typical use case is that of providing an APRS wide service to
all HAM radio operators. For example the callsign \'REPEAT\' on the APRS
network is actually an instance of APRSD that can provide a list of HAM
repeaters in the area of the callsign that sent the message.
Ham radio operator using an APRS enabled HAM radio sends a message to
check the weather. An APRS message is sent, and then picked up by APRSD.
The APRS packet is decoded, and the message is sent through the list of
plugins for processing. For example, the WeatherPlugin picks up the
message, fetches the weather for the area around the user who sent the
request, and then responds with the weather conditions in that area.
Also includes a watch list of HAM callsigns to look out for. The watch
list can notify you when a HAM callsign in the list is seen and now
available to message on the APRS network.
Installation
------------
**Install uv (recommended):**
``uv`` is a fast Python package installer and resolver. To install ``uv``\ , visit `https://docs.astral.sh/uv/getting-started/installation/ <https://docs.astral.sh/uv/getting-started/installation/>`_
To install ``aprsd``\ , use uv:
``uv pip install aprsd``
Or with the traditional pip:
``pip install aprsd``
Example usage
-------------
``aprsd -h``
Help
----
:
..code-block::
└─> aprsd -h
Usage: aprsd [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
check-version Check this version against the latest in pypi.org.
completion Show the shell completion code
dev Development type subcommands
fetch-stats Fetch stats from a APRSD admin web interface.
healthcheck Check the health of the running aprsd server.
list-extensions List the built in plugins available to APRSD.
list-plugins List the built in plugins available to APRSD.
listen Listen to packets on the APRS-IS Network based on FILTER.
sample-config Generate a sample Config file from aprsd and all...
send-message Send a message to a callsign via APRS_IS.
server Start the aprsd server gateway process.
version Show the APRSD version.
Commands
--------
Configuration
^^^^^^^^^^^^^
This command outputs a sample config yml formatted block that you can
edit and use to pass in to ``aprsd`` with ``-c``. By default aprsd looks in
``~/.config/aprsd/aprsd.yml``
``aprsd sample-config``
..code-block::
└─> aprsd sample-config
...
server
^^^^^^
This is the main server command that will listen to APRS-IS servers and
look for incomming commands to the callsign configured in the config
file
..code-block::
└─[$] > aprsd server --help
Usage: aprsd server [OPTIONS]
Start the aprsd server gateway process.
Options:
--loglevel [CRITICAL|ERROR|WARNING|INFO|DEBUG]
The log level to use for aprsd.log
[default: INFO]
-c, --config TEXT The aprsd config file to use for options.
[default:
/Users/i530566/.config/aprsd/aprsd.yml]
--quiet Don't log to stdout
-f, --flush Flush out all old aged messages on disk.
[default: False]
-h, --help Show this message and exit.
└─> aprsd server
Registering LogMonitorThread
2025-01-06 16:27:12.398 | MainThread | INFO | APRSD is up to date | aprsd.cmds.server:server:82
2025-01-06 16:27:12.398 | MainThread | INFO | APRSD Started version: 4.2.4 | aprsd.cmds.server:server:83
-c, --config TEXT The aprsd config file to use for options.
[default:
/Users/i530566/.config/aprsd/aprsd.yml]
--quiet Don't log to stdout
--aprs-login TEXT What callsign to send the message from.
[env var: APRS_LOGIN]
--aprs-password TEXT the APRS-IS password for APRS_LOGIN [env
var: APRS_PASSWORD]
-n, --no-ack Don't wait for an ack, just sent it to APRS-
IS and bail. [default: False]
-w, --wait-response Wait for a response to the message?
[default: False]
--raw TEXT Send a raw message. Implies --no-ack
-h, --help Show this message and exit.
Development
-----------
*``git clone git@github.com:craigerl/aprsd.git``
*``cd aprsd``
*``make``
Workflow
^^^^^^^^
While working aprsd, The workflow is as follows:
*
Checkout a new branch to work on by running
``git checkout -b mybranch``
*
Make your changes to the code
*
Run Tox with the following options:
*``tox -epep8``
*``tox -efmt``
*``tox -p``
*
Commit your changes. This will run the pre-commit hooks which does
checks too
``git commit``
*
Once you are done with all of your commits, then push up the branch
to github with:
``git push -u origin mybranch``
*
Create a pull request from your branch so github tests can run and
we can do a code review.
Release
^^^^^^^
To do release to pypi:
*
Tag release with:
``git tag -v1.XX -m "New release"``
*
Push release tag:
``git push origin master --tags``
*
Do a test build and verify build is valid by running:
``make build``
*
Once twine is happy, upload release to pypi:
``make upload``
Building your own APRSD plugins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For information on building your own APRSD plugins, see the `Plugin Development documentation <https://aprsd.readthedocs.io/en/latest/plugin.html>`_.
Docker Container
----------------
For information on building Docker containers (official and development builds), see the `Docker Container documentation <https://aprsd.readthedocs.io/en/latest/readme.html#docker-container>`_.
Running the container
---------------------
There is a ``docker-compose.yml`` file in the ``docker/`` directory that can
be used to run your container. To provide the container an ``aprsd.conf``
configuration file, change your ``docker-compose.yml`` as shown below:
..code-block::
volumes:
- $HOME/.config/aprsd:/config
To install plugins at container start time, pass in a list of
comma-separated list of plugins on PyPI using the ``APRSD_PLUGINS``
environment variable in the ``docker-compose.yml`` file. Note that version
