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.

RDS carries among others the following information:

RDS transmits at 1,187.5 bit/s as a BPSK signal on a 57 kHz subcarrier. A complete PS transmission takes approximately 0.35 seconds under error-free conditions.

2 · Why an AI Plugin?

During long-distance FM reception (DX) – especially via tropospheric ducting or Sporadic-E propagation – signals are often weak and affected by multipath interference or co-channel interference. This results in:

• Packet loss: Entire RDS groups are lost in transit
• Bit errors: Individual bits are decoded incorrectly
• Incomplete PS names: Only 2–3 of the 8 characters are received correctly
• Unknown PI codes: Block A contains errors, PI unreadable

3 · What's New in Version 2.2a

Version 2.2a is a targeted bug-fix release. No new features are introduced; the three fixes below address edge-case defects in the PS lock engine and the PI confirmation handler that were identified through field testing after the v2.2 release.

4 · Architecture – The Two Plugin Components

5 · Simple Explanation – How the Plugin Works

Imagine listening to an announcement in a busy train station with a lot of background noise. The first time you might only catch "...NR...", the second time "...NRJ...". After hearing it 10 times, you can say with high confidence: the announcement said "NRJ".

That is exactly what the plugin does with RDS data: it listens to many erroneous packets, collects them all, and votes statistically on which character at which position is most likely the correct one. In v2.0 it additionally consults the online fmdx.org transmitter database to cross-check and immediately confirm the station name. Version 2.1 extended this with regional PI codes and special PI pass-through. Version 2.2 makes the confidence journey visible in the panel through the new Provisional → Locked status display. Version 2.2a corrects three subtle defects in the lock engine that could prevent correct locking in specific edge cases.

5.1 · Learning by Voting

The station name (PS) consists of 8 character positions. Each position is voted on separately:

After enough votes, a reliable station name emerges. Through its database the plugin already knows thousands of stations – for recognised ones, the full name is available immediately.

5.2 · fmdx.org Reference Database

