Detailed Description

Encapsulates a Sensor component for the flight control system.

Syntax:

<sensor name="name">
  <input> property </input>
  <lag> number </lag>
  <noise [variation="PERCENT|ABSOLUTE"] [distribution="UNIFORM|GAUSSIAN"] > number </noise>
  <quantization name="name">
    <bits> number </bits>
    <min> number </min>
    <max> number </max>
  </quantization>
  <drift_rate> number </drift_rate>
  <gain> number </gain>
  <bias> number </bias>
  <delay [type="time|frames"]> number < /delay>
</sensor>

Example:

<sensor name="aero/sensor/qbar">
  <input> aero/qbar </input>
  <lag> 0.5 </lag>
  <noise variation="PERCENT"> 2 </noise>
  <quantization name="aero/sensor/quantized/qbar">
    <bits> 12 </bits>
    <min> 0 </min>
    <max> 400 </max>
  </quantization>
  <bias> 0.5 </bias>
</sensor>

The only required element in the sensor definition is the input element. In that case, no degradation would be modeled, and the output would simply be the input.

Noise can be Gaussian or uniform, and the noise can be applied as a factor (PERCENT) or additively (ABSOLUTE). The noise that can be applied at each frame of the simulation execution is calculated as a random factor times a noise value that is specified in the config file. When the noise distribution type is Gaussian, the random number can be between roughly -3 and +3 for a span of six sigma. When the distribution type is UNIFORM, the random value can be between -1.0 and +1.0. This random value is multiplied against the specified noise to arrive at a random noise value for the frame. If the noise type is PERCENT, then random noise value is added to one, and that sum is then multiplied against the input signal for the sensor. In this case, the specified noise value in the config file would be expected to actually be a percent value, such as 0.05 (for a 5% variance). If the noise type is ABSOLUTE, then the random noise value specified in the config file is understood to be an absolute value of noise to be added to the input signal instead of being added to 1.0 and having that sum be multiplied against the input signal as in the PERCENT type. For the ABSOLUTE noise case, the noise number specified in the config file could be any number.

If the type is ABSOLUTE, then the noise number times the random number is added to the input signal instead of being multiplied against it as with the PERCENT type of noise.

If a noise element is specified, then a property will be created, named name/randomseed if the name contains a path separator '/' or fcs/name/randomseed if the name does not contain a path separator. Which allows a user to specify a random seed to be used for the noise generation.

The delay element can specify a frame delay. The integer number provided is the number of frames to delay the output signal.

Author: Jon S. Berndt

Version

Revision: 1.24

Definition at line 133 of file FGSensor.h.

#include <FGSensor.h>

Inheritance diagram for FGSensor:

Collaboration diagram for FGSensor:

Public Member Functions
	FGSensor (FGFCS fcs, Element element)

double	GetFailHigh (void) const

double	GetFailLow (void) const

double	GetFailStuck (void) const

int	GetNoiseRandomSeed (void) const

int	GetQuantized (void) const

void	ResetPastStates (void) override

bool	Run (void) override

void	SetFailHigh (double val)

void	SetFailLow (double val)

void	SetFailStuck (double val)

void	SetNoiseRandomSeed (int seed)

Public Member Functions inherited from FGFCSComponent
	FGFCSComponent (FGFCS fcs, Element el)
	Constructor.

virtual	~FGFCSComponent ()
	Destructor.

std::string	GetName (void) const

double	GetOutput (void) const

virtual double	GetOutputPct (void) const

std::string	GetType (void) const

virtual void	SetOutput (void)

Public Member Functions inherited from FGJSBBase
	FGJSBBase ()
	Constructor for FGJSBBase.

virtual	~FGJSBBase ()
	Destructor for FGJSBBase.

void	disableHighLighting (void)
	Disables highlighting in the console output.

Protected Types
enum	eDistributionType { eUniform =0 , eGaussian }

enum	eNoiseType { ePercent =0 , eAbsolute }

Protected Member Functions
void	Bias (void)

void	bind (Element el, FGPropertyManager pm) override

