Package org.yamcs.time

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.
In addition it takes two other parameters:
  • 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.
The time of flight can be fixed or computed by the 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 than validity, 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 by getTime(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.

  • Field Details

  • Constructor Details

    • TimeCorrelationService

      public TimeCorrelationService()

  • Method Details

    • getSpec

      public Spec getSpec()
      Description copied from interface: YamcsService
      Returns the valid configuration options for this service.
      Specified by:
      getSpec in interface YamcsService
      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 interface YamcsService
      Overrides:
      init in class AbstractYamcsService
      Parameters:
      yamcsInstance - The yamcs instance, or null if this is a global service.
      serviceName - The service name.
      config - The configured arguments for this service. If YamcsService.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 Time
      ert - - 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 return Instant.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 clock

      If the coefficients are not computed yet, it will return Long.MIN_VALUE

      Parameters:
      scheduleTime -
      Returns:

    • 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.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

      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.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

      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 class com.google.common.util.concurrent.AbstractService

    • doStop

      protected void doStop()
      Specified by:
      doStop in class com.google.common.util.concurrent.AbstractService

    • getTofEstimator

      public TimeOfFlightEstimator getTofEstimator()

    • getSystemParameters

      public List<ParameterValue> getSystemParameters(long gentime)
      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 interface SystemParametersProducer

    • 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 TcoConfig getTcoConfig()

    • getStatus

      public TcoStatus getStatus()