# aprstastic
[](https://pypi.org/project/aprstastic)
[](https://pypi.org/project/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](https://github.com/afourney/aprstastic/blob/main/CONTRIBUTING.md) for details.
## New!
:fire: 2-minute [YouTube demo](https://www.youtube.com/watch?v=qUvpZUwl-cY)
:fire: Over-the-air discovery and registration now supported. See image below.
:fire: Call sign registrations are now (optionally) beaconed to [MESHID-01](https://aprs.fi/?c=message&call=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](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
```console
pip install aprstastic
```
```console
python -m aprstastic
```
The first time aprstastic runs, it will create a sample `aprstastic.yaml` file. **Edit the sample**, then run it again.
```console
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](http://www.aprs.org/doc/APRS101.PDF), `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](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "aprstastic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "aprs, aprs-gateway, aprs-is, gateway, lora, lora-gateway, meshtastic, meshtastic-gateway",
"author": null,
"author_email": "Adam Fourney <adam.fourney@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/0d/8a12b915e3a1c82ca6f5f47d5c9529dbf58f9190685c92cb7296bd873e50/aprstastic-0.0.1a25.tar.gz",
"platform": null,
"description": "# aprstastic\n\n[](https://pypi.org/project/aprstastic)\n[](https://pypi.org/project/aprstastic)\n\n---\n\n> [!WARNING]\n> Legal operation of this software requires an amateur radio license and a valid call sign.\n\n> [!NOTE]\n> Star this repo to follow our progress! This code is under active development, and contributions are both welcomed and appreciated. See [CONTRIBUTING.md](https://github.com/afourney/aprstastic/blob/main/CONTRIBUTING.md) for details.\n\n## New!\n\n:fire: 2-minute [YouTube demo](https://www.youtube.com/watch?v=qUvpZUwl-cY)\n\n:fire: Over-the-air discovery and registration now supported. See image below.\n\n:fire: Call sign registrations are now (optionally) beaconed to [MESHID-01](https://aprs.fi/?c=message&call=MESHID-01) to facilitate a global roaming profile.\n\n## Introduction\n\n`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):\n\n![Example aprstastic registration flow. Start by sending 'aprs?' to any public channel. Wait for a direct message. Reply with !register CALLSIGN-SSID.](https://github.com/afourney/aprstastic/blob/main/imgs/flow.png \"Example aprstastic registration flow.\")\n\nIn 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.\n\nThese interactions are demonstrated in the following YouTube video [https://www.youtube.com/watch?v=qUvpZUwl-cY](https://www.youtube.com/watch?v=qUvpZUwl-cY)\n\nEach gateway mimics an iGate, and can support multiple Meshtastic users, as long as their call signs and devices are pre-registered.\n\n## Special Commands\n\nVarious special commands can be issued by sending direct Meshtastic messages to the gateway. The following commands are currently supported.\n\n**Register a device:**\n\nUse the following command to register a Meshtastic device to a call sign, replacing `<YOUR_CALLSIGN>` appropriately:\n\n```\n!register <YOUR_CALLSIGN>\n```\n\ne.g.,\n\n```\n!register N0CALL-1\n```\n\n**Unregister a device:**\n\nUse the following command to unregister a Meshtastic device AND call sign.\n\n```\n!unregister\n```\n\n**Print version information:**\n\nUse the following command to print the gateway's info and version.\n\n```\n!version\n```\n\n## Installation, Configuration, and Running\n\n```console\npip install aprstastic\n```\n\n```console\npython -m aprstastic\n```\n\nThe first time aprstastic runs, it will create a sample `aprstastic.yaml` file. **Edit the sample**, then run it again.\n\n```console\nnano ~/.config/aprstastic/aprstastic.yaml\npython -m aprstastic\n```\n\n## Addressing APRS messages\n\nHow does the gateway know the addressee (\"to\" address) of APRS packets when all Meshtastic messages are addressed to the gateway device?\n\nTo 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).**\n\nAs an example, from Meshtastic you could interact with the Winlink gateway (WLNK-1) as follows:\n\n```\nWLNK-1: ?\n```\n\nThe reply from Winlink would be:\n\n```\nNOCALL-1: SP, SMS, L, R#, K#, Y#, F#, P, G, A, I, PR, B (? + cmd for more)\n```\n\nYou could then simply enter:\n\n```\nL\n```\n\nand it would assume a reply to `WLNK-1`, producing the following response:\n\n```\nNOCALL-1: 10/11/2024 23:52:30 No messages.\n```\n\n## Compliance\n\naprstastic 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.\n\n## A Note for APRS-IS Admins\n\nInstances 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](http://www.aprs.org/doc/APRS101.PDF), `APZ` designates an experimental application in development. In this case, `MAG` is short for 'Meshtastic-APRS Gateway'.\n\n## License\n\n`aprstastic` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Meshtastic-APRS Gateway",
"version": "0.0.1a25",
"project_urls": {
"Documentation": "https://github.com/afourney/aprstastic#readme",
"Issues": "https://github.com/afourney/aprstastic/issues",
"Source": "https://github.com/afourney/aprstastic"
},
"split_keywords": [
"aprs",
" aprs-gateway",
" aprs-is",
" gateway",
" lora",
" lora-gateway",
" meshtastic",
" meshtastic-gateway"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7c30d6a30035b0c490afd4d1f63098aae4f3c78bbd64648f27753e60eccd57aa",
"md5": "56e76a488c1f6605bfe2d43a327557dc",
"sha256": "b9143a5c843ce331f510ffd16d7d39db36e9d0adf1da1da2768612226017e07b"
},
"downloads": -1,
"filename": "aprstastic-0.0.1a25-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56e76a488c1f6605bfe2d43a327557dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22234,
"upload_time": "2024-11-12T04:59:43",
"upload_time_iso_8601": "2024-11-12T04:59:43.638688Z",
"url": "https://files.pythonhosted.org/packages/7c/30/d6a30035b0c490afd4d1f63098aae4f3c78bbd64648f27753e60eccd57aa/aprstastic-0.0.1a25-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f0d8a12b915e3a1c82ca6f5f47d5c9529dbf58f9190685c92cb7296bd873e50",
"md5": "6db7597a5e40c1fc491f2dc0559c0743",
"sha256": "20d275fb85490a8753ca4a61943de9597a33802129da3ee2ee85be20959733f1"
},
"downloads": -1,
"filename": "aprstastic-0.0.1a25.tar.gz",
"has_sig": false,
"md5_digest": "6db7597a5e40c1fc491f2dc0559c0743",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 20264,
"upload_time": "2024-11-12T04:59:42",
"upload_time_iso_8601": "2024-11-12T04:59:42.008594Z",
"url": "https://files.pythonhosted.org/packages/2f/0d/8a12b915e3a1c82ca6f5f47d5c9529dbf58f9190685c92cb7296bd873e50/aprstastic-0.0.1a25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 04:59:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "afourney",
"github_project": "aprstastic#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aprstastic"
}
JSON
