 |
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.
******************************************************************************/
/*
Radio Model header file
Author: Alex Jackson
*/
/*
Metadata for MS GUI:
imdata = {"displayname" : "Radio Model",
"exclude" : False,
"category" : "Assemblies"
}
aliases = {"frequency" : "Frequency (Hz)",
"bandwidth" : "Bandwidth (Hz)",
"bit_rate" : "Bit Rate (bps)",
"power_TX" : "Transmit Power (W)",
"gain_TX" : "Transmit Gain (dBi)",
"loss_TX" : "Transmit Loss (dB)",
"gain_RX" : "Receive Gain (dBi)",
"loss_RX" : "Receive Loss (dB)",
"noise_temperature" : "System Noise Temperature (K)",
"cross_pol_loss" : "Cross Polarization Loss (dB)",
"ebno_required" : "Eb/N0 Required (dB)",
"power_draw_TX" : "Transmit Power Draw (W)",
"power_draw_RX" : "Receive Power Draw (W)",
"other_radio" : "Other Radio Model",
"frame" : "Radio's Frame",
"transmitting" : "Transmitting (1 = yes, 0 = no, -1 = auto)",
"masked" : "Masked (false = visible)",
"free_space_path_loss" : "EXCLUDE",
"tx_eff_isotropic_radiated_pwr" : "EXCLUDE",
"tx_power_RX" : "EXCLUDE",
"tx_system_noise_figure" : "EXCLUDE",
"tx_signal_to_noise_ratio" : "Signal to Noise Ratio (dB)",
"tx_ebno_received" : "Eb/N0 Received (dB)",
"tx_link_margin" : "Link Margin (dB)",
"rx_eff_isotropic_radiated_pwr" : "EXCLUDE",
"rx_power_RX" : "EXCLUDE",
"rx_system_noise_figure" : "EXCLUDE",
"rx_signal_to_noise_ratio" : "Signal to Noise Ratio (dB)",
"rx_ebno_received" : "Eb/N0 Received (dB)",
"rx_link_margin" : "Link Margin (dB)",
"power_draw" : "Power Draw (W)",
}
*/
#ifndef MODELS_COMMUNICATIONS_RADIO_MODEL_H
#define MODELS_COMMUNICATIONS_RADIO_MODEL_H
#include "simulation/Model.h"
#include "SimpleComAnalysisModel.h"
#include "models/states/FrameStateSensorModel.h"
namespace warptwin {
/**
* @brief Model of spacecraft radio including losses and gains with comm links and power draw
*
* This model is used to calculate the communications link and power draw of a
* radio system. It is meant to be configured in pairs. All the parameters are referring to the
* characteristics of this radio. First, define all of the attributes of this radio model and pass
* in another radio model with its own configuration as a parameter. The the output of this
* model uses simple communication analysis to calculate the comms data based on the relationship
* between the two radios. For example, you could have one radio model attached to a ground
* station and another representing a spacecraft. You assign the transmit and receive
* characteristics in each radio model and then set the other_radio parameter to point to the
* other model. The model will then output information about the link in both the receive and
* transmit direction from the point of view of this radio. The output from each radio will be
* identical except from the perspective of the radio. This means to analyze the full link
* between the two, you only need the output of one of the models.
*
* This model also calculates the power draw of the radio based on whether it is transmitting or
* receiving. If the radio is transmitting,the power draw output will be the power_draw_TX
* parameter, and if it is receiving, the power draw output will be the power_draw_RX parameter.
*
* IMPORTANT: Though loss is generally expressed as a negative gain, this model assumes that loses
* are positive and will subtract accordingly. For example, suppose your receiver system has poor
* circuitry and you expect the power received to decrease by half. This would be a gain of -3 dB,
* however this model expects the user to input a loss of positive 3 dB. In general, loss = -gain.
*
* Author: Alex Jackson <alex.jackson@attx.tech>
*/
MODEL(RadioModel)
public:
// Model params
// NAME TYPE DEFAULT VALUE
START_PARAMS
/** The transmitter carrier frequency in hertz (Hz) (MUST MATCH OTHER RADIO). Default is
* the amateur radio satellite communication frequency of 437 MHz. */
SIGNAL(frequency, double, 437e6)
/** The bandwidth of transmission (Hz) 50 kHz is common for UHF
* (MUST MATCH OTHER RADIO)*/
SIGNAL(bandwidth, double, 50e3)
/** The bit rate in bits per second (bps) 9600bps is a common value for UHF
* (MUST MATCH OTHER RADIO)*/
SIGNAL(bit_rate, double, 9600.0)
/** The transmit power in Watts (W). Transmit power is usually around 1 Watt for cubesats */
SIGNAL(power_TX, double, 1.0)
/** Return loss of this radio when transmitting, this value describes ratio of power
* that is reflected back into the system. Should be input as positive
* but is normally negative. Default is a representative value of 14 dB */
SIGNAL(return_loss, double, 14.0)
/** The transmit antenna gain in decibels relative to isotropic (dBi) Default is 2.15
* representative of a dipole */
SIGNAL(gain_TX, double, 2.15)
/** The total transmit system loss in decibels (dB). This is the accumulation
* of transmitter pointing loss, and transmitter circuit loss. Inputting zero
* assumes that there is no return loss (despite this actually being 100% return
* loss). 5 db is a conservative estimate for typical satellite systems */
SIGNAL(loss_TX, double, 5.0)
/** The receive antenna gain in decibels relative to isotropic (dBi). Usually the
* same as the transmit antenna gain unless there is a separate receive antenna. */
SIGNAL(gain_RX, double, 2.15)
/** The noise temperature in Kelvin (K). This value is realted to the
* system noise density by Boltzmann*noise_temp and system noise power
* by the equation band_width*noise_density. Generic input of 307.5 should be replaced by
* data sheet value(MUST MATCH OTHER RADIO)*/
SIGNAL(noise_temperature, double, 307.5)
/** The total receive system loss in decibels (dB). This is the accumulation
* of receiver side loss such as pointing loss, radome loss, polarization loss,
* and atmospheric loss. 4 db is a conservative estimate for typical satellite systems */
SIGNAL(loss_RX, double, 4.0)
/** The cross polarization loss in decibels (dB). General rule of thumb,
* if both RX and TX have same-hand circular or linear (0dB), if there
* is a circular to linear match (3dB), but a right vs left circular
* mismatch can result in 20 to 30 dB loss. (MUST MATCH OTHER RADIO)*/
SIGNAL(cross_pol_loss, double, 0.0)
/** The energy per bit to noise ratio required in dB. Based on various
* modulation schemes for a desired bit error rate. For BPSK an Eb/N0
* required of about 11 allows for a bit error rate around 1e-6.
* (MUST MATCH OTHER RADIO)*/
SIGNAL(ebno_required, double, 11.0)
/** The power draw of the radio when transmitting in Watts (W) Note that this is
* different from the transmit power. Default is no power draw*/
SIGNAL(power_draw_TX, double, 0.0)
/** The power draw of the radio when receiving in Watts (W). Default is no power draw */
SIGNAL(power_draw_RX, double, 0.0)
/** A pointer to the other radio model to which this radio is communicating */
SIGNAL(other_radio, GraphTreeObject*, nullptr)
/** The frame that the radio is attached to. Used to calculate range */
SIGNAL(frame, Frame*, nullptr)
END_PARAMS
// Model inputs
// NAME TYPE DEFAULT VALUE
START_INPUTS
/** This is the mask flag for the ground station. True for masked, False for visible */
SIGNAL(masked, bool, true)
/** An int to indicate if the radio is transmitting. The power draw is set to the
* TX power draw if greater than 0 and RX power draw if equal to 0. If this is less
* than zero it is set to the opposite of the masked flag (constantly transmitting when
* in view) */
SIGNAL(transmitting, int, -1)
END_INPUTS
// Model outputs
// NAME TYPE DEFAULT VALUE
START_OUTPUTS
/** The free space path loss in decibels (FSPL) (dB). This is the same in
* both directions */
SIGNAL(free_space_path_loss, double, 0.0)
/** The effective isotropic radiated power (EIRP) in decibel-milliWatts (dBm) */
SIGNAL(tx_eff_isotropic_radiated_pwr, double, 0.0)
/** The receive power in decibel-milliWatts (dBm) */
SIGNAL(tx_power_RX, double, 0.0)
/** The system noise figure (NF) in decibel-milliWatts/Hz (dBm/Hz) */
SIGNAL(tx_system_noise_figure, double, 0.0)
/** The signal-to-noise density ratio (SNR) in decibel (dB) */
SIGNAL(tx_signal_to_noise_ratio, double, 0.0)
/** The energy per bit to noise ratio in in decibels (dB) */
SIGNAL(tx_ebno_received, double, 0.0)
/** The link margin in decibels (dB) */
SIGNAL(tx_link_margin, double, 0.0)
/** The effective isotropic radiated power (EIRP) in decibel-milliWatts (dBm) */
SIGNAL(rx_eff_isotropic_radiated_pwr, double, 0.0)
/** The receive power in decibel-milliWatts (dBm) */
SIGNAL(rx_power_RX, double, 0.0)
/** The system noise figure (NF) in decibel-milliWatts/Hz (dBm/Hz) */
SIGNAL(rx_system_noise_figure, double, 0.0)
/** The signal-to-noise density ratio (SNR) in decibel (dB) */
SIGNAL(rx_signal_to_noise_ratio, double, 0.0)
/** The energy per bit to noise ratio in in decibels (dB) */
SIGNAL(rx_ebno_received, double, 0.0)
/** The link margin in decibels (dB) */
SIGNAL(rx_link_margin, double, 0.0)
/** The power draw of the radio in Watts (W) */
SIGNAL(power_draw, double, 0.0)
END_OUTPUTS
protected:
int16 start() override;
int16 execute() override;
// The simple com analysis models that this model uses to compute comms data
SimpleComAnalysisModel _tx_com_analysis_model;
SimpleComAnalysisModel _rx_com_analysis_model;
// The frame state sensor used to get range data for the com analysis models
FrameStateSensorModel _fss;
};
}
#endif
1.16.1