Table of Contents

1. Introduction & System Requirements

The TEF Logger App is a highly specialized software tool designed for visualizing, recording, and managing FM reception data originating from TEF668x-based receivers (specifically those running the ESP32 firmware by PE5PVB). The application communicates wirelessly via the UDP protocol, decodes highly complex RF metadata (Frequency, PI Code, RDS strings, Signal Strength) in real-time, and fuses this information with the smartphone's native GPS data to generate URDS-compliant CSV logbooks for the global DX community.

Furthermore, the app deeply integrates data from the FMDX.org ecosystem. It renders interactive maps, employs statistical prediction models (AI) to reconstruct fragmented RDS texts, visualizes live telemetry from GPS satellites, and asynchronously downloads high-resolution station logos.

System Requirements

• Hardware: TEF 668x receiver with recent PE5PVB ESP32 firmware (v2.20 or newer).
• Network: A Wi-Fi network or a mobile hotspot capable of establishing a direct socket connection between the receiver and the smartphone.
• Operating System: Smartphone running Android 8.0 (API Level 26) or higher.
• FMLIST Account (Optional): Required only if log files are to be automatically transmitted to the global URDS servers.

2. Network Architecture & Connectivity

Specific Network Binding (Routing Bypass)

Modern Android versions (Android 6.0+) feature aggressive network routing protocols. If a device has an active mobile data connection (LTE/5G) while simultaneously connected to a Wi-Fi network that lacks external internet access (such as the direct hotspot created by the TEF receiver), Android defaults to routing all data traffic through the cellular network. Consequently, incoming local UDP broadcast packets on Port 9100 are ignored and dropped.

To resolve this architectural hurdle, the app performs a deep integration into the system's Connectivity Manager upon launch. It scans all available network interfaces for the "WIFI" transport layer and explicitly forces its internal Datagram Socket to bind exclusively to this local network adapter. Additionally, the system is instructed to prioritize the IPv4 stack to prevent timeout issues inherent to modern IPv6 cellular networks.

Establishing a Connection

1. Ensure that both the receiver and the smartphone are logged into the exact same Wi-Fi subnet, or connect the TEF receiver directly to the smartphone's mobile hotspot.
2. Launch the app. The socket listener initializes automatically and awaits broadcast packets from the TEF hardware.
3. If multiple receivers are broadcasting on large networks, you can specifically target the desired device by its IP address via Menu → TEF Source.

3. User Interface & Real-Time Processing

Real-Time Data Processing

Once a connection is established, the application deconstructs the incoming comma-separated UDP payload at millisecond intervals. An internal watchdog timer simultaneously monitors the stream every 500 milliseconds; if packets cease arriving, the display safely resets to prevent frozen data states.

The following real-time data is visualized in highly optimized UI containers:

• Status Toolbar: A dedicated hardware status toolbar renders active RDS flags such as Stereo, TP (Traffic Program), and TA (Traffic Announcement) to provide instant feedback on the transmission state.
• Core Radio Data: Frequency, PI code, calculated signal strength, and the Program Service (PS) name.
  (Tip: Tapping the PS name opens an overlay listing all known name variants from the online FMDX database, alongside variants learned locally by the AI).
• PS Underscores: To enhance the readability of highly fragmented texts during deep DXing, any empty spaces within the PS name are consistently rendered as underscores (`_`).
• Packet Counters: Real-time telemetry counters (`#Pi`, `#PS`, `#rawPi`) display the exact number of data packets received, aiding DXers in precise signal quality assessment.
• Validation Indicators: Dynamic UI color coding highlights validated PI, PS, and Alternative Frequencies (AF), providing instant visual feedback distinguishing between flawless hardware data and AI-predicted states.
• Extended RDS Data: Radio Text (RT), Alternative Frequencies (AF), and Program Type (PTY). You can click on any Alternative Frequency (AF) displayed in the list to automatically tune your TEF receiver to that frequency.

