Skip to content

Satellite tracker and pass predictor for Android, inspired by Gpredict

Fixed linear calculator Doppler chain and per-satellite offset restore (#265)

atsunatsufa7b8cefe7ec
diff --git a/core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/DopplerFrequencyCalculator.kt b/core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/DopplerFrequencyCalculator.kt
index 1bd9037c..a7e009bc 100644
--- a/core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/DopplerFrequencyCalculator.kt
+++ b/core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/DopplerFrequencyCalculator.kt
@@ -16,18 +16,31 @@ import java.util.Locale
/**
* Computes Doppler-corrected reciprocal frequencies for linear transponders.
*
- * For a linear (passband) transponder, uplink and downlink frequencies are
- * related by a fixed passband offset. When the satellite moves, both are
- * Doppler-shifted. Given one, this computes the other:
+ * The full physical path:
*
- * downlink → uplink: mapDownlinkToUplink (passband) → getUplinkFreq (Doppler)
- * uplink → downlink: mapUplinkToDownlink (passband) → getDownlinkFreq (Doppler)
+ * TX to RX (uplink -> downlink):
+ * 1. Ground transmits f_tx
+ * 2. Satellite receives f_tx * (c - v) / c (uplink Doppler)
+ * 3. Satellite transmits the passband mapping of (2) (mapping happens on board)
+ * 4. Ground hears (3) * (c - v) / c (downlink Doppler)
+ *
+ * RX to TX (downlink -> uplink), the same chain in reverse:
+ * 4. Ground hears f_rx
+ * 3. Satellite transmits f_rx * (c + v) / c (undo downlink Doppler)
+ * 2. Satellite receives the inverse passband mapping of (3)
+ * 1. Ground must transmit (2) * (c + v) / c (undo uplink Doppler)
+ *
+ * Both legs of the trip are Doppler shifted and by different amounts (uplink
+ * and downlink frequencies differ), so the mapping must happen between the two
+ * shifts on satellite-received frequencies. Addresses GitHub issue #91
+ * (Custom frequency Doppler correction).
*/
object DopplerFrequencyCalculator {
/**
- * Given a downlink frequency, compute the Doppler-corrected uplink frequency.
- * Returns null if the transponder is not a linear passband type.
+ * Given a downlink frequency (what the user hears), compute the
+ * uplink frequency the user should transmit.
+ * Full path: 4 -> 3 -> 2 -> 1
*/
fun computeUplinkFromDownlink(
downlinkHz: Long,
@@ -35,17 +48,23 @@ object DopplerFrequencyCalculator {
orbitalPos: OrbitalPos
): Long? {
if (!isLinearTransponder(transponder)) return null
- val baseUplink = TransponderMapper.mapDownlinkToUplink(downlinkHz, transponder) ?: return null
- return orbitalPos.getUplinkFreq(baseUplink)
+ // 4 -> 3 undo the downlink Doppler: the frequency the satellite transmits
+ val satTx = orbitalPos.getUplinkFreq(downlinkHz)
+ // 3 -> 2 inverse passband mapping
+ val satRx = TransponderMapper.mapDownlinkToUplink(satTx, transponder) ?: return null
+ // 2 -> 1 undo the uplink Doppler: the frequency the ground station transmits
+ return orbitalPos.getUplinkFreq(satRx)
}
/**
- * Given a downlink frequency, compute the Doppler-corrected uplink frequency
- * with an offset applied to the downlink (in Hz).
- * Returns null if the transponder is not a linear passband type.
+ * Given a downlink frequency (what the user hears), compute the
+ * uplink frequency the user should transmit, with an offset applied
+ * to the downlink (in Hz).
+ * Full path: 4 -> 3 -> 2 -> 1
*
* The user-entered downlink frequency already includes the offset, so subtract
- * it before mapping the downlink passband position back to the uplink.
+ * it before the inverse passband mapping. The offset lives in the satellite
+ * frequency domain, hence it is removed after undoing the downlink Doppler.
*/
fun computeUplinkFromDownlinkWithOffset(
downlinkHz: Long,
@@ -54,13 +73,20 @@ object DopplerFrequencyCalculator {
offsetHz: Long
): Long? {
if (!isLinearTransponder(transponder)) return null
- val baseUplink = TransponderMapper.mapDownlinkToUplink(downlinkHz - offsetHz, transponder) ?: return null
- return orbitalPos.getUplinkFreq(baseUplink)
+ // 4 -> 3 undo the downlink Doppler (the offset travels with it)
+ val satTxWithOffset = orbitalPos.getUplinkFreq(downlinkHz)
+ // 3 remove the offset (it lives in the satellite frequency domain)
+ val satTx = satTxWithOffset - offsetHz
+ // 3 -> 2 inverse passband mapping
+ val satRx = TransponderMapper.mapDownlinkToUplink(satTx, transponder) ?: return null
+ // 2 -> 1 undo the uplink Doppler
+ return orbitalPos.getUplinkFreq(satRx)
}
/**
- * Given an uplink frequency, compute the Doppler-corrected downlink frequency.
- * Returns null if the transponder is not a linear passband type.
+ * Given an uplink frequency (what the user transmits), compute the
+ * downlink frequency the user will hear.
+ * Full path: 1 -> 2 -> 3 -> 4
*/
fun computeDownlinkFromUplink(
uplinkHz: Long,
@@ -68,14 +94,19 @@ object DopplerFrequencyCalculator {
orbitalPos: OrbitalPos
): Long? {
if (!isLinearTransponder(transponder)) return null
- val baseDownlink = TransponderMapper.mapUplinkToDownlink(uplinkHz, transponder) ?: return null
- return orbitalPos.getDownlinkFreq(baseDownlink)
+ // 1 -> 2 uplink Doppler: the frequency the satellite receives
+ val satRx = orbitalPos.getDownlinkFreq(uplinkHz)
+ // 2 -> 3 passband mapping
+ val satTx = TransponderMapper.mapUplinkToDownlink(satRx, transponder) ?: return null
+ // 3 -> 4 downlink Doppler: what the ground station hears
+ return orbitalPos.getDownlinkFreq(satTx)
}
/**
- * Given an uplink frequency, compute the Doppler-corrected downlink frequency
- * with an offset applied to the downlink (in Hz).
- * Returns null if the transponder is not a linear passband type.
+ * Given an uplink frequency (what the user transmits), compute the
+ * downlink frequency the user will hear, with an offset applied
+ * to the downlink (in Hz).
+ * Full path: 1 -> 2 -> 3 -> 4
*/
fun computeDownlinkFromUplinkWithOffset(
uplinkHz: Long,
@@ -84,8 +115,12 @@ object DopplerFrequencyCalculator {
offsetHz: Long
): Long? {
if (!isLinearTransponder(transponder)) return null
- val baseDownlink = TransponderMapper.mapUplinkToDownlink(uplinkHz, transponder) ?: return null
- return orbitalPos.getDownlinkFreq(baseDownlink + offsetHz)
+ // 1 -> 2 uplink Doppler: the frequency the satellite receives
+ val satRx = orbitalPos.getDownlinkFreq(uplinkHz)
+ // 2 -> 3 passband mapping
+ val satTx = TransponderMapper.mapUplinkToDownlink(satRx, transponder) ?: return null
+ // 3 apply the offset (satellite frequency domain), 3 -> 4 downlink Doppler
+ return orbitalPos.getDownlinkFreq(satTx + offsetHz)
}
/** True if this transponder supports linear passband mapping. */
diff --git a/core/domain/src/test/java/com/rtbishop/look4sat/core/domain/DopplerFrequencyCalculatorTest.kt b/core/domain/src/test/java/com/rtbishop/look4sat/core/domain/DopplerFrequencyCalculatorTest.kt
index dd832672..38de7a46 100644
--- a/core/domain/src/test/java/com/rtbishop/look4sat/core/domain/DopplerFrequencyCalculatorTest.kt
+++ b/core/domain/src/test/java/com/rtbishop/look4sat/core/domain/DopplerFrequencyCalculatorTest.kt
@@ -268,6 +268,71 @@ class DopplerFrequencyCalculatorTest {
val roundTripDownlink = DopplerFrequencyCalculator.computeDownlinkFromUplink(uplink!!, xpdr, orbitalPos)
assertNotNull(roundTripDownlink)
val error = kotlin.math.abs(roundTripDownlink!! - originalDownlink)
- assertTrue("Round-trip error too large: $error", error < 10000)
+ // Both legs of the trip carry their own Doppler shift, so the reverse
+ // computation must undo both. A single-shift implementation leaves an
+ // error of roughly (uplink + downlink) Doppler, ~6.8 kHz at 3.5 km/s.
+ assertTrue("Round-trip error too large: $error", error < 100)
+ }
+
+ @Test
+ fun computeDownlinkFromUplink_appliesUplinkAndDownlinkDoppler() {
+ // 7 km/s range rate: the uplink is Doppler shifted before the passband
+ // mapping and the downlink after it. Both shifts must be applied - the
+ // mapping happens on the satellite-received frequency, not the ground one.
+ val xpdr = linearTransponder()
+ val orbitalPos = pos(7.0)
+ val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplink(145_200_000L, xpdr, orbitalPos)
+ assertNotNull(downlink)
+ // A single-shift implementation maps the ground frequency first and
+ // yields 435_189_838 here, missing the uplink shift of 3391 Hz.
+ assertEquals(435_186_447L, downlink)
+ }
+
+ @Test
+ fun computeDownlinkFromUplink_inverted_appliesUplinkAndDownlinkDoppler() {
+ val xpdr = linearTransponder(inverted = true, downHigh = 435_500_000L)
+ val orbitalPos = pos(7.0)
+ val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplink(145_200_000L, xpdr, orbitalPos)
+ assertNotNull(downlink)
+ assertEquals(435_293_226L, downlink)
+ }
+
+ @Test
+ fun computeUplinkFromDownlink_roundTripAtHighRangeRate() {
+ val xpdr = linearTransponder()
+ val orbitalPos = pos(7.0)
+ val originalUplink = 145_200_000L
+ val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplink(originalUplink, xpdr, orbitalPos)
+ assertNotNull(downlink)
+ val roundTripUplink = DopplerFrequencyCalculator.computeUplinkFromDownlink(downlink!!, xpdr, orbitalPos)
+ assertNotNull(roundTripUplink)
+ val error = kotlin.math.abs(roundTripUplink!! - originalUplink)
+ // A single-shift implementation is not its own inverse: the round trip
+ // drifts by ~(uplink + downlink) Doppler, 13.5 kHz at 7 km/s.
+ assertTrue("Round-trip error too large: $error", error < 100)
+ }
+
+ @Test
+ fun computeOffsetRoundTrip_atHighRangeRate() {
+ val xpdr = linearTransponder()
+ val orbitalPos = pos(7.0)
+ val originalUplink = 145_200_000L
+ val downlink = DopplerFrequencyCalculator.computeDownlinkFromUplinkWithOffset(
+ uplinkHz = originalUplink,
+ transponder = xpdr,
+ orbitalPos = orbitalPos,
+ offsetHz = 2_500L
+ )
+ assertNotNull(downlink)
+ assertEquals(435_188_947L, downlink)
+ val roundTripUplink = DopplerFrequencyCalculator.computeUplinkFromDownlinkWithOffset(
+ downlinkHz = downlink!!,
+ transponder = xpdr,
+ orbitalPos = orbitalPos,
+ offsetHz = 2_500L
+ )
+ assertNotNull(roundTripUplink)
+ val error = kotlin.math.abs(roundTripUplink!! - originalUplink)
+ assertTrue("Round-trip error too large: $error", error < 100)
}
}
diff --git a/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarState.kt b/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarState.kt
index 0383b85d..3b9db61f 100644
--- a/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarState.kt
+++ b/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarState.kt
@@ -101,4 +101,11 @@ sealed interface RadarAction {
// Calculator actions
data class ChangeCalculatorOffset(val offsetKHz: String) : RadarAction
+
+ /**
+ * The transponder currently driving the calculator (null when the satellite has
+ * no linear transponder). The per-satellite offset follows it instead of the
+ * transceiver selection, so it loads and saves even when nothing is selected.
+ */
+ data class CalculatorTransponderChanged(val catnum: Int?) : RadarAction
}
diff --git a/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarViewModel.kt b/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarViewModel.kt
index 55e4ec45..27d2d9bc 100644
--- a/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarViewModel.kt
+++ b/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/RadarViewModel.kt
@@ -70,6 +70,7 @@ class RadarViewModel(
private var compassOffset = settingsRepo.otherSettings.value.radarCompassOffset
private var compassOffsetElev = settingsRepo.otherSettings.value.radarCompassOffsetElev
private var transponders: List<SatRadio> = emptyList()
+ private var calculatorCatnum: Int? = null
private var sstvDecoder: SstvDecoder? = null
private var sstvRecordingJob: Job? = null
private var sensorCollectionJob: Job? = null
@@ -260,16 +261,8 @@ class RadarViewModel(
// Compute toggle state before the update so we don't read post-update value
val isTogglingOff = _uiState.value.transceivers.selectedUuid == action.uuid
val newUuid = if (isTogglingOff) null else action.uuid
- // Load the saved offset for the newly selected satellite
- val offsetKHz = if (!isTogglingOff) {
- transponders.find { it.uuid == action.uuid }
- ?.catnum?.let { settingsRepo.getSatelliteOffset(it) } ?: ""
- } else ""
_uiState.update {
- it.copy(
- transceivers = it.transceivers.copy(selectedUuid = newUuid),
- calculatorOffsetKHz = offsetKHz
- )
+ it.copy(transceivers = it.transceivers.copy(selectedUuid = newUuid))
}
// Only update the tracking service when selecting a different transponder to
// avoid resetting a user-adjusted TX base on re-expand
@@ -320,7 +313,9 @@ class RadarViewModel(
_uiState.update { it.copy(sstv = it.sstv.copy(currentFrame = null)) }
}
is RadarAction.ChangeCalculatorOffset -> {
- val catnum = _uiState.value.transceivers.selectedUuid?.let { uuid ->
+ // Keyed by the transponder driving the calculator, so the offset saves
+ // even when no transceiver is selected (or selection was toggled off)
+ val catnum = calculatorCatnum ?: _uiState.value.transceivers.selectedUuid?.let { uuid ->
transponders.find { it.uuid == uuid }?.catnum
}
if (catnum != null) {
@@ -328,6 +323,11 @@ class RadarViewModel(
}
_uiState.update { it.copy(calculatorOffsetKHz = action.offsetKHz) }
}
+ is RadarAction.CalculatorTransponderChanged -> {
+ calculatorCatnum = action.catnum
+ val offsetKHz = action.catnum?.let { settingsRepo.getSatelliteOffset(it) } ?: ""
+ _uiState.update { it.copy(calculatorOffsetKHz = offsetKHz) }
+ }
}
}
diff --git a/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/TransceiversPage.kt b/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/TransceiversPage.kt
index 78af38a4..e319952d 100644
--- a/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/TransceiversPage.kt
+++ b/feature/radar/src/main/java/com/rtbishop/look4sat/feature/radar/TransceiversPage.kt
@@ -140,6 +140,13 @@ fun CalculatorPage(
?: calculatorTransceivers.firstOrNull()
}
+ // Keep the per-satellite offset in sync with the transponder driving the
+ // calculator: load the saved value on open/satellite change, and remember
+ // its catnum so editing saves even when no transceiver is selected
+ LaunchedEffect(selectedTransceiver?.uuid) {
+ onAction(RadarAction.CalculatorTransponderChanged(selectedTransceiver?.catnum))
+ }
+
if (selectedTransceiver == null) {
EmptyTransceiversContent(modifier)
return