Table of Contents

1 · What is the Scanner Plugin?

The Scanner Plugin is a comprehensive add-on for the FM-DX-Webserver that transforms a passive FM receiver into an intelligent, automated FM DX logging station. It provides automatic frequency scanning across the FM band (or a configurable sub-range), real-time RDS-based station identification, sophisticated signal filtering, and automated logging to multiple output formats including HTML, URDS CSV, and FMLIST.

The plugin runs as two cooperating scripts:

• scanner_server.js – Node.js server process that controls the tuner, drives the scan engine, evaluates signal strength, and writes log files.
• scanner.js – Browser-side client script that renders the UI controls, reflects the current scanner state, and communicates with the server via WebSocket.

Key capabilities at a glance:

• Automatic FM band scan (normal, blacklist, whitelist, spectrum, difference modes)
• PE5PVB firmware integration for TEF6686 / ESP32 hardware scan and search
• Dynamic noise-floor calibration using a configurable reference frequency
• Spectrum-graph-based fast scan (requires Spectrum Graph plugin)
• Automatic antenna switching at the upper band limit
• GPS-based dynamic location update (requires GPS plugin)
• Multi-format logging: filtered/raw HTML log, URDS CSV, FMLIST autolog
• Multiple named configuration profiles switchable live from the web UI
• Mobile-friendly UI with adaptive button layout
• URDS Map Viewer and URDS Log Validator buttons

2 · Architecture – Components and Data Flow

3 · Installation

1. Download the latest release as a ZIP archive from the GitHub releases page.
2. Unpack all files from the plugins/ folder inside the ZIP into:
   …/fm-dx-webserver-main/plugins/
3. Stop or close the FM-DX-Webserver if it is running.
4. Start the webserver with npm run webserver in a Node.js console and check the console output for errors.
5. Open the webserver settings page and activate the Scanner plugin in the plugin list.
6. Stop the webserver again.
7. Start the webserver again with npm run webserver and verify the console output — the scanner should now initialise and print its configuration summary.
8. Edit the automatically created configuration file at:
   …/fm-dx-webserver-main/plugins_configs/scanner.json
   (Use the Scanner Wizard — see §4)
9. Stop the webserver, then start it once more for the configuration to take full effect.

4 · Configuration – The Scanner Wizard

The recommended way to create or modify the scanner configuration is the Scanner Wizard, an interactive web tool that generates a ready-to-use scanner.json file with all options described inline:

Alternatively you can edit the JSON file directly. The sections below describe every parameter group.

4.1 · General Settings

4.2 · Sensitivity & Scan Timing

Sensitivity value ranges by unit

4.3 · Scan Modes

The defaultScannerMode parameter (default: "normal") sets the active scan mode at startup. The user can change it live via the scanner controls dropdown. Available modes:

4.4 · Spectrum & Difference Scan

The spectrum and difference scan modes require the Spectrum Graph plugin to be installed and active. In addition, the variable rescanDelay in the SpectrumGraph.json must be set to 0 so that a fresh spectrum is captured automatically after each full band sweep.

4.5 · Logging Settings

Log file locations

4.6 · FMLIST Integration

The scanner can automatically submit DX log entries to FMLIST when a station exceeds the configured distance thresholds. A valid OM ID and a webserver UUID token are required.

4.7 · Multiple Configuration Files

Since version 4.2, the scanner supports multiple named configuration profiles. Additional profiles are stored as extra JSON files in the plugins_configs/ folder following the naming pattern:

plugins_configs/
├── scanner.json          ← default profile
├── scanner_Dave.json     ← profile "Dave"
├── scanner_SpE.json      ← profile "SpE"
└── scanner_Tropo.json    ← profile "Tropo"

When more than one scanner config file exists, a drop-down selector appears in the webserver settings panel (admin login required). Selecting a profile instantly loads and applies all its settings — including scan mode, sensitivity, FMLIST options, and logging preferences — without restarting the server. The active profile is persisted across server restarts in plugins/Scanner/scanner_state.json.

5 · User Interface

5.1 · Auto Scan Button

The Auto Scan button is injected into the FM-DX-Webserver's main tuning panel. Its behaviour depends on press duration:

While autoscan is active:

• The button turns blue (bg-color-4)
• Tuning buttons (freq-up / freq-down), search buttons, and the command input are hidden
• A blinking "Autoscan active!" overlay appears in the tune-buttons panel
• On mobile (<769 px), the scanner controls are shown instead of the volume slider

5.2 · Scanner Controls (Sensitivity, Mode, Hold Time)

When the scanner control panel is open (long-press on Auto Scan button), three dropdown controls appear:

Changes to any dropdown are sent immediately to the server via WebSocket. The server responds with an updated broadcast that refreshes all connected clients. The control panel visibility is persisted in a browser cookie (scannerControlsStatus) for 7 days.