Menu Configurations

The user interface is highly customizable via the main menu:

4. Background Engine, WakeLocks & Resurrection

The core philosophy of the app is autonomous logging over extended periods, often while the smartphone is stowed in a pocket. The Android operating system natively attempts to suspend applications to conserve battery. Several highly technical protection mechanisms counteract this to guarantee uninterrupted data collection.

Manual vs. Automatic Logging

• Manual Logging: Tap the MAN LOG button at the bottom left to record a single snapshot of the current metadata directly to the active CSV file.
• Auto-Logging: Long-press the MAN LOG button to toggle automatic, continuous logging. The engine will autonomously write data streams to the file at predefined intervals.

Background Resilience & Auto-Resurrection

Because processing continuous UDP streams demands active processor time, the application runs a dedicated background service paired with specialized background optimization locks (WakeLocks, WifiLocks, and MulticastLocks). These ensure your phone's CPU and Wi-Fi radio do not power down when the screen turns off.

Resurrection Protocol: If Android's memory management (Low Memory Killer) violently terminates the application during a massive resource constraint, the app utilizes a system-level alarm watchdog. This mechanism guarantees that the background logging engine will autonomously revive and restart itself exactly 4 minutes after a crash.

Log File Handling & Selection Architecture

All recorded data is structured into dedicated LogFile instances, defined by a display name and a physical File pointer. The app utilizes a highly stable tracking architecture for these files:

• Stable Path Selection: The background adapter tracks active log files exclusively via their absolute system paths rather than their object memory instances. This ensures that background logging and UI selections remain perfectly stable and immune to duplicate instance errors when the dataset updates.
• Batch Operations: A long-press on any log file checkbox triggers a global "Select All" or "Clear All" function, allowing for rapid batch processing or multiplexed uploading of your logged sessions.

Extended URDS CSV Architecture (All 49 Columns)

All collected data is physically appended to the targeted CSV file located in Downloads/logs/. To maintain strict URDS standard compatibility while supporting advanced local features (like AI injection), the CSV schema is strictly organized into 49 fixed columns (Indexed 0 to 48). Unused columns are deliberately left empty (rendered as consecutive commas) to act as padding for the FMLIST parsers.

5. Lock Screen / Pocket Mode

During mobile use (e.g., cycling or hiking), carrying an active smartphone in a pocket frequently results in capacitive phantom inputs on the touchscreen. This can inadvertently close the app or halt the logging process. As of v6.01, this feature is universally unlocked for all Android versions.

How the Overlay Works

Activated via the menu, the Lock Screen function technically injects a pitch-black layout container with an extremely high Z-axis priority (elevation) over the entire user interface. This overlay completely consumes all incoming touch events before they can reach the buttons or input fields beneath it. Concurrently, the rendering engine for the station logo is paused and hidden to prevent accidental interaction. Background processes continue entirely unaffected.

The Unlock Algorithm

A simple tap or swipe is insufficient to remove the overlay. The algorithm requires exactly 3 consecutive touches within 1000 milliseconds (1 second).

• Upon the first tap, an event handler logs the timestamp and smoothly fades in a visual hint ("Tap 3x to unlock") using an alpha animation.
• If the second and third taps occur within the time window, the overlay is immediately destroyed, freeing the UI.
• If the time window expires, the counter resets to zero and the hint fades out. This essentially eliminates the possibility of accidental unlocking in a pocket.

6. Hybrid GPS & Satellite Telemetry

The Hybrid Location Engine

Position tracking is designed for extreme fault tolerance. The location service initially attempts to use Google Mobile Services (FusedLocationProvider) to obtain an ultra-fast, high-precision fix by combining hardware sensors, cell tower triangulation, and satellite data. If this fails (e.g., on custom ROMs lacking Google services, or encountering a 15-second timeout), the system seamlessly falls back to the native Android LocationManager, reading data directly from the physical hardware chips.