void	Drift (void)

void	Gain (void)

void	Lag (void)

void	Noise (void)

void	ProcessSensorSignal (void)

void	Quantize (void)

Protected Member Functions inherited from FGFCSComponent
void	CheckInputNodes (size_t MinNodes, size_t MaxNodes, Element *el)

void	Clip (void)

void	Delay (void)

Protected Attributes
double	bias

int	bits

double	ca

double	cb
	lag filter coefficient "a"

enum JSBSim::FGSensor::eDistributionType	DistributionType

int	divisions

double	drift

double	drift_rate

bool	fail_high

bool	fail_low

bool	fail_stuck

double	gain

double	granularity

double	lag

double	max

double	min

int	noise_type

double	noise_variance

enum JSBSim::FGSensor::eNoiseType	NoiseType

double	PreviousInput

double	PreviousOutput
	lag filter coefficient "b"

std::string	quant_property

int	quantized

double	span

Protected Attributes inherited from FGFCSComponent
bool	clip

FGParameter_ptr	ClipMax

FGParameter_ptr	ClipMin

bool	cyclic_clip

unsigned int	delay

double	delay_time

double	dt

FGFCS *	fcs

int	index

std::vector< FGPropertyValue_ptr >	InitNodes

double	Input

std::vector< FGPropertyValue_ptr >	InputNodes

std::string	Name

double	Output

std::vector< double >	output_array

std::vector< SGPropertyNode_ptr >	OutputNodes

std::string	Type

Additional Inherited Members
Public Types inherited from FGJSBBase
enum	{ eL = 1 , eM , eN }
	Moments L, M, N. More...

enum	{ eP = 1 , eQ , eR }
	Rates P, Q, R. More...

enum	{ eU = 1 , eV , eW }
	Velocities U, V, W. More...

enum	{ eX = 1 , eY , eZ }
	Positions X, Y, Z. More...

enum	{ ePhi = 1 , eTht , ePsi }
	Euler angles Phi, Theta, Psi. More...

enum	{ eDrag = 1 , eSide , eLift }
	Stability axis forces, Drag, Side force, Lift. More...

enum	{ eRoll = 1 , ePitch , eYaw }
	Local frame orientation Roll, Pitch, Yaw. More...

enum	{ eNorth = 1 , eEast , eDown }
	Local frame position North, East, Down. More...

enum	{ eLat = 1 , eLong , eRad }
	Locations Radius, Latitude, Longitude. More...

enum	{ inNone = 0 , inDegrees , inRadians , inMeters , inFeet }
	Conversion specifiers. More...

Static Public Member Functions inherited from FGJSBBase
static const std::string &	GetVersion (void)
	Returns the version number of JSBSim.

static constexpr double	KelvinToFahrenheit (double kelvin)
	Converts from degrees Kelvin to degrees Fahrenheit.

static constexpr double	CelsiusToRankine (double celsius)
	Converts from degrees Celsius to degrees Rankine.

static constexpr double	RankineToCelsius (double rankine)
	Converts from degrees Rankine to degrees Celsius.

static constexpr double	KelvinToRankine (double kelvin)
	Converts from degrees Kelvin to degrees Rankine.

static constexpr double	RankineToKelvin (double rankine)
	Converts from degrees Rankine to degrees Kelvin.

static constexpr double	FahrenheitToCelsius (double fahrenheit)
	Converts from degrees Fahrenheit to degrees Celsius.

static constexpr double	CelsiusToFahrenheit (double celsius)
	Converts from degrees Celsius to degrees Fahrenheit.

static constexpr double	CelsiusToKelvin (double celsius)
	Converts from degrees Celsius to degrees Kelvin.

static constexpr double	KelvinToCelsius (double kelvin)
	Converts from degrees Kelvin to degrees Celsius.

static constexpr double	FeetToMeters (double measure)
	Converts from feet to meters.

static bool	EqualToRoundoff (double a, double b)
	Finite precision comparison.

static bool	EqualToRoundoff (float a, float b)
	Finite precision comparison.

