# wsprdaemon Overview

This document provides a comprehensive summary of the `wsprdaemon` project, a sophisticated system for receiving, decoding, and reporting Weak Signal Propagation Reporter (WSPR) and FST4W signals. The analysis is based on the content of the official GitHub repository.

## 1. Project Purpose and Overview

`wsprdaemon` is a Linux-based service designed to operate as a reliable, autonomous appliance for amateur radio operators and researchers. Its primary function is to decode WSPR and FST4W spots from one or more Software-Defined Radios (SDRs) and reliably upload them to public databases like wsprnet.org. The project emphasizes high reliability, advanced features, and scientific data collection, going far beyond the capabilities of standard tools like WSJT-X.

As stated in the project's `README.md`:

> Wsprdaemon (WD) runs as a Linux service to decode WSPR and FST4W spots from one or more [Kiwis] and/or RX888 SDRs and *reliably* post them to [wsprnet.org]. It includes many features not found in WSJT-x, including multiple band and/or multiple receiver support. WD also records additional information about spots like doppler shift and background noise level which permit much deeper understanding of propagation conditions. [1]

The system is notable for its robustness, with features to automatically recover from power and internet outages, caching all gathered data until successful delivery is confirmed. It is a significant contributor to the WSPR network, with the documentation noting that top spotting sites running `wsprdaemon` account for approximately 33% of the millions of spots reported daily.

## 2. Core Functionality

`wsprdaemon` offers a rich feature set tailored for advanced and large-scale WSPR monitoring operations.

| Feature | Description |
| :--- | :--- |
| **Multi-Receiver Support** | Can simultaneously process signals from multiple SDRs, such as KiwiSDRs and RX888s. |
| **Spot Merging** | For a given band, it can merge spots from multiple receivers (e.g., different antennas) and report only the one with the best Signal-to-Noise Ratio (SNR). |
| **Advanced Scheduling** | Allows users to create complex schedules to switch between different bands at specific times of the day or at times relative to sunrise and sunset. This is particularly useful for receivers with a limited number of channels. |
| **Reliable Uploading** | Caches all decoded spots and associated data locally. It ensures data is delivered to upstream servers (like wsprnet.org) by retrying uploads after network or power interruptions. |
| **Noise Measurement** | Records background noise levels, allowing for the creation of noise graphs and deeper analysis of band conditions. This data can be uploaded to services like graphs.wsprdaemon.org. |
| **Scientific Data Collection** | Integrates with the HamSCI GRAPE (Great American Radio Propagation Experiment) project by recording and uploading I/Q data of WWV and CHU time-signal broadcasts for ionospheric research. |
| **Multiple Decode Modes** | Supports various WSPR and FST4W modes, including deep search options (`wsprd -d`) for enhanced sensitivity. |
| **Daemon-based Operation** | Runs as a collection of background daemons, managed by a central watchdog process, ensuring continuous, unattended operation. |

## 3. System Architecture

The architecture of `wsprdaemon` is modular and heavily based on shell scripting to coordinate a pipeline of tasks. The system is designed as a series of daemons that handle specific stages of the process, from data acquisition to final reporting.

The high-level data flow is as follows:

1.  **Audio Capture (`recording.sh`):** The process begins with capturing audio (or I/Q data) from the configured SDRs. For KiwiSDRs, it uses `kiwirecorder.py`. For RX888 receivers, it leverages the `ka9q-radio` software suite. The system records audio into precisely timed 2-minute WAV files, synchronized with the global WSPR transmission schedule.

2.  **Signal Decoding (`decoding.sh`):** Once a WAV file is created, a decoding daemon processes it. The core decoding is performed by `wsprd`, a command-line utility from the WSJT-X software suite. `wsprdaemon` can utilize the deep search mode of `wsprd` to maximize the number of decoded spots.

3.  **Data Aggregation and Merging (`posting.sh`):** Decoded spots are passed to a posting daemon. If multiple receivers are monitoring the same band, this stage is responsible for merging the spots and selecting the best one based on SNR.

4.  **Data Uploading (`upload-client-utils.sh`):** The final stage involves formatting the spot data and uploading it to various external services. The system has dedicated logic for posting to wsprnet.org, pskreporter.info, and the project's own data collection server at wsprdaemon.org, which stores extended information like noise levels.

This entire process is supervised by a `watchdog.sh` script, which periodically checks the health of all running daemons, manages job schedules, and handles process restarts, ensuring the system's resilience.

## 4. Code Organization and Implementation

The repository is a large project, comprising over 24,000 lines of code. The implementation is a mix of shell scripts, Python, and C, with each language used for tasks suited to its strengths.

| Language | Lines of Code (approx.) | Primary Role |
| :--- | :--- | :--- |
| **Shell (Bash)** | 18,000 | **Core Orchestration.** The vast majority of the system's logic, including the main entry point (`wsprdaemon.sh`), daemon management, scheduling, and the overall processing pipeline, is implemented in a series of interconnected shell scripts. |
| **Python** | 4,000 | **Supporting Tools and Server Components.** Python is used for various utility scripts (`noise_plot.py`, `wav2grape.py`) and for the server-side components (`wsprdaemon_server.py`, `wsprdaemon_reflector.py`) that receive data from client installations. |
| **C** | 3,000 | **High-Performance Data Capture.** C is used for performance-critical tasks, specifically for recording audio data from SDRs. Files like `wd-record.c` and `pcmrecord.c` are used to capture data from `ka9q-radio` streams efficiently. |

Key files and directories in the repository include:

-   `wsprdaemon.sh`: The main entry point and command-line interface for the entire system.
-   `*.sh` files: A large collection of modular shell scripts, each handling a specific part of the system (e.g., `decoding.sh`, `recording.sh`, `posting.sh`, `watchdog.sh`).
-   `wsprdaemon.conf` / `wd_template.conf`: The configuration file where users define their station parameters, receivers, and schedules.
-   `docs/`: Contains extensive documentation in Markdown format, which is built into a ReadTheDocs website.
-   `ka9q-radio/`: A git submodule containing the `ka9q-radio` SDR software, which is a key dependency for RX888 support.
-   `*.py` files: Various Python scripts for tasks like noise analysis, data conversion, and server-side logic.
-   `*.c` files: C source code for custom data recording tools.

## 5. Configuration and Usage

`wsprdaemon` is configured via a single file, `wsprdaemon.conf`, which is a shell script that sets various environment variables. The user must define:

-   **Reporter Information:** Callsign and grid square (`WSPRNET_REPORTER_ID`, `REPORTER_GRID`).
-   **Receiver List (`RECEIVER_LIST`):** A list of all SDRs the system will use, including their type, address, and credentials.
-   **Schedule (`WSPR_SCHEDULE`):** A detailed schedule that tells the system which receiver should listen on which band at what time and with which decoding modes.

The system is controlled from the command line using the `wsprdaemon.sh` script, which accepts commands to start (`-a`), stop (`-z`), and check the status (`-s`) of the daemons.

The documentation provides a 

Quick Start Guide to get users up and running quickly.

## 6. Conclusion

`wsprdaemon` is a powerful and feature-rich WSPR decoding and reporting system designed for serious hobbyists and scientific users. Its robust, daemon-based architecture, extensive use of shell scripting for orchestration, and support for multiple receivers and advanced scheduling make it a highly flexible and reliable tool. The project is well-documented and actively maintained, serving a critical role in the global WSPR and amateur radio science communities.

## 7. References

[1] `wsprdaemon` GitHub Repository, README.md. [https://github.com/rrobinett/wsprdaemon](https://github.com/rrobinett/wsprdaemon)