Satellite Radar & Signal Visualization

Tapping the GPS data on the main screen opens the Satellite View. This interface does not display static text; rather, it intercepts raw NMEA telemetry callbacks from the satellites and computes a real-time radar map.

• Constellation Support: Detects and classifies satellites into their respective global networks: GPS (US), GLONASS (Russia), Galileo (EU), Beidou (China), SBAS, QZSS, and IRNSS.
• Dynamic SNR Graphing: Renders a live color-coded mapping based on the Signal-to-Noise Ratio (SNR) for every satellite in view. Signal strength is color-coded: Green (Excellent > 35), Yellow-Green (Good > 25), Orange (Marginal > 15), and Red (Poor < 15).
• Active Fix Status: The view differentiates between satellites actively being used to calculate your current position, versus those that are merely visible above the horizon but not locked.
• Sky Radar Map: Plots the physical position of each satellite (based on its azimuth and elevation) on a radial radar chart, showing you exactly where the satellites are in the sky above your head in relation to cardinal directions (N, E, S, W).

7. Map Engine & Proxy Failover System

The app offers two distinct geographic mapping environments (Live TX Map and URDS Log Map), both built upon OpenStreetMap tiles. To circumvent API rate limits and geoblocking, a complex network architecture is employed.

Failover Proxy & SSL Bypass

Map tiles are never loaded directly from OSM servers. The network manager routes requests through a primary proxy server, injecting device and OS telemetry for authentication. If this server responds with a timeout (e.g., server failure), the app's background thread instantly switches to a hardcoded backup proxy server.
Because older devices (Android 8 and 9) often possess expired Let's Encrypt root certificates (resulting in "Trust anchor not found" errors), the app injects a custom TrustManager for map downloads, safely bypassing SSL verification exclusively for these specific proxy connections.

Slippy-Map Caching (Offline Mode)

All downloaded tiles (PNG images) are stored in the device's local cache based on their Z/X/Y coordinates. When the "Offline Caching" feature is triggered, the app calculates a bounding box around current coordinates and preemptively downloads all necessary images up to Zoom Level 16. The WebView then renders these maps entirely from local storage without requiring an internet connection. In the event of an invalid map license, the system actively triggers a purge sequence, wiping the WebView, JSON, and physical tile caches to protect server bandwidth.

Live TX Map Engine

The Live TX Map is a real-time visualization environment tailored for active DXing. It features:

• Interactive Station Box: A dynamic, floating data table (responsive and strictly optimized for both smartphones and tablets via viewport sizing) displaying all transmitters on the currently tuned frequency. It provides instant readouts for Frequency, Station Name, City, ITU, PI, Antenna Polarization, and ERP.
• Frequency Lock Mode: Tapping a frequency in the station table "locks" the map to that specific frequency, preventing the UI from jumping when the hardware receiver tunes elsewhere. A red lock icon and a locked header visually indicate this state. Tapping anywhere on the map instantly releases the lock and restores real-time hardware tracking.
• Smart Auto-Zoom (A-Button): An intelligent "A" button toggles the Auto-Zoom capability. The engine dynamically calculates the perfect zoom level using distinct scaling tables tailored separately for tablets and smartphones, guaranteeing that your GPS location and the distant transmitter are perfectly framed without manual intervention.
• GPS Tracking Trail: The map silently records and plots your physical movement as a trail of blue dots (up to 5,000 persistent waypoints). A new point is plotted whenever a frequency change paired with a valid PI code occurs, giving you a visual history of your active DX path.
• Marker Intelligence & Polylines: Transmitters are plotted with custom antenna icons scaled directly by their ERP (Low, Medium, High). Actively matched stations turn red. The engine calculates precise distances via the Haversine formula and draws dashed connection lines between your receiver's GPS coordinates and the transmitter mast.
• Live Stream Audio Integration: If a matched station provides an internet stream (via the FMLIST API), the built-in ExoPlayer automatically resolves the URL (parsing .m3u/.pls playlists and natively providing http/https fallbacks) and streams the audio directly within the app. This allows for immediate, manual acoustic verification of distant catches.

