Class TimeCorrelationService
- java.lang.Object
-
- com.google.common.util.concurrent.AbstractService
-
- org.yamcs.AbstractYamcsService
-
- org.yamcs.time.TimeCorrelationService
-
- All Implemented Interfaces:
com.google.common.util.concurrent.Service
,SystemParametersProducer
,YamcsService
public class TimeCorrelationService extends AbstractYamcsService implements SystemParametersProducer
On-board time correlation service (inspired from SCOS2K (ESA MCS)).It receives samples
(obt, ert, tof)
where:- obt - onboard time considered to be a counter starting at 0 when an on-board computer starts. This service uses an 64bits integer.
- ert - Earth Reception Time - the timestamp when the signal has been received on the ground - it is typically
provided by a ground station. This service expects the time to be provided in the
Instant
format which has picoseconds resolution.
- onboardDelay - configurable in the service configuration. It covers any delay happening on-board (sampling time, radiation time)
- tof - time of flight - the time it takes for the signal to reach the ground.
TimeOfFlightEstimator
by dynamically interpolating from data provided by a flight dynamics system.Computes
m
= gradient andc
= offset such thatob_time = m*obt + c
The determination of the gradient and offset is done using the least squares method.
The number of samples used for computing the coefficients is configurable and has to be minimum 2.
Accuracy and validity
Once the coefficients have been calculated, for each new sample received a deviation is calculated as the delta between the OBT computed using the coefficients and the OBT which is part of the sample (after adjusting for delays). The deviation is compared with the accuracy and validity parameters:- If the deviation is greater than
accuracy
but smaller thanvalidity
, then a recalculation of the coefficients is performed based on the last received samples. - If the deviation is greater than
validity
then the coefficients are declared as invalid and all the samples from the buffer except the last one are dropped. The time returned bygetTime(long)
will be invalid until the required number of new samples is received and the next recalculation is performed
Historical coefficients
The service keeps track of multiple intervals corresponding to different on-board time resets. At Yamcs startup the service loads a list of intervals from the tco table.If using the historical recording to insert some old data into the Yamcs, in order to get the correct coefficients one has to know the approximate time when the data has been generated.
Verify Only Mode
If the on-board clock is synchronized via a different method, this service can still be used to verify the synchronization.The method
verify(org.yamcs.TmPacket)
will check the difference between the packet generation time and the expected generation time (using ert - delays) and in case the difference is greater than the validity, the packet will be changed with the local computed time and the flagTmPacket.setLocalGenTime()
will also be set.Usage
To use this service there will be typically one component which adds samples using the
addSample(long, Instant)
each time it receives a correlation sample from on-board. How the on-board system will send such samples is mission specific (for example the PUS protocol defines some specific time packets for this purpose).In addition there will be other components (preprocessors or other services) which can use the class to get a Yamcs time associated to a specific OBT.
This class is thread safe: the synchronised methods
addSample(long, org.yamcs.time.Instant)
andreset()
are the only one where the state is changed and thus thegetTime(long)
can be used from multiple threads concurrently.
-
-
Field Summary
Fields Modifier and Type Field Description static int
MAX_HISTCOEF
static String
TABLE_NAME
static TupleDefinition
TDEF
-
Fields inherited from class org.yamcs.AbstractYamcsService
config, log, serviceName, yamcsInstance
-
-
Constructor Summary
Constructors Constructor Description TimeCorrelationService()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addSample(long obt, Instant ert)
Add a time synchronisation sample.protected void
doStart()
protected void
doStop()
void
forceCoefficients(Instant obi, long obt, double offset, double gradient)
Instant
getHistoricalTime(Instant obi, long obt)
Returns the time when the on-board clock had the given value. obi is an approximative time used to search in history for the coefficients applicable at that time.Spec
getSpec()
Returns the valid configuration options for this service.org.yamcs.protobuf.TcoStatus
getStatus()
List<ParameterValue>
getSystemParameters()
return the next bunch of parameter values.org.yamcs.protobuf.TcoConfig
getTcoConfig()
Instant
getTime(long obt)
Returns the time when the on-board clock had the given value.TimeOfFlightEstimator
getTofEstimator()
void
init(String yamcsInstance, String serviceName, YConfiguration config)
Initialize this service.void
reset()
Forgets about the computed coefficients and the stored tuples.void
setAccuracy(double accuracy)
void
setDefaultTof(double defaultTof)
void
setOnboardDelay(double onboardDelay)
void
setValidity(double validity)
void
timestamp(long obt, TmPacket pkt)
Set the generation time of the packet based on the computed coefficients.void
verify(TmPacket pkt)
Verify the time synchronization of the packet.-
Methods inherited from class org.yamcs.AbstractYamcsService
getConfig, getYamcsInstance
-
Methods inherited from class com.google.common.util.concurrent.AbstractService
addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, failureCause, isRunning, notifyFailed, notifyStarted, notifyStopped, startAsync, state, stopAsync, toString
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface com.google.common.util.concurrent.Service
addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, failureCause, isRunning, startAsync, state, stopAsync
-
Methods inherited from interface org.yamcs.YamcsService
init
-
-
-
-
Field Detail
-
TABLE_NAME
public static final String TABLE_NAME
- See Also:
- Constant Field Values
-
MAX_HISTCOEF
public static final int MAX_HISTCOEF
- See Also:
- Constant Field Values
-
TDEF
public static final TupleDefinition TDEF
-
-
Method Detail
-
getSpec
public Spec getSpec()
Description copied from interface:YamcsService
Returns the valid configuration options for this service.- Specified by:
getSpec
in interfaceYamcsService
- Returns:
- the argument specification, or null if the args should not be validated.
-
init
public void init(String yamcsInstance, String serviceName, YConfiguration config) throws InitException
Description copied from interface:YamcsService
Initialize this service. This is called before the service is started. All operations should finish fast.- Specified by:
init
in interfaceYamcsService
- Overrides:
init
in classAbstractYamcsService
- Parameters:
yamcsInstance
- The yamcs instance, or null if this is a global service.serviceName
- The service name.config
- The configured arguments for this service. IfYamcsService.getSpec()
is implemented then this contains the arguments after being validated (including any defaults).- Throws:
InitException
- When something goes wrong during the execution of this method.
-
addSample
public void addSample(long obt, Instant ert)
Add a time synchronisation sample.If the coefficients are already computed, the sample will be used to asses the accuracy of the computation. If the accuracy is lower than
accuracy
, the coefficients will be recomputed based on the latest samples.If the coefficients are not yet computed, the sample will be simply added to the sample buffer. If there are enough samples in the buffer, the coefficients will be calculated.
- Parameters:
obt
- - On-Board Timeert
- - Earth Reception Time- Throws:
IllegalArgumentException
- if the obt or ert are smaller than the ones in the previous sample
-
reset
public void reset()
Forgets about the computed coefficients and the stored tuples.Should be called when the on-board clock resets.
-
getTime
public Instant getTime(long obt)
Returns the time when the on-board clock had the given value. If the coefficients are not computed yet, it will returnInstant.INVALID_INSTANT
- Parameters:
obt
-- Returns:
- the time instant corresponding to the on-board obt tick.
-
timestamp
public void timestamp(long obt, TmPacket pkt)
Set the generation time of the packet based on the computed coefficients.If the coefficients are not valid, set the generation time to gentime = ert-delays and also set the flag
TmPacket.setLocalGenTime()
The packet has to have the ert set, otherwise an exception is thrown
- Parameters:
obt
-pkt
-- Throws:
IllegalArgumentException
- if the packet has no ert set
-
verify
public void verify(TmPacket pkt)
Verify the time synchronization of the packet. This assumes that the packet generation time has already been computed (by a packet pre-processor).If the deviation between the provided generation time and the expected generation time (computed based on the ert - delays) is greater than the validity threshold, the generation time is changed to the expected time and the
TmPacket.setLocalGenTime()
is also set.The computed deviation is also published as a processed parameter.
- Parameters:
pkt
-- Throws:
IllegalArgumentException
- if the packet has no ert set
-
getHistoricalTime
public Instant getHistoricalTime(Instant obi, long obt)
Returns the time when the on-board clock had the given value. obi is an approximative time used to search in history for the coefficients applicable at that time.Returns
Instant.INVALID_INSTANT
if no historical coefficients are found.- Parameters:
obi
-obt
-- Returns:
-
doStart
protected void doStart()
- Specified by:
doStart
in classcom.google.common.util.concurrent.AbstractService
-
doStop
protected void doStop()
- Specified by:
doStop
in classcom.google.common.util.concurrent.AbstractService
-
getTofEstimator
public TimeOfFlightEstimator getTofEstimator()
-
getSystemParameters
public List<ParameterValue> getSystemParameters()
Description copied from interface:SystemParametersProducer
return the next bunch of parameter values. The values must contain a reference to a Parameter (i.e. parameter definition) and that Parameter does not need to be coming from the XtceDB - the provider can just make it up on the fly.- Specified by:
getSystemParameters
in interfaceSystemParametersProducer
-
setAccuracy
public void setAccuracy(double accuracy)
-
setValidity
public void setValidity(double validity)
-
setOnboardDelay
public void setOnboardDelay(double onboardDelay)
-
setDefaultTof
public void setDefaultTof(double defaultTof)
-
forceCoefficients
public void forceCoefficients(Instant obi, long obt, double offset, double gradient)
-
getTcoConfig
public org.yamcs.protobuf.TcoConfig getTcoConfig()
-
getStatus
public org.yamcs.protobuf.TcoStatus getStatus()
-
-