 |
WarpTwin
Documentation for WarpTwin models and classes.
|
|
WarpTwin
Documentation for WarpTwin models and classes.
|
/******************************************************************************
* Copyright (c) ATTX INC 2025. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the
* proprietary and confidential information of ATTX, INC. The Software is
* furnished under a license agreement between ATTX and the user organization
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or
* transmitted in any form or by any means, for any purpose, without the express
* written permission of ATTX, INC.
******************************************************************************/
/*
GPS model header file
Author: James Tabony
*/
/*
Metadata for MS GUI:
imdata = {"displayname" : "GPS",
"exclude" : False,
"category" : "Sensors"
}
aliases = {"pos_bias_initial" : "Position Bias",
"vel_bias_initial" : "Velocity Bias",
"mount_frame" : "Spacecraft Body",
"mount_position__mf" : "Body Mount Position",
"rate_hz" : "Rate Hz",
"seed_value" : "EXCLUDE",
"earth_rotating_frame" : "Earth Rotating Frame",
"max_altitude" : "Max Altitude",
"min_altitude" : "EXCLUDE",
"max_speed" : "Max Speed",
"latency" : "EXCLUDE",
"pos_gaussian_noise" : "Position Noise",
"vel_gaussian_noise" : "Velocity Noise",
"pos_walking_bias_std" : "EXCLUDE",
"vel_walking_bias_std" : "EXCLUDE",
"meas_pos_GPS_PCR" : "Meas. Position (ECEF)",
"perfect_pos_GPS_PCR" : "EXCLUDE",
"perfect_accel_sf" : "EXCLUDE",
"meas_vel_GPS_PCR" : "Meas. Velocity (ECEF)",
"perfect_vel_GPS_PCR" : "EXCLUDE",
"longitude_detic" : "EXCLUDE",
"latitude_detic" : "EXCLUDE",
"altitude_detic" : "EXCLUDE",
"is_valid" : "Meas. Validity Flag",
"operational_power_draw" : "Operational Power Draw",
"mass" : "Mass",
"current_power_draw" : "Current Power Draw",
}
*/
#ifndef MODELS_SENSORS_GPS_H
#define MODELS_SENSORS_GPS_H
#include "simulation/Model.h"
#include "frames/Frame.h"
#include "models/support/MarkovUncertaintyModel.h"
#include "monitors/RateMonitor.h"
#include "models/states/FrameStateSensorModel.h"
#include "constants/unitutils.h"
#include "utils/LatencyUtil.hpp"
namespace warptwin {
/**
* @brief GPS Model
*
* This model simulates a simple GPS with bias and noise
* The model also includes black-out zones based on altitude and velocity.
*
* This model does not simulate a GPS receiver but instead simulates the GPS as a
* bought and configured component. Therefore it does not include clock bias drift
* and pseudoranging computations
*
* HOW DOES THIS GPS MODEL HANDLE NOISE:
* The standard deviations of the position measurement and the velocity measurement is
* treated separated because position is typically gathered from pseudoranging and velocity
* is typically gathered from Doppler shift measurements, so the two values are uncorrelated.
*
* The standard deviations are in the model inputs so that one could configure an external model
* or function that chooses the standard deviations based on temperature, time, radiation, or some
* other inmportant factor.
*
* TODO: Change planet_rotating_frame param to a planet ptr so that GPS can ouput relative to ECI and can work on planets other than Earth
*
* Author: James Tabony <james.tabony@attx.tech>
*/
/// @brief Sensor output struct for latency model, its members are the same as the model outputs. Its default constructor populates members with defualt output values
struct _gps_output_struct {
CartesianVector3 meas_pos_GPS_PCR;
CartesianVector3 meas_vel_GPS_PCR;
double longitude_detic;
double latitude_detic;
double altitude_detic;
bool is_valid;
// Default constuctor (should populate with model defualt outputs)
_gps_output_struct()
: meas_pos_GPS_PCR(CartesianVector3({0.0, 0.0, 0.0})),
meas_vel_GPS_PCR(CartesianVector3({0.0, 0.0, 0.0})),
longitude_detic(0.0),
latitude_detic(0.0),
altitude_detic(0.0),
is_valid(false) {}
// Custom constructor
_gps_output_struct(CartesianVector3 meas_pos_GPS_PCR, CartesianVector3 meas_vel_GPS_PCR, double longitude_detic, double latitude_detic, double altitude_detic, bool is_valid)
: meas_pos_GPS_PCR(meas_pos_GPS_PCR),
meas_vel_GPS_PCR(meas_vel_GPS_PCR),
longitude_detic(longitude_detic),
latitude_detic(latitude_detic),
altitude_detic(altitude_detic),
is_valid(is_valid) {}
};
MODEL(GPS)
public:
// Model params
// NAME TYPE DEFAULT VALUE
START_PARAMS
/** The initial bias in position measurement output described as a three-element vector in meters.
* Default is no bias. Must be set before model startup. */
SIGNAL(pos_bias_initial, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The initial bias in velocity measurement output described as a three-element vector in meters/second.
* Default is no bias. Must be set before model startup. */
SIGNAL(vel_bias_initial, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The vehicle frame relative to which the sensor is mounted and aligned. This is most
* typically the body frame of a spacecraft or other vehicle. mount_position__mf and mount_alignment_mf
* are described relative to this frame. */
SIGNAL(mount_frame, Frame*, nullptr)
/** The position of the sensor in the mount frame, represented in the default simulation
* unit (meters by default. pretty much always meters) */
SIGNAL(mount_position__mf, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The rate at which the sensor generates an output, in hertz. This value must be some
* positive (non-zero) integer. (Hz) */
SIGNAL(rate_hz, int, 0)
/** Value to seed the internal RNG for this model. */
SIGNAL(seed_value, int, 0)
/** The frame in which the GPS measurements are given relative to. This is the primary planets
* rotating frame (e.g. ECEF). For now, this must be Earth's rotating frame. */
SIGNAL(earth_rotating_frame, Frame*, nullptr)
/** Maximum altitude above the WGS84 ellipsoid that the GPS will work. Defaults to
* 18,000 meters, the maximum altitude set by CoCom for civilian GPS devices. (meters) */
SIGNAL(max_altitude, double, 18000.0)
/** Minimum altitude above the WGS84 ellipsoid that the GPS will work. (meters) */
SIGNAL(min_altitude, double, 0.0)
/** Maximum speed with respect to the rotating primary that the GPS will work.
* Defaults to 1900 km/hr, the maximum speed set by CoCom for civilian GPS devices. (meters/second) */
SIGNAL(max_speed, double, 1900.0*warpos::KM_TO_METERS/warpos::HOURS_TO_SECONDS)
/** Latency of the gps sensor, millisecond value for the amount of delay in sim time for
* the correct values to be reflected in the outputs. Must be set before executive startup.
* Defaults to no delay. (milliseconds) */
SIGNAL(latency, int, 0)
/** Power draw of the GPS. This value may or may not be the peak power draw provided by most
* data sheets. This value is the expected power draw of a sensor when operational. (Watts) */
SIGNAL(operational_power_draw, double, 0.0)
/** Mass of the GPS. (kg) */
SIGNAL(mass, double, 0.0)
END_PARAMS
// Model inputs
// NAME TYPE DEFAULT VALUE
START_INPUTS
/** The one-sigma Gaussian noise in position measurement output described as a three-element vector
* in meters. Default is no noise. */
SIGNAL(pos_gaussian_noise, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The one-sigma Gaussian noise in velocity measurement output described as a three-element vector
* in meters/second. Default is no noise. */
SIGNAL(vel_gaussian_noise, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The one-sigma Gaussian noise in the position bias drift described as a three-element vector
* in meters/sqrt(second). Default is no walking-bias drift. */
SIGNAL(pos_walking_bias_std, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The one-sigma Gaussian noise in the velocity bias drift described as a three-element vector
* in meters/second/sqrt(second). Default is no walking-bias drift. */
SIGNAL(vel_walking_bias_std, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
END_INPUTS
// Model outputs
// NAME TYPE DEFAULT VALUE
START_OUTPUTS
/** Output time tied to measurements. Output time is exactly the navigation time
* (see SimTimeManager for configuration), without latency (instantaneous) but
* but with a rate that mirrors output rate */
SIGNAL(output_time, clockwerk::Time, clockwerk::Time(0, 0))
/** The measured output position of the GPS sensor frame with respect to the PCR frame.
* This is not the position of the body but instead the position of the GPS sensor. This
* value includes noise, bias, and blackout-zones. */
SIGNAL(meas_pos_GPS_PCR, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The "perfect" output position of the GPS sensor with respect to the PCR frame.
* This is not the position of the body but instead the position of the GPS sensor. This
* value does not include noise, bias, or blackout-zones.
* This is an informational parameter and is not subject to latency. */
SIGNAL(perfect_pos_GPS_PCR, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The measured output velocity of the GPS sensor frame with respect to the PCR frame.
* This is not the velocity of the body but instead the velocity of the GPS sensor. This
* value includes noise, bias, and blackout-zones. */
SIGNAL(meas_vel_GPS_PCR, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The "perfect" output velocity of the GPS sensor frame with respect to the PCR frame.
* This is not the velocity of the body but instead the velocity of the GPS sensor. This
* value does not include noise, bias, or blackout-zones.
* This is an informational parameter and is not subject to latency. */
SIGNAL(perfect_vel_GPS_PCR, CartesianVector3, CartesianVector3({0.0, 0.0, 0.0}))
/** The detic longitude of the GPS sensor frame. Does include sensor noise, bias, and
* blackout-zones. (rad) */
SIGNAL(longitude_detic, double, 0.0)
/** The detic latitude of the GPS sensor frame. Does include sensor noise, bias, and
* blackout-zones. (rad) */
SIGNAL(latitude_detic, double, 0.0)
/** The detic altitude of the GPS sensor frame. Does include sensor noise, bias, and
* blackout-zones. (meters) */
SIGNAL(altitude_detic, double, 0.0)
/** Boolean value to notify if the output measurement is valid (i.e. boolean for
* blackout-zones). True = not in blackout-zone, False = in blackout-zone. */
SIGNAL(is_valid, bool, false)
/** Power draw of the sensor. This value is populated when the model is active, and zero
* when the model is deactive. Allows the user to create duty cycles and power budgets. (Watts) */
SIGNAL(current_power_draw, double, 0.0)
END_OUTPUTS
/// @brief Accessor for the sensor's frame
clockwerk::DataIO<Frame*> sensor_frame = clockwerk::DataIO<Frame*>(this, "sensor_frame", &_sensor_frame);
/// @brief Accessor for the internal rate monitor model
/// @return Pointer to the rate monitor model
warptwin::RateMonitor* rateMonitor() {return &_rate_monitor;}
/// @brief Accessor for the internal noise model
/// @return Pointer to the internal noise model
warptwin::MarkovUncertaintyModel* getNoiseModel() {return &_sensor_noise_model;}
int16 activate() override;
int16 deactivate() override;
protected:
int16 start() override;
int16 execute() override;
/// @brief Function to configure sensor -- runs in all constructors
void _configureInternal();
/// @brief The sensor frame in which all measurements will be taken
Frame _sensor_frame;
/// @brief The bias and noise model for sensor output
MarkovUncertaintyModel _sensor_noise_model;
/// @brief Rate monitor to control the rate at which the sensor runs
RateMonitor _rate_monitor;
/// @brief Frame state sensor model of the GPS frame relative to the PCR frame
FrameStateSensorModel _state_GPS_PCR;
/// @brief Truth altitude used for dead-zone determination
double _truth_altitude;
/// @brief Truth speed used for dead-zone determination
double _truth_speed;
/// @brief Dummy variables for ignoring unneeded function implicit returns
double _dummy;
/// @brief Internal variables for function implicit returns
double _output_lon, _output_lat, _output_alt;
/// @brief Internal variables for the previous bias of the position and velocity measurements
CartesianVector3 _previous_pos_bias, _previous_vel_bias;
/// @brief Internal variables for the perturbed position and velocity
CartesianVector3 _perturbed_pos, _perturbed_vel;
/// @brief Internal latency model, templated to the sensor output struct
LatencyUtil<_gps_output_struct> _latency_model;
/// @brief Temporary variable for the latest recorded output added to latency model and dummy output for stepping though latency
_gps_output_struct _last_output, _latency_return;
};
}
#endif
1.16.1