From f7138f4cab2962cfb138717c756de1179d2f6ed5 Mon Sep 17 00:00:00 2001 From: Walter Boring Date: Tue, 27 Jan 2026 15:45:04 -0500 Subject: [PATCH] updated docs --- MANIFEST.in | 2 +- Makefile | 4 +- README.md | 298 ++++++++++++++++++++++++++ aprsd_slack_plugin/base_plugin.py | 24 +-- aprsd_slack_plugin/location_plugin.py | 44 ++-- aprsd_slack_plugin/message_plugin.py | 30 +-- docs/conf.py | 2 +- docs/index.rst | 2 +- pyproject.toml | 2 +- tox.ini | 3 +- 10 files changed, 357 insertions(+), 54 deletions(-) create mode 100644 README.md diff --git a/MANIFEST.in b/MANIFEST.in index 485b85d..ed2194e 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include README.rst +include README.md include LICENSE.txt include requirements.txt include aprsd_slack_plugin/py.typed diff --git a/Makefile b/Makefile index 41e1118..366c8bb 100644 --- a/Makefile +++ b/Makefile @@ -17,8 +17,8 @@ help: # Help for the Makefile dev: venv ## Create the virtualenv with all the requirements installed docs: build - cp README.rst docs/readme.rst - cp Changelog docs/changelog.rst + cp README.md docs/readme.md + cp ChangeLog docs/changelog.rst tox -edocs clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts diff --git a/README.md b/README.md new file mode 100644 index 0000000..4dce26f --- /dev/null +++ b/README.md @@ -0,0 +1,298 @@ +# aprsd_slack_plugin + +[![Python CI](https://github.com/hemna/aprsd-slack-plugin/workflows/python/badge.svg)](https://github.com/hemna/aprsd-slack-plugin/actions) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://black.readthedocs.io/en/stable/) +[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://timothycrosley.github.io/isort/) + +This project is a Python plugin for the [APRSD server daemon](https://github.com/craigerl/aprsd) written by Craig Lamparter. The plugin provides integration with Slack, allowing APRS messages and location data to be forwarded to Slack channels. + +## Features + +The plugin includes three main components: + +1. **Location Plugin** - Reports APRS location data to Slack channels with weather information +2. **Message Plugin** - Forwards APRS messages to Slack channels +3. **Notify Plugin** - Sends notifications when watched callsigns appear on APRS + +## Requirements + +- Python 3.11+ +- [APRSD](https://github.com/craigerl/aprsd) - APRS daemon server +- Slack Bot Token and Signing Secret (see setup instructions below) + +## Installation + +Install the plugin using pip: + +```bash +pip install aprsd-slack-plugin +``` + +Or install from source: + +```bash +git clone https://github.com/hemna/aprsd-slack-plugin.git +cd aprsd-slack-plugin +pip install -e . +``` + +## Slack Bot Setup + +Before configuring the plugin, you need to create a Slack bot application: + +1. Go to [api.slack.com](https://api.slack.com/apps) and create a new app +2. A good guide for creating the app, tokens, and permissions can be found at: + [https://api.slack.com/start/building/bolt-python](https://api.slack.com/start/building/bolt-python) + +3. You will need: + - **Signing Secret**: Found in "Basic Information" → "App Credentials" + - **Bot User OAuth Token**: Found in "OAuth & Permissions" → "OAuth Tokens for Your Team" → "Bot User OAuth Access Token" + +4. Required Bot Token Scopes: + - `chat:write` - To post messages to channels + - `channels:read` (optional) - To read channel information + +5. Install the app/bot into your workspace + +## Configuration + +Add the following section to your APRSD configuration file (typically `~/.config/aprsd/aprsd.conf` or `~/.config/aprsd/aprsd.yml`): + +### YAML Configuration Format + +```yaml +aprsd_slack_plugin: + signing_secret: "your_slack_signing_secret_here" + bot_token: "xoxb-your-bot-token-here" + channels: + - "#general" + - "#aprs" + - "#hamradio" +``` + +### INI Configuration Format + +```ini +[aprsd_slack_plugin] +signing_secret = your_slack_signing_secret_here +bot_token = xoxb-your-bot-token-here +channels = #general,#aprs,#hamradio +``` + +### Configuration Options + +- **`signing_secret`** (required): Your Slack app's signing secret from the App Credentials page +- **`bot_token`** (required): Your Slack bot's OAuth token (starts with `xoxb-`) +- **`channels`** (required): List of Slack channel names (with or without `#` prefix) where messages will be posted + +## Usage + +Once configured, the plugin will automatically integrate with APRSD. The plugins respond to specific APRS message commands: + +### Location Plugin + +The Location Plugin responds to messages starting with `L` or `l` and reports the location of a callsign to Slack. + +**Command Format:** +``` +L [callsign] +``` + +**Examples:** + +1. Get your own location: + ``` + L + ``` + +2. Get location for a specific callsign: + ``` + L N0CALL + ``` + +**Slack Output:** +The plugin will post a formatted message to your configured Slack channels with: +- Callsign with link to aprs.fi +- Location description (from weather.gov if in US) +- Map link to aprs.fi +- Altitude in feet +- Time since last update + +**Example Slack Message:** +``` +APRSD - Slack Location Plugin +📍 N0CALL - Location + +Location: Downtown Denver, CO +Map Location: http://aprs.fi/... +Altitude: 5280 ft +Time: 2.3 h ago +``` + +### Message Plugin + +The Message Plugin forwards APRS messages to Slack channels. + +**Command Format:** +``` +s +slack +``` + +**Examples:** + +1. Send a simple message: + ``` + s Hello from APRS! + ``` + +2. Send a longer message: + ``` + slack Testing the Slack integration + ``` + +**Slack Output:** +The plugin will post a message showing the callsign and message content: + +``` +APRSD - Slack Message Plugin +📡 N0CALL says s Hello from APRS! +``` + +### Notify Plugin + +The Notify Plugin automatically sends notifications when callsigns on your watchlist appear on APRS. + +**Setup:** +Add callsigns to your APRSD watchlist configuration. When those callsigns appear on APRS, the plugin will automatically notify your Slack channels. + +**Slack Output:** +``` +APRSD - Slack Notification Plugin +📡 N0CALL - Is now on APRS +``` + +## Example Interactions + +### Example 1: Checking Your Location + +**APRS Message:** +``` +L +``` + +**Slack Output:** +``` +APRSD - Slack Location Plugin +📍 N0CALL - Location + +Location: Mountain View, CA +Map Location: http://aprs.fi/#!mt=roadmap&z=15&lat=37.4056&lng=-122.0775 +Altitude: 150 ft +Time: 0.5 h ago +``` + +### Example 2: Checking Another Station's Location + +**APRS Message:** +``` +L W1AW +``` + +**Slack Output:** +``` +APRSD - Slack Location Plugin +📍 W1AW - Location + +Location: Newington, CT +Map Location: http://aprs.fi/#!mt=roadmap&z=15&lat=41.6875&lng=-72.7278 +Altitude: 200 ft +Time: 1.2 h ago +``` + +### Example 3: Sending a Message to Slack + +**APRS Message:** +``` +s Just finished a QSO on 2m! +``` + +**Slack Output:** +``` +APRSD - Slack Message Plugin +📡 N0CALL says s Just finished a QSO on 2m! +``` + +### Example 4: Watchlist Notification + +When a callsign on your watchlist appears on APRS, you'll automatically receive: + +**Slack Output:** +``` +APRSD - Slack Notification Plugin +📡 W1AW - Is now on APRS +``` + +## Troubleshooting + +### Plugin Not Responding + +1. Check that the plugin is enabled in your APRSD configuration +2. Verify your Slack credentials are correct: + - `signing_secret` matches your app's signing secret + - `bot_token` is valid and starts with `xoxb-` +3. Ensure the bot is installed in your Slack workspace +4. Check APRSD logs for error messages + +### Messages Not Appearing in Slack + +1. Verify the channel names are correct (case-sensitive) +2. Ensure the bot has been invited to the channels (if they're private) +3. Check that the bot has `chat:write` scope +4. Verify the bot token hasn't expired + +### Location Plugin Not Working + +1. Ensure you have an `aprs_fi.apiKey` configured in APRSD +2. Check that the callsign exists on aprs.fi +3. Verify network connectivity to aprs.fi and weather.gov + +## Development + +### Running Tests + +```bash +tox +``` + +Or run specific test environments: + +```bash +tox -e py311 # Run Python 3.11 tests +tox -e lint # Run linting with ruff +tox -e type-check # Run type checking with mypy +``` + +### Code Style + +This project uses: +- [black](https://black.readthedocs.io/) for code formatting +- [ruff](https://docs.astral.sh/ruff/) for linting +- [isort](https://pycqa.github.io/isort/) for import sorting + +## License + +Licensed under the Apache License, Version 2.0. See LICENSE.txt for details. + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## Support + +For issues and questions: +- GitHub Issues: [https://github.com/hemna/aprsd-slack-plugin/issues](https://github.com/hemna/aprsd-slack-plugin/issues) + +## Related Projects + +- [APRSD](https://github.com/craigerl/aprsd) - The APRS daemon this plugin extends diff --git a/aprsd_slack_plugin/base_plugin.py b/aprsd_slack_plugin/base_plugin.py index 4677fc7..818d982 100644 --- a/aprsd_slack_plugin/base_plugin.py +++ b/aprsd_slack_plugin/base_plugin.py @@ -5,7 +5,6 @@ from slack_sdk import WebClient import aprsd_slack_plugin - CONF = cfg.CONF LOG = logging.getLogger("APRSD") @@ -18,23 +17,22 @@ class SlackPluginBase: that location string to the configured slack channel. To use this: - Create a slack bot for your workspace at api.slack.com. - A good source of information on how to create the app - and the tokens and permissions and install the app in your - workspace is here: - https://api.slack.com/start/building/bolt-python + 1. Create a slack bot for your workspace at api.slack.com. + A good source of information is here: + https://api.slack.com/start/building/bolt-python + 2. You will need the signing secret from the Basic Information -> + App Credentials form. - You will need the signing secret from the - Basic Information -> App Credentials form. - You will also need the Bot User OAuth Access Token from - OAuth & Permissions -> OAuth Tokens for Your Team -> - Bot User OAuth Access Token. + 3. You will also need the Bot User OAuth Access Token from + OAuth & Permissions -> OAuth Tokens for Your Team -> + Bot User OAuth Access Token. - Install the app/bot into your workspace. + 4. Install the app/bot into your workspace. + + 5. Edit your ~/.config/aprsd/aprsd.yml and add the section:: - Edit your ~/.config/aprsd/aprsd.yml and add the section slack: signing_secret: bot_token: diff --git a/aprsd_slack_plugin/location_plugin.py b/aprsd_slack_plugin/location_plugin.py index 9831148..c17d1c3 100644 --- a/aprsd_slack_plugin/location_plugin.py +++ b/aprsd_slack_plugin/location_plugin.py @@ -6,9 +6,10 @@ from aprsd import packets, plugin, plugin_utils from oslo_config import cfg import aprsd_slack_plugin -from aprsd_slack_plugin import base_plugin -from aprsd_slack_plugin import conf # noqa - +from aprsd_slack_plugin import ( + base_plugin, + conf, # noqa +) CONF = cfg.CONF LOG = logging.getLogger("APRSD") @@ -26,23 +27,22 @@ class SlackLocationPlugin( that location string to the configured slack channel. To use this: - Create a slack bot for your workspace at api.slack.com. - A good source of information on how to create the app - and the tokens and permissions and install the app in your - workspace is here: - https://api.slack.com/start/building/bolt-python + 1. Create a slack bot for your workspace at api.slack.com. + A good source of information is here: + https://api.slack.com/start/building/bolt-python + 2. You will need the signing secret from the Basic Information -> + App Credentials form. - You will need the signing secret from the - Basic Information -> App Credentials form. - You will also need the Bot User OAuth Access Token from - OAuth & Permissions -> OAuth Tokens for Your Team -> - Bot User OAuth Access Token. + 3. You will also need the Bot User OAuth Access Token from + OAuth & Permissions -> OAuth Tokens for Your Team -> + Bot User OAuth Access Token. - Install the app/bot into your workspace. + 4. Install the app/bot into your workspace. + + 5. Edit your ~/.config/aprsd/aprsd.conf and add the section:: - Edit your ~/.config/aprsd/aprsd.conf and add the section slack: signing_secret: bot_token: @@ -110,9 +110,11 @@ class SlackLocationPlugin( callsign_url = f"" - aprs_url = "".format( - lat, - lon, + aprs_url = ( + "".format( + lat, + lon, + ) ) message = {} @@ -128,7 +130,11 @@ class SlackLocationPlugin( # if the coordinates are outside of the US, we don't get this # aread description - if wx_data and "location" in wx_data and "areaDescription" in wx_data["location"]: + if ( + wx_data + and "location" in wx_data + and "areaDescription" in wx_data["location"] + ): attachment["fields"].append( { "title": "Location", diff --git a/aprsd_slack_plugin/message_plugin.py b/aprsd_slack_plugin/message_plugin.py index 62769ed..07c7ae7 100644 --- a/aprsd_slack_plugin/message_plugin.py +++ b/aprsd_slack_plugin/message_plugin.py @@ -5,9 +5,10 @@ from aprsd import packets from oslo_config import cfg import aprsd_slack_plugin -from aprsd_slack_plugin import base_plugin -from aprsd_slack_plugin import conf # noqa - +from aprsd_slack_plugin import ( + base_plugin, + conf, # noqa +) CONF = cfg.CONF LOG = logging.getLogger("APRSD") @@ -20,23 +21,22 @@ class SlackMessagePlugin(base_plugin.SlackPluginBase): to aprsd, then forwards the message to the configured slack channel. To use this: - Create a slack bot for your workspace at api.slack.com. - A good source of information on how to create the app - and the tokens and permissions and install the app in your - workspace is here: - https://api.slack.com/start/building/bolt-python + 1. Create a slack bot for your workspace at api.slack.com. + A good source of information is here: + https://api.slack.com/start/building/bolt-python + 2. You will need the signing secret from the Basic Information -> + App Credentials form. - You will need the signing secret from the - Basic Information -> App Credentials form. - You will also need the Bot User OAuth Access Token from - OAuth & Permissions -> OAuth Tokens for Your Team -> - Bot User OAuth Access Token. + 3. You will also need the Bot User OAuth Access Token from + OAuth & Permissions -> OAuth Tokens for Your Team -> + Bot User OAuth Access Token. - Install the app/bot into your workspace. + 4. Install the app/bot into your workspace. + + 5. Edit your ~/.config/aprsd/aprsd.yml and add the section:: - Edit your ~/.config/aprsd/aprsd.yml and add the section slack: signing_secret: bot_token: diff --git a/docs/conf.py b/docs/conf.py index 0faf919..a7aaf05 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -63,7 +63,7 @@ master_doc = "index" # # 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. diff --git a/docs/index.rst b/docs/index.rst index d899070..33fce29 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ ``aprsd_slack_plugin`` Documentation ==================================== -.. include:: ../README.rst +For installation, configuration, and usage instructions, see the `README.md `_ file. .. toctree:: :maxdepth: 2 diff --git a/pyproject.toml b/pyproject.toml index fe226ce..7859b69 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" name = "aprsd_slack_plugin" version = "1.2.0" description = "Amateur radio APRS daemon which listens for messages and responds" -readme = "README.rst" +readme = "README.md" requires-python = ">=3.11" license = {file = "LICENSE.txt"} authors = [ diff --git a/tox.ini b/tox.ini index 6d32dee..b3675c8 100644 --- a/tox.ini +++ b/tox.ini @@ -46,10 +46,11 @@ commands = uv run ruff check aprsd_slack_plugin tests [testenv:docs] -skip_install = true +package = editable deps = pytest sphinx + aprsd changedir = {toxinidir}/docs commands = uv run python clean_docs.py