Continuous Traffic Logging: Connects to APRS-IS and logs all gateway traffic
Comprehensive Tracking: Captures callsigns, packet types, timestamps, and geographic data
Geographic Analysis: Automatically detects state/region from position packets
Flexible Reporting: CLI tools for generating usage reports by time period, station, and geography
Reliable Operation: Automatic reconnection with exponential backoff
Systemd Integration: Run as a system service for unattended operation
Efficient Storage: SQLite database with optimized indexes for fast queries

Installation

Prerequisites

Python 3.9 or higher
pip or uv package manager

Using uv (Recommended)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install gtemon in development mode
cd gtemon
uv pip install -e .

Using pip

cd gtemon
pip install -e .

Quick Start

1. Create Configuration File

gtemon-daemon --create-config

This creates config.yaml in the current directory. Edit it with your settings:

aprs:
  callsign: NTSGTE          # Your gateway callsign
  passcode: "-1"            # Use -1 for read-only access
  server: rotate.aprs2.net
  port: 14580
  filter: "b/NTSGTE p/NTSGTE"  # Track packets to/from NTSGTE

database:
  path: /var/lib/gtemon/gtemon.db

logging:
  level: INFO
  file: /var/log/gtemon/gtemon.log

2. Test the Daemon

Run the daemon in the foreground to test:

gtemon-daemon -c config.yaml -v

You should see packets being logged. Press Ctrl+C to stop.

3. Generate Reports

Once you have some data, generate a summary report:

gtemon-report summary --last-days 7

APRS-IS Filters

The filter configuration determines what traffic you receive. Common filters:

b/CALL - Packets heard by CALL (buddied)
p/CALL - Packets originated by CALL
r/lat/lon/dist - Radius filter (dist in km)
Combine with spaces: b/NTSGTE p/NTSGTE

See APRS-IS filter documentation for more options.

Reporting Commands

Summary Report

# Last 30 days
gtemon-report summary --last-month

# Specific date range
gtemon-report summary --start 2025-01-01 --end 2025-01-31

# Last week
gtemon-report summary --last-days 7

Top Stations

# Top 20 most active stations
gtemon-report top-stations --limit 20

Database Info

gtemon-report info

Export to CSV

gtemon-report export data.csv --last-month

Running as a Service

1. Create System User

sudo useradd -r -s /bin/false gtemon
sudo mkdir -p /var/lib/gtemon /var/log/gtemon /etc/gtemon
sudo chown gtemon:gtemon /var/lib/gtemon /var/log/gtemon

2. Install Configuration

sudo cp config.yaml /etc/gtemon/
sudo chown root:gtemon /etc/gtemon/config.yaml
sudo chmod 640 /etc/gtemon/config.yaml

Update /etc/gtemon/config.yaml with appropriate paths:

database:
  path: /var/lib/gtemon/gtemon.db
logging:
  level: INFO
  file: /var/log/gtemon/gtemon.log

3. Install and Enable Service

sudo cp systemd/gtemon.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable gtemon
sudo systemctl start gtemon

4. Check Status

sudo systemctl status gtemon
sudo journalctl -u gtemon -f

Configuration Reference

APRS Settings

aprs.callsign: Your gateway callsign for APRS-IS authentication
aprs.passcode: APRS-IS passcode (use -1 for read-only)
aprs.server: APRS-IS server hostname
aprs.port: APRS-IS port (typically 14580)
aprs.filter: Server-side filter string

Database Settings

database.path: Path to SQLite database file

Logging Settings

logging.level: Log level (DEBUG, INFO, WARNING, ERROR)
logging.file: Log file path (omit for stdout only)

Daemon Settings

daemon.reconnect_max_backoff: Maximum reconnection delay in seconds

Database Schema

The system uses SQLite with two main tables:

packets

Stores all received packets:

id: Auto-incrementing primary key
timestamp: Packet timestamp (UTC)
source_call: Source callsign
dest_call: Destination callsign
path: Digipeater path
packet_type: position, message, telemetry, etc.
latitude, longitude: Coordinates (if available)
state: State/region (if determined)
raw_packet: Original packet string

stations_summary

Aggregated statistics per station:

callsign: Station callsign
first_seen, last_seen: Timestamps
total_packets: Total packet count
last_state, last_latitude, last_longitude: Last known location

Troubleshooting

No packets received

Check APRS-IS credentials: callsign and passcode
Verify filter syntax in configuration
Test connectivity: telnet rotate.aprs2.net 14580
Check logs: journalctl -u gtemon -n 100

Database permission errors

Ensure the database directory is writable by the daemon user:

sudo chown -R gtemon:gtemon /var/lib/gtemon

High CPU usage

The daemon is designed to be lightweight. If you experience high CPU:

Check for excessive reconnection loops (review logs)
Verify your filter isn't too broad (receiving too much traffic)
Consider increasing reconnect_max_backoff in config

Development

Running Tests

pytest tests/

Code Formatting

black gtemon/
ruff check gtemon/

License

MIT License - see LICENSE file for details

Contributing

This is a volunteer project for ham radio network reporting. Issues and pull requests welcome!

Credits

Built for the NTS Gateway Traffic Monitoring project.

Uses:

aprslib for APRS parsing
Click for CLI
PyYAML for configuration