Metadata-Version: 2.4
Name: core-aprs-client
Version: 0.90
Summary: Extensible APRS bot framework with dupe detection, beacon/bulletin support and other nice features. Just add your custom APRS bot functions - the APRS bot framework will take care of the rest.
Home-page: https://github.com/joergschultzelutter/core-aprs-client
Author: Joerg Schultze-Lutter
Author-email: joerg.schultze.lutter@gmail.com
License: GNU General Public License v3 (GPLv3)
Keywords: Ham Radio,Amateur Radio,APRS
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aprslib>=0.7.2
Requires-Dist: apprise>=1.9.4
Requires-Dist: expiringdict>=1.2.2
Requires-Dist: unidecode>=1.4.0
Requires-Dist: apscheduler>=3.11.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# core-aprs-client

![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![PyPi version](https://img.shields.io/pypi/v/core-aprs-client.svg)](https://pypi.python.org/pypi/core-aprs-client)

Core APRS client framework with dupe detection, bulletin/beaconing support, and other APRS-IS related stuff.

```core-aprs-client``` is a modernized version of [mpad](https://github.com/joergschultzelutter/mpad)'s APRS functions which can be used for building your very own APRS client / bot. Its framework supports all of [mpad](https://github.com/joergschultzelutter/mpad)'s core APRS messaging functions, such as connecting to APRS-IS, message dupe detection, ACK handling, and other functionality such as APRS bulletins (supporting both static and dynamic contents) and APRS beaconing. However, ```core-aprs-client``` deliberately lacks any _specific_ APRS bot functions such as WX reporting etc. 

This is where _you_ step in. Add your bot-specific code to the client's APRS framework code. Everything else related to APRS messaging and communication with APRS-IS will be covered by the ```core-aprs-client``` framework.

## Sample APRS Client

The following example illustrates a fully functional APRS bot. You will provide the APRS message input parser code and the generator responsible for the outgoing APRS message content. Everything else will be handled by the `core-aprs-client` framework.

```python
from CoreAprsClient import CoreAprsClient

# Your custom input parser and output generator code
from input_parser import parse_input_message
from output_generator import generate_output_message

import logging

if __name__ == '__main__':
    client = CoreAprsClient(config_file="core_aprs_client.cfg",
                            log_level=logging.INFO,
                            input_parser=parse_input_message,
                            output_generator=generate_output_message)
    client.activate_client()
```

It's as simple as that.

## Core features
- Core APRS-IS functionality, covering both 'old' and '[new](http://www.aprs.org/aprs11/replyacks.txt)' ACK processing
- Configurable dupe message handler
- Optional:
    - APRS beacons and bulletins, including support for dynamic bulletin content generated during runtime
    - Program crash handler, allowing you to get notified in case the client program crashes

## Installation and Configuration

### Installation instructions
Instructions for installing the framework and its sample APRS client on your computer can be found [here](https://github.com/joergschultzelutter/core-aprs-client/blob/master/docs/installation.md).

### Client Configuration
The steps for modifying the client's config file are described [here](https://github.com/joergschultzelutter/core-aprs-client/blob/master/docs/configuration.md).

### Framework examples 
[This directory](https://github.com/joergschultzelutter/core-aprs-client/blob/master/framework_examples/README.md) contains sample program code; it also contains the ready-to-use templates for the framework's configuration files.

### `CoreAprsClient` class description
The framework's class methods are described [here](https://github.com/joergschultzelutter/core-aprs-client/blob/master/docs/coreaprsclient_class.md)

### Source Code Anatomy
A brief overview on this repositories' software modules used by the client can be found [here](https://github.com/joergschultzelutter/core-aprs-client/blob/master/docs/anatomy.md).

### Framework usage
The steps for using the client framework are described [here](https://github.com/joergschultzelutter/core-aprs-client/blob/master/docs/framework_usage.md).

### Client schematics
If you want to learn about the bot's basic processing structure, then have a look at [this diagram](https://github.com/joergschultzelutter/core-aprs-client/blob/master/docs/schematics.md).

## Known issues and caveats
- This software is single-threaded. Due to APRS-IS's technical nature of resubmitting non-ack'ed messages, this limitation should not be an issue, though. Future versions of this software might support queued processing of incoming requests.
- This software is intended to be used by licensed ham radio operators. If you are not a licensed ham radio operator, then this program is not (yet) for you. Why not take a look at sites such as [Hamstudy](https://hamstudy.org/) and [50 Ohm](https://50ohm.de/) - and get licensed?
- You should at least know the APRS basics before you use this software. Acquaint yourself with [the official APRS documentation](https://github.com/wb2osz/aprsspec) and learn about [how APRS works](https://how.aprs.works/) in general. Additionally, have a look at the [APRS Foundation](https://www.aprsfoundation.org/)'s website.
- You HAVE to assign your personal call sign to the bot.
- You HAVE to [request your personal APRS TOCALL](https://github.com/aprsorg/aprs-deviceid) for using this bot __in production__. See the [APRS Device ID](https://github.com/aprsorg/aprs-deviceid/blob/main/ALLOCATING.md#development-phase) information section on proper usage.

## The fine print

- If you intend to host an instance of this program, you must be a licensed radio amateur. BYOP: Bring your own (APRS-IS) passcode. If you don't know what this is, then this program is not for you.
- APRS is a registered trademark of APRS Software and Bob Bruninga, WB4APR.
