C++ Module: reactionWheelStateEffector
Executive Summary
Class that is used to implement an effector impacting a dynamic body that does not itself maintain a state or represent a changing component of the body (for example: gravity, thrusters, solar radiation pressure, etc.)
The module
PDF Description
contains further information on this module’s function,
how to run it, as well as testing.
Message Connection Descriptions
The following table lists all the module input and output messages. The module msg connection is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.
Msg Variable Name |
Msg Type |
Description |
|---|---|---|
rwMotorCmdInMsg |
(optional) RW motor torque array cmd input message. If not connected the motor torques are set to zero. |
|
rwSpeedOutMsg |
RW speed array output message. |
|
rwOutMsgs |
vector of RW log output messages. |
User Guide
The reaction wheel state effector module provides functionality for simulating reaction wheels in a spacecraft. It includes safety mechanisms to prevent numerical instability that can occur with excessive wheel acceleration or when using unlimited torque with small spacecraft inertia.
Initialization and Reset
When the attached spacecraft registers the effector states, the module initializes the wheel-speed and applicable
wheel-angle states. For each fully coupled jitter wheel, it also derives the center-of-mass offset d from
U_s / mass and sets the off-diagonal inertia J13 to U_d. This mandatory attachment path initializes the
dynamics configuration even when the reaction wheel state effector is not added to a simulation task.
The Reset() method refreshes these derived configuration values, initializes every wheel’s command entry to zero,
reports a warning when a Stribeck coefficient is zero, and clears the wheel-speed output buffer.
The wheel count cannot exceed MAX_EFF_CNT, because the effector
publishes a fixed-size wheel-speed array even when its motor-command input is unlinked. State registration, Reset(), command
reading, and wheel-speed publication reject excessive counts with BasiliskError before accessing the arrays.
Command storage is also sized during state registration and input reading, so it does not depend on a scheduled
Reset(). Direct calls to ConfigureRWRequests() may supply partial NewRWCmds vectors, but the vector
cannot exceed the wheel count.
Configure all wheels and their models before InitializeSimulation() registers their states. After registration,
addReactionWheel() raises BasiliskError without adding a device. The wheel count and the allocation of a
jitter-angle state to each wheel must remain unchanged. Changes through ReactionWheelData are rejected before
reset, command processing, output publication, or dynamics access, even when the effector is absent from the task.
The derived numRW and numRWJitter counts must not be edited. Reset() preserves the registered states;
use a new effector and simulation when changing the state layout. Calling Reset() before state registration
does not freeze the layout.
Threshold Parameters
The module includes two configurable threshold parameters:
maxWheelAcceleration: Maximum allowed wheel acceleration to prevent numerical instability. Default value is 1.0e6 rad/s^2.largeTorqueThreshold: Threshold for warning about large torque with unlimited torque setting. Default value is 10.0 Nm.
These parameters can be accessed and modified using the following getter and setter methods:
# Get the current maximum wheel acceleration threshold
current_max_accel = reactionWheelStateEffector.getMaxWheelAcceleration()
# Set a new maximum wheel acceleration threshold
reactionWheelStateEffector.setMaxWheelAcceleration(2.0e6) # rad/s^2
# Get the current large torque threshold
current_torque_threshold = reactionWheelStateEffector.getLargeTorqueThreshold()
# Set a new large torque threshold
reactionWheelStateEffector.setLargeTorqueThreshold(15.0) # Nm
-
class ReactionWheelStateEffector : public SysModel, public StateEffector
- #include <reactionWheelStateEffector.h>
reaction wheel state effector class
Public Functions
-
ReactionWheelStateEffector()
-
~ReactionWheelStateEffector()
-
void registerStates(DynParamManager &states)
Initialize the wheel configuration and register the effector dynamics states.
For fully coupled jitter wheels, this method derives the center-of-mass offset and off-diagonal inertia from the configured static and dynamic imbalance parameters. It then registers and initializes the wheel-speed states and, when required, the wheel-angle states.
- Parameters:
states – [inout] Dynamic parameter manager used to register states or properties.
-
void linkInStates(DynParamManager &states)
Link the required dynamics states.
- Parameters:
states – [in] Dynamic parameter manager containing the required states.
-
void writeOutputStateMessages(uint64_t integTimeNanos)
This method is here to write the output message structure into the specified message.
- Parameters:
integTimeNanos – The current time used for time-stamping the message
-
void computeDerivatives(double integTime, Eigen::Vector3d rDDot_BN_N, Eigen::Vector3d omegaDot_BN_B, Eigen::MRPd sigma_BN)
Compute the effector state derivatives.
- Parameters:
integTime – [in] [s] Current integration time.
rDDot_BN_N – [in] [m/s^2] Hub translational acceleration expressed in inertial-frame components.
omegaDot_BN_B – [in] [rad/s^2] Hub angular acceleration expressed in body-frame components.
sigma_BN – [in] Hub attitude relative to the inertial frame.
-
void updateEffectorMassProps(double integTime)
Method for stateEffector to give mass contributions.
Update the effector mass properties.
- Parameters:
integTime – [in] [s] Current integration time.
-
void updateContributions(double integTime, BackSubMatrices &backSubContr, Eigen::MRPd sigma_BN, Eigen::Vector3d omega_BN_B, Eigen::Vector3d g_N)
Back-sub contributions.
Update the effector Backsubstitution contributions.
- Parameters:
integTime – [in] [s] Current integration time.
backSubContr – [inout] Backsubstitution contributions.
sigma_BN – [in] Hub attitude relative to the inertial frame.
omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.
g_N – [in] [m/s^2] Gravitational acceleration expressed in inertial-frame components.
-
void updateEnergyMomContributions(double integTime, Eigen::Vector3d &rotAngMomPntCContr_B, double &rotEnergyContr, Eigen::Vector3d omega_BN_B)
Energy and momentum calculations.
Update the effector energy and momentum contributions.
- Parameters:
integTime – [in] [s] Current integration time.
rotAngMomPntCContr_B – [inout] [kg*m^2/s] Rotational angular momentum contribution.
rotEnergyContr – [inout] [J] Rotational energy contribution.
omega_BN_B – [in] [rad/s] Hub angular velocity expressed in body-frame components.
-
void Reset(uint64_t CurrentSimNanos)
Reset the reaction-wheel command and output buffers.
This method refreshes model-dependent derived wheel configuration values, initializes the command entry for each configured wheel, reports a zero Stribeck coefficient, and clears the wheel-speed output buffer.
- Parameters:
CurrentSimNanos – [in] [ns] Current simulation time.
Add a reaction-wheel configuration and its output message.
Note
Wheels can only be added before state registration.
- Parameters:
NewRW – [in] Reaction-wheel configuration to add.
-
void UpdateState(uint64_t CurrentSimNanos)
This method is the main cyclical call for the scheduled part of the RW dynamics model. It reads the current commands array and sets the RW configuration data based on that incoming command set. Note that the main dynamical method (ComputeDynamics()) is not called here and is intended to be called from the dynamics plant in the system
- Parameters:
CurrentSimNanos – The current simulation time in nanoseconds
-
void WriteOutputMessages(uint64_t CurrentClock)
This method is here to write the output message structure into the specified message.
- Parameters:
CurrentClock – The current time used for time-stamping the message
-
void ReadInputs()
This method is used to read the incoming command message and set the associated command structure for operating the RWs.
-
void ConfigureRWRequests(double CurrentTime)
This method is used to read the new commands vector and set the RW firings appropriately. It assumes that the ReadInputs method has already been run successfully.
- Parameters:
CurrentTime – The current simulation time converted to a double
-
inline double getMaxWheelAcceleration() const
Get the maximum wheel acceleration threshold.
- Returns:
Maximum wheel acceleration in rad/s^2
-
inline void setMaxWheelAcceleration(double val)
Set the maximum wheel acceleration threshold.
- Parameters:
val – New maximum wheel acceleration value in rad/s^2
-
inline double getLargeTorqueThreshold() const
Get the large torque threshold for unlimited torque warning.
- Returns:
Large torque threshold in Nm
-
inline void setLargeTorqueThreshold(double val)
Set the large torque threshold for unlimited torque warning.
- Parameters:
val – New large torque threshold value in Nm
Public Members
-
std::vector<std::shared_ptr<RWConfigPayload>> ReactionWheelData
RW information.
-
ReadFunctor<ArrayMotorTorqueMsgPayload> rwMotorCmdInMsg
RW motor torque array cmd input message.
-
Message<RWSpeedMsgPayload> rwSpeedOutMsg
RW speed array output message.
-
std::vector<Message<RWConfigLogMsgPayload>*> rwOutMsgs
vector of RW log output messages
-
std::vector<RWCmdMsgPayload> NewRWCmds
Incoming attitude commands.
-
RWSpeedMsgPayload rwSpeedMsgBuffer = {}
(-) Output data from the reaction wheels
-
std::string nameOfReactionWheelOmegasState
class variable
-
std::string nameOfReactionWheelThetasState
class variable
-
size_t numRW
number of reaction wheels
-
size_t numRWJitter
number of RW with jitter
-
BSKLogger bskLogger
BSK Logging.
Private Functions
-
void validateDimensions()
Validate the wheel count against command and speed message capacities.
Reject wheel arrays that cannot fit the command and speed payloads.
-
void validateRegisteredLayout()
Reject changes to the registered speed and angle state layout.
Reject state-layout changes without relying on live parent state pointers.
-
void initializeWheelConfiguration(RWConfigPayload &rw)
Initialize model-dependent derived reaction-wheel configuration values.
- Parameters:
rw – [inout] Reaction-wheel configuration to initialize.
Private Members
-
std::optional<std::vector<bool>> registeredWheelLayout
Per-wheel jitter-state allocation after registration.
-
ArrayMotorTorqueMsgPayload incomingCmdBuffer = {}
One-time allocation for savings.
-
uint64_t prevCommandTime
Time for previous valid thruster firing.
-
double maxWheelAcceleration = 1.0e6
[rad/s^2] Maximum allowed wheel acceleration to prevent numerical instability
-
double largeTorqueThreshold = 10.0
[Nm] Threshold for warning about large torque with unlimited torque setting
-
ReactionWheelStateEffector()