Table of Contents

1 · What is RDS?

RDS (Radio Data System) is a digital communication standard that transmits data as an inaudible signal modulated onto FM broadcasts (87.5–108 MHz). It was standardised under ETSI EN 50067 and has been in use across Europe since the 1980s. In North America, a nearly identical standard exists called RBDS.

RDS carries a variety of continuous digital metadata alongside the analog audio signal. The most commonly used data fields are:

RDS transmits at 1,187.5 bit/s as a BPSK signal on a 57 kHz subcarrier. A complete basic data block containing PI, PTY, TP, and two characters of the PS name requires 104 bits (26 bits per block × 4 blocks). A complete 8-character PS transmission takes approximately 0.35 seconds under perfect, error-free conditions.

2 · Why an AI Plugin?

Under local reception conditions with a strong antenna, RDS decoding is instantaneous and error-free. However, during long-distance FM reception (DX) – especially via tropospheric ducting, meteor scatter, or Sporadic-E propagation – signals are often extremely weak, rapidly fading, and severely affected by multipath interference or co-channel interference.

When the signal-to-noise ratio drops, the native RDS decoder built into the receiver chips (like TEF6686 / NXP) struggles:

• Packet loss: Entire RDS groups are lost in transit due to sudden deep fades.
• Bit errors: Individual bits flip, causing incorrect characters to be parsed.
• Incomplete PS names: Because the PS name is sent 2 characters at a time, severe fading often results in only 2 or 4 of the 8 characters being received correctly. The UI flickers between spaces, correct letters, and garbage.
• False Identifications: Extreme noise can occasionally trick the hardware CRC (Cyclic Redundancy Check) into accepting a garbage block as "valid", injecting random ghost PI codes or phantom PS characters.

3 · What's New in Version 2.4

Version 2.4 brings highly requested administrative features to the front-end, visualizes deep propagation data in the UI, and radically overhauls the database matching algorithms to favor smart propagation scoring over simple line-of-sight distance.

1. Extended Station Data Visualization v2.4

The Statistics panel now displays rich context for the matched FMDX.org reference. When a match occurs, the UI renders:

• Transmitter Location: The human-readable location name and its ITU country code (e.g., Wittenberg (D)).
• Transmitter Power: The Effective Radiated Power (ERP) in kW and the Polarization [H/V/M/C] (e.g., 100 kW [H]).
• Exact Path Metrics: The calculated Haversine distance in kilometers and the azimuth bearing in degrees from your current GPS location to the transmitter mast.

2. Smart Propagation Scoring v2.4

Previously, when multiple transmitters shared the same PI code, the algorithm simply selected the physically closest mast. Version 2.4 introduces the calculatePropagationScore() algorithm which uses real-world RF propagation physics to pick the most logical transmitter:

• Prioritizes strong signals (ERP scaling via logarithmic curves).
• Site verification: Grants massive bonuses if you are simultaneously receiving other frequencies from the same physical mast (using AF set cross-referencing).
• Sporadic-E checks: Recognizes patterns characteristic of SpE reflections and prevents aggressive local-only overrides.

3. Local Database UI Management v2.4

A brand new LOCAL DB section has been added to the main panel. It actively lists all stored memory entries specifically tied to the currently tuned frequency. It shows the stored PI, the resolved PS string, and the historical seen-count.

4. Admin Database Purge Controls v2.4

For users logged in as Administrators, the new LOCAL DB list features a red ✕ next to every entry. Clicking this executes an immediate WebSocket command (rdsm_delete_pi) to safely purge phantom, ghost, or misidentified PI codes from your persistent local rdsm_memory.json. A confirmation dialog prevents accidental clicks.

5. Panel State Persistence v2.4

Dragging the RDS panel around the screen is no longer temporary. The UI now saves its exact pixel coordinates in your browser's localStorage and automatically restores the panel to your preferred screen location across page reloads.

