Satellite tracker and pass predictor for Android, inspired by Gpredict
Kotlin amsatcelestrakgpsham-radiohamlibhamradiokotlinnasaradiosatellitesatellite-datasatellite-positionsatellite-predictionsatellitessatnogssdrspacespacexstarlink
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.ktindex 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.ktindex 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.ktindex 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 actionsdata 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.ktindex 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.radarCompassOffsetprivate var compassOffsetElev = settingsRepo.otherSettings.value.radarCompassOffsetElevprivate var transponders: List<SatRadio> = emptyList()+ private var calculatorCatnum: Int? = nullprivate var sstvDecoder: SstvDecoder? = nullprivate var sstvRecordingJob: Job? = nullprivate var sensorCollectionJob: Job? = null@@ -260,16 +261,8 @@ class RadarViewModel(// Compute toggle state before the update so we don't read post-update valueval isTogglingOff = _uiState.value.transceivers.selectedUuid == action.uuidval 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.ktindex 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