mirror of
https://github.com/craigerl/aprsd.git
synced 2026-06-05 15:44:40 -04:00
Added Sphinx based documentation
This patch adds the docuemntation source tree in docs. You can build the documentation with tox -edocs View the documentation by opening a browser and viewing aprsd/docs/_build/index.html
This commit is contained in:
Vendored
Vendored
@@ -0,0 +1,77 @@
|
||||
aprsd.plugins package
|
||||
=====================
|
||||
|
||||
Submodules
|
||||
----------
|
||||
|
||||
aprsd.plugins.email module
|
||||
--------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.email
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.fortune module
|
||||
----------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.fortune
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.location module
|
||||
-----------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.location
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.ping module
|
||||
-------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.ping
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.query module
|
||||
--------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.query
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.time module
|
||||
-------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.time
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.version module
|
||||
----------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.version
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugins.weather module
|
||||
----------------------------
|
||||
|
||||
.. automodule:: aprsd.plugins.weather
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Module contents
|
||||
---------------
|
||||
|
||||
.. automodule:: aprsd.plugins
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -0,0 +1,93 @@
|
||||
aprsd package
|
||||
=============
|
||||
|
||||
Subpackages
|
||||
-----------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
aprsd.plugins
|
||||
|
||||
Submodules
|
||||
----------
|
||||
|
||||
aprsd.client module
|
||||
-------------------
|
||||
|
||||
.. automodule:: aprsd.client
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.email module
|
||||
------------------
|
||||
|
||||
.. automodule:: aprsd.email
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.fake\_aprs module
|
||||
-----------------------
|
||||
|
||||
.. automodule:: aprsd.fake_aprs
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.fuzzyclock module
|
||||
-----------------------
|
||||
|
||||
.. automodule:: aprsd.fuzzyclock
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.main module
|
||||
-----------------
|
||||
|
||||
.. automodule:: aprsd.main
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.messaging module
|
||||
----------------------
|
||||
|
||||
.. automodule:: aprsd.messaging
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.plugin module
|
||||
-------------------
|
||||
|
||||
.. automodule:: aprsd.plugin
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.threads module
|
||||
--------------------
|
||||
|
||||
.. automodule:: aprsd.threads
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
aprsd.utils module
|
||||
------------------
|
||||
|
||||
.. automodule:: aprsd.utils
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
Module contents
|
||||
---------------
|
||||
|
||||
.. automodule:: aprsd
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
@@ -0,0 +1,7 @@
|
||||
aprsd
|
||||
=====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
aprsd
|
||||
@@ -0,0 +1,22 @@
|
||||
#!/usr/bin/env python3
|
||||
|
||||
"""Removes temporary Sphinx build artifacts to ensure a clean build.
|
||||
|
||||
This is needed if the Python source being documented changes significantly. Old sphinx-apidoc
|
||||
RST files can be left behind.
|
||||
"""
|
||||
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
|
||||
|
||||
def main() -> None:
|
||||
docs_dir = Path(__file__).resolve().parent
|
||||
for folder in ("_build", "apidoc"):
|
||||
delete_dir = docs_dir / folder
|
||||
if delete_dir.exists():
|
||||
shutil.rmtree(delete_dir)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+188
@@ -0,0 +1,188 @@
|
||||
#
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file does only contain a selection of the most common options. For a
|
||||
# full list see the documentation:
|
||||
# http://www.sphinx-doc.org/en/master/config
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, os.path.abspath("../src"))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = "APRSD"
|
||||
copyright = ""
|
||||
author = "Craig Lamparter"
|
||||
|
||||
# The short X.Y version
|
||||
version = "v1.5.0"
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = ""
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.doctest",
|
||||
"sphinx.ext.todo",
|
||||
"sphinx.ext.viewcode",
|
||||
"sphinx.ext.napoleon",
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ["_templates"]
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = ".rst"
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = "index"
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = None
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = "alabaster"
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
html_theme_options = {
|
||||
# Override the default alabaster line wrap, which wraps tightly at 940px.
|
||||
"page_width": "auto",
|
||||
}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ["_static"]
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# The default sidebars (for documents that don't match any pattern) are
|
||||
# defined by theme itself. Builtin themes are using these templates by
|
||||
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
|
||||
# 'searchbox.html']``.
|
||||
#
|
||||
# html_sidebars = {}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ---------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = "adoc"
|
||||
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, "a.tex", "a Documentation", "a", "manual"),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ------------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [(master_doc, "a", "a Documentation", [author], 1)]
|
||||
|
||||
|
||||
# -- Options for Texinfo output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(
|
||||
master_doc,
|
||||
"a",
|
||||
"a Documentation",
|
||||
author,
|
||||
"a",
|
||||
"One line description of project.",
|
||||
"Miscellaneous",
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Epub output -------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
|
||||
# The unique identifier of the text. This can be a ISBN number
|
||||
# or the project homepage.
|
||||
#
|
||||
# epub_identifier = ''
|
||||
|
||||
# A unique identification for the text.
|
||||
#
|
||||
# epub_uid = ''
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ["search.html"]
|
||||
|
||||
|
||||
# -- Extension configuration -------------------------------------------------
|
||||
|
||||
# -- Options for todo extension ----------------------------------------------
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = True
|
||||
@@ -0,0 +1,71 @@
|
||||
APRSD Configure
|
||||
===============
|
||||
|
||||
Configure APRSD
|
||||
------------------------
|
||||
|
||||
Once APRSD is :doc:`installed <install>` You will need to configure the config file
|
||||
for running.
|
||||
|
||||
|
||||
Generate config file
|
||||
---------------------
|
||||
If you have never run the server, running it the first time will generate
|
||||
a sample config file in the default location of ~/.config/aprsd/aprsd.yml
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
└─[$] -> aprsd server
|
||||
Load config
|
||||
/home/aprsd/.config/aprsd/aprsd.yml is missing, creating config file
|
||||
Default config file created at /home/aprsd/.config/aprsd/aprsd.yml. Please edit with your settings.
|
||||
|
||||
You can see the sample config file output
|
||||
|
||||
Sample config file
|
||||
------------------
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
└─[$] -> cat ~/.config/aprsd/aprsd.yml
|
||||
aprs:
|
||||
host: rotate.aprs.net
|
||||
logfile: /tmp/arsd.log
|
||||
login: someusername
|
||||
password: somepassword
|
||||
port: 14580
|
||||
aprsd:
|
||||
enabled_plugins:
|
||||
- aprsd.plugins.email.EmailPlugin
|
||||
- aprsd.plugins.fortune.FortunePlugin
|
||||
- aprsd.plugins.location.LocationPlugin
|
||||
- aprsd.plugins.ping.PingPlugin
|
||||
- aprsd.plugins.query.QueryPlugin
|
||||
- aprsd.plugins.time.TimePlugin
|
||||
- aprsd.plugins.weather.WeatherPlugin
|
||||
- aprsd.plugins.version.VersionPlugin
|
||||
plugin_dir: ~/.config/aprsd/plugins
|
||||
ham:
|
||||
callsign: KFART
|
||||
imap:
|
||||
host: imap.gmail.com
|
||||
login: imapuser
|
||||
password: something here too
|
||||
port: 993
|
||||
use_ssl: true
|
||||
shortcuts:
|
||||
aa: 5551239999@vtext.com
|
||||
cl: craiglamparter@somedomain.org
|
||||
wb: 555309@vtext.com
|
||||
smtp:
|
||||
host: imap.gmail.com
|
||||
login: something
|
||||
password: some lame password
|
||||
port: 465
|
||||
use_ssl: false
|
||||
|
||||
|
||||
Note, You must edit the config file and change the ham callsign to your
|
||||
legal FCC HAM callsign, or aprsd server will not start.
|
||||
|
||||
.. include:: links.rst
|
||||
@@ -0,0 +1,30 @@
|
||||
.. a documentation master file, created by
|
||||
sphinx-quickstart on Wed Dec 19 18:34:22 2018.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
``APRSD`` Documentation
|
||||
=======================
|
||||
|
||||
.. include:: readme.rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
readme
|
||||
install
|
||||
configure
|
||||
server
|
||||
plugin
|
||||
|
||||
apidoc/modules.rst
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. include:: links.rst
|
||||
@@ -0,0 +1,67 @@
|
||||
APRSD installation
|
||||
==================
|
||||
|
||||
Install info in a nutshell
|
||||
--------------------------
|
||||
|
||||
**Pythons**: Python 3.6 or later
|
||||
|
||||
**Operating systems**: Linux, OSX, Unix
|
||||
|
||||
**Installer Requirements**: setuptools_
|
||||
|
||||
**License**: Apache license
|
||||
|
||||
**git repository**: https://github.com/craigerl/aprsd
|
||||
|
||||
Installation with pip
|
||||
--------------------------------------
|
||||
|
||||
Use the following command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
pip install aprsd
|
||||
|
||||
It is fine to install ``aprsd`` itself into a virtualenv_ environment.
|
||||
|
||||
Install from clone
|
||||
-------------------------
|
||||
|
||||
Consult the GitHub page how to clone the git repository:
|
||||
|
||||
https://github.com/craigerl/aprsd
|
||||
|
||||
and then install in your environment with something like:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ cd <path/to/clone>
|
||||
$ pip install .
|
||||
|
||||
or install it `editable <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_ if you want code changes to propagate automatically:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ cd <path/to/clone>
|
||||
$ pip install --editable .
|
||||
|
||||
so that you can do changes and submit patches.
|
||||
|
||||
|
||||
Install for development
|
||||
----------------------------
|
||||
|
||||
For developers you should clone the repo from github, then use the Makefile
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ cd <path/to/clone>
|
||||
$ make
|
||||
|
||||
This creates a virtualenv_ directory, install all the requirements for
|
||||
development as well as aprsd in `editable <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_ mode.
|
||||
It will install all of the pre-commit git hooks required to test prior to committing code.
|
||||
|
||||
|
||||
.. include:: links.rst
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _`Cookiecutter`: https://cookiecutter.readthedocs.io
|
||||
.. _`pluggy`: https://pluggy.readthedocs.io
|
||||
.. _`cookiecutter-tox-plugin`: https://github.com/tox-dev/cookiecutter-tox-plugin
|
||||
.. _devpi: https://doc.devpi.net
|
||||
.. _Python: https://www.python.org
|
||||
.. _virtualenv: https://pypi.org/project/virtualenv
|
||||
.. _`pytest`: https://pytest.org
|
||||
.. _nosetests:
|
||||
.. _`nose`: https://pypi.org/project/nose
|
||||
.. _`Holger Krekel`: https://twitter.com/hpk42
|
||||
.. _`pytest-xdist`: https://pypi.org/project/pytest-xdist
|
||||
.. _ConfigParser: https://docs.python.org/3/library/configparser.html
|
||||
|
||||
.. _`easy_install`: http://peak.telecommunity.com/DevCenter/EasyInstall
|
||||
.. _pip: https://pypi.org/project/pip
|
||||
.. _setuptools: https://pypi.org/project/setuptools
|
||||
.. _`jenkins`: https://jenkins.io/index.html
|
||||
.. _sphinx: https://pypi.org/project/Sphinx
|
||||
.. _discover: https://pypi.org/project/discover
|
||||
.. _unittest2: https://pypi.org/project/unittest2
|
||||
.. _mock: https://pypi.org/project/mock/
|
||||
.. _flit: https://flit.readthedocs.io/en/latest/
|
||||
.. _poetry: https://poetry.eustace.io/
|
||||
.. _pypy: https://pypy.org
|
||||
|
||||
.. _`Python Packaging Guide`: https://packaging.python.org/tutorials/packaging-projects/
|
||||
.. _`tox.ini`: :doc:configfile
|
||||
|
||||
.. _`PEP-508`: https://www.python.org/dev/peps/pep-0508/
|
||||
.. _`PEP-517`: https://www.python.org/dev/peps/pep-0517/
|
||||
.. _`PEP-518`: https://www.python.org/dev/peps/pep-0518/
|
||||
@@ -0,0 +1,55 @@
|
||||
APRSD Command Plugin Development
|
||||
================================
|
||||
|
||||
APRSDPluginBase
|
||||
------------------------
|
||||
|
||||
Plugins are written as python objects that extend the APRSDPluginBase class.
|
||||
This is an abstract class that has several properties and a method that must be implemented
|
||||
by your subclass.
|
||||
|
||||
Properties
|
||||
----------
|
||||
|
||||
* name - the Command name
|
||||
* regex - The regular expression that if matched against the incoming APRS message,
|
||||
will cause your plugin to be called.
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
* command - This method is called when the regex matches the incoming message from APRS.
|
||||
If you want to send a message back to the sending, just return a string
|
||||
in your method implementation. If you get called and don't want to reply, then
|
||||
you should return a messaging.NULL_MESSAGE to signal to the plugin processor
|
||||
that you got called and processed the message correctly. Otherwise a usage
|
||||
string may get returned to the sender.
|
||||
|
||||
|
||||
Example Plugin
|
||||
--------------
|
||||
|
||||
There is an example plugin in the aprsd source code here:
|
||||
aprsd/examples/plugins/example_plugin.py
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
|
||||
from aprsd import plugin
|
||||
|
||||
LOG = logging.getLogger("APRSD")
|
||||
|
||||
|
||||
class HelloPlugin(plugin.APRSDPluginBase):
|
||||
"""Hello World."""
|
||||
|
||||
version = "1.0"
|
||||
# matches any string starting with h or H
|
||||
command_regex = "^[hH]"
|
||||
command_name = "hello"
|
||||
|
||||
def command(self, fromcall, message, ack):
|
||||
LOG.info("HelloPlugin")
|
||||
reply = "Hello '{}'".format(fromcall)
|
||||
return reply
|
||||
+392
@@ -0,0 +1,392 @@
|
||||
APRSD
|
||||
-----
|
||||
|
||||
.. image:: https://badge.fury.io/py/aprsd.svg
|
||||
:target: https://badge.fury.io/py/aprsd
|
||||
|
||||
.. image:: https://github.com/craigerl/aprsd/workflows/python/badge.svg
|
||||
:target: https://github.com/craigerl/aprsd/actions
|
||||
|
||||
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
||||
:target: https://black.readthedocs.io/en/stable/
|
||||
|
||||
.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
|
||||
:target: https://timothycrosley.github.io/isort/
|
||||
|
||||
.. image:: https://static.pepy.tech/personalized-badge/aprsd?period=month&units=international_system&left_color=black&right_color=orange&left_text=Downloads
|
||||
:target: https://pepy.tech/project/aprsd
|
||||
|
||||
|
||||
Summary
|
||||
=======
|
||||
|
||||
`APRSD <http://github.com/craigerl/aprsd>`_ is a Ham radio `APRS <http://aprs.org>`_ message command gateway built on python.
|
||||
|
||||
APRSD listens on amateur radio aprs-is network for messages and respond to them.
|
||||
It has a plugin architecture for extensibility. Users of APRSD can write their own
|
||||
plugins that can respond to APRS-IS messages.
|
||||
|
||||
You must have an amateur radio callsign to use this software. APRSD gets
|
||||
messages for the configured HAM callsign, and sends those messages to a
|
||||
list of plugins for processing. There are a set of core plugins that
|
||||
provide responding to messages to check email, get location, ping,
|
||||
time of day, get weather, and fortune telling as well as version information
|
||||
of aprsd itself.
|
||||
|
||||
Typical use case
|
||||
================
|
||||
|
||||
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.
|
||||
|
||||
|
||||
APRSD Capabilities
|
||||
==================
|
||||
|
||||
* server - The main aprsd server processor. Send/Rx APRS messages to HAM callsign
|
||||
* send-message - use aprsd to send a command/message to aprsd server. Used for development testing
|
||||
* sample-config - generate a sample aprsd.yml config file for use/editing
|
||||
* bash completion generation. Uses python click bash completion to generate completion code for your .bashrc/.zshrc
|
||||
|
||||
|
||||
List of core server plugins
|
||||
===========================
|
||||
|
||||
Plugins function by specifying a regex that is searched for in the APRS message.
|
||||
If it matches, the plugin runs. IF the regex doesn't match, the plugin is skipped.
|
||||
|
||||
* EmailPlugin - Check email and reply with contents. Have to configure IMAP and SMTP settings in aprs.yml
|
||||
* FortunePlugin - Replies with old unix fortune random fortune!
|
||||
* LocationPlugin - Checks location of ham operator
|
||||
* PingPlugin - Sends pong with timestamp
|
||||
* QueryPlugin - Allows querying the list of delayed messages that were not ACK'd by radio
|
||||
* TimePlugin - Current time of day
|
||||
* WeatherPlugin - Get weather conditions for current location of HAM callsign
|
||||
* VersionPlugin - Reports the version information for aprsd
|
||||
|
||||
|
||||
Current messages this will respond to:
|
||||
======================================
|
||||
|
||||
::
|
||||
|
||||
APRS messages:
|
||||
l(ocation) [callsign] = descriptive current location of your radio
|
||||
8 Miles E Auburn CA 1673' 39.92150,-120.93950 0.1h ago
|
||||
w(eather) = weather forecast for your radio's current position
|
||||
58F(58F/46F) Partly Cloudy. Tonight, Heavy Rain.
|
||||
t(ime) = respond with the current time
|
||||
f(ortune) = respond with a short fortune
|
||||
-email_addr email text = send an email, say "mapme" to send a current position/map
|
||||
-2 = resend the last 2 emails from your imap inbox to this radio
|
||||
p(ing) = respond with Pong!/time
|
||||
v(ersion) = Respond with current APRSD Version string
|
||||
anything else = respond with usage
|
||||
|
||||
|
||||
Meanwhile this code will monitor a single imap mailbox and forward email
|
||||
to your BASECALLSIGN over the air. Only radios using the BASECALLSIGN are allowed
|
||||
to send email, so consider this security risk before using this (or Amatuer radio in
|
||||
general). Email is single user at this time.
|
||||
|
||||
There are additional parameters in the code (sorry), so be sure to set your
|
||||
email server, and associated logins, passwords. search for "yourdomain",
|
||||
"password". Search for "shortcuts" to setup email aliases as well.
|
||||
|
||||
|
||||
Example usage:
|
||||
==============
|
||||
|
||||
aprsd -h
|
||||
|
||||
Help
|
||||
====
|
||||
::
|
||||
|
||||
└─[$] > aprsd -h
|
||||
Usage: aprsd [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Shell completion for click-completion-command Available shell types:
|
||||
bash Bourne again shell fish Friendly interactive shell
|
||||
powershell Windows PowerShell zsh Z shell Default type: auto
|
||||
|
||||
Options:
|
||||
--version Show the version and exit.
|
||||
-h, --help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
install Install the click-completion-command completion
|
||||
sample-config This dumps the config to stdout.
|
||||
send-message Send a message to a callsign via APRS_IS.
|
||||
server Start the aprsd server process.
|
||||
show Show the click-completion-command completion code
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
Output
|
||||
======
|
||||
::
|
||||
|
||||
└─[$] > aprsd sample-config
|
||||
|
||||
aprs:
|
||||
host: rotate.aprs.net
|
||||
logfile: /tmp/arsd.log
|
||||
login: someusername
|
||||
password: somepassword
|
||||
port: 14580
|
||||
aprsd:
|
||||
enabled_plugins:
|
||||
- aprsd.plugin.EmailPlugin
|
||||
- aprsd.plugin.FortunePlugin
|
||||
- aprsd.plugin.LocationPlugin
|
||||
- aprsd.plugin.PingPlugin
|
||||
- aprsd.plugin.TimePlugin
|
||||
- aprsd.plugin.WeatherPlugin
|
||||
- aprsd.plugin.VersionPlugin
|
||||
plugin_dir: ~/.config/aprsd/plugins
|
||||
ham:
|
||||
callsign: KFART
|
||||
imap:
|
||||
host: imap.gmail.com
|
||||
login: imapuser
|
||||
password: something here too
|
||||
port: 993
|
||||
use_ssl: true
|
||||
shortcuts:
|
||||
aa: 5551239999@vtext.com
|
||||
cl: craiglamparter@somedomain.org
|
||||
wb: 555309@vtext.com
|
||||
smtp:
|
||||
host: imap.gmail.com
|
||||
login: something
|
||||
password: some lame password
|
||||
port: 465
|
||||
use_ssl: false
|
||||
|
||||
|
||||
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
|
||||
|
||||
::
|
||||
|
||||
└─[$] > aprsd server --help
|
||||
Usage: aprsd server [OPTIONS]
|
||||
|
||||
Start the aprsd server process.
|
||||
|
||||
Options:
|
||||
--loglevel [CRITICAL|ERROR|WARNING|INFO|DEBUG]
|
||||
The log level to use for aprsd.log
|
||||
[default: DEBUG]
|
||||
|
||||
--quiet Don't log to stdout
|
||||
--disable-validation Disable email shortcut validation. Bad
|
||||
email addresses can result in broken email
|
||||
responses!!
|
||||
|
||||
-c, --config TEXT The aprsd config file to use for options.
|
||||
[default: ~/.config/aprsd/aprsd.yml]
|
||||
|
||||
-h, --help Show this message and exit.
|
||||
(.venv3) ┌─[waboring@dl360-1] - [~/devel/aprsd] - [Sun Dec 20, 12:32] -
|
||||
└─[$] <git:(master*)> aprsd server
|
||||
Load config
|
||||
[12/20/2020 12:33:03 PM] [MainThread ] [INFO ] APRSD Started version: 1.0.2
|
||||
[12/20/2020 12:33:03 PM] [MainThread ] [INFO ] Checking IMAP configuration
|
||||
[12/20/2020 12:33:04 PM] [MainThread ] [INFO ] Checking SMTP configuration
|
||||
|
||||
|
||||
send-message
|
||||
------------
|
||||
|
||||
This command is typically used for development to send another aprsd instance
|
||||
test messages
|
||||
|
||||
::
|
||||
|
||||
└─[$] > aprsd send-message -h
|
||||
Usage: aprsd send-message [OPTIONS] TOCALLSIGN [COMMAND]...
|
||||
|
||||
Send a message to a callsign via APRS_IS.
|
||||
|
||||
Options:
|
||||
--loglevel [CRITICAL|ERROR|WARNING|INFO|DEBUG]
|
||||
The log level to use for aprsd.log
|
||||
[default: DEBUG]
|
||||
|
||||
--quiet Don't log to stdout
|
||||
-c, --config TEXT The aprsd config file to use for options.
|
||||
[default: ~/.config/aprsd/aprsd.yml]
|
||||
|
||||
--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]
|
||||
|
||||
-h, --help Show this message and exit.
|
||||
|
||||
|
||||
Example Message output:
|
||||
-----------------------
|
||||
|
||||
|
||||
SEND EMAIL (radio to smtp server)
|
||||
=================================
|
||||
|
||||
::
|
||||
|
||||
Received message______________
|
||||
Raw : KM6XXX>APY400,WIDE1-1,qAO,KM6XXX-1::KM6XXX-9 :-user@host.com test new shortcuts global, radio to pc{29
|
||||
From : KM6XXX
|
||||
Message : -user@host.com test new shortcuts global, radio to pc
|
||||
Msg number : 29
|
||||
|
||||
Sending Email_________________
|
||||
To : user@host.com
|
||||
Subject : KM6XXX
|
||||
Body : test new shortcuts global, radio to pc
|
||||
|
||||
Sending ack __________________ Tx(3)
|
||||
Raw : KM6XXX-9>APRS::KM6XXX :ack29
|
||||
To : KM6XXX
|
||||
Ack number : 29
|
||||
|
||||
|
||||
RECEIVE EMAIL (imap server to radio)
|
||||
====================================
|
||||
|
||||
::
|
||||
|
||||
Sending message_______________ 6(Tx3)
|
||||
Raw : KM6XXX-9>APRS::KM6XXX :-somebody@gmail.com email from internet to radio{6
|
||||
To : KM6XXX
|
||||
Message : -somebody@gmail.com email from internet to radio
|
||||
|
||||
Received message______________
|
||||
Raw : KM6XXX>APY400,WIDE1-1,qAO,KM6XXX-1::KM6XXX-9 :ack6
|
||||
From : KM6XXX
|
||||
Message : ack6
|
||||
Msg number : 0
|
||||
|
||||
|
||||
LOCATION
|
||||
========
|
||||
|
||||
::
|
||||
|
||||
Received Message _______________
|
||||
Raw : KM6XXX-6>APRS,TCPIP*,qAC,T2CAEAST::KM6XXX-14:location{2
|
||||
From : KM6XXX-6
|
||||
Message : location
|
||||
Msg number : 2
|
||||
Received Message _______________ Complete
|
||||
|
||||
Sending Message _______________
|
||||
Raw : KM6XXX-14>APRS::KM6XXX-6 :KM6XXX-6: 8 Miles E Auburn CA 0' 0,-120.93584 1873.7h ago{2
|
||||
To : KM6XXX-6
|
||||
Message : KM6XXX-6: 8 Miles E Auburn CA 0' 0,-120.93584 1873.7h ago
|
||||
Msg number : 2
|
||||
Sending Message _______________ Complete
|
||||
|
||||
Sending ack _______________
|
||||
Raw : KM6XXX-14>APRS::KM6XXX-6 :ack2
|
||||
To : KM6XXX-6
|
||||
Ack : 2
|
||||
Sending ack _______________ Complete
|
||||
|
||||
AND... ping, fortune, time.....
|
||||
|
||||
|
||||
Development
|
||||
-----------
|
||||
|
||||
* git clone git@github.com:craigerl/aprsd.git
|
||||
* cd aprsd
|
||||
* make
|
||||
|
||||
Workflow
|
||||
========
|
||||
|
||||
While working aprsd, The workflow is as follows
|
||||
|
||||
* Edit code, save file
|
||||
* run tox -efmt
|
||||
* run tox -p
|
||||
* git commit ( This will run the pre-commit hooks which does checks too )
|
||||
|
||||
|
||||
Release
|
||||
=======
|
||||
|
||||
To do release to pypi:
|
||||
|
||||
* Tag release with
|
||||
|
||||
git tag -v1.XX -m "New release"
|
||||
|
||||
* push release tag up
|
||||
|
||||
git push origin master --tags
|
||||
|
||||
* Do a test build and verify build is valid
|
||||
|
||||
make build
|
||||
|
||||
* Once twine is happy, upload release to pypi
|
||||
|
||||
make upload
|
||||
|
||||
|
||||
Docker Container
|
||||
----------------
|
||||
|
||||
Building
|
||||
========
|
||||
|
||||
There are 2 versions of the container Dockerfile that can be used.
|
||||
The main Dockerfile, which is for building the official release container
|
||||
based off of the pip install version of aprsd and the Dockerfile-dev,
|
||||
which is used for building a container based off of a git branch of
|
||||
the repo.
|
||||
|
||||
Official Build
|
||||
==============
|
||||
|
||||
docker build -t hemna6969/aprsd:latest .
|
||||
|
||||
Development Build
|
||||
=================
|
||||
|
||||
docker build -t hemna6969/aprsd:latest -f Dockerfile-dev .
|
||||
|
||||
|
||||
Running the container
|
||||
=====================
|
||||
|
||||
There is a docker-compose.yml file that can be used to run your container.
|
||||
There are 2 volumes defined that can be used to store your configuration
|
||||
and the plugins directory: /config and /plugins
|
||||
|
||||
If you want to install plugins at container start time, then use the
|
||||
environment var in docker-compose.yml specified as APRS_PLUGINS
|
||||
Provide a csv list of pypi installable plugins. Then make sure the plugin
|
||||
python file is in your /plugins volume and the plugin will be installed at
|
||||
container startup. The plugin may have dependencies that are required.
|
||||
The plugin file should be copied to /plugins for loading by aprsd
|
||||
@@ -0,0 +1,53 @@
|
||||
APRSD server
|
||||
============
|
||||
|
||||
Running the APRSD server
|
||||
------------------------
|
||||
|
||||
Once APRSD is :doc:`installed <install>` and :doc:`configured <configure>` the server can be started by
|
||||
running.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
aprsd server
|
||||
|
||||
The server will start several threads to deal handle incoming messages, outgoing
|
||||
messages, checking and sending email.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
[MainThread ] [INFO ] APRSD Started version: 1.5.1
|
||||
[MainThread ] [INFO ] Checking IMAP configuration
|
||||
[MainThread ] [INFO ] Checking SMTP configuration
|
||||
[MainThread ] [DEBUG] Connect to SMTP host SSL smtp.gmail.com:465 with user 'test@hemna.com'
|
||||
[MainThread ] [DEBUG] Connected to smtp host SSL smtp.gmail.com:465
|
||||
[MainThread ] [DEBUG] Logged into SMTP server SSL smtp.gmail.com:465
|
||||
[MainThread ] [INFO ] Validating 2 Email shortcuts. This can take up to 10 seconds per shortcut
|
||||
[MainThread ] [ERROR] 'craiglamparter@somedomain.org' is an invalid email address. Removing shortcut
|
||||
[MainThread ] [INFO ] Available shortcuts: {'wb': 'waboring@hemna.com'}
|
||||
[MainThread ] [INFO ] Loading Core APRSD Command Plugins
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.email.EmailPlugin'(1.0) '^-.*'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.fortune.FortunePlugin'(1.0) '^[fF]'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.location.LocationPlugin'(1.0) '^[lL]'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.ping.PingPlugin'(1.0) '^[pP]'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.query.QueryPlugin'(1.0) '^\?.*'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.time.TimePlugin'(1.0) '^[tT]'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.weather.WeatherPlugin'(1.0) '^[wW]'
|
||||
[MainThread ] [INFO ] Registering Command plugin 'aprsd.plugins.version.VersionPlugin'(1.0) '^[vV]'
|
||||
[MainThread ] [INFO ] Skipping Custom Plugins directory.
|
||||
[MainThread ] [INFO ] Completed Plugin Loading.
|
||||
[MainThread ] [DEBUG] Loading saved MsgTrack object.
|
||||
[RX_MSG ] [INFO ] Starting
|
||||
[TX_MSG ] [INFO ] Starting
|
||||
[MainThread ] [DEBUG] KeepAlive Tracker(0): {}
|
||||
[RX_MSG ] [INFO ] Creating aprslib client
|
||||
[RX_MSG ] [INFO ] Attempting connection to noam.aprs2.net:14580
|
||||
[RX_MSG ] [INFO ] Connected to ('198.50.198.139', 14580)
|
||||
[RX_MSG ] [DEBUG] Banner: # aprsc 2.1.8-gf8824e8
|
||||
[RX_MSG ] [INFO ] Sending login information
|
||||
[RX_MSG ] [DEBUG] Server: # logresp KM6XXX-14 verified, server T2VAN
|
||||
[RX_MSG ] [INFO ] Login successful
|
||||
[RX_MSG ] [DEBUG] Logging in to APRS-IS with user 'KM6XXX-14'
|
||||
|
||||
|
||||
.. include:: links.rst
|
||||
Reference in New Issue
Block a user