How hemna/aprsd-email-plugin works
Project Type and Purpose
• Type: Python plugin (library/extension) for the APRSD (“APRS Daemon”) project
• Purpose:
– Receive APRS frames from the radio network via APRSD
– Parse certain frames as “email” messages and relay them to an SMTP server
– Poll an IMAP inbox for new email and inject them back into APRS as APRS frames
– Acknowledge receipt back to the sender over APRS
High-Level File-Structure Analysis
• Top-level files: setup.cfg/pyproject.toml, setup.py, Makefile, tox.ini – standard Python package & CI
• aprsd_email_plugin/
– aprsd_email_plugin.py: plugin entrypoint and core logic
– conf/main.py & conf/opts.py: configuration parsing & CLI integration
• docs/: Sphinx-based documentation
• tests/: unit tests for parsing, send/receive, and main plugin behavior
Key Components
A. APRSD Core Daemon
– Plugin Loader / Event Loop
– Radio Interface (TNC/KISS) connecting to the APRS radio network
B. Email Plugin Module
– Initialization & Configuration (conf/main.py, conf/opts.py)
– APRS Message Parser (identify “email” frames)
– Outgoing Email Handler (SMTP client)
– Incoming Email Handler (IMAP client & poller)
– Acknowledgment Generator (builds ack frames)
C. External Services
– SMTP Server (internet email relay)
– IMAP Server (incoming mailbox)
– Amateur-radio network (APRS over RF or internet gateways)
Relationships & Data Flows
1. APRS-to-Email (Radio → APRSD → Plugin → SMTP):
• Radio network emits an APRS frame → APRSD Core receives it
• APRSD Core dispatches to loaded Email Plugin
• Plugin’s parser inspects the frame; if marked for email, extracts sender, recipient, payload
• Outgoing Email Handler uses SMTP client library to deliver to the recipient’s SMTP server
• Plugin generates an APRS “ack” frame and hands it back to APRSD to transmit on the radio
2. Email-to-APRS (IMAP → Plugin → APRSD → Radio):
• Plugin’s IMAP poller periodically connects to the IMAP server
• New messages are fetched; plugin formats each as an APRS frame
• Plugin hands frames to APRSD Core for transmission over the radio network
• Incoming APRS “ack” frames are parsed by the plugin to correlate delivery status
Architectural Patterns & Principles
• Plugin/Extension pattern: the Email logic is decoupled from APRSD Core, loaded at runtime
• Event-driven design: APRSD’s event loop triggers plugin callbacks on message arrival
• Separation of concerns:
– Configuration parsing (conf/)
– APRS frame parsing/generation (aprsd_email_plugin.py)
– Network I/O (SMTP/IMAP clients vs. TNC interface)
• Retry/Ack mechanism: frameless, stateless ack frames to ensure reliable delivery