The Live Map (TX MAP) user guide can be downloaded here: Download PDF.

URDS Log Map & Playback Engine

The URDS map is a robust offline playback tool for analyzing recorded CSV log files. Its features include:

• Multi-File Log Merging: You can select multiple URDS log files simultaneously. The Kotlin engine intelligently aggregates and deduplicates markers and waypoints into a single, cohesive mapping session.
• Waypoint Navigation & Auto-Playback: A dedicated navigation bar allows you to step through logged waypoints chronologically. Long-pressing the navigation arrows triggers an "Auto-Run" playback mode (advancing at 2-second intervals), automatically reliving your DX session on the map.
• Advanced Camera Tracking (AZ/FO):
  • AZ (Auto-Zoom): Dynamically adjusts the map's bounding box to keep both the currently selected logged waypoint and its associated transmitter strictly within the viewport.
  • FO (Follow): Locks the camera to strictly follow the sequence of logged waypoints as you step through time.
• Rich Telemetry Popups: Tapping a log waypoint reveals a detailed telemetry popup displaying the precise Frequency, PS Info, PI-Code, Signal Strength (dBµV), Station Name, Station ID, Distance, and Receiver Height (m). The exact UTC timestamp is displayed in a dedicated, floating screen overlay.
• Persistent State Memory: The map engine utilizes local storage to securely save your current zoom level, center coordinates, selected waypoint, and navigation mode across app restarts, resuming exactly where you left off.

The URDS Mapviewer Guide (URDS MAP) user guide can be downloaded here: Download PDF.

8. Station Identification & Dynamic Logo Rendering

Mathematical Localization (Haversine & Epsilon)

Incoming data is matched against the FMDX database. To avoid floating-point rounding errors (e.g., if the TEF chip reports 104.295 MHz, but the database expects 104.300 MHz), the engine rasterizes frequencies using a strict mathematical tolerance limit (Epsilon = 0.02 MHz).
Once coordinates of a transmitter mast are known, the app uses the Haversine Formula, accounting for the Earth's curvature, to calculate the precise distance and the Azimuth angle required for physically aiming directional antennas.

PI Regional Codes (piReg): The identification engine intelligently handles regionalized program splits (piReg). In countries where national networks split into local variants (using the second nibble of the PI code), the app correctly resolves and displays the specific regional station name rather than defaulting to the national parent network.

Ambiguity Resolution & Manual ID Editing

If multiple physical transmitters share the exact same PI code on your current frequency, a badge (e.g., "+3") appears next to the Station ID. Note: To save UI space, frequencies with an excessive amount of additional locations (e.g., widespread networks in Italy) will display this badge safely capped as "99+".

• Tap the badge to choose the correct physical tower from a dropdown list.
• Once selected, the station name, location, and Station ID update immediately across the UI.
• A pencil icon located next to the ID allows for direct, manual editing of the Station ID, which instantly forces the UI and log files to align with your custom input.
• Additionally, Sporadic-E logic mathematically adjusts scoring parameters if a transmission is detected from over 500km away.

Dynamic Station Logos

The app features an interactive overlay displaying the broadcasting station's high-resolution logo (supporting both raster PNG and scalable vector SVG formats fetched securely via logos.fmdx.org).

