mirror of
https://github.com/hemna/aprsd-weewx-plugin.git
synced 2026-07-29 21:34:12 -04:00
update docs and readme
This commit is contained in:
@@ -0,0 +1,37 @@
|
||||
aprsd\_weewx\_plugin.conf package
|
||||
=================================
|
||||
|
||||
Submodules
|
||||
----------
|
||||
|
||||
aprsd\_weewx\_plugin.conf.main module
|
||||
-------------------------------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin.conf.main
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
|
||||
aprsd\_weewx\_plugin.conf.opts module
|
||||
-------------------------------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin.conf.opts
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
|
||||
aprsd\_weewx\_plugin.conf.weewx module
|
||||
--------------------------------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin.conf.weewx
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
|
||||
Module contents
|
||||
---------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin.conf
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
@@ -0,0 +1,37 @@
|
||||
aprsd\_weewx\_plugin package
|
||||
============================
|
||||
|
||||
Subpackages
|
||||
-----------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
aprsd_weewx_plugin.conf
|
||||
|
||||
Submodules
|
||||
----------
|
||||
|
||||
aprsd\_weewx\_plugin.cli module
|
||||
-------------------------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin.cli
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
|
||||
aprsd\_weewx\_plugin.weewx module
|
||||
---------------------------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin.weewx
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
|
||||
Module contents
|
||||
---------------
|
||||
|
||||
.. automodule:: aprsd_weewx_plugin
|
||||
:members:
|
||||
:show-inheritance:
|
||||
:undoc-members:
|
||||
@@ -0,0 +1,7 @@
|
||||
aprsd_weewx_plugin
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
aprsd_weewx_plugin
|
||||
+4
-1
@@ -1 +1,4 @@
|
||||
.. include:: ../AUTHORS.rst
|
||||
Authors
|
||||
=======
|
||||
|
||||
.. include:: ../AUTHORS
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
CHANGES
|
||||
=======
|
||||
|
||||
v0.3.2
|
||||
------
|
||||
|
||||
* another try
|
||||
|
||||
v0.3.1
|
||||
------
|
||||
|
||||
* Updated pressure \* 10
|
||||
|
||||
v0.3.0
|
||||
------
|
||||
|
||||
* Take the pressure from pressure\_inHg
|
||||
|
||||
v0.2.0
|
||||
------
|
||||
|
||||
* update for 0.2.0
|
||||
* Fixed pep8 failures
|
||||
* Update to aprsd 3.0.0 and include config options!
|
||||
* don't dump the whole packet
|
||||
* use Tx to send
|
||||
* Working with pre 2.7.0
|
||||
* Removed trace
|
||||
* lint
|
||||
* Added pbr version
|
||||
* Fixed missing entry in requirements.txt
|
||||
* Create FUNDING.yml
|
||||
|
||||
v0.1.2
|
||||
------
|
||||
|
||||
* Fixed README.rst formatting
|
||||
* Updated from first repo
|
||||
* Initial commit
|
||||
+17
-15
@@ -20,12 +20,10 @@
|
||||
import os
|
||||
import sys
|
||||
|
||||
|
||||
sys.path.insert(0, os.path.abspath(".."))
|
||||
|
||||
import aprsd_weewx_plugin
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
@@ -34,7 +32,7 @@ import aprsd_weewx_plugin
|
||||
|
||||
# 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.viewcode"]
|
||||
extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "myst_parser"]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ["_templates"]
|
||||
@@ -42,8 +40,10 @@ 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"
|
||||
source_suffix = {
|
||||
".rst": "restructuredtext",
|
||||
".md": "markdown",
|
||||
}
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = "index"
|
||||
@@ -67,7 +67,7 @@ release = aprsd_weewx_plugin.__version__
|
||||
#
|
||||
# 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
|
||||
language = "en"
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
@@ -97,7 +97,7 @@ html_theme = "alabaster"
|
||||
# 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"]
|
||||
# html_static_path = ["_static"] # Commented out since _static directory doesn't exist
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ---------------------------------------
|
||||
@@ -112,15 +112,12 @@ 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',
|
||||
@@ -131,9 +128,11 @@ latex_elements = {
|
||||
# [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(
|
||||
master_doc, "aprsd_weewx_plugin.tex",
|
||||
master_doc,
|
||||
"aprsd_weewx_plugin.tex",
|
||||
"APRSD Weewx Plugin Documentation",
|
||||
"Walter A. Boring IV", "manual",
|
||||
"Walter A. Boring IV",
|
||||
"manual",
|
||||
),
|
||||
]
|
||||
|
||||
@@ -144,9 +143,11 @@ latex_documents = [
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(
|
||||
master_doc, "aprsd_weewx_plugin",
|
||||
master_doc,
|
||||
"aprsd_weewx_plugin",
|
||||
"APRSD Weewx Plugin Documentation",
|
||||
[author], 1,
|
||||
[author],
|
||||
1,
|
||||
),
|
||||
]
|
||||
|
||||
@@ -158,7 +159,8 @@ man_pages = [
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(
|
||||
master_doc, "aprsd_weewx_plugin",
|
||||
master_doc,
|
||||
"aprsd_weewx_plugin",
|
||||
"APRSD Weewx Plugin Documentation",
|
||||
author,
|
||||
"aprsd_weewx_plugin",
|
||||
|
||||
@@ -1 +1,4 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
.. include:: ../CONTRIBUTING.rst
|
||||
|
||||
+4
-1
@@ -1 +1,4 @@
|
||||
.. include:: ../HISTORY.rst
|
||||
History
|
||||
========
|
||||
|
||||
.. include:: ../ChangeLog
|
||||
|
||||
+9
-1
@@ -5,11 +5,19 @@ Welcome to APRSD Nearest station plugin's documentation!
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
readme
|
||||
readme.md
|
||||
installation
|
||||
usage
|
||||
contributing
|
||||
authors
|
||||
history
|
||||
changelog
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
:caption: API Documentation:
|
||||
|
||||
apidoc/modules
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
+88
-1
@@ -4,6 +4,15 @@
|
||||
Installation
|
||||
============
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before installing the plugin, ensure you have:
|
||||
|
||||
* **APRSD** version 4.2.0 or higher installed and configured
|
||||
* **Weewx** weather station software running and configured
|
||||
* Access to an **MQTT broker** (local or remote)
|
||||
* **Python** 3.8 or higher
|
||||
|
||||
Stable release
|
||||
--------------
|
||||
@@ -44,8 +53,86 @@ Once you have a copy of the source, you can install it with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ python setup.py install
|
||||
$ pip install .
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
After installation, you need to configure the plugin in your APRSD configuration file.
|
||||
|
||||
Basic Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Add the plugin to your APRSD configuration (typically ``aprsd.yml``):
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
aprsd:
|
||||
enabled_plugins:
|
||||
- aprsd_weewx_plugin.weewx.WeewxMQTTPlugin
|
||||
|
||||
aprsd_weewx_plugin:
|
||||
enabled: true
|
||||
mqtt_host: localhost
|
||||
mqtt_port: 1883
|
||||
mqtt_user: weewx
|
||||
mqtt_password: your_password_here
|
||||
|
||||
With Automatic Weather Reporting
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To enable automatic weather reporting to APRS-IS, add latitude and longitude:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
aprsd_weewx_plugin:
|
||||
enabled: true
|
||||
mqtt_host: localhost
|
||||
mqtt_port: 1883
|
||||
mqtt_user: weewx
|
||||
mqtt_password: your_password_here
|
||||
latitude: 37.7749
|
||||
longitude: -122.4194
|
||||
report_interval: 300 # Report every 5 minutes (in seconds)
|
||||
|
||||
Configuration Options
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``enabled`` (boolean): Enable/disable the plugin (default: false)
|
||||
* ``mqtt_host`` (string): MQTT broker hostname (required)
|
||||
* ``mqtt_port`` (integer): MQTT broker port (required)
|
||||
* ``mqtt_user`` (string): MQTT username (optional)
|
||||
* ``mqtt_password`` (string): MQTT password (optional, but recommended)
|
||||
* ``latitude`` (float): Station latitude for automatic reporting (optional)
|
||||
* ``longitude`` (float): Station longitude for automatic reporting (optional)
|
||||
* ``report_interval`` (integer): Seconds between automatic reports (default: 60)
|
||||
|
||||
Weewx MQTT Setup
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Ensure your Weewx installation publishes weather data to MQTT. Add this to your Weewx configuration (``weewx.conf``):
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[MQTT]
|
||||
host = localhost
|
||||
port = 1883
|
||||
topic = weather/loop
|
||||
unit_system = US
|
||||
|
||||
The plugin subscribes to the ``weather/loop`` topic and expects JSON-formatted weather data.
|
||||
|
||||
Exporting Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can view all available configuration options using the CLI tool:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ aprsd-weewx-plugin-export-config
|
||||
|
||||
This outputs all configuration options in JSON format.
|
||||
|
||||
.. _Github repo: https://github.com/hemna/aprsd-weewx-plugin
|
||||
.. _tarball: https://github.com/hemna/aprsd-weewx-plugin/tarball/master
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# APRSD Weewx Plugin
|
||||
|
||||
[](https://pypi.org/project/aprsd-weewx-plugin/)
|
||||
[](https://pypi.org/project/aprsd-weewx-plugin/)
|
||||
[](https://pypi.org/project/aprsd-weewx-plugin)
|
||||
[](https://opensource.org/licenses/GNU%20GPL%20v3.0)
|
||||
|
||||
[](https://aprsd-weewx-plugin.readthedocs.io/)
|
||||
[](https://github.com/hemna/aprsd-weewx-plugin/actions?workflow=Tests)
|
||||
[](https://codecov.io/gh/hemna/aprsd-weewx-plugin)
|
||||
[](https://github.com/pre-commit/pre-commit)
|
||||
|
||||
## Features
|
||||
|
||||
* TODO
|
||||
|
||||
## Requirements
|
||||
|
||||
* TODO
|
||||
|
||||
## Installation
|
||||
|
||||
You can install **APRSD Weewx Plugin** via [pip](https://pip.pypa.io/) from [PyPI](https://pypi.org/):
|
||||
|
||||
```console
|
||||
$ pip install aprsd-weewx-plugin
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Please see the [Command-line Reference](https://aprsd-weewx-plugin.readthedocs.io/en/latest/usage.html) for details.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are very welcome.
|
||||
To learn more, see the [Contributor Guide](contributing).
|
||||
|
||||
## License
|
||||
|
||||
Distributed under the terms of the [GNU GPL v3.0 license](https://opensource.org/licenses/GNU%20GPL%20v3.0),
|
||||
**APRSD Weewx Plugin** is free and open source software.
|
||||
|
||||
## Issues
|
||||
|
||||
If you encounter any problems,
|
||||
please [file an issue](https://github.com/hemna/aprsd-weewx-plugin/issues) along with a detailed description.
|
||||
|
||||
## Credits
|
||||
|
||||
This project was generated from [@hemna](https://github.com/hemna)'s [APRSD Plugin Python Cookiecutter](https://github.com/hemna/cookiecutter-aprsd-plugin) template.
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
Usage
|
||||
=====
|
||||
|
||||
The APRSD Weewx Plugin provides two main functions:
|
||||
|
||||
1. **Weather Query Responses**: Responds to APRS messages with current weather data
|
||||
2. **Automatic Weather Reporting**: Periodically sends weather packets to APRS-IS
|
||||
|
||||
Querying Weather via APRS
|
||||
--------------------------
|
||||
|
||||
Once the plugin is configured and running, you can query weather data by sending an APRS message to your station's callsign. The plugin responds to messages that start with ``w`` or ``W``.
|
||||
|
||||
Example Interaction
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Here's a typical interaction:
|
||||
|
||||
**You send:**
|
||||
::
|
||||
|
||||
WB4BOR-1>APRS,TCPIP*:>w WB4BOR
|
||||
|
||||
**Plugin responds:**
|
||||
::
|
||||
|
||||
WB4BOR>APRS,TCPIP*:>WX: 72.5F/54.0F Wind 5@270G12 65% RA 0.00 0.00/hr 29.92inHg
|
||||
|
||||
Response Format
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The weather response follows this format:
|
||||
|
||||
::
|
||||
|
||||
WX: <temp>/<dewpoint> Wind <speed>@<direction>G<gust> <humidity>% RA <day_rain> <rate>/hr <pressure>inHg
|
||||
|
||||
Field Breakdown
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
* **Temperature/Dewpoint**: Current temperature and dewpoint (Fahrenheit or Celsius)
|
||||
* **Wind**: Wind speed (mph or m/s), direction in degrees, and gust speed
|
||||
* **Humidity**: Relative humidity percentage
|
||||
* **Rain**: Daily rainfall total and current rain rate
|
||||
* **Pressure**: Barometric pressure (inHg or mBar)
|
||||
|
||||
Example Responses
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Imperial Units (Fahrenheit, mph, inHg):**
|
||||
::
|
||||
|
||||
WX: 72.5F/54.0F Wind 5@270G12 65% RA 0.00 0.00/hr 29.92inHg
|
||||
|
||||
**Metric Units (Celsius, m/s, mBar):**
|
||||
::
|
||||
|
||||
WX: 22.5C/12.2C Wind 2@270G5 65% RA 0.00 0.00/hr 1013.25mBar
|
||||
|
||||
**With Rain:**
|
||||
::
|
||||
|
||||
WX: 68.0F/55.0F Wind 8@180G15 72% RA 0.25 0.10/hr 30.05inHg
|
||||
|
||||
Automatic Weather Reporting
|
||||
---------------------------
|
||||
|
||||
When latitude and longitude are configured, the plugin automatically sends weather packets to APRS-IS at regular intervals. These packets:
|
||||
|
||||
* Appear on APRS.fi and other APRS mapping services
|
||||
* Include your station's position and weather data
|
||||
* Are sent at the interval specified by ``report_interval`` (default: 60 seconds)
|
||||
|
||||
Example APRS Weather Packet
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The plugin sends standard APRS weather packets that look like this on APRS.fi:
|
||||
|
||||
::
|
||||
|
||||
WB4BOR>APRS,TCPIP*:@251234z3745.50N/12225.00W_270/005g012t072r000p000P000h65b10130
|
||||
|
||||
This packet includes:
|
||||
* Timestamp (25th day, 12:34 UTC)
|
||||
* Position (37°45.50'N, 122°25.00'W)
|
||||
* Wind direction 270° at 5 mph, gusting to 12 mph
|
||||
* Temperature 72°F
|
||||
* Rainfall data
|
||||
* Pressure and humidity
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
No Response to Weather Queries
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If the plugin doesn't respond to weather queries:
|
||||
|
||||
1. Check that the plugin is enabled in your APRSD configuration
|
||||
2. Verify MQTT connection is working (check APRSD logs)
|
||||
3. Ensure Weewx is publishing to the ``weather/loop`` topic
|
||||
4. Check that MQTT credentials are correct
|
||||
|
||||
No Automatic Reports
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If automatic weather reports aren't appearing:
|
||||
|
||||
1. Verify ``latitude`` and ``longitude`` are configured
|
||||
2. Check that your APRSD callsign is set correctly
|
||||
3. Ensure APRSD is connected to APRS-IS
|
||||
4. Review the ``report_interval`` setting
|
||||
|
||||
MQTT Connection Issues
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you see MQTT connection errors:
|
||||
|
||||
1. Verify the MQTT broker is running and accessible
|
||||
2. Check firewall settings for the MQTT port
|
||||
3. Verify MQTT username and password (if required)
|
||||
4. Test MQTT connection with a tool like ``mosquitto_sub``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mosquitto_sub -h localhost -p 1883 -t weather/loop
|
||||
|
||||
Testing the Plugin
|
||||
------------------
|
||||
|
||||
You can test the plugin by:
|
||||
|
||||
1. **Checking APRSD logs** for plugin initialization messages
|
||||
2. **Sending a test message** via APRS to your callsign with "w" or "W"
|
||||
3. **Monitoring MQTT traffic** to verify Weewx is publishing data
|
||||
4. **Checking APRS.fi** for automatic weather reports (if enabled)
|
||||
|
||||
Example Test Session
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. Start APRSD with the plugin enabled
|
||||
2. Wait for MQTT connection confirmation in logs
|
||||
3. Send APRS message: ``w YOURCALL``
|
||||
4. Receive weather response
|
||||
5. Check APRS.fi for automatic reports (if configured)
|
||||
Reference in New Issue
Block a user