4 · Architecture – The Two Plugin Components

The plugin is strictly split into two layers:

1. The Server Layer (Node.js): This intercepts the low-level hex data arriving from the TEF chip over the serial connection. It performs all the heavy lifting: downloading the 30MB FMDX index, calculating Haversine distances, managing the persistent local JSON database, running the statistical weighting engine, and eventually forcibly overwriting the output of the native datahandler.js when RDS Follow Mode is enabled.
2. The Client Layer (Browser): A pure frontend UI written in vanilla JavaScript. It connects directly to the server plugin via a dedicated WebSocket channel. It performs no decoding logic of its own; it exists solely to draw the beautiful debugging panels, the statistical confidences, the FMDX verification badges, and to capture Admin commands like database deletions.

5 · Simple Explanation – How the Plugin Works

5.1 · Learning by Voting

The station name (PS) consists of 8 character positions. Each position is voted on separately. The receiver hardware flags every 16-bit block with an "Error Level" from 0 (perfect) to 3 (unrecoverable).

When the AI Decoder receives a raw PS character (e.g. at position 0), it looks at the hardware error level:

• Level 0: Perfect read. Awards heavy points to this character.
• Level 1: 1-bit error corrected by hardware. Awards medium points.
• Level 2/3: Corrupt. Discarded immediately.

These points are accumulated in the server's memory. As time passes, the points decay (using a 7-day half-life formula). This allows the plugin to "forget" old corrupted data while strongly favoring a consistent signal. After enough votes, a reliable station name emerges.

5.2 · fmdx.org Reference Database

On startup (and automatically every 6 hours) the plugin downloads the full FM transmitter database from maps.fmdx.org/api/?qth={lat},{lon} centred on the receiver's own location. All transmitters within a radius of 3000 km are indexed into two lightning-fast in-memory lookup tables.

Each fmdx.org entry provides:

• PI code – primary programme identification code
• PIreg – optional regional PI code used by some national networks
• PS name variants – one or more 8-character PS strings the station is known to broadcast
• Station name – the human-readable full name
• Distance – computed via Haversine formula

5.3 · PS Lock Engine and Hybrid Case

Once a PS name has been determined with high confidence, it is locked – the displayed name stops changing until the frequency or PI code changes. This totally eliminates UI flickering.

The lock is achieved through three priority levels:

The Hybrid Case System: Many stations transmit their PS names in ALL CAPS (e.g. ANTENNE ) but they look terrible in the UI. FMDX.org contains beautifully formatted mixed-case variants (e.g. Antenne ). The plugin uses a Hybrid Constructor: if the live received uppercase letter mathematically matches the reference mixed-case letter at the exact same position, the plugin swaps in the beautiful mixed-case letter before sending it to the web server.

5.4 · Provisional → Locked Status Display

Before a PS name is fully locked, the decoder goes through an intermediate provisional stage. This state is communicated to the user via the STATUS row in the panel.

5.5 · Frequency Change and Pre-Cache

When you change frequencies, the native decoder usually blanks out completely. The AI plugin behaves differently. Because it stores historical data in rdsm_memory.json, the moment you tune to a new frequency, it looks up known transmitters for that frequency.

If it finds a station in its memory that matches the frequency, it instantly prepares the "Predicted PS" and displays it in the statistics panel, even before a single RDS packet has been received from the antenna. If RDS Follow Mode is enabled, this cached prediction is immediately pushed to the web UI.

5.6 · Dynamic vs. Static Stations

Some stations unfortunately use their PS field to transmit scrolling text (song titles, phone numbers) instead of a static station name. This is officially illegal under the RDS standard but widely practiced (especially in Italy and Eastern Europe).

The AI decoder features a Dynamic Jump Engine. It maintains a rolling buffer of the last 8 full strings received. If it detects that the strings are shifting sideways (scrolling) or constantly alternating between vastly different words, it flags the PI code as isDynamic: true.

