/* ---------------------------------------------------------------------- */ /* MPMessages.h */ /* */ /* ---------------------------------------------------------------------- */ /* */ /* (c) Copyright 2001, 2002 EdgeTech Inc */ /* */ /* This file contains proprietary information, and trade secrets of */ /* EdgeTech, and may not be disclosed or reproduced without the prior */ /* written consent of EdgeTech. */ /* */ /* EdgeTech is not responsible for the consequences of the use or misuse */ /* of this software, even if they result from defects in it. */ /* */ /* Messages for controlling multiping sonar processing */ /* ---------------------------------------------------------------------- */ #ifndef __MP_MESSAGES_H__ #define __MP_MESSAGES_H__ /* ---------------------------------------------------------------------- */ /* includes */ /* ---------------------------------------------------------------------- */ #include "MessageOffsets.h" /* ---------------------------------------------------------------------- */ /* defines */ /* ---------------------------------------------------------------------- */ /* Maximum number of pulses in the water column */ #define MP_MAX_PULSE_PHASES (8) /* Maximum compensation gain ranges. */ #define MP_MAX_ADCGAIN_RANGES (4) /* ---------------------------------------------------------------------- */ /* A list of device messages */ /* ---------------------------------------------------------------------- */ typedef enum { /* -------------------------------------------------------------------- */ /* MP Messages. */ /* -------------------------------------------------------------------- */ /* Set or get current MP parameters (MPParametersType) */ MP_MESSAGE_MP_PARAMETERS = MESSAGE_OFFSET_MP, /* MP Processing Mode: (SonarMessageLongType ) Choose from */ /* 0: No Post processing - Outputs N*M channels of data where N is the */ /* number of pulse phases and M is the number of channels. */ /* 1: Fore array data. */ /* 2: Aft array data. */ /* 3: Focussed data (blended). */ MP_MESSAGE_BLENDING_MODE, /* Save the current calibration settings (as last known good) */ MP_MESSAGE_ACCEPT_CALIBRATION, /* Set the active data set for calibration (SonarMessageLongType). */ /* Choose from: */ /* 0 : Factory defaults. */ /* 1 : Last known good set (Undoes last calibration) */ MP_MESSAGE_CALIBRATE_SET_ACTIVE_DATASET, /* Calibration step - setting the pulse power level. */ /* Receives a parameter (SonarMessageLongType) with the amount of */ /* correction to apply. A value of 0 will reset to full power. */ /* A value of 1000 will apply a full correction based on the current */ /* pulse power range bin. Values between 1 and 999 apply only a */ /* fraction of the required correction factor and are incremental */ /* to the current setting. */ /* Since setting the pulse power will cause pulses to be downloaded */ /* this can take a few seconds to complete. */ MP_MESSAGE_CALIBRATE_PULSEPOWER, /* Calibration step - setting the gain per range bins. */ /* Receives a parameter (SonarMessageLongType) with the amount of */ /* correction to apply. A value of 0 will reset to 0 DB gain */ /* A value of 1000 will apply a full correction based on the current */ /* statistics. Values between 1 and 999 apply only a */ /* fraction of the required correction factor and are incremental */ /* to the current setting. */ MP_MESSAGE_CALIBRATE_ADCGAINS, /* Enable / disable dynamic gain balancing for the specified subsystem */ /* (SonarMessageLongType). When enabled, per pulse phase statistics are*/ /* used to dynamically adjust gain to balance the frequency sensitivity */ /* per pulse phase and per range "bin". Dynamic gain balancing should */ /* be turned off when calibration is done so that the true gain */ /* imbalances can be seen by the operator to judge calibration quality */ /* A value of 0 disables gain balancing for the subsystem. A value of 1*/ /* enables gain balancing. */ MP_MESSAGE_DYNAMIC_GAIN_BALANCING, /* Changes on a get, queries on a set, the pulse frequency shift which */ /* is stored in the PulseCal.pcf file. (SonarMessageLongType) */ /* The frequency shift is in hertz and can be either positive or */ /* negative. This is specific to a subsystem. */ MP_MESSAGE_MODIFY_CENTER_FREQUENCY, /* Steps required to calibrate a pulse: */ /* (1) Select the pulse for calibration. */ /* (2) Set mode to blended. */ /* (3) Set the ping range so that the bottom return is visible */ /* (4) Set the pulse power ranges in the MP_MESSAGE_MP_PARAMETERS msg */ /* so that about 20 ms of data are averaged starting after the */ /* first bottom return (requires operator interaction. */ /* (5) Reset to full pulse power MP_MESSAGE_CALIBRATE_PULSEPOWER(0) */ /* (6) Enable AGC and allow gain to stabilize. */ /* (7) Allow statistics to settle. */ /* (8) Set pulse power MP_MESSAGE_CALIBRATE_PULSEPOWER(1000) or */ /* MP_MESSAGE_CALIBRATE_PULSEPOWER */ /* (9) View results. Repeat from 8 if blended data is not good. */ /* (10)Save calibration pars MP_MESSAGE_ACCEPT_CALIBRATION as last good */ /* (11)Make last good active MP_MESSAGE_CALIBRATE_SET_ACTIVE_DATASET */ /* Note: We are currently not planning to use the ADC Gains */ /* but if we did, you would need to set the ADC Gain range bins and */ /* allow the data to settle and then issue a: */ /* MP_MESSAGE_CALIBRATE_ADCGAINS(1000) BEFORE doing steps 12 and 13 */ } MPMessagesType; /* ---------------------------------------------------------------------- */ /* Calibration information and statistics structure. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Number of phases (pulses in water column) for current pulse file. */ /* Note that this is determined by the pulse file and is ignored on a */ /* SET. */ short numPhases; /* Number of pings processed to date. */ short numPings; /* Average signal level for each channel and bin. */ /* These values are continuously computed. These fields are ignored on */ /* a SONAR_COMMAND_SET. */ /* Units of DB * 10 (one tenth of a DB) */ /* The outer index has the following meaning: */ /* 0: port Fore, 1: port Aft, 2: stbd Fore, 3: stbd Aft */ short ADCSignal[MP_MAX_PULSE_PHASES][MP_MAX_ADCGAIN_RANGES][4]; short PulsePowerSignal[MP_MAX_PULSE_PHASES][4]; /* Average ADCMax reading for all channels in counts (max of 32767) */ /* These can be used to set the VGA gain values */ short ADCMax[4]; /* Calibration status. If calibration is pending then this will be the */ /* estimated number of seconds before the calibration completes. */ short calStatus; } MPCalInfoType; /* ---------------------------------------------------------------------- */ /* Calibration factors. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Pulse power level * 1000 for up to 8 pulse phases. Value must be */ /* between -1000 and +1000. These are the actual attenuation factors as*/ /* calibrated. */ /* Index 0 for port, index 1 for starboard. */ short pulsePowerLevel[MP_MAX_PULSE_PHASES][2]; /* Gains applied to fore and aft arrays. */ /* Index 0 for fore, index 1 for aft. */ short VGAGain[2]; /* Gains applied to ADC data fore and aft arrays. */ /* Units of DB * 10 (one tenth of a DB) */ /* Index 0:port fore, 1:port aft, 2:stbd fore, 3:stbd aft */ short ADCGain[MP_MAX_PULSE_PHASES][MP_MAX_ADCGAIN_RANGES][4]; } MPCalFactorsType; /* ---------------------------------------------------------------------- */ /* Calibration parameters. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Start / end time in 10 * MS to begin averaging for pulse power */ /* correction */ short calPulsePowerStart; short calPulsePowerEnd; /* Start/end time in 10*MS to begin averaging for ADC per channel scale */ /* Up to 4 ranges can be specified. If more then one range is present */ /* then the actual gain applied is linearly interpolated between the */ /* center points of each range. */ /* The center point of each range MUST be monotically increasing AND the*/ /* End value must be greater than the start value or the range and all */ /* that follow in the list are ignored. */ short calADCStart[MP_MAX_ADCGAIN_RANGES]; short calADCEnd[MP_MAX_ADCGAIN_RANGES]; /* Maximum attenuation factor for any pulse in 10 * DB. */ short calMaxPulseAttenuation; /* Maximum gain factor for any adc channel in 10 * DB. */ short calMaxADCGain; /* Target value in raw counts for ADC values when VGA Gains are applied */ short VGAGainTargetValue; /* Range to calibrate at in 10 * MS. */ short calRange; } MPCalParsType; /* ---------------------------------------------------------------------- */ /* All cal parameters structure. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Flags, used for a SONAR_COMMAND_SET. Bits are: */ /* 1 : Blending values set. */ /* 2 : Cal parameters set. */ /* 3 : Cal factors set (pulse powers) */ /* 4 : Cal factors set (non-vga ADC gains). */ /* 5 : Cal factors set (VGA Gains). */ /* Note that settings the cal factors will only be effective until */ /* the next time a pulse is loaded since the reference set of */ /* cal factors is modifed with each new pulse. */ /* 6 : Description. */ short flags; /* Text description of this data set. */ char description[80]; /* -------------------------------------------------------------------- */ /* Misc information. */ /* -------------------------------------------------------------------- */ MPCalInfoType calInfo; /* -------------------------------------------------------------------- */ /* Post processing options. */ /* -------------------------------------------------------------------- */ /* MP Blending parameters A(Alpha) and R(Range in MS) */ /* Weighting factor (W) as a function of time T is: */ /* W = 1 / (1 + (T/R)**(A/1000.0)) */ /* Blended value as a function of F(Fore) and A(Aft) arrays is: */ /* Blended = W * F + (1 - W) * A */ short blendingAlpha; /* alpha * 1000 */ short blendingRange; /* 10 * MS */ /* -------------------------------------------------------------------- */ /* Calibration parameters. */ /* -------------------------------------------------------------------- */ MPCalParsType calPars; /* -------------------------------------------------------------------- */ /* Calibration factors. */ /* -------------------------------------------------------------------- */ MPCalFactorsType calFactors; /* -------------------------------------------------------------------- */ /* Reserved for future use. */ /* -------------------------------------------------------------------- */ long int reserved[16]; } MPParametersType; #endif /* __MP_MESSAGES_H__ */ /* ---------------------------------------------------------------------- */ /* end MPMessages.h */ /* ---------------------------------------------------------------------- */