The scanner client also watches the webserver's signal-unit selector (#signal-selector-input) every 250 ms. When the unit changes (dBf → dBµV → dBm), the sensitivity dropdown is rebuilt with the correct value list and labels, and the currently displayed sensitivity value is recalculated accordingly.

5.3 · Search Buttons

Two search buttons (◀◀ and ▶▶) are inserted next to the standard frequency step buttons:

• ◀◀ (search-down): Triggers a downward search scan. In PE5PVB mode sends C1; otherwise calls startSearch('down') on the server.
• ▶▶ (search-up): Triggers an upward search scan. In PE5PVB mode sends C2; otherwise calls startSearch('up') on the server.

Search buttons are hidden during active autoscan. They are always available without admin login (unrestricted command), but a warning is shown if the tuner is locked to admin.

5.4 · Map Viewer & URDS Log Validator Buttons

If CSVcreate: true is set and a CSV log file exists, two additional icon buttons are injected into the plugin panel (desktop only — hidden on touch devices):

6 · Technical Deep Dive

6.1 · Scan Algorithm

The scan engine runs as a setInterval loop on the server with a configurable tick rate (scanIntervalTime, default 500 ms). Each tick calls updateFrequency(), which:

1. Advances currentFrequency by the appropriate step (0.01 MHz below 74 MHz, 0.1 MHz above — or 0.01 MHz in whitelist mode)
2. Applies the active filter (blacklist / whitelist / spectrum / difference) to skip ineligible frequencies
3. Calls sendDataToClient(currentFrequency) to retune the receiver
4. Waits for the next tick and evaluates the incoming signal data via checkStereo() or PE5PVBlog()

Band-end wrap behaviour

When currentFrequency exceeds tuningUpperLimit during autoscan, the handleBandEnd() routine is called. It:

1. Stops the interval and locks the scanner via isCalibrating = true
2. Sends the next-antenna command if antenna switching is enabled
3. Jumps to tuningLowerLimit and waits for a fresh spectrum scan (up to 15 s)
4. Runs SensitivityValueCalibration() again if configured
5. Releases the lock and restarts startScan('up')

In normal / blacklist / whitelist modes the scanner remembers the last tuned frequency across band-end restarts and continues from where it left off rather than returning to the lower limit, avoiding repeated scanning of already-checked frequencies within the same autoscan session.

6.2 · Sensitivity Calibration

When SensitivityCalibrationFrequenz is set, the scanner performs an automatic noise-floor measurement before every full band sweep instead of using a fixed threshold.

async function SensitivityValueCalibration() {
  isCalibrating = true;
  try {
    clearInterval(scanInterval);

    // --- Path 1: spectrum array available ---
    if (sigArray.length > 0) {
      const entry = sigArray.find(
        i => parseFloat(i.freq).toFixed(2) === targetFreqStr);
      if (entry) {
        Sensitivity = Math.round(parseFloat(entry.sig))
                    + Math.round(defaultSensitivityValue);
      }
    }

    // --- Path 2: physical tune + 2 s wait ---
    else {
      sendDataToClient(calibFreq);
      // wait until tuner reports calibration frequency
      while (Math.abs(parseFloat(freq) - calibFreq) >= 0.05) {
        await sleep(100);
      }
      await sleep(2000); // stabilise
      Sensitivity = Math.round(strength)
                  + Math.round(defaultSensitivityValue);
    }

    // broadcast updated Sensitivity to all clients
    DataPluginsSocket.send(JSON.stringify(
      createMessage('broadcast', '255.255.255.255',
        Scan, '', Sensitivity, ScannerMode, ScanHoldTime, FMLIST_Autolog)));
  } finally {
    isCalibrating = false;
  }
}

6.3 · Spectrum & Difference Scan Internals

Both spectrum-based modes rely on the sigArray provided by the Spectrum Graph plugin via the data_plugins WebSocket. The scanner listens for type: 'sigArray' messages and processes them in handleDataPluginsMessage():

Step 1 – Local station masking

// Find all entries above SpectrumLimiterValue
const primaryFreqs = sigArray.filter(e =>
  e.sig > SpectrumLimiterValue &&
  Math.round(e.freq * 100) % 10 === 0  // primary 0.1 MHz grid only
);

// Extend mask to ±0.1 MHz neighbours above SpectrumPlusMinusValue
primaryFreqs.forEach(p => {
  if (p.sig >= SpectrumPlusMinusValue) {
    sigArray.filter(e =>
      e.freq >= p.freq - 0.1 && e.freq <= p.freq + 0.1
    ).forEach(e => extendedMask.add(e.freq));
  }
});

// sigArraySpectrum = everything NOT masked
sigArraySpectrum = sigArray.filter(e =>
  !extendedMask.has(e.freq) && !primaryFreqs.some(p => p.freq === e.freq)
);