• Smart Caching & Flicker-Free Loading: Logos load instantly from local device memory to completely eliminate UI flickering. In the background, the app quietly checks the server using HTTP caching headers (ETag / Last-Modified) to see if a newer version exists, seamlessly cross-fading the image only if the server version has genuinely changed.
• Interactive "Wiggle" UI (Edit Mode):
  • Long-Press the Logo: Enters Edit Mode. The logo visually wiggles and pulses, and a floating control panel dynamically appears.
  • Zoom (+ / -): Use the floating buttons to step the scale of the logo up or down (strictly constrained between 70% and 200% to prevent graphical distortion).
  • Drag & Drop: Touch and move the logo anywhere on the screen. A mathematical collision boundary actively prevents you from dragging the logo outside the visible display area.
  • Double Tap: Instantly resets the logo to its default, centered position and original scale (100%).
  • Persistent State Memory: Your custom scale and screen position (X/Y coordinates) are automatically saved to the system's SharedPreferences. The app will remember exactly where you placed the logo, even after completely restarting the application.
  • Close (X): Tap the 'X' button on the control panel to lock the logo in its new place and safely exit Edit Mode.

9. TEF Remote Control & Frequency Mapping

Via the TEF Remote menu, the app displays a control overlay. Every button press is converted in real-time into a command string, packaged into a UDP datagram, and transmitted back to the ESP32 chip.

Core Controls

• Manual Tuning: Frequency up and down step buttons.
• Hardware Scanner: Search up and down buttons to jump to the next strong signal.
• Auto Scan Toggle: The "SCAN OFF" button activates the continuous Auto Scan mode embedded in the TEF firmware. When active, it turns orange and displays "SCAN ON".

Auto-Scan Safety Reset (Failsafe)

If the UDP connection drops or the Wi-Fi disconnects while Auto Scan is running, the app triggers a critical safety fallback. It automatically commands the ESP32 chip to halt the ongoing auto-scan process, preventing the hardware from endlessly scanning without a client to record the data.

Manual Frequency Entry (OIRT Support)

A long-press on the Scan button opens a dialog for direct frequency input. The app routes the input string through a Regular Expression (Regex) parser that cleans invalid characters. This allows inputs like "991", "99.1", or "99100" to be processed uniformly. The parser explicitly supports low frequency ranges down to 68.80 MHz, enabling full command over the Eastern European OIRT band.

10. Log Management & Multipart Uploads

The URDS Options menu conceals a complete file manager. The architecture relies on a RecyclerView utilizing set-based path selection. This ensures file selection remains perfectly stable during scrolling.

Managing Local Files

• Export / Download: Copies files from the isolated app sandbox into the smartphone's public Downloads/URDS/ directory, making them accessible to spreadsheet software or messenger apps.
• Import: Utilizing Android's Storage Access Framework, external CSVs can be securely pulled back into the sandbox to be rendered on maps or validated.

Multipart Uploads & Header Injection

When uploading logs to FMLIST, the app automatically merges multiple selected logs and compresses them into a GZIP archive to drastically reduce cellular data consumption. The HTTP-POST upload is executed using a "Multipart/Form-Data" format.

Crucially, the app automatically injects hardware metadata—the exact TEF hardware type and ESP32 firmware version—into the HTTP POST headers. This ensures highly accurate records in the global URDS database.

A specialized tracking engine intercepts the byte streams being pushed through the socket, calculating the exact percentage uploaded in real time and feeding it back to the UI progress bar, preventing ANR (Application Not Responding) crashes on slow connections.

In-App Beta Updates

Users can fetch the latest experimental versions directly inside the app. The update engine pulls version manifests from the server, displays detailed changelogs, and executes direct APK downloads without relying on external app stores.

11. Advanced Integrations (URDS Validator & RDS AI)

URDS Log Validator

The integrated URDS Log Validator is a cornerstone feature that allows users to audit their raw CSV logs directly within the app before uploading. It cross-references recorded data with the FMDX database, assigns confidence scores to each reception, and offers an 'Auto-Fix' capability to mathematically repair erroneous PI and PS values. It features a fully interactive UI to manually resolve ambiguous stations, filter by confidence (e.g., <40%, 40-73%), and inject custom text comments directly into the log rows before saving the enriched, clean CSV back to local storage.

You can find a detailed guide for the URDS Log Validator here: URDS Log Validator Documentation.

RDS AI Predictor

