aprstastic 0.0.1a24

A Meshtastic-APRS Gateway

aprstastic

---

[!WARNING] Legal operation of this software requires an amateur radio license and a valid call sign.

[!NOTE] Star this repo to follow our progress! This code is under active development, and contributions are both welcomed and appreciated. See CONTRIBUTING.md for details.

New!

:fire: 2-minute YouTube demo

:fire: Over-the-air discovery and registration now supported. See image below.

:fire: Call sign registrations are now (optionally) beaconed to MESHID-01 to facilitate a global roaming profile.

Introduction

aprstastic is a bidirectional Meshtastic APRS gateway for Meshtastic users with amateur radio licenses. It runs on stock Meshtastic devices (LongFast, 915MHz, etc.), allowing you to participate and extend the public network, while using pre-registered associations between Meshtastic device IDs and amateur radio call signs to bidirectionally gate APRS packets in a way that is compliant with FCC regulations. To this end, operation requires at least two Meshtastic devices: one to serve as the gateway, and the others are the clients. The following image demonstrates how operators can register with the gateway (and the broader global network, if registration beaconing is enabled):

In this scenario, direct messages to the gateway will be forwarded to APRS with the "from" call sign KK7CMT-8. Likewise, APRS messages addressed to KK7CMT-8 will be routed to the originating/registered Meshtastic device via direct message. If registration beaconing is enabled, registration will also trigger a one-time APRS broadcast of the device-id to call sign mapping, allowing all other participating aprstastic gateways to learn the association. This enables devices to roam between participating gateways.

These interactions are demonstrated in the following YouTube video https://www.youtube.com/watch?v=qUvpZUwl-cY

Each gateway mimics an iGate, and can support multiple Meshtastic users, as long as their call signs and devices are pre-registered.

Special Commands

Various special commands can be issued by sending direct Meshtastic messages to the gateway. The following commands are currently supported.

Register a device:

Use the following command to register a Meshtastic device to a call sign, replacing <YOUR_CALLSIGN> appropriately:

!register <YOUR_CALLSIGN>

e.g.,

!register N0CALL-1

Unregister a device:

Use the following command to unregister a Meshtastic device AND call sign.

!unregister

Print version information:

Use the following command to print the gateway's info and version.

!version

Installation, Configuration, and Running

pip install aprstastic

python -m aprstastic

The first time aprstastic runs, it will create a sample aprstastic.yaml file. Edit the sample, then run it again.

nano ~/.config/aprstastic/aprstastic.yaml
python -m aprstastic

Addressing APRS messages

How does the gateway know the addressee ("to" address) of APRS packets when all Meshtastic messages are addressed to the gateway device?

To address this, we adopt the "CALLSIGN: " convention. Messages should start with the addressee's call sign, followed by a colon. If this is omitted, then the call sign of the addressee is taken to be that of the previous message (i.e., to respond to the previously received message).

As an example, from Meshtastic you could interact with the Winlink gateway (WLNK-1) as follows:

WLNK-1: ?

The reply from Winlink would be:

NOCALL-1: SP, SMS, L, R#, K#, Y#, F#, P, G, A, I, PR, B (? + cmd for more)

You could then simply enter:

L

and it would assume a reply to WLNK-1, producing the following response:

NOCALL-1: 10/11/2024 23:52:30 No messages.

Compliance

aprstastic only allows messages to transit if they are found in the client device-to-callsign mapping, and are thus attributable to a licensed operator. Random messages published on channels like LongFast, or from other devices do not qualify. All messages are unencrypted before they leave Meshtastic, so all APRS traffic is clear text.

A Note for APRS-IS Admins

Instances of the aprstastic gateway identify themselves to the APRS-IS level 2 servers with the software version number APZMAG. In accordance to the Protocol Reference, APZ designates an experimental application in development. In this case, MAG is short for 'Meshtastic-APRS Gateway'.

License

aprstastic is distributed under the terms of the MIT license.