static bool	EqualToRoundoff (float a, double b)
	Finite precision comparison.

static bool	EqualToRoundoff (double a, float b)
	Finite precision comparison.

static constexpr double	Constrain (double min, double value, double max)
	Constrain a value between a minimum and a maximum value.

static constexpr double	sign (double num)

Static Public Attributes inherited from FGJSBBase
static char	highint [5] = {27, '[', '1', 'm', '\0' }
	highlights text

static char	halfint [5] = {27, '[', '2', 'm', '\0' }
	low intensity text

static char	normint [6] = {27, '[', '2', '2', 'm', '\0' }
	normal intensity text

static char	reset [5] = {27, '[', '0', 'm', '\0' }
	resets text properties

static char	underon [5] = {27, '[', '4', 'm', '\0' }
	underlines text

static char	underoff [6] = {27, '[', '2', '4', 'm', '\0' }
	underline off

static char	fgblue [6] = {27, '[', '3', '4', 'm', '\0' }
	blue text

static char	fgcyan [6] = {27, '[', '3', '6', 'm', '\0' }
	cyan text

static char	fgred [6] = {27, '[', '3', '1', 'm', '\0' }
	red text

static char	fggreen [6] = {27, '[', '3', '2', 'm', '\0' }
	green text

static char	fgdef [6] = {27, '[', '3', '9', 'm', '\0' }
	default text

static short	debug_lvl = 1

Static Protected Member Functions inherited from FGJSBBase
static std::string	CreateIndexedPropertyName (const std::string &Property, int index)

Static Protected Attributes inherited from FGJSBBase
static constexpr double	radtodeg = 180. / M_PI

static constexpr double	degtorad = M_PI / 180.

static constexpr double	hptoftlbssec = 550.0

static constexpr double	psftoinhg = 0.014138

static constexpr double	psftopa = 47.88

static constexpr double	fttom = 0.3048

static constexpr double	ktstofps = 1852./(3600*fttom)

static constexpr double	fpstokts = 1.0 / ktstofps

static constexpr double	inchtoft = 1.0/12.0

static constexpr double	m3toft3 = 1.0/(fttomfttomfttom)

static constexpr double	in3tom3 = inchtoftinchtoftinchtoft/m3toft3

static constexpr double	inhgtopa = 3386.38

static constexpr double	slugtolb = 32.174049
	Note that definition of lbtoslug by the inverse of slugtolb and not to a different constant you can also get from some tables will make lbtoslug*slugtolb == 1 up to the magnitude of roundoff.

static constexpr double	lbtoslug = 1.0/slugtolb

static constexpr double	kgtolb = 2.20462

static constexpr double	kgtoslug = 0.06852168

static const std::string	needed_cfg_version = "2.0"

static const std::string	JSBSim_version = JSBSIM_VERSION " " __DATE__ " " __TIME__

Member Enumeration Documentation

◆ eDistributionType

enum eDistributionType

protected

Definition at line 156 of file FGSensor.h.

156{eUniform=0, eGaussian} DistributionType;

◆ eNoiseType

enum eNoiseType

protected

Definition at line 155 of file FGSensor.h.

155{ePercent=0, eAbsolute} NoiseType;

Constructor & Destructor Documentation

◆ FGSensor()

FGSensor	(	FGFCS *	fcs,
		Element *	element
	)

