aprs.me/docs/contexts/packets.md

Packets Context

Overview

Module: Aprsme.Packets (lib/aprsme/packets.ex) Behaviour: Aprsme.PacketsBehaviour

Core domain for APRS packet storage, retrieval, querying, and management.

Schema: Aprsme.Packet (lib/aprsme/packet.ex)

The packets table is daily-partitioned on received_at. Composite primary key: {id, received_at}.

Key Field Groups

Group	Fields
Identity	id, sender (callsign), base_callsign, ssid, destination, path
Position	lat (decimal), lon (decimal), location (PostGIS geometry), has_position (boolean), dao (map)
Symbol	symbol_code, symbol_table_id
Weather	temperature, humidity, wind_speed, wind_direction, wind_gust, pressure, rain_1h, rain_24h, rain_since_midnight, snow, has_weather
Equipment	manufacturer, equipment_type, course, speed, altitude
Messaging	addressee, message_text, message_number
Other	data_type, region, comment, raw_packet, device_identifier, data (JSONB)

Changeset Pipeline

The changeset/2 function auto-computes:

• has_position and has_weather booleans
• location PostGIS point from lat/lon
• Symbol normalization
• Course/wind_direction normalization
• Display-only fields swept into data JSONB column

Schema: Aprsme.BadPacket (lib/aprsme/bad_packet.ex)

Failed packets stored in badpackets table:

• raw_packet — original APRS frame
• error_message, error_type — parsing/storage error details
• attempted_at — timestamp

Public API

Storage

• store_packet/1 — Sanitize → build attrs → insert; errors → badpackets
• store_bad_packet/2 — Record parse/insert failures

Querying

• get_recent_packets/1 — Cursor-paginated, latest first
• get_recent_packets_for_map/1 — Lightweight map-optimized query (~22 columns)
• get_latest_packet_for_callsign/1 — Single callsign latest
• get_latest_positions_for_callsigns/1 — Batch latest positions
• get_nearby_stations/3,4 — KNN spatial query via PostGIS <-> operator
• get_weather_packets/4 — Time-bound weather data
• get_other_ssids/1 — Find SSID variants of a base callsign
• get_total_packet_count/0 — Via PostgreSQL function

Replay

• get_packets_for_replay/1 — Historical packets filtered by callsign/bounds/region/time
• stream_packets_for_replay/1 — Lazy stream with timing preservation
• get_historical_packet_count/1 — Area packet density

Weather

• get_latest_weather_packet/1 — Latest weather for station
• has_weather_packets?/1, weather_callsigns/1 — Weather presence queries

Maintenance

• clean_old_packets/0, clean_packets_older_than/1 — Retention cleanup
• get_oldest_packet_timestamp/0 — Oldest data timestamp

Submodules

QueryBuilder (lib/aprsme/packets/query_builder.ex)

Composable Ecto query helpers: with_position/1, for_callsign/2, within_bounds/2, weather_only/1, chronological/1, recent_first/1, select_map_fields/1, etc.

PreparedQueries (lib/aprsme/packets/prepared_queries.ex)

High-performance prepared statements for hot paths: KNN queries, weather queries, bounds-filtered queries, callsign lookups.

Clustering (lib/aprsme/packets/clustering.ex)

Grid-based heatmap clustering for low-zoom map views (zoom ≤ 8). Reduces thousands of points to manageable grid cells.

Supporting Utilities

Module	Purpose
Aprsme.PacketSanitizer	Prevents DB field overflow
Aprsme.PacketFieldWhitelist	Filters fields for insert_all
Aprsme.Encoding / EncodingUtils	String/data normalization
Aprsme.Convert	Unit conversions
Aprsme.Callsign	Callsign parsing, normalization, SSID extraction
Aprsme.Maidenhead	Maidenhead grid locator conversion
Aprsme.GeoUtils	Geographic calculations
Aprsme.WeatherCache	ETS cache for weather callsign presence (TTL 5 min)

Database

• packets table: daily-partitioned, managed by Aprsme.PartitionManager
• badpackets table: standard table for error logging
• PostGIS extensions required for spatial queries
• get_packet_count() PostgreSQL function for efficient counting