C++ Module: extForceTorque
Executive Summary
This module applies external forces and torque to a body. It can represent disturbances due to outgassing or thrusters, or directly apply requested control forces and torque.
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 |
|---|---|---|
cmdTorqueInMsg |
Optional body-frame torque command; defaults to zero until sampled. |
|
cmdForceBodyInMsg |
Optional body-frame force command; defaults to zero until sampled. |
|
cmdForceInertialInMsg |
Optional inertial-frame force command; defaults to zero until sampled. |
Initialization, Commands, and Reset
The configured extForce_N, extForce_B, and extTorquePntB_B vectors default to zero. All three cached
message commands also start at zero when the effector is constructed, so force evaluation is safe before
Reset() or UpdateState() runs. This applies both to hub attachment and to attachment to a state effector.
See Initialization and Configuration Validation for the general initialization contract.
Attachment alone is sufficient to apply configured static forces and torque. Add the effector to a task to
sample message commands through UpdateState(). For commands to be available to a spacecraft update, schedule
the command producer first, then this effector, then the spacecraft. Force evaluation adds each linked input’s
cached command to its corresponding configured vector; it does not read messages. A command written before
initialization therefore contributes zero until the first input-processing call. Between calls, the cached
command is held constant even if the input message changes. An unlinked input contributes zero.
Reset() clears the three cached commands and leaves the configured static force and torque vectors unchanged.
Repeated resets are safe and do not modify the parent’s integrated states. The next force evaluation uses the
cleared buffers; the next UpdateState() samples the linked messages again. Reset does not clear or consume
the input messages themselves.
Attaching to a State Effector
This effector supports the branching described in Advanced: Effector Module Branching, so its load can be carried by an appendage instead of the hub. Attach it to the parent state effector rather than to the spacecraft:
stateEff.addDynamicEffector(extFTObject, segment)
This effector reads no kinematics of its own, so the body frame force and torque it is given are
interpreted in the parent segment’s frame and the torque is applied about that segment’s frame
origin. An inertial frame force is unaffected by the choice of parent. The segment argument is
omitted for a parent with a single degree of freedom.
The spacecraft drives the parent state effector and its attached loads. Schedule this child effector when it needs to sample message commands, using the same ordering described above for hub attachment.
-
class ExtForceTorque : public SysModel, public DynamicEffector
- #include <extForceTorque.h>
External force and torque dynamic effector.
Public Functions
-
ExtForceTorque()
This is the constructor. It sets some default initializers that can be overridden by the user.
-
~ExtForceTorque()
The destructor. Nothing of note is performed here
-
void Reset(uint64_t CurrentSimNanos)
Clear cached message commands without changing configured static forces or torque.
Note
Repeated calls leave the command buffers at zero. Linked commands are sampled again by UpdateState().
- Parameters:
CurrentSimNanos – [in] [ns] Current simulation time.
-
void UpdateState(uint64_t CurrentSimNanos)
class method
Update the scheduled effector state.
- Parameters:
CurrentSimNanos – [in] [ns] Current simulation time.
-
void linkInStates(DynParamManager &statesIn)
class method
Link the required dynamics states.
- Parameters:
statesIn – [in] Dynamic parameter manager containing the required states.
-
void writeOutputMessages(uint64_t currentClock)
class method
This module does not write any output messages.
- Parameters:
currentClock – The current time used for time-stamping the message
-
void readInputMessages()
This method is used to read the incoming message and set the associated buffer structure.
-
void computeForceTorque(double integTime, double timeStep)
This method is used to compute the RHS forces and torques. Note: the module can set any of these three vectors, or a subset. Regarding the external force, the matrix representations in the body (B) and inertial (N) frame components are treated as 2 separate vectors. Only set both if you mean to, as both vectors will be included.
- Parameters:
integTime – [in] [s] Current integration time.
timeStep – [in] [s] Integration time step.
Public Members
-
BSKLogger bskLogger
BSK Logging.
-
ReadFunctor<CmdTorqueBodyMsgPayload> cmdTorqueInMsg
commanded torque input msg
-
ReadFunctor<CmdForceBodyMsgPayload> cmdForceBodyInMsg
commanded force input msg in B frame
-
ReadFunctor<CmdForceInertialMsgPayload> cmdForceInertialInMsg
commanded force input msg in N frame
Private Members
-
CmdTorqueBodyMsgPayload incomingCmdTorqueBuffer = {}
Cached torque command; zero until input processing.
-
CmdForceInertialMsgPayload incomingCmdForceInertialBuffer = {}
Cached inertial force command; zero until input processing.
-
CmdForceBodyMsgPayload incomingCmdForceBodyBuffer = {}
Cached body force command; zero until input processing.
-
ExtForceTorque()