Definition at line 54 of file FGSensor.cpp.

  : FGFCSComponent(fcs, element), generator(fcs->GetExec()->GetRandomGenerator())
{
  // inputs are read from the base class constructor
 
  bits = quantized = divisions = 0;
  PreviousInput = PreviousOutput = 0.0;
  min = max = bias = gain = noise_variance = lag = drift_rate = drift = span = 0.0;
  granularity = 0.0;
  noise_type = 0;
  fail_low = fail_high = fail_stuck = false;
 
  Element* quantization_element = element->FindElement("quantization");
  if ( quantization_element) {
    if ( quantization_element->FindElement("bits") ) {
      bits = (int)quantization_element->FindElementValueAsNumber("bits");
    }
    divisions = (1<<bits);
    if ( quantization_element->FindElement("min") ) {
      min = quantization_element->FindElementValueAsNumber("min");
    }
    if ( quantization_element->FindElement("max") ) {
      max = quantization_element->FindElementValueAsNumber("max");
    }
    quant_property = quantization_element->GetAttributeValue("name");
    span = max - min;
    granularity = span/divisions;
  }
  if ( element->FindElement("bias") ) {
    bias = element->FindElementValueAsNumber("bias");
  }
  if ( element->FindElement("gain") ) {
    gain = element->FindElementValueAsNumber("gain");
  }
  if ( element->FindElement("drift_rate") ) {
    drift_rate = element->FindElementValueAsNumber("drift_rate");
  }
  if ( element->FindElement("lag") ) {
    lag = element->FindElementValueAsNumber("lag");
    double denom = 2.00 + dt*lag;
    ca = dt*lag / denom;
    cb = (2.00 - dt*lag) / denom;
  }
  if ( element->FindElement("noise") ) {
    noise_variance = element->FindElementValueAsNumber("noise");
    string variation = element->FindElement("noise")->GetAttributeValue("variation");
    if (variation == "PERCENT") {
      NoiseType = ePercent;
    } else if (variation == "ABSOLUTE") {
      NoiseType = eAbsolute;
    } else {
      NoiseType = ePercent;
      FGLogging log(LogLevel::ERROR);
      log << "Unknown noise type in sensor: " << Name
        << "\n  defaulting to PERCENT.\n";
    }
    string distribution = element->FindElement("noise")->GetAttributeValue("distribution");
    if (distribution == "UNIFORM") {
      DistributionType = eUniform;
    } else if (distribution == "GAUSSIAN") {
      DistributionType = eGaussian;
    } else {
      DistributionType = eUniform;
      FGLogging log(LogLevel::ERROR);
      log << "Unknown random distribution type in sensor: " << Name
        << "\n  defaulting to UNIFORM.\n";
    }
  }
 
  bind(element, fcs->GetPropertyManager().get());
 
  Debug(0);
}

◆ ~FGSensor()

~FGSensor ( )

virtual

Definition at line 130 of file FGSensor.cpp.

{
  Debug(1);
}

Member Function Documentation

◆ Bias()

void Bias ( void )

protected

Definition at line 207 of file FGSensor.cpp.

{
  Output += bias;
}

◆ bind()

void bind	(	Element *	el,
		FGPropertyManager *	pm
	)

overrideprotectedvirtual

Reimplemented from FGFCSComponent.

Definition at line 251 of file FGSensor.cpp.

{
  string tmp = Name;
 
  FGFCSComponent::bind(el, PropertyManager);
 
  if (Name.find("/") == string::npos) {
    tmp = "fcs/" + PropertyManager->mkPropertyName(Name, true);
  }
  const string tmp_low = tmp + "/malfunction/fail_low";
  const string tmp_high = tmp + "/malfunction/fail_high";
  const string tmp_stuck = tmp + "/malfunction/fail_stuck";
  const string tmp_randomseed = tmp + "/randomseed";
 
  PropertyManager->Tie( tmp_low, this, &FGSensor::GetFailLow, &FGSensor::SetFailLow);
  PropertyManager->Tie( tmp_high, this, &FGSensor::GetFailHigh, &FGSensor::SetFailHigh);
  PropertyManager->Tie( tmp_stuck, this, &FGSensor::GetFailStuck, &FGSensor::SetFailStuck);
  PropertyManager->Tie( tmp_randomseed, this, &FGSensor::GetNoiseRandomSeed, &FGSensor::SetNoiseRandomSeed);
 
  if (!quant_property.empty()) {
    if (quant_property.find("/") == string::npos) { // not found
      string qprop = "fcs/" + PropertyManager->mkPropertyName(quant_property, true);
      SGPropertyNode* node = PropertyManager->GetNode(qprop, true);
      if (node->isTied()) {
        XMLLogException err(el);
        err << "Property " << tmp << " has already been successfully bound (late).\n";
        throw err;
      }
      else
        PropertyManager->Tie(qprop, this, &FGSensor::GetQuantized);
    }
  }
}