When a station is flagged as dynamic, the statistical voting engine is completely bypassed, because voting on scrolling text produces absolute garbage (a mix of letters from different words). Instead, the plugin switches to a raw pass-through mode for that station.

5.7 · Alternate Frequency (AF) Decoding

The Alternate Frequency list is transmitted as a highly compressed set of 8-bit codes. The plugin decodes these codes according to the standard table (Method A):

Code 1 = 87.6 MHz ... Code 204 = 107.9 MHz

The decoded frequencies are maintained in a Set to guarantee uniqueness. In the UI, the AF badge illuminates and displays the total count. Hovering over the badge reveals the exact list of frequencies.

5.8 · RDS Follow Mode

By default, the AI Decoder operates purely as an invisible observer. It draws its own floating statistics panel but does not alter the main web interface (the large blue PS blocks and RadioText banner at the top of the FM-DX-Webserver page). The native TEF hardware controls the main UI.

Clicking the RDS Follow button at the bottom of the stats panel takes the AI active. Once activated, the AI plugin forcefully intercepts the data pipeline and injects its mathematically stabilized, FMDX-verified, hybrid-cased PS strings and RadioText directly into the main web server UI. The flickering native decoder is completely overridden.

5.9 · Special / Wildcard PI Codes

Certain PI codes are considered invalid or uninformative by the standard, particularly 0000 and FFFF. Cheap transmitters or pirate stations often use these.

The plugin has a special bypass logic for these. If it detects 0000 or FFFF, it skips database lookup, skips FMDX verification, and skips statistical voting. It acts purely as a raw pass-through, allowing you to see the raw text of pirate stations without the AI attempting to "correct" them into known stations.

5.10 · Regional PI Codes (PIreg)

In many countries (like Germany or France), national networks broadcast identical programming on dozens of transmitters, but insert local news for 5 minutes an hour. During those 5 minutes, they switch their PI code to a "Regional" PI code.

The plugin supports this flawlessly. The FMDX database download brings both the Primary PI and the Regional PI. If the plugin detects the Regional PI, it mathematically treats it exactly the same as the Primary PI. The station will lock instantly without needing to rebuild its statistical voting profile from scratch.

5.11 · The Panel – Display Elements

The floating AI panel is divided into sections:

• Header: Drag handle, version info, connection status dot, manual link (?), and close button.
• PS Slots: Eight massive characters representing the live prediction. The brightness of the letter indicates confidence. The colored bar underneath indicates the source (Blue = Statistical/Raw, Gold = FMDX confirmed).
• RT: Shows the previously completed RadioText line, and the currently forming line.
• Flags: TP, TA, MUSIC/SPEECH, STEREO, AF count, ECC byte.
• Groups: A live matrix illuminating which RDS group types (0A, 2A, 4A etc.) are currently being received.
• FMDX.ORG: See section 5.12.
• LOCAL DB: See section 5.13.
• Footer: Total group count, RDS Follow button, and the live BER (Bit Error Rate) rolling tape.

5.12 · Extended FMDX Station Data v2.4

A new feature in v2.4. When the statistics panel is expanded (by clicking the STATISTICS button), and a valid FMDX database match occurs, a golden highlighted section appears.

It displays:

• 🌐 fmdx.org [Station Name]
• match: [XX]% - How closely the live characters match the reference.
• [Tx Site Name] ([ITU Code]) - Example: Berlin/Scholzplatz (D).
• [ERP] kW [Polarization] · [Distance] km · [Azimuth]°

This allows DXers to instantly verify not just what station they are receiving, but exactly where it is transmitting from, its power output, and which direction to point their directional yagi antennas.

5.13 · Local Database Management v2.4

Also new in v2.4, the main panel now features a LOCAL DB section at the very bottom.

