Class TimeCorrelationService
- All Implemented Interfaces:
com.google.common.util.concurrent.Service
,SystemParametersProducer
,YamcsService
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 and c
= offset such that
ob_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 flag TmPacket.setLocalGenTimeFlag()
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)
and reset()
are the only one where the
state is changed and thus the getTime(long)
can be used from multiple threads concurrently.
-
Nested Class Summary
Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service
com.google.common.util.concurrent.Service.Listener, com.google.common.util.concurrent.Service.State
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
static final String
static final TupleDefinition
Fields inherited from class org.yamcs.AbstractYamcsService
config, log, serviceName, yamcsInstance
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Add a time synchronisation sample.protected void
doStart()
protected void
doStop()
void
forceCoefficients
(Instant obi, long obt, double offset, double gradient) 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.long
getObt
(long scheduleTime) Returns the on-board time corresponding to the given on-board clockgetSpec()
Returns the valid configuration options for this service.getSystemParameters
(long gentime) return the next bunch of parameter values.getTime
(long obt) Returns the time when the on-board clock had the given value.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
Set the generation time of the packet based on the computed coefficients.void
Verify the time synchronization of the packet.Methods inherited from class org.yamcs.AbstractYamcsService
findStream, getConfig, getYamcsInstance
Methods inherited from class com.google.common.util.concurrent.AbstractService
addListener, awaitRunning, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, awaitTerminated, doCancelStart, 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, awaitRunning, awaitTerminated, awaitTerminated, awaitTerminated, failureCause, isRunning, startAsync, state, stopAsync
Methods inherited from interface org.yamcs.parameter.SystemParametersProducer
getFrequency
-
Field Details
-
TABLE_NAME
- See Also:
-
MAX_HISTCOEF
public static final int MAX_HISTCOEF- See Also:
-
TDEF
-
-
Constructor Details
-
TimeCorrelationService
public TimeCorrelationService()
-
-
Method Details
-
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, ornull
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
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
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.
-
getObt
public long getObt(long scheduleTime) Returns the on-board time corresponding to the given on-board clockIf the coefficients are not computed yet, it will return Long.MIN_VALUE
- Parameters:
scheduleTime
-- Returns:
-
timestamp
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.setLocalGenTimeFlag()
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
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.setLocalGenTimeFlag()
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
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
-
getSystemParameters
Description copied from interface:SystemParametersProducer
return the next bunch of parameter values.The gentime is the mission time when the parameter collection started. The returning parameters can use this time to allow all parameters in one collection interval to be timestamped with the same time.
- 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
-
getTcoConfig
-
getStatus
-