◆ Drift()

void Drift ( void )

protected

Definition at line 221 of file FGSensor.cpp.

{
  drift += drift_rate*dt;
  Output += drift;
}

◆ Gain()

void Gain ( void )

protected

Definition at line 214 of file FGSensor.cpp.

{
  Output *= gain;
}

◆ GetFailHigh()

double GetFailHigh ( void ) const

inline

Definition at line 144 of file FGSensor.h.

144{if (fail_high) return 1.0; else return 0.0;}

◆ GetFailLow()

double GetFailLow ( void ) const

inline

Definition at line 143 of file FGSensor.h.

143{if (fail_low) return 1.0; else return 0.0;}

◆ GetFailStuck()

double GetFailStuck ( void ) const

inline

Definition at line 145 of file FGSensor.h.

145{if (fail_stuck) return 1.0; else return 0.0;}

◆ GetNoiseRandomSeed()

int GetNoiseRandomSeed ( void ) const

Definition at line 295 of file FGSensor.cpp.

{
  if (RandomSeed)
    return *RandomSeed;
  else
    return fcs->GetExec()->SRand();
}

◆ GetQuantized()

int GetQuantized ( void ) const

inline

Definition at line 146 of file FGSensor.h.

146{return quantized;}

◆ Lag()

void Lag ( void )

protected

Definition at line 240 of file FGSensor.cpp.

{
  // "Output" on the right side of the "=" is the current input
  Output = ca * (Output + PreviousInput) + PreviousOutput * cb;
 
  PreviousOutput = Output;
  PreviousInput  = Input;
}

◆ Noise()

void Noise ( void )

protected

Definition at line 185 of file FGSensor.cpp.

{
  double random_value=0.0;
 
  if (DistributionType == eUniform)
    random_value = generator->GetUniformRandomNumber();
  else
    random_value = generator->GetNormalRandomNumber();
 
  switch( NoiseType ) {
  case ePercent:
    Output *= (1.0 + noise_variance*random_value);
    break;
 
  case eAbsolute:
    Output += noise_variance*random_value;
    break;
  }
}

◆ ProcessSensorSignal()

void ProcessSensorSignal ( void )

protected

Definition at line 159 of file FGSensor.cpp.

{
  // Degrade signal as specified
 
  if (!fail_stuck) {
    Output = Input; // perfect sensor
 
    if (lag != 0.0)            Lag();       // models sensor lag and filter
    if (noise_variance != 0.0) Noise();     // models noise
    if (drift_rate != 0.0)     Drift();     // models drift over time
    if (gain != 0.0)           Gain();      // models a finite gain
    if (bias != 0.0)           Bias();      // models a finite bias
 
    if (delay != 0)            Delay();     // models system signal transport latencies
 
    if (fail_low)  Output = -HUGE_VAL;
    if (fail_high) Output =  HUGE_VAL;
 
    if (bits != 0)             Quantize();  // models quantization degradation
 
    Clip();
  }
}

◆ Quantize()

void Quantize ( void )

protected

Definition at line 229 of file FGSensor.cpp.

{
  if (Output < min) Output = min;
  if (Output > max) Output = max;
  double portion = Output - min;
  quantized = (int)(portion/granularity);
  Output = quantized*granularity + min;
}

◆ ResetPastStates()

void ResetPastStates ( void )

overridevirtual

Reimplemented from FGFCSComponent.

Definition at line 137 of file FGSensor.cpp.

{
  FGFCSComponent::ResetPastStates();
 
  PreviousOutput = PreviousInput = Output = 0.0;
}

◆ Run()

bool Run ( void )

overridevirtual

Reimplemented from FGFCSComponent.

Definition at line 146 of file FGSensor.cpp.

{
  Input = InputNodes[0]->getDoubleValue();
 
  ProcessSensorSignal();
 
  SetOutput();
 
  return true;
}