The RDS AI Predictor acts as an intelligent, mathematical interception layer between the receiver and the screen. Because conventional RDS decoders often produce flickering letters when reception is weak, the AI evaluates the raw stream before it reaches the UI.

• Character-Level Voting Matrix: A concurrent hash map evaluates incoming text fragments character by character. A letter at a specific position must accumulate a required number of "hits" across consecutive packets before it is mathematically locked onto the UI. Result: completely flicker-free names on weak signals.
• 200ms Hardware Lag Filter: When scrolling rapidly through frequencies, the TEF chip's internal buffer does not empty immediately. The AI monitors frequency changes down to the millisecond and specifically discards all packets within this time window, entirely eliminating "ghost stations".
• Bigram Probability Correction: If a word is missing one or two letters due to static noise, the engine analyzes adjacent letters and cross-references them against European probability matrices to intelligently guess the missing character.
• Reverse & Forward Lookup: If noise destroys the PI code but the text remains readable, the system performs a reverse lookup to interpolate the missing PI code. Conversely, it automatically fills in missing text if a clean PI code is received.
• Dynamic PS Bypass: The AI recognizes illegal scrolling texts (Scrolling PS) via character shifts. It temporarily deactivates the lock algorithm, allowing the text to scroll smoothly across the display.

You can find a detailed guide for the RDS AI Predictor here: RDS AI Predictor Documentation.

12. FMDX Connector

• FMDX Webserver nodes can be directly connected to the TEF Logger app.
• An unlimited number of web server profiles can be added and managed.
• Intuitive profile selection via swipe gestures or dedicated left/right navigation buttons.
• Integrated system logging function for deep diagnostic monitoring.
• Optional remote control of the autoscan function (requires admin password and the scanner plugin, available from version 3.9: webserver-scanner).

FMDX Connector App: Download

13. Troubleshooting & FAQ

Q: No data from TEF. All values remain at zero.

A: UDP broadcasting is immediately paused by the TEF receiver whenever its internal hardware menu is open. Close the menu on the device. Furthermore, check if your smartphone and receiver are logged into the exact same subnet, and verify under Menu → TEF Source that the correct local IP address is selected.

Q: GPS coordinates are missing or show 0.0000.

A: Ensure that Android location permissions in system settings are set to "Allow all the time". Note that Wi-Fi-only tablets often lack a physical GPS chip, and network-based positioning can fail in nature far away from Wi-Fi routers.

Q: Automatic logging stops after some time when the screen is off.

A: Aggressive battery optimizers (especially on Xiaomi, Samsung, and Huawei devices) intervene deeply in the system and "kill" the app's protective WakeLock. You must manually navigate to the App Info in Android settings, select "Battery," and strictly enforce the "Unrestricted" profile.

Q: The Live TX Map shows only a white area.

A: The rendering engine (Android System WebView) on your device is outdated or has crashed internally. On older systems (Android 9/10), update the Chrome/WebView app via the Play Store. On newer devices, fully swiping the TEF Logger App away via the task manager to rebuild the rendering context usually suffices.

Q: The station name rapidly switches between two stations when I change the frequency.

A: You are scrolling through frequencies faster than the AI's 200ms hardware lag filter can catch. The TEF chip's internal ring buffer is overlapping old and new data. Pause for at least one second when manual tuning to allow the buffer to clear properly.

Q: On weak signals, some letters in the name are white, others are gray. Why?

A: White letters have been mathematically fully verified or checked exactly against the FMDX database. Gray letters indicate a statistical prediction (e.g., Bigram correction) by the AI engine. As soon as the signal improves slightly, the engine overwrites the prediction with real data, and the letters turn white.

14. Version History (Changelog)

15. Credits

• App Developer: Highpoint
• Firmware Project: PE5PVB – TEF6686_ESP32
• Database Integration: fmlist.org / maps.fmdx.org

Developed in collaboration with the international FM‑DX community.