core-aprs-client 0.97

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.

core-aprs-client

Table of contents

• Introduction
• Sample APRS Client
• Core features
• Installation and Configuration
  • Installation instructions
  • Client Configuration
  • Framework examples
  • CoreAprsClient class description
  • Source Code Anatomy
  • Framework usage
  • Client schematics
• Known issues and caveats
• Projects that use core-aprs-client
• Known issues and caveats
• Alternatives to core-aprs-client
• The fine print

Introduction

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's APRS functions which can be used for building your very own APRS client / bot. Its framework supports all of 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. Additionally, support for rare use cases such as pre- and post-processing of APRS requests is provided. 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.

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' 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
  • Support for pre- and post-processing
• All configuration settings are stored in a single program configuration file

Installation and Configuration

Installation instructions

Instructions for installing the framework and its sample APRS client on your computer can be found here.

Client Configuration

The steps for modifying the client's config file are described here.

Framework examples

This directory 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

Source Code Anatomy

A brief overview on this repositories' software modules used by the client can be found here.

Framework usage

The steps for using the client framework are described here.

Client schematics

If you want to learn about the bot's basic processing structure, then have a look at this diagram.

Projects that use core-aprs-client

A list of my projects that are dependent on core-aprs-client can be found here

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 and 50 Ohm - and get licensed?
• You should at least know the APRS basics before you use this software. Acquaint yourself with the official APRS documentation and learn about how APRS works in general. Additionally, have a look at the APRS Foundation's website.
• You HAVE to assign your personal call sign to the bot.
• You HAVE to request your personal APRS TOCALL for using this bot in production. See the APRS Device ID information section on proper usage.

Alternatives to core-aprs-client

A great alternative to core-aprs-client is KM6LYW'saprsd. If you don't intend to use core-aprs-client's specific functionalities such as pre- and post-processing (which afaik aren't supported by aprsd), this program might be a viable alternative.

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.