Step 2 – Difference filter

// freqMap2 = previous scan pass signals for current antenna
sigArrayDifference = sigArraySpectrum.filter(item => {
  const sig  = parseFloat(item.sig);
  if (sig < Sensitivity) return false;            // below threshold
  if (!freqMap2.has(item.freq)) return true;     // new frequency
  return Math.abs(sig - freqMap2.get(item.freq))  // changed by
       > SpectrumChangeValue;                      // SpectrumChangeValue
});

Step 3 – Per-antenna baseline storage

Four baseline arrays (sigArraySave0 – sigArraySave3) store the previous spectrum pass for each of up to four antennas independently. This prevents false difference detections when the antenna is switched.

6.4 · WebSocket Communication

All real-time communication between server and clients uses the FM-DX-Webserver's /data_plugins WebSocket endpoint. Messages follow this envelope:

{
  "type":   "Scanner",
  "value":  {
    "status":             "request" | "response" | "broadcast" | "command",
    "Scan":               "on" | "off",
    "Sensitivity":        number,          // internal dBf value
    "ScannerMode":        "normal" | ...,
    "ScanHoldTime":       number,          // seconds
    "ScanPE5PVB":         boolean,
    "SearchPE5PVB":       boolean,
    "SpectrumLimiterValue":number,
    "StatusFMLIST":       "off" | "on" | "auto",
    "InfoFMLIST":         "...",           // optional status string
    "AvailableConfigs":   ["default", ...],
    "ActiveConfig":       "default" | "..."
  },
  "source": "clientIP",
  "target": "serverIP | 255.255.255.255"
}

Message flow overview

6.5 · Authentication & Access Control

The plugin distinguishes between two client types based on the message.source field:

TEF Logger authentication flow

All scan and config commands from TEF Logger clients are silently ignored until authentication succeeds. Search commands (Search: "up"/"down") are exempt from authentication and are always executed immediately for any client type.

On the browser side, authentication is handled by checking the webserver's page text:

• "You are logged in as an administrator." → isTuneAuthenticated = true, admin dropdown created
• "You are logged in and can control the receiver." → isTuneAuthenticated = true
• Tuner key/lock icon present → isTunerLocked = true, tuning blocked unless admin

6.6 · Logging – HTML, CSV, FMLIST

HTML log

The HTML log is created from FilteredTemplate.html (located in the scanner plugin folder) as a header template and appended with one <tr> row per detected station. The row includes: date, time, frequency, PI code, PS name (spaces replaced with underscores), station name, city, ITU country, antenna name, polarisation, ERP, signal strength (converted to the configured unit), distance, azimuth, station ID, scan mode (A=auto / M=manual), and three action links (Stream, Map, FMLIST).

URDS CSV log

A new CSV file is created at the start of each autoscan session (format: YYYYMMDDTHHMMSS_fm_rds.csv). Each entry is one line with 40+ comma-separated fields compatible with the URDS (Universal RDS) format, including nanosecond-resolution timestamps, GPS coordinates, signal levels in dBµV, RDS fields (PI, PS, TP, TA, PTY, ECC, AF, RT), and transmitter metadata fetched live from the maps.fmdx.org API.

// CSV line structure (abbreviated)
30,{UNIXTIME},freq,{Hz},rdson,{SNRMIN},{SNRMAX},
{dateTimeNs},{GPS_LAT},{GPS_LON},{GPS_MODE},{GPS_ALT},{GPS_TIME},
{PI},1,{PS},1,{TA},{TP},{MUSIC},{PTY},{GRP},{STEREO},{DYNPTY},
{OTHERPI},,{ALLPSTEXT},{OTHERPS},,{ECC},{STATIONID},{AF},{RT},,,,,
{TX_NAME},{TX_CITY},{TX_ITU},{TX_ERP},{TX_POL},{TX_DIST},{TX_AZ},{TX_LAT},{TX_LON}

TX latitude/longitude are fetched live from maps.fmdx.org/api/?id={stationid} for each log entry. If the station ID is missing or the API call fails, the TX coordinate fields are left empty.

FMLIST autolog

When FMLIST_Autolog is set to "on" or "auto", the function writeLogFMLIST() is called for each identified DX station that passes the distance and blacklist filters. The submission is a JSON POST to api.fmlist.org/fmdx.org/slog.php and includes the webserver's UUID token, OM ID, coordinates, and a log message string. A successful "OK!" response triggers a green toast notification in all connected browsers.

6.7 · Blacklist & Whitelist

Three separate text files control frequency/PI filtering. All files are located in plugins/Scanner/ and are reloaded automatically when changed on disk (via fs.watchFile):

Frequency matching uses a tolerance of ±0.05 MHz (floating-point safe). Whitelist matching uses exact two-decimal rounding. The combined blacklist+PI format allows suppressing a specific station on a shared frequency (e.g. 89.000;D3C3) without affecting other stations on 89.0 MHz.

6.8 · Antenna Switching

When AntennaSwitch: "on" is configured and the FM-DX-Webserver has two or more antennas enabled, the scanner cycles through them at the end of every full band sweep via sendNextAntennaCommand():

function sendNextAntennaCommand() {
  if (enabledAntennas.length < 2) return;
  const ant = enabledAntennas[currentAntennaIndex];
  sendCommandToClient(`Z${ant.number - 1}`); // Z0–Z3
  currentAntennaIndex =
    (currentAntennaIndex + 1) % enabledAntennas.length;
}

In auto mode (StartAutoScan: "auto"), the antenna is also restored to its pre-scan state when a user connects and autoscan stops. The current antenna at scan start is saved in saveAutoscanAntenna and restored via sendCommandToClient(`Z${saveAutoscanAntenna}`).

The four spectrum baseline arrays (sigArraySave0–3) are maintained per antenna index so that the difference scan can compare against the correct previous pass for each antenna independently.

6.9 · Dynamic Config File Watcher

The scanner uses fs.watchFile() (poll-based, 1-second interval) rather than fs.watch() (inotify-based) for config file monitoring. This is intentional — fs.watchFile is more reliable for config files across different filesystems and prevents rapid duplicate triggers during atomic saves by text editors.

The plugins_configs/ directory itself is also watched via fs.watch() with a 500 ms debounce. When a new scanner_X.json file appears or is deleted, availableScannerConfigs is updated and the admin dropdown in the browser is refreshed automatically. If the currently active profile file is deleted, the scanner falls back to scanner.json.

The function updateSettings() rewrites specific constant declarations directly inside scanner.js (the browser-side client file) using regex replacements, so that the browser always receives the correct feature flags (EnableBlacklist, EnableSpectrumScan, SignalStrengthUnit, AvailableScannerConfigs, ActiveScannerConfig, etc.) on the next page load. A byte-for-byte comparison prevents unnecessary disk writes.

7 · All Configuration Parameters Reference

Complete reference for plugins_configs/scanner.json. All parameters are optional — missing keys are filled with the defaults shown.

8 · Important Notes & Known Issues

Spectrum scan requires rescanDelay = 0

The Spectrum Graph plugin must have rescanDelay set to 0 in its own config file (plugins_configs/SpectrumGraph.json). Without this, the spectrum array will not be refreshed after each band sweep and the scanner will repeatedly tune the same frequencies.

SpectrumLimiterValue must be greater than Sensitivity

In spectrum and difference modes, Sensitivity must always be strictly less than SpectrumLimiterValue. If this condition is violated (e.g. after a manual sensitivity change), the server logs the error "Sensitivity must be smaller than SpectrumLimiter!" and the browser displays a red toast warning. The scan continues but will find no valid frequencies until the values are corrected.

PE5PVB mode limitations

• The Scanner Mode dropdown (normal / blacklist / spectrum etc.) is hidden in PE5PVB mode — the firmware controls the scan behaviour.
• Sensitivity values in PE5PVB mode are 1–30 (firmware-specific scale) and are sent as the I{value} command.
• ScanHoldTime is sent as K{value} to the firmware.
• Spectrum / difference scan and antenna switching are not available in PE5PVB mode.

FMLIST submissions require a valid UUID

The webserver must have a UUID token configured (config.identification.token not null). Without it, all FMLIST POST requests are blocked server-side. The UUID is set during the FM-DX-Webserver initial setup or via the settings page.

maps.fmdx.org TX coordinate lookup adds latency

For every CSV log entry, the scanner fetches the transmitter's geographic coordinates from maps.fmdx.org/api/?id={stationid}. This is an HTTPS request with a 5-second timeout. On slow or offline connections the TX lat/lon fields will be empty but the log entry is still written. Consider setting Scanmode: 0 (offline mode) if internet connectivity is not available.

Speaker module and Node.js compatibility

The speaker npm module requires native compilation (node-gyp). On Node.js versions above 18, compilation may fail. If acoustic control is not required, leave BEEP_CONTROL: false (default).

Public IP fetch on startup

The browser-side script fetches the client's public IP from https://icanhazip.com at startup to populate the WebSocket message source field. If this service is unavailable, the initial WebSocket request will fail and the scanner will show an error toast. The page must be reloaded to retry.

Mobile layout constraints

On screens narrower than 769 px, the scanner button is placed inside a popup panel ("Bandwidth & Antennas" or "Filters") rather than the main tuning row. The Map Viewer and Validator buttons are suppressed on all touch devices (pointer: coarse media query).

9 · Version History (Summary)

Scanner Plugin · Documentation v4.2c · Author: Highpoint · powered by PE5PVB · March 2026
github.com/Highpoint2000/webserver-scanner · Scanner Wizard