This UI dynamically queries the server's rdsm_memory.json and extracts all stations that the plugin has ever seen on the currently tuned frequency. It shows the PI code, the locked PS string, whether it was flagged as dynamic (⚡), and how many packets it has historically received.

Deletion: Sometimes the TEF hardware generates a "Ghost PI" - a totally fake PI code generated by random noise that unfortunately passes the CRC check. If the plugin logs this, it will appear in the Local DB list. Logged-in Administrators will see a red ✕ next to the entry. Clicking this deletes the phantom station from the server's permanent memory immediately.

6 · Technical Deep Dive

6.1 · RDS Group Structure and Error Correction

An RDS data stream consists of consecutive "Groups", each 104 bits long. A group is split into 4 Blocks (A, B, C, D) of 26 bits each. Each block contains 16 bits of payload data and 10 bits for a Checkword/Offset word used for Error Detection and Correction.

• Block A: Always contains the 16-bit PI code.
• Block B: Contains the Group Type (e.g. 0A, 2A), PTY, TP, and addressing bits.
• Block C / C': Contains Alternate Frequencies or is used for RadioText.
• Block D: Usually contains the PS string characters (2 chars per group) or RadioText segments.

The native receiver chip evaluates the 10-bit checkword and assigns an error level array (e.g. errB = [0, 0, 1, 3]) for the four blocks:

• 0: No errors found. Math is perfect.
• 1: Small burst error detected, mathematically corrected by hardware. Trustworthy.
• 2: Large error detected. Uncorrectable. Garbage data.
• 3: Complete synchronization failure.

The AI decoder strictly ignores any payload data from a block that has an error level of 2 or 3. Only levels 0 and 1 are permitted into the voting algorithms.

6.2 · fmdx.org Bulk Index & Smart Propagation Score v2.4

The plugin downloads roughly 30MB of JSON data from the FMDX APIs. It parses this immense list of global transmitters and filters out anything further than 3000km from your GPS location.

In version 2.4, selecting the correct transmitter when multiple sites share a PI code is no longer based purely on shortest distance. The new calculatePropagationScore(ref, dbEntry) function calculates a weighted score based on physics:

function calculatePropagationScore(ref, dbEntry) {
    if (!ref) return 0;
    const distKm = ref.distKm || 9999;
    let distScore = 0;
    
    // Distance Tiers
    if (distKm <= 100) distScore = 100;
    else if (distKm <= 300) distScore = 80;
    else if (distKm <= 800) distScore = 40; 
    else if (distKm <= 2500) distScore = 20; 
    else distScore = 5;
    
    // Power (ERP) factor: Logarithmic scale up to 50 points
    const erp = ref.erp || 0.1;
    const pwrScore = Math.min(50, Math.log10(Math.max(1, erp * 10)) * 15);
    
    // Site Verification: Cross-referencing active AFs
    let siteBonus = 0;
    if (ref.txName) {
        let sharedSites = 0;
        for (const f of currentState.afSet) {
            const freqRefs = getFreqRefs(f);
            if (freqRefs.some(r => r.txName === ref.txName)) sharedSites++;
        }
        siteBonus = Math.min(30, sharedSites * 10);
    }
    
    // Sporadic-E characteristic check
    let spEBonus = 0;
    if (distKm > 800 && distKm < 2500) {
        const cleanCount = countCleanRawPositions();
        if (cleanCount >= 4) spEBonus = 20;
    }
    
    // Historical confirmation bonus
    let histBonus = 0;
    if (dbEntry && dbEntry.seenCount > 10) histBonus = 15;
    
    return distScore + pwrScore + siteBonus + spEBonus + histBonus;
}

6.3 · PS Lock Engine – Priority Ladder

The checkAndLockPS(pi) function is the core supervisor of the UI state. It runs every time a new RDS packet arrives. It evaluates the current live buffer against the memory and the reference.

It uses a strict priority ladder:

1. If a fully verified string already exists in the local database (entry.psVerifiedRaw), use it.
2. If the live buffer characters match an FMDX.org reference string at >75%, construct a hybrid string and lock it.
3. If 8/8 characters are received error-free directly from the airwaves, run them against the strict FMDX sanity filter (to block CRC collisions). If they pass, lock and store as psVerifiedRaw.

6.4 · Provisional → Locked Status Engine

The client UI calculates the STATUS string based on boolean flags and confidences sent by the server:

• psProvisionalConf must exceed 0.55 (55%) to move from WAIT to PROVISIONAL.
• psStableMs measures how long the provisional string has remained totally unchanged.
• psLocked is a boolean. When true, the UI turns green and displays the psLockReason.

6.5 · Voting Engine – Compact Aggregation Format

Votes are stored in rdsm_memory.json in a compact format to prevent file bloat. Instead of storing an array of 5,000 "N"s, it stores an aggregated weight object:

"ps": {
  "0": {
    "N": {
      "w": 45.2,
      "count": 120,
      "firstSeen": 1712849200,
      "lastSeen": 1712850000
    }
  }
}

The weight (w) decays mathematically based on the time elapsed since lastSeen, using the VOTE_HALFLIFE_DAYS constant (7 days).

6.6 · Confidence Calculation

Confidence is a floating point number between 0.0 and 1.0. It is calculated by blending multiple factors:

• Raw Factor (42%): How many of the 8 slots are currently reporting hardware error level 0 or 1.
• Reference Factor (33%): How closely the live buffer matches the FMDX.org variant for this PI. Modulated by the ECC Country Multiplier (penalizing if the country codes don't match).
• Voted Average (18%): The statistical dominance of the winning character across all historical votes.
• AF Coverage Bonus (+10%): If the live received Alternate Frequencies match the FMDX.org database frequencies.
• Dynamic Penalty (-15%): Applied if the station is known to scroll text, forcing it to remain provisional longer.

6.7 · PI Verification Pipeline

To prevent a random hardware bit-flip from generating a totally fake PI code and polluting the database, the server requires a PI code to be verified multiple times before it is considered "real".

The threshold for verification is dynamic. The getConfirmThreshold(pi) function lowers the requirement if there is strong evidence the PI is real. For example, if the PI exists in the FMDX database for the tuned frequency at a distance < 500km, the threshold drops to 1 (instant verification). If it's totally unknown, it requires multiple identical packets.

6.8 · Database Format and Storage Management

The local database rdsm_memory.json is saved automatically every 60 seconds (DB_SAVE_INTERVAL). On exit (SIGINT/SIGTERM), an emergency save is fired.

To prevent infinite growth, the memory is capped at MAX_STATIONS = 2000. When saving, the server purges:

• Stations older than STATION_EXPIRE_DAYS (90 days).
• Weak entries (no PS, no AFs, seen < 2 times) older than QUICK_EXPIRE_DAYS (7 days).
• Any stations beyond the 2000 limit, sorted by oldest `lastSeen` date.

6.9 · WebSocket Protocol and Delete Logic v2.4

The client and server communicate via a standard JSON WebSocket protocol. The server broadcasts payloads of type: 'rdsm_ai' continuously.

In version 2.4, a new client-to-server command was added for Admin deletion:

{
  "type": "rdsm_delete_pi",
  "pi": "D3C3"
}

When the server receives this, it deletes the D3C3 key from the db object and sets dbDirty = true. The client optimistically updates its own UI instantly.

6.10 · dataHandler Patch – Property Locking

To override the native datahandler.js, the server plugin intercepts the variables right before they are dispatched via the main Webserver WebSockets. It overwrites dataHandler.dataToSend.ps and dataHandler.dataToSend.pi with the mathematically verified AI strings. It also forces dataHandler.dataToSend.ps_errors = '0,0,0,0,0,0,0,0' to tell the native UI to stop flickering.

6.11 · FMDX.ORG Panel – Frequency Chips and AF Coverage

The client UI calculates the "AF Coverage %". It extracts the array of Alternate Frequencies from the active FMDX.org JSON reference block. It then compares this array against the live currentState.afSet (the AFs currently being decoded from the live radio signal). The overlap percentage is rendered in the UI.

The UI creates a horizontal scrolling list of "Frequency Chips". The chips turn bright blue if the frequency is actively being received, and stay grey if it is listed in the database but currently missing from the live signal.

6.12 · GPS WebSocket Listener

The server plugin connects to its *own* local websocket at `ws://127.0.0.1:8080/data_plugins` to listen for GPS payloads. If a connected TEF receiver has a GPS module attached, or if a user inputs manual coordinates into the web interface, the server catches the type: 'GPS' payload.

To prevent noisy GPS modules from triggering a 30MB FMDX index rebuild every 5 seconds, the coordinates are rounded to 2 decimal places (`roundGps`), and a rebuild is only triggered if the distance moved exceeds FMDX_REINDEX_MIN_DIST_KM (100km).

6.13 · Panel State Persistence v2.4

The frontend Javascript hooks into the `mouseup` event of the drag handler. It reads `el.style.left` and `el.style.top` and dumps a JSON object into `window.localStorage.setItem('rdsm_panel_pos')`. On page load, this is parsed and injected directly into the DOM CSS properties, guaranteeing the panel stays exactly where you left it.

7 · REST API Reference

While the AI Decoder communicates primarily over WebSockets for live data, it exposes a silent footprint on the main HTTP API of the FM-DX Webserver.

When polling the /api endpoint of the server, standard RDS fields are replaced by the AI if Follow Mode is active:

{
  "freq": "104.600",
  "pi": "D3B8",
  "ps": "RTL     ",
  "pty": 10,
  "rds": true,
  "ta": 0,
  "tp": 1,
  "ms": 1,
  "af": [89000, 104600],
  "rt0": "RTL - BERLINS HITRADIO",
  "country_name": "Germany",
  "country_iso": "DE"
}

If Follow mode is disabled, the /api returns the native hardware decoding results, which may contain spaces or errors like "R L ".

8 · Configuration Parameters

Advanced users can tweak the constants at the top of rds-ai-decoder_server.js to tune the AI behavior for specific DXing styles (e.g. meteor scatter vs tropo).

9 · Troubleshooting & FAQ

The FMDX match says 0% even though the station is correct.

This happens when the FMDX database variant uses special characters, differing casing, or abbreviations that mathematically clash with the raw data. Ensure you have given the station enough time to decode cleanly. If the station recently rebranded, the FMDX database might simply be out of date. The AI will eventually lock onto the Raw RDS string instead of the FMDX variant.

The panel is stuck on "WAIT collecting..." forever.

The signal is too weak, or the TEF chip is dropping every packet with Error Level 2 or 3. The plugin aggressively filters out garbage data. If the hardware cannot deliver a single Level 1 packet, the AI has nothing to vote on.

I clicked the red ✕ to delete a PI, but it came back instantly!

If you are still tuned to the frequency and the hardware is still decoding that exact PI code from the noise floor, the plugin will instantly recreate the memory entry. Tune away to a blank frequency before purging ghost PI codes.

Why is "RDS Follow" greyed out?

You must be logged into the FM-DX-Webserver as an Administrator. The standard Webserver authentication applies. Because RDS Follow forcefully overrides the main display for everyone viewing the server remotely, guest access to this toggle is strictly prohibited.

My GPS coordinates drifted and caused a massive lag spike.

Ensure your GPS hardware has a solid lock. The plugin mitigates GPS jitter by rounding to ~1km and requiring a 100km total movement before triggering the 30MB FMDX index rebuild. If you see constant console logs about "fmdx.org index built", your coordinates in `config.json` might be oscillating wildly due to a bad script pushing fake GPS data to the websocket.