◆ SetFailHigh()

void SetFailHigh ( double val )

inline

Definition at line 140 of file FGSensor.h.

140{if (val > 0.0) fail_high = true; else fail_high = false;}

◆ SetFailLow()

void SetFailLow ( double val )

inline

Definition at line 139 of file FGSensor.h.

139{if (val > 0.0) fail_low = true; else fail_low = false;}

◆ SetFailStuck()

void SetFailStuck ( double val )

inline

Definition at line 141 of file FGSensor.h.

141{if (val > 0.0) fail_stuck = true; else fail_stuck = false;}

◆ SetNoiseRandomSeed()

void SetNoiseRandomSeed ( int seed )

Definition at line 289 of file FGSensor.cpp.

{
  RandomSeed = sr;
  generator = std::make_shared<RandomNumberGenerator>(*RandomSeed);
}

Member Data Documentation

◆ bias

double bias

protected

Definition at line 159 of file FGSensor.h.

◆ bits

int bits

protected

Definition at line 171 of file FGSensor.h.

◆ ca

double ca

protected

Definition at line 166 of file FGSensor.h.

◆ cb

double cb

protected

lag filter coefficient "a"

Definition at line 167 of file FGSensor.h.

◆ divisions

int divisions

protected

Definition at line 173 of file FGSensor.h.

◆ drift

double drift

protected

Definition at line 162 of file FGSensor.h.

◆ drift_rate

double drift_rate

protected

Definition at line 161 of file FGSensor.h.

◆ fail_high

bool fail_high

protected

Definition at line 175 of file FGSensor.h.

◆ fail_low

bool fail_low

protected

Definition at line 174 of file FGSensor.h.

◆ fail_stuck

bool fail_stuck

protected

Definition at line 176 of file FGSensor.h.

◆ gain

double gain

protected

Definition at line 160 of file FGSensor.h.

◆ granularity

double granularity

protected

Definition at line 165 of file FGSensor.h.

◆ lag

double lag

protected

Definition at line 164 of file FGSensor.h.

◆ max

double max

protected

Definition at line 157 of file FGSensor.h.

◆ min

double min

protected

Definition at line 157 of file FGSensor.h.

◆ noise_type

int noise_type

protected

Definition at line 170 of file FGSensor.h.

◆ noise_variance

double noise_variance

protected

Definition at line 163 of file FGSensor.h.

◆ PreviousInput

double PreviousInput

protected

Definition at line 169 of file FGSensor.h.

◆ PreviousOutput

double PreviousOutput

protected

lag filter coefficient "b"

Definition at line 168 of file FGSensor.h.

◆ quant_property

std::string quant_property

protected

Definition at line 177 of file FGSensor.h.

◆ quantized

int quantized

protected

Definition at line 172 of file FGSensor.h.

◆ span

double span

protected

Definition at line 158 of file FGSensor.h.

The documentation for this class was generated from the following files:

Detailed Description

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Member Enumeration Documentation

◆ eDistributionType

◆ eNoiseType

Constructor & Destructor Documentation

◆ FGSensor()

◆ ~FGSensor()

Member Function Documentation

◆ Bias()

◆ bind()

◆ Drift()

◆ Gain()

◆ GetFailHigh()

◆ GetFailLow()

◆ GetFailStuck()

◆ GetNoiseRandomSeed()

◆ GetQuantized()

◆ Lag()

◆ Noise()

◆ ProcessSensorSignal()

◆ Quantize()

◆ ResetPastStates()

◆ Run()

◆ SetFailHigh()

◆ SetFailLow()

◆ SetFailStuck()

◆ SetNoiseRandomSeed()

Member Data Documentation

◆ bias

◆ bits

◆ ca

◆ cb

◆ divisions

◆ drift

◆ drift_rate

◆ fail_high

◆ fail_low

◆ fail_stuck

◆ gain

◆ granularity

◆ lag

◆ max

◆ min

◆ noise_type

◆ noise_variance

◆ PreviousInput

◆ PreviousOutput

◆ quant_property

◆ quantized

◆ span