On startup (and 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 in-memory lookup tables: one keyed by frequency (fmdxByFreq), and one keyed by PI code (fmdxByPI).

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 eliminates the flickering that occurs when weak reception alternately produces correct and incorrect characters.

The lock is achieved through three priority levels:

After a lock is set, the dynamic jump engine handles stations with multiple PS variants. When the live buffer matches a different known variant at ≥ 75%, the locked PS jumps to the new variant without unlocking.

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, located directly below the PI Code row.

The STATUS row cycles through three visual states:

5.5 · Frequency Change and Pre-Cache

When tuning to a new frequency, the following sequence runs:

5.6 · Dynamic vs. Static Stations

5.7 · Alternate Frequency (AF) Decoding

RDS Group 0A Block C carries up to two AF codes per group. The plugin decodes these codes according to the ETSI EN 50067 formula:

function decodeAFCode(code) {
  // code 1–204 → frequency in MHz: (code + 875) / 10
  // e.g. code 1 → 87.6 MHz, code 204 → 107.9 MHz
  if (code >= 1 && code <= 204) return (code + 875) / 10;
  return null;   // 205–255 are special codes (filler, LF/MF, ...)
}

Decoded frequencies are stored in the DB, displayed in the AF flag, forwarded to the dataHandler in Follow mode, and cross-referenced against the fmdx.org altFreqs list for the coverage badge in the FMDX.ORG panel row.

5.8 · RDS Follow Mode

5.9 · Special / Wildcard PI Codes

Certain PI codes are reserved and must never be treated as real station identifiers:

When isSpecialPI(pi) returns true, the plugin enters a pass-through mode:

• No voting, no DB writes, no PS lock
• Raw PS characters from the live buffer are forwarded directly to the AI prediction and, in Follow mode, to the dataHandler
• The FMDX.ORG section remains empty (no reference lookup)
• PI is confirmed immediately with threshold = 1
• freqRefs is set to an empty array (no fmdx.org gate applied)
• STATUS row remains at WAIT (no locking occurs)

5.10 · Regional PI Codes (PIreg)

Some national radio networks transmit a regional PI code (pireg) instead of a single primary national PI code. Without PIreg support, the received regional PI would fail the fmdx.org lookup. The plugin's two-priority lookup handles this transparently: primary PI is checked first, then pireg. When a match is found via pireg, the stats object carries both pireg (the received code) and piMain (the primary PI back-reference).

5.11 · The Panel – Display Elements

6 · Technical Deep Dive

6.1 · RDS Group Structure and Error Correction

An RDS group consists of 4 blocks of 26 bits each (16 bits payload + 10 bits CRC checksum). The error correction code is a shortened cyclic code capable of detecting up to 5 bit errors and correcting up to 2 bit errors per block.

The plugin receives these error levels as the array errB[0..3] and converts them into confidence weights:

Group types and their relevance to the plugin

6.2 · fmdx.org Bulk Index, Distance Filter and PIreg

After downloading the bulk transmitter data from maps.fmdx.org/api/?qth={lat},{lon}, the plugin builds two in-memory indexes. The pipeline indexes both the primary PI and the optional regional PIreg:

Reference matching at runtime – two-priority lookup

function findBestRefEntry(pi) {
  if (isSpecialPI(pi)) return null;
  const refs  = fmdxByFreq[roundFreq(currentFreq)] || [];
  const piUp  = pi.toUpperCase();

  // Priority 1: exact primary PI match on current frequency
  const exact = refs.filter(r => r.pi === piUp);
  if (exact.length === 1) return exact[0];
  if (exact.length > 1)
    return exact.sort((a,b) => (a.distKm??99999)-(b.distKm??99999))[0];

  // Priority 2: regional PI (pireg) match on current frequency
  const piRegMatches = refs.filter(r => r.pireg && r.pireg === piUp);
  if (piRegMatches.length === 1) return piRegMatches[0];
  if (piRegMatches.length > 1)
    return piRegMatches.sort((a,b) => (a.distKm??99999)-(b.distKm??99999))[0];

  return null;
}

6.3 · PS Lock Engine – Priority Ladder

The PS lock is managed by checkAndLockPS(pi), called after every complete PS round (all 4 segments received). Special PIs are never locked – they bypass this function entirely.

6.4 · Provisional → Locked Status Engine

Before a PS is fully locked, the server tracks a provisional candidate – the best current guess with its associated confidence and how long it has been stable. This state is broadcast in every rdsm_ai message and rendered by the client as the STATUS row.

Server-side: building the provisional state

The server computes the provisional PS and its metadata in buildAIPrediction(). The key fields populated are:

Client-side: renderStatus()

function renderStatus() {
  const el = document.getElementById('rdsm-status');
  if (!el) return;

  if (st.psLocked) {
    const reason = st.psLockReason ? ` – ${st.psLockReason}` : '';
    el.innerHTML = `
      <span class="rf on" style="background:#1b3b2a;color:#44ff88;
        border:1px solid #44ff88;padding:3px 7px;line-height:1.6;">LOCKED</span>
      <span style="color:#777;font-size:11px;">${reason}</span>`;
    return;
  }

  const confPct = Math.round((st.psProvisionalConf || 0) * 100);
  if (st.psProvisional && confPct >= 55) {
    const stableS = (st.psStableMs || 0) / 1000;
    el.innerHTML = `
      <span class="rf on" style="background:#2a2331;color:#c8a020;
        border:1px solid #c8a020;padding:3px 7px;line-height:1.6;">PROVISIONAL</span>
      <span style="color:#888;font-size:11px;">
        ${confPct}% · stable ${stableS.toFixed(1)}s</span>`;
  } else {
    el.innerHTML = `
      <span class="rf" style="border:1px solid #2a2a2a;">WAIT</span>
      <span style="color:#555;font-size:11px;">collecting…</span>`;
  }
}

Integration points

• onAI(d) – updates all five fields from the incoming message, then calls renderStatus() and renderAll()
• reset() – sets psProvisional = null, psProvisionalConf = 0, psStableMs = 0, psLockReason = null, psLocked = false, then calls renderStatus()

CSS

#rdsm-status { overflow: visible; line-height: 1.8; }

6.5 · Three Bug Fixes in v2.2a FIX

This section provides the full technical context for each of the three bug fixes introduced in v2.2a.

Bug 1 – psIsDynamic false positive reset in onPIConfirmed()

Root cause

The psIsDynamic flag is set to true by checkPSDynamic() when either a scrolling pattern or at least two recurring different PS strings are detected over time. Once set, this flag is sticky: it is only cleared on a frequency change or plugin restart. There was no code path that re-evaluated the flag against fresh fmdx.org evidence at PI confirmation time.

This created a feedback loop: a station that briefly exhibited a scrolling PS during a poor DX episode (or whose DB entry was polluted by a co-channel interference event on the same frequency) was permanently treated as dynamic, bypassing all voting and lock logic.

Fix

At the beginning of onPIConfirmed(pi), immediately after retrieving the fmdx.org reference entry, the following guard clause was added:

// Bug 1 fix: reset psIsDynamic if fmdx.org has exactly one static variant
if (entry.psIsDynamic && ref?.psVariants?.length === 1) {
    entry.psIsDynamic = false;
    entry.ps          = {};
    entry.psResolved  = null;
    entry.psConf      = new Array(8).fill(0);
    dbDirty = true;
    if (DEBUG) logInfo(`[${PLUGIN_NAME}] PI ${pi}: psIsDynamic reset (fmdx ref has 1 static variant)`);
}

Conditions for reset

Both conditions must hold simultaneously. If fmdx.org lists 0 variants (unknown station) or 2+ variants (genuinely multi-variant), the flag is not touched.

Effect

After the reset, the vote table is empty and the entry behaves like a freshly seen station. The fmdx.org seed is then applied (as for any new PI), and the lock engine proceeds normally. On subsequent receptions the station will accumulate votes and reach LOCKED state via Priority A, B, or C as appropriate.

Bug 2 – psVerifiedRaw not stored when fmdx.org ref exists

Root cause

Inside checkAndLockPS(), the block that writes entry.psVerifiedRaw when a full raw verification round succeeds (allRawVerified = true) was guarded by:

// v2.2 (buggy):
if (allRawVerified) {
    const candidate = currentState.psBuf.join('');
    if (isPSStringClean(candidate)) {
        const nu = candidate.trim().toUpperCase();
        const ok = !ref?.psVariants?.length ||
            ref.psVariants.some(v => ...);
        if (ok && !entry.psVerifiedRaw) {
            entry.psVerifiedRaw   = candidate;
            entry.psVerifiedRawTs = Date.now();
            dbDirty = true;
        }
    }
}
// Only reached if !newPS (i.e. Priority A and B both produced null)
if (!newPS && allRawVerified) {
    // set newPS from psBuf
}

The outer write block (the one that stores psVerifiedRaw in the DB) was placed inside a branch that was only reached when Priority A (psVerifiedRaw already exists) and Priority B (fmdx.org match ≥ 75%) both failed to produce a newPS. Because Priority B succeeds for any well-known station on a clean reception day, the outer write block was never entered for those stations – a clean raw round was never cached.

Fix

The psVerifiedRaw write block was lifted out of the conditional ladder and placed unconditionally within the allRawVerified check, using a plain else instead of else if (!ref?.psVariants?.length):

// v2.2a (fixed): psVerifiedRaw is always stored when allRawVerified,
// regardless of whether a fmdx.org reference exists.
if (allRawVerified) {
    const candidate = currentState.psBuf.join('');
    if (isPSStringClean(candidate)) {
        const nu = candidate.trim().toUpperCase();
        const ok = !ref?.psVariants?.length ||
            ref.psVariants.some(v =>
                v.trim().toUpperCase() === nu ||
                v.trim().toUpperCase().startsWith(nu) ||
                nu.startsWith(v.trim().toUpperCase()));
        if (ok && !entry.psVerifiedRaw) {
            entry.psVerifiedRaw   = candidate;
            entry.psVerifiedRawTs = Date.now();
            dbDirty = true;
        }
    }
}

Effect

After this fix, the first error-free complete PS round for any station – including those with a fmdx.org reference – is stored in psVerifiedRaw. On subsequent sessions the lock engine can use Priority A immediately instead of having to rediscover the PS via votes or reference matching. This accelerates locking and makes the plugin more robust on frequencies where fmdx.org match scores are borderline.

Bug 3 – Priority A fallback unreachable due to else if logic error

Root cause

In the Priority A branch of checkAndLockPS(), the code was structured as:

// v2.2 (buggy):
if (entry.psVerifiedRaw && isPSStringClean(entry.psVerifiedRaw) &&
    entry.psVerifiedRaw.trim().length > 0) {

    if (ref?.psVariants?.length > 0) {
        if (refMatchIsGood && bestScore >= 0.8)
            newPS = buildHybridPS(bestVariant);
        else
            newPS = entry.psVerifiedRaw;   // ← inner else: correct
    } else if (!ref?.psVariants?.length) {
        newPS = entry.psVerifiedRaw;      // ← outer else if: UNREACHABLE
                                          //   (!A === !A is tautology of outer if)
    }
    if (newPS) lockReason = 'DB verified string';
}

The else if (!ref?.psVariants?.length) is the logical complement of if (ref?.psVariants?.length > 0). These two branches are mutually exclusive and exhaustive – the outer else if could never be reached because its condition is identical to the negation of the preceding if condition. In JavaScript, when the outer if is false (no variants), the else if is true, but since both expressions evaluate to the same boolean, the branch is equivalent to a plain else. However, because the inner else (inside if (ref?.psVariants?.length > 0)) already assigns newPS = entry.psVerifiedRaw when refMatchIsGood is false, the outer else if only matters for the case where there is no reference at all – and there it is indeed reachable.

The actual defect is subtler: when a reference exists but refMatchIsGood is false, the inner else correctly sets newPS = entry.psVerifiedRaw. But when a reference exists and refMatchIsGood is true but bestScore < 0.8, the inner if is false and the inner else sets newPS = entry.psVerifiedRaw – this is actually correct. The real issue revealed by code review is that the structure was confusing and the outer else if was redundant noise that could mask future refactoring errors.

The fix simplifies the structure to a plain else, making the intent unambiguous:

// v2.2a (fixed):
if (entry.psVerifiedRaw && isPSStringClean(entry.psVerifiedRaw) &&
    entry.psVerifiedRaw.trim().length > 0) {

    if (ref?.psVariants?.length > 0) {
        if (refMatchIsGood && bestScore >= 0.8)
            newPS = buildHybridPS(bestVariant);
        else
            newPS = entry.psVerifiedRaw;
    } else {                              // ← plain else (was: else if)
        newPS = entry.psVerifiedRaw;
    }
    if (newPS) lockReason = 'DB verified string';
}

Effect

The simplified structure ensures that whenever Priority A is reached and entry.psVerifiedRaw is present and clean, newPS will always be set to either a hybrid PS (when fmdx.org match is strong) or the raw verified string (all other cases). No code path within Priority A can now produce newPS = null.

Combined impact of all three fixes

6.6 · Voting Engine – Compact Aggregation Format

A compact aggregated format is used instead of a list of individual timestamps. Votes are never cast for special PIs.

Format per character position (JSON)

// db[pi].ps[position][character]
{
  "w":         147.3,         // current weighted score (lazy-decayed)
  "count":     18,            // raw number of votes received
  "firstSeen": 1773554046944, // Unix timestamp of first vote (ms)
  "lastSeen":  1773554677188  // Unix timestamp of last vote (ms)
}

Lazy Exponential Decay

function applyDecay(v, now) {
  const ageMs  = now - v.lastSeen;
  const halfMs = 7 * 86400000;
  v.w        = v.w * Math.pow(0.5, ageMs / halfMs);
  v.lastSeen = now;
}

Values below 0.1 weight with fewer than 3 votes are deleted on the next write access (noise suppression).

Consistency Boost

When a character already clearly dominates (weight > 2× all competitors combined), the new vote receives a multiplier of 1.5×.

6.7 · Confidence Calculation

conf = share      * 0.5   // winner's share of total weight
     + dominance  * 0.3   // gap between winner and runner-up
     + voteFactor * 0.2   // experience factor (saturates at 30+ votes)

// Upper bound: 0.97

Confidence Scale – Colour Mapping in the Panel

Normal: rgb(v) where v = 20 + conf × 220  ·  ref-match: warm gold  ·  ref-seed: amber  ·  bigram: v = 15 + conf × 30

PS source types

6.8 · PI Verification Pipeline

6.9 · Special PI Pass-Through

6.10 · Database Format and Storage Management

File structure (rdsm_memory.json)

{
  "_meta": {
    "rdsFollowMode": false,
    "savedAt": 1773556231184,
    "dbVersion": 1
  },
  "D3C3": {
    "freq":           "104.00",
    "ps": { "0": { "N": {w,count,firstSeen,lastSeen}, ... }, ... },
    "psResolved":    "NRJ     ",
    "psConf":        [0.97,0.95,0.93,0,0,0,0,0],
    "psVerifiedRaw": "NRJ     ",
    "psVerifiedRawTs": 1773554677188,
    "psIsDynamic":   false,
    "psLastRaw":     ["N","R","J"," "," "," "," "," "],
    "psLastRawTs":   1773554677188,
    "pty":           10,
    "tp":            true,
    "ta":            false,
    "ms":            1,
    "stereo":        true,
    "ecc":           "E1",
    "af":            [89.5, 94.1, 98.0],
    "seen":          1773554677188,
    "seenCount":     847
  }
  // Note: special PI codes (FFFF, 0000) are NEVER stored here
}

psVerifiedRaw integrity check

On load and before every save, isPSStringClean() validates any stored psVerifiedRaw. Strings containing characters outside printable ASCII (0x20–0x7E) or extended Latin (0xA0–0xFF) are discarded. This prevents corrupt blocks from a previous errLevel-2 decode session from poisoning future sessions.

DB Version Migration

When the server starts and finds a database without _meta.dbVersion === 1, it performs a one-time automatic wipe. The rdsFollowMode setting is preserved across the wipe.

Retention periods and limits

6.11 · WebSocket Protocol

Communication between the server plugin and the browser runs over WebSocket on the path /data_plugins. All messages are JSON.

Example rdsm_ai payload (v2.2a)

{
  "type":       "rdsm_ai",
  "pi":         "D3C3",
  "ps": [
    { "char": "A", "conf": 0.97, "src": "ref-match" },
    { "char": "n", "conf": 0.95, "src": "ref-match" },
    // ... 6 more slots
  ],
  "rt": { "text": "Dua Lipa - Levitating", "score": 0.72, "src": "raw-rt" },
  "af":         [89.5, 94.1, 98.0],
  "psName":     "Antenne Bayern",
  "psNameSrc":  "fmdx",
  "psVariants": ["Antenne ", "ANTENNE "],
  "altFreqs": [
    {
      "freq":       "89.5",
      "distKm":     88,
      "station":    "Antenne Bayern",
      "psVariants": ["Antenne "]
    }
  ],
  "psProvisional":     "Antenne ",
  "psProvisionalConf": 0.87,
  "psStableMs":        4800,
  "psLockReason":      "FMDX match 95%",
  "psLocked":          true,
  "stats": {
    "freq":          "104.00",
    "seenCount":     847,
    "psVoteTotal":   312,
    "psIsDynamic":   false,
    "psLocked":      true,
    "refStation":    "Antenne Bayern",
    "refDistKm":     142,
    "refMatchScore": 95,
    "pireg":         null,
    "piMain":        null
  },
  "ts": 1773556231184
}

6.12 · dataHandler Patch – Property Locking

The native decoder receives the complete raw stream in all modes. In Follow mode, all writes to the protected fields are intercepted via JavaScript property descriptors and restored after the native decoder returns.

dh.handleData = function(wss, receivedData, rdsWss) {
  // 1. AI parsing runs first (always)
  interceptLines(receivedData);

  if (aiExclusiveMode) return;

  if (rdsFollowMode && piConfirmed) {
    applyFollowToDataHandler();

    const locked = {};
    fields.forEach(f => {
      locked[f] = dh.dataToSend[f];
      Object.defineProperty(dh.dataToSend, f, {
        get: () => locked[f],
        set: () => {},
        configurable: true
      });
    });

    const result = orig.call(this, wss, receivedData, rdsWss);

    fields.forEach(f => {
      Object.defineProperty(dh.dataToSend, f, {
        value: locked[f], writable: true, configurable: true
      });
    });
    return result;
  }

  return orig.call(this, wss, receivedData, rdsWss);
};

Locked fields: pi, ps, ps_errors, pty, tp, ta, ms, rt0, rt1, rt0_errors, rt1_errors, rt_flag, true, configurable: true }); }); return result; } return orig.call(this, wss, receivedData, rdsWss); };

Locked fields: pi, ps, ps_errors, pty, tp, ta, ms, rt0, rt1, rt0_errors, rt1_errors, rt_flag, ecc, country_iso, country_name, af.

// Excerpt from bigram table:
BIGRAM = {
  ' ': { 'R':25, 'S':20, 'M':18, 'F':15, ... },
  'F': { 'M':40, 'R':12, ... },
  // 26 letter rows + digit rows
}
// Confidence of a bigram guess: max. ~10% – clearly a placeholder

ws.on('message', (raw) => {
  const msg = JSON.parse(raw);
  if (msg.type === 'GPS' && msg.value.status === 'active') {
    if (lat !== ownLat || lon !== ownLon) {
      ownLat = lat; ownLon = lon;
      // Rebuild fmdx.org index (both fmdxByFreq and fmdxByPI)
      if (fmdxLoadedAt > 0) buildFmdxIndex(cachedRaw);
    }
  }
});

<!-- Inside the rdsm-hdr flex bar -->
<a id="rdsm-manual-link"
   href="https://highpoint.fmdx.org/manuals/RDS-AI-Decoder-Documentation-v2.2a.html"
   target="_blank"
   title="Open RDS AI Decoder Manual">?</a>

// rds-ai-decoder_server.js – top of module
let _aiTimer = null;

// Cancel any pending broadcast before scheduling a new one
if (_aiTimer) { clearTimeout(_aiTimer); _aiTimer = null; }
_aiTimer = setTimeout(() => {
    _aiTimer = null;
    broadcast({ type: 'rdsm_ai', ...prediction, ts: Date.now() });
    if (rdsFollowMode) applyFollowToDataHandler();
}, AI_BROADCAST_DELAY);

{
  "stationCount":  312,
  "fmdxFreqCount": 4872,
  "fmdxPICount":   5140,
  "rdsFollowMode": false,
  "aiExclusiveMode": false,
  "piConfirmed":   true,
  "psLocked":      true,
  "currentPI":     "D3C3",
  "currentFreq":   "104.00"
}