tsc_GnssModes

The tsc_GnssModes class is used to control, query and perform measurements with a GNSS receiver.   A tsc_GnssModes object contains a setting for each mode that is settable on a receiver.  To use the object, all modes that are needed on the instrument (such as Measured Antenna Height) are first set to the required values, then an action method is called which will send all the modes to the instrument in the correct sequence.

The action methods always set all modes that have been specified, taking into account the current receiver state.  If a mode is already set correctly on the receiver, then it is not sent again.  This allows the programmer to set up the required modes and perform all GNSS operations without needing to query the current instrument state.  If another application or task within survey core changes the instrument's state, it will be restored to the settings specified in the tsc_GnssModes object before the action (eg: a measurement) is taken.

The modes in a tsc_GnssModes object all start off as unspecified, which means any receiver operation that is initiated using the object will not alter that mode from whatever is current.

Some settings supply criteria for measurements to heed.  While they do not affect the receiver behaviour directly they control the perception of what quality is required for a measurement to be considered successful.

Coordinates can be returned as absolute ECEF to the antenna phase center (APC) or as ECEF deltas between the APCs of the rover and base antenna.  Note that the frame of reference for the ECEF will be raw and in terms of the current survey, for example a RTX survey may differ to a RTK survey and care should be taken about how your coordinate is used.

Constructors

tsc_GnssModes (tsc_GnssInstrument& instrument);
This constructs an empty modes object and binds it to the specified instrument.

Public methods

General methods

int Identifier ();
Returns a unique identifer, allocated at construction, that identifies this tsc_GnssModes instance.  This can be used to tie an event back to the operation that caused it.

void PopulateFromInstrument();
Populate most of the tsc_GnssModes settings from the currently connected receiver.

void PopulateAntennaFromCurrentAntenna();
Populate antenna information from the current configuration.   

void PopulateAntenna(const tsc_GnssAntenna& antenna);
Populate the antenna settings from the supplied antenna.

tsc_GnssEnvironment GetEnvironment () const;
Generate a tsc_GnssEnvironment object from the modes instance.  Note that the environment will based upon the current job environment but overridden by any specified modes settings.

void Reset();
Resets all modes within the object to unspecified.

void ClearCriteria();
Stops any current operation and resets the measurement criteria.

void Abort();
Abort any currently running operation.  Note that OnFailed may be called and any pending instrument requests may still occur.

bool InProgress () const;
Returns true if some action method is in progress or the class is waiting for a synchronous operation to complete (which could be caught in the stack frame).

bool Failed () const;
Returns true if the last or current operation failed (which includes timeouts).

bool TimedOut () const;
Returns true if the last or current operation has timed out.

bool SetPositionRate (tsc_GnssEpochRate rate);
Sets the Gnss receiver position rate. Returns true if successful. The default position rate is 1 per second (1 Hz).
The position rate applies only to the streaming data from tsc_IGnssMonitor. Some older receivers are not supported.

tsc_GnssEpochRate GetPositionRate () const;
Get Gnss receiver position rate. The position rate applies only on the streaming data from tsc_IGnssMonitor. Some older receivers are not supported.

bool SetRoverPositionOffset (const tsc_EcefDeltas& newOffsets);
Set an offset to the reported Rover position during a Survey.  This will affect all GNSS coordinates reported by SurveyCore and should be used cautiously.

To succeed the offsets must not contain any double_Null values.

The effect will last for the duration of the current RTK base and will be cleared by the adoption of a new base, the end of the survey or when overwritten by a second call to this function.

The offset is not part of the GNSS environment.  A note record will be placed in the database detailing the offset values.

tsc_EcefDeltas GetRoverPositionOffset () const;
Gets the current offset to the reported Rover position during a RTK Survey. The results will be double_Null is the survey is not running or no offset is set.

bool ClearRoverPositionOffset ();
Clears the offset modifying the Rover position during a Survey.  This will affect all GNSS coordinates reported by SurveyCore and should be used cautiously.
The offset is not part of the GNSS environment.  A note record will be placed in the database.

Capability

bool SupportsReInitialisation();
Determine if the ReInitialisation command is supported by the instrument.

bool SupportsMeasurement();
Determine if the Measurement command is currently supported by the instrument.  Returns false if a compatible (RTK) survey is not running.

Action methods

The action methods come in two flavours; synchronous and asynchronous.  Synchronous methods block execution until completion, whereas asynchronous methods return immediately and continue operating in the background.  The default timeout is 30.0 seconds. Take great care using the synchronous methods, particularly in a tsc_Form class. See the page Pitfalls using Synchronous methods for an in-depth explanation of the problems.

