Begin WSPRStation Implementation

Author: consuelita

AudioCoder/src/main/java/org/operatorfoundation/audiocoder/WSPRAudioSource.kt

@@ -0,0 +1,4 @@
+package org.operatorfoundation.audiocoder
+
+interface WSPRAudioSource {
+}

AudioCoder/src/main/java/org/operatorfoundation/audiocoder/WSPRDecodeResult.kt

@@ -0,0 +1,70 @@
+package org.operatorfoundation.audiocoder
+
+data class WSPRDecodeResult(
+    /**
+     * Amateur radio callsign of the transmitting station.
+     *
+     * Examples: "W1AW", "JA1XYZ", "DL0ABC"
+     * Standard amateur radio callsign format as assigned by national authorities.
+     * May include portable/mobile indicators like "/P" or "/M".
+     */
+    val callsign: String,
+
+    /**
+     * Maidenhead grid square locator indicating station location.
+     *
+     * Examples: "FN31", "JO65", "PM96"
+     * 4-character or 6-character Maidenhead locator system coordinate.
+     * Provides approximate geographic location for propagation analysis.
+     */
+    val gridSquare: String,
+
+    /**
+     * Transmit power level in dBm (decibels relative to 1 milliwatt).
+     *
+     * Common values: 0, 3, 7, 10, 13, 17, 20, 23, 27, 30, 33, 37, 40, 43, 47, 50, 53, 57, 60
+     * Higher values indicate more transmit power.
+     * WSPR protocol encodes specific power levels, not arbitrary values.
+     */
+    val powerLevelDbm: Int,
+
+    /**
+     * Signal-to-noise ratio in dB at the receiving station.
+     *
+     * Typical range: -30 dB to +10 dB
+     * Negative values are common and indicate weak signal conditions.
+     * More negative values indicate weaker signals relative to noise floor.
+     */
+    val signalToNoiseRatioDb: Float,
+
+    /**
+     * Frequency offset from the expected signal frequency in Hz.
+     *
+     * Typical range: ±200 Hz from center frequency (1500 Hz)
+     * Indicates transmitter frequency accuracy and drift.
+     * Used for automatic frequency correction and propagation analysis.
+     */
+    val frequencyOffsetHz: Double,
+
+    /**
+     * Complete decoded message as received.
+     *
+     * Format: "CALLSIGN GRID POWER"
+     * Example: "W1AW FN31 30"
+     * Contains the raw decoded message for verification and logging.
+     */
+    val completeMessage: String,
+
+    /**
+     * Timestamp when this message was decoded (milliseconds since Unix epoch).
+     *
+     * Used for:
+     * - Chronological sorting of decode results
+     * - Time-based analysis of propagation
+     * - Duplicate detection across decode cycles
+     */
+    val decodeTimestamp: Long
+)
+{
+
+}

AudioCoder/src/main/java/org/operatorfoundation/audiocoder/WSPRStation.kt

@@ -0,0 +1,191 @@
+package org.operatorfoundation.audiocoder
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+import java.util.*
+
+/**
+ * WSPR station provides complete amateur radio WSPR (Weak Signal Propagation Reporter) functionality.
+ *
+ * This class handles the complete WSPR workflow:
+ * - Automatic timing synchronization with the global WSPR schedule
+ * - Audio collection during transmission windows
+ * - Signal decoding using the native WSPR decoder
+ * - Result management and reporting
+ *
+ * The WSPR protocol operates on a strict 2-minute cycle:
+ * - Even minutes (00, 02, 04...): Transmission/reception windows
+ * - Odd minutes (01, 03, 05...): Silent periods for frequency coordination
+ *
+ * Usage:
+ * ```kotlin
+ * val audioSource = MyWSPRAudioSource()
+ * val station = WSPRStation(audioSource)
+ * station.start() // Begins automatic operation
+ *
+ * // Observe results
+ * station.decodeResults.collect { results ->
+ *     // Handle decoded WSPR messages
+ * }
+ * ```
+ *
+ * @param audioSource Provider of audio data for WSPR processing
+ * @param configuration Station operating parameters and preferences
+ */
+class WSPRStation(
+    private val audioSource: WSPRAudioSource,
+    private val configuration: WSPRStationConfiguration = WSPRStationConfiguration.createDefault()
+)
+{
+    // ========== Core Components ==========
+
+}
+
+/**
+ * WSPR timing constants used throughout the station implementation.
+ */
+object WSPRTimingConstants
+{
+    /** Standard WSPR cycle duration: 2 minutes */
+    const val WSPR_CYCLE_DURATION_SECONDS = 120L
+
+    /** WSPR transmission duration: approximately 110.g seconds */
+    const val WSPR_TRANSMISSION_DURATION_SECONDS = 111L
+
+    /** Native decoder audio collection requirement: exactly 114 seconds */
+    const val AUDIO_COLLECTION_DURATION_SECONDS = 114L
+    const val AUDIO_COLLECTION_DURATION_MILLISECONDS = AUDIO_COLLECTION_DURATION_SECONDS * 1000L
+
+    /** Delay before starting decode after transmission begins: 2 seconds */
+    const val DECODE_START_DELAY_SECONDS = 2L
+
+    /** Duration of each audio chunk read during collection: 1 second */
+    const val AUDIO_CHUNK_DURATION_MILLISECONDS = 1000L
+
+    /** Pause between audio chunk reads: 100ms */
+    const val AUDIO_COLLECTION_PAUSE_MILLISECONDS = 100L
+
+    /** How often to update cycle information for UI: 1 second */
+    const val CYCLE_INFORMATION_UPDATE_INTERVAL_MILLISECONDS = 1000L
+
+    /** Brief pause between operations: 2 seconds */
+    const val BRIEF_OPERATION_PAUSE_MILLISECONDS = 2000L
+
+    /** Maximum delay for error backoff: 5 minutes */
+    const val MAXIMUM_ERROR_BACKOFF_MILLISECONDS = 300_000L
+}
+
+/**
+ * Configuration parameters for WSPR station operation.
+ * Contains all user-configurable settings and operating parameters.
+ */
+data class WSPRStationConfiguration(
+    /** WSPR operating frequency in MHz (e.g., 14.0956 for 20m band) */
+    val operatingFrequencyMHz: Double,
+
+    /** Whether to user Lower Sideband mode (LSB) instead of Upper Sideband mode (USB) */
+    val useLowerSidebandMode: Boolean,
+
+    /** Whether to use time-aligned decoding windows vs sliding windows */
+    val useTimeAlignedDecoding: Boolean,
+
+    /** Station callsign for identification (optional) */
+    val stationCallsign: String?,
+
+    /** Station Maidenhead grid square location (optional) */
+    val stationGridSquare: String?
+    )
+{
+    companion object
+    {
+        /**
+         * Creates a default configuration suitable for most WSPR operations.
+         * Uses 20m band (most popular), USB mode, and time-aligned decoding.
+         */
+        fun createDefault(): WSPRStationConfiguration
+        {
+            return WSPRStationConfiguration(
+                operatingFrequencyMHz = WSPRBandplan.getDefaultFrequency(),
+                useLowerSidebandMode = false,
+                useTimeAlignedDecoding = true,
+                stationCallsign = null,
+                stationGridSquare = null
+            )
+        }
+
+        /**
+         * Creates configuration for a specific WSPR band.
+         *
+         * @param bandName Band identifier (e.g., "20m", "40m", "80m")
+         * @return Configuration for the specified band, or default if band not found
+         */
+        fun createForBand(bandName: String): WSPRStationConfiguration
+        {
+            val band = WSPRBandplan.ALL_BANDS.find { it.name.equals(bandName, ignoreCase = true) }
+                ?: WSPRBandplan.ALL_BANDS.first { it.isPopular }
+
+            return WSPRStationConfiguration(
+                operatingFrequencyMHz = band.dialFrequencyMHz,
+                useLowerSidebandMode = false,
+                useTimeAlignedDecoding = true,
+                stationCallsign = null,
+                stationGridSquare = null
+            )
+        }
+    }
+}
+
+/**
+ * Represents the current state of WSPR station operation.
+ * Provides detailed information about what the station is currently doing.
+ */
+sealed class WSPRStationState
+{
+    /** Station is not running */
+    object Stopped : WSPRStationState()
+
+    /** Station is initializing and starting up */
+    object Starting : WSPRStationState()
+
+    /** Station is running and monitoring for decode opportunities */
+    object Running : WSPRStationState()
+
+    /** Station is shutting down */
+    object Stopping : WSPRStationState()
+
+    /**
+     * Station is waiting for the next WSPR decode window to begin.
+     * @param windowInfo Information about the upcoming decode window
+     */
+    data class WaitingForNextWindow(val windowInfo: WSPRDecodeWindowInformation) : WSPRStationState()
+
+    /** Station is preparing to collect audio (clearing buffers, etc.) */
+    object PreparingForCollection : WSPRStationState()
+
+    /** Station is actively collecting audio for decode */
+    object CollectingAudio : WSPRStationState()
+
+    /** Station is processing collected audio through the WSPR decoder */
+    object ProcessingAudio : WSPRStationState()
+
+    /**
+     * Decode cycle completed successfully.
+     * @param decodedSignalCount Number of WSPR signals found in this cycle
+     */
+    data class DecodeCompleted(val decodedSignalCount: Int) : WSPRStationState()
+
+    /**
+     * Station encountered an error and requires attention.
+     * @param errorDescription Human-readable description of the error
+     */
+    data class Error(val errorDescription: String) : WSPRStationState()
+}
+
+/**
+ * Custom exception for WSPR station-specific errors.
+ * Provides structured error reporting for station operation failures.
+ */
+class WSPRStationException(
+    message: String,
+    cause: Throwable? = null
+) : Exception(message, cause)