Synchronous

These action methods do not return until the operation succeeds, fails, or times out.  While the operation is in progress, Survey Core will continue to process messages for the calling thread which means that (for instance) a form that calls one of these methods will continue to redraw normally.

Important: Because form events continue to be processed while waiting, it may be necessary to prevent re-entry of the event handler while the instrument operation is in progress.  Please see the sample code near the bottom of this page about how to avoid this problem.

Take great care using the synchronous methods, particularly in a tsc_Form class.  See the page Pitfalls using Synchronous methods for an in-depth explanation of the problems.

The monitor parameter specifies a class that implements the tsc_IGnssModesMonitor interface for handling events resulting from the operation.  It may be specified as NULL (or omitted), which avoids the use of event handlers, and the return code must be tested to determine if the operation succeeded.  Any kind of failure or timeout returns false.

bool ApplyModes (tsc_IGnssModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
Sends all specified modes to the instrument and returns true if the operation succeeds.  Unspecified modes, and modes that are already correctly set in the instrument are not sent.

bool ForceReInitialisation(tsc_IGnssModesMonitor* monitor=NULL, double timeout=DefaultTimeout);
Forces the receiver to reacquire the RTK initialisation.

tsc_Ecef MeasureEcef(tsc_IGnssModesMonitor* monitor=NULL, tsc_GnssTilt* tilt=NULL, double timeout=DefaultTimeout);
Takes a measurement and returns the result as a tsc_Ecef coordinate.

tsc_EcefDeltas MeasureEcefDeltas (
                  tsc_IGnssModesMonitor* monitor = NULL,
                  tsc_GnssTilt* tilt = NULL,
                  double timeout = DefaultTimeout);
Takes a measurement and returns the result as a tsc_EcefDeltas coordinate.

In all cases a return value of true means that the operation completed successfully.  A value of false (or double_Null coordinate values) indicates that the tsc_GnssModes object is busy or stuck in a wait, no RTK survey is running or the operation either timed out or failed.

Asynchronous

These methods are called in pairs; first a Start method, then a Wait method.  If the tsc_GnssModes object is destroyed before the operation is complete, it will be aborted.

Asynchronous methods are generally safer to use than their synchronous cousins.  Synchronous methods block the stack and may cause serious problems if used incorrectly.

bool StartApplyModes        (tsc_IGnssModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
bool StartReInitialisation  (tsc_IGnssModesMonitor* monitor = NULL, double timeout = DefaultTimeout);
bool StartMeasure           (tsc_IGnssModesMonitor* monitor = NULL, double timeout = DefaultTimeout);

These methods are identical to their synchronous equivalents, except that they return immediately after the operations have been started on the instrument.  This may take a little time, but significantly less than the entire time the operation will take.  A return value of false indicates that the tsc_GnssModes object is busy, no suitable RTK survey is running, or the operation immediately failed.

bool WaitForCompletion();
This method will wait until the preceding operation has completed.  If the operation has already finished, it will not wait at all, and if no operation has ever been started on the tsc_TsModes instance it will wait forever. If called immediately after the start method, then it effectively becomes synchronous.

tsc_Ecef       WaitForMeasureEcef      (tsc_GnssPrecisions* precisions = NULL, tsc_GnssTilt* tilt = NULL);
tsc_EcefDeltas WaitForMeasureEcefDeltas(tsc_GnssPrecisions* precisions = NULL, tsc_GnssTilt* tilt = NULL);
Waits for a measure operation to complete, and returns the results.  If the previous operation was not a Measure, or the results have already been obtained, the returned object will contain double_Null values in its members.

tsc_Ecef       GetMeasureResultEcef      (tsc_GnssPrecisions* precisions = NULL, tsc_GnssTilt* tilt = NULL);
tsc_EcefDeltas GetMeasureResultEcefDeltas(tsc_GnssPrecisions* precisions = NULL, tsc_GnssTilt* tilt = NULL);
Similar to WaitForMeasureXXX but does not wait.  If a measurement is not started or is not complete then a double_Null coordinate will be returned.  Use this function inside the tsc_IGnssModesMonitor::OnGnssModesMeasurementComplete event handler to retrieve the result.

Mode setting and querying methods

Each mode and criteria type has three methods; a Set method, a Clear method, and a Query method.  All these methods return the same type - a tsc_ModesResult enumeration which describes the current mode as one of:

• • tsmr_Unspecified - The mode has not been specified in this instance.

  • tsmr_Specified - The mode has been specified, it is supported, and is read/write.

  • tsmr_Supported - The mode is supported - does not imply the specified status.

  • tsmr_Unsupported - The mode is unsupported - does not imply the specified status.

The query methods have two options specified by the tsc_QueryMode argument:

• tsqm_QueryThis

  • Queries the tsc_TsModes instance.

• tsqm_QueryInstrument

  • Queries the instrument.

• tsqm_QuerySupported

  • Queries the current connection and configuration to determine if the feature is currently supported.  This type of query will use the result parameter to determine if a particular option is being tested making it an in/out parameter.  Use Unknown or Unspecified values as input when referring to the overall setting.

General Settings

    tsc_ModesResult      SetMeasuredAntennaHeight         (double newSetting);
    tsc_ModesResult      ClearMeasuredAntennaHeight       ();
    tsc_ModesResult      QueryMeasuredAntennaHeight       (tsc_QueryMode mode, double& result);
    tsc_ModesResult      SetAntennaMeasurementMethod      (int newSetting);
    tsc_ModesResult      ClearAntennaMeasurementMethod    ();
    tsc_ModesResult      QueryAntennaMeasurementMethod    (tsc_QueryMode mode, int& result);  
    tsc_ModesResult      SetMeasureEpochRate              (tsc_GnssEpochRate newSetting);
    tsc_ModesResult      ClearMeasureEpochRate            ();
    tsc_ModesResult      QueryMeasureEpochRate            (tsc_QueryMode mode, tsc_GnssEpochRate& result);
    tsc_ModesResult      SetTiltCompensatedMeasurement    (bool newSetting);
    tsc_ModesResult      ClearTiltCompensatedMeasurement  ();
    tsc_ModesResult      QueryTiltCompensatedMeasurement  (tsc_QueryMode mode, bool& result);

    Use this to configure the receiver to perform tilt calculations to allow tilted point measurements.

    When this is set true and a measurement is requested the pole tilt data will be recorded.

    During this type of measurements the position rate is 0.5Hz regardless of the MeasureEpochRate.

Measurement methods are expressed as an index into the array of known measurement methods for the current antenna; use this method to retrieve the list of measurement types.  Index 0 is always available.

    tsc_StringList       CurrentAntennaMeasurementMethods() const;

Measurement criteria

While these behave and appear much like settings they are in fact used to determine the quality of the measurement.  You can set these to define minimum acceptable criteria for a measurement to continue or complete.  If a Maximum criteria is exceeded during the measure then the measurement is aborted.  In general the measurement continues until the minimum criteria are met or a timeout occurs.  In most cases specifying a criteria to a value such as double_Null is equivalent to Clearing that criteria.  For example, setting the FixedSolutionRequired to false or MaximumPdop to double_Null are effectively Clear operations when it is implemented.

Note: DOP values change very slowly when the receiver is in static mode as the satellite constellation typically remains constant.

Note: MaximumRms is a precondition tested before measurements can start.

    tsc_ModesResult      SetMaximumPdop     (double newSetting);

    tsc_ModesResult      ClearMaximumPdop   ();

    tsc_ModesResult      QueryMaximumPdop   (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMaximumHdop     (double newSetting);

    tsc_ModesResult      ClearMaximumHdop   ();

    tsc_ModesResult      QueryMaximumHdop   (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMaximumVdop     (double newSetting);

    tsc_ModesResult      ClearMaximumVdop   ();

    tsc_ModesResult      QueryMaximumVdop   (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMaximumGdop     (double newSetting);

    tsc_ModesResult      ClearMaximumGdop   ();

    tsc_ModesResult      QueryMaximumGdop   (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMaximumRms      (double newSetting);

    tsc_ModesResult      ClearMaximumRms    ();

    tsc_ModesResult      QueryMaximumRms    (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMinimumHorizontalPrecision   (double newSetting);

    tsc_ModesResult      ClearMinimumHorizontalPrecision ();

    tsc_ModesResult      QueryMinimumHorizontalPrecision (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMinimumVerticalPrecision     (double newSetting);

    tsc_ModesResult      ClearMinimumVerticalPrecision   ();

    tsc_ModesResult      QueryMinimumVerticalPrecision   (tsc_QueryMode mode, double& result);

    tsc_ModesResult      SetMinimumNumberOfSatellites    (int newSetting);

    tsc_ModesResult      ClearMinimumNumberOfSatellites  ();

    tsc_ModesResult      QueryMinimumNumberOfSatellites  (tsc_QueryMode mode, int& result);

    tsc_ModesResult      SetFixedSolutionRequired        (bool newSetting);

    tsc_ModesResult      ClearFixedSolutionRequired      ();

    tsc_ModesResult      QueryFixedSolutionRequired      (tsc_QueryMode mode, bool& result);

    Note that a 'fixed' solution is only available on older receivers that do not support the HdGnss flag (see tsc_GnssInstrument).
    Modern receiever position quality should be determined by precisions instead.

    tsc_ModesResult      SetMaximumTilt                  (double newSetting);

    tsc_ModesResult      ClearMaximumTilt                ();

    tsc_ModesResult      QueryMaximumTilt                (tsc_QueryMode mode, double& result);

Use the MaximumTilt to set a tolerance for pole tilt from vertical in radians during the measurement (when supported by the receiver):

    tsc_ModesResult      SetMaximumMovement  (

                            double newSetting,

                            tsc_CriteriaInterpretation appliedWhen = tsci_AbortWhenExceeded

                         );

    tsc_ModesResult      ClearMaximumMovement ();

    tsc_ModesResult      QueryMaximumMovement (tsc_QueryMode mode, double& result);

Use the MaximumMovement to set a tolerance for pole movement in meters during the measurement (when supported by the receiver):

    tsc_ModesResult      SetMaximumMagneticInteference (

                                  tsmi_MagneticInterference newSetting,

                                  tsc_CriteriaInterpretation appliedWhen = tsci_AbortWhenExceeded

                         );

    tsc_ModesResult      ClearMaximumMagneticInteference ();

    tsc_ModesResult      QueryMaximumMagneticInteference (tsc_QueryMode mode, tsmi_MagneticInterference& result);

Use the MaximumMagneticInteference to set a tolerance for magnetic interference during the measurement.
Important: Recommended for and only active when performing tilt compensated points.

    tsc_ModesResult      SetMinimumEpoch    (int newSetting);

    tsc_ModesResult      ClearMinimumEpoch  ();

    tsc_ModesResult      QueryMinimumEpoch  (tsc_QueryMode mode, int& result);

The measurement will not be considered complete until MinimumEpoch number of epochs have occurred. An epoch takes 1 second, so for instance, specifying 3 means the measurement will likely take 3 seconds, although this time may be greater depending on conditions. The minimum value is 1 but this should be avoided for all but the roughest of positions. The default is 2 and most modern (~2020) receivers will give good positions at this setting. Higher values (with diminishing returns) can give increased precision and may be necessary for older receivers.

Enumerations

tsc_ModesResult

enum tsc_ModesResult
{
    tsmr_Unspecified = 0,
    tsmr_Specified,
    tsmr_Supported,
    tsmr_Unsupported,
};

tsc_QueryMode

enum tsc_QueryMode
{
    tsqm_QueryThis = 0,
    tsqm_QueryInstrument,
    tsqm_QuerySupported
};

tsc_GnssMeasurementFailReason

enum tsc_GnssMeasurementFailReason
{
    tsfr_MeasurementSuccessful                = 0x0000,
    tsfr_MaximumPdopExceeded                  = 0x0001,
    tsfr_MaximumHdopExceeded                  = 0x0002,
    tsfr_MaximumVdopExceeded                  = 0x0004,
    tsfr_MaximumRmsExceeded                   = 0x0008,
    tsfr_OutsideMinimumHPrec                  = 0x0010,
    tsfr_OutsideMinimumVPrec                  = 0x0020,
    tsfr_BelowMinimumNumberOfSatellites       = 0x0040,
    tsfr_FixedSolutionRequired                = 0x0080,
    tsfr_MaximumGdopExceeded                  = 0x0100,
    tsfr_MaximumTiltExceeded                  = 0x0200,
    tsfr_BelowMinimumEpochCount               = 0x0400,
    tsfr_ExceededMaximumMovement              = 0x0800,
    tsfr_ExceededMaximumMagneticInterference  = 0x1000
};

tsc_GnssFixStatus

enum tsc_GnssFixStatus
{
    tsfs_Unsupported,
    tsfs_Float,
    tsfs_Fixed
};

tsc_GnssEpochRate

enum tsc_GnssEpochRate
{
    tser_EpochRateUnknown = -1,
    tser_EpochRate1Hz     = 1,
    tser_EpochRate5Hz     = 5
};

tsmi_MagneticInterference

enum tsmi_MagneticInterference
{
    tsmi_MaxSafeToUseMagInterference    = 50,
    tsmi_MaxWithWarningMagInterference  = 98,
    tsmi_OffScaleMagInterference        = 99,
    tsmi_UnknownMagInterference         = 255
};