Module: prescribedTrans

Executive Summary

This module profiles a PrescribedMotionMsgPayload message for a specified translational maneuver for a secondary rigid body connected to a rigid spacecraft hub at a hub-fixed location, \(\mathcal{M}\). The body frame for the prescribed body is designated by the frame \(\mathcal{F}\). Accordingly, the prescribed states for the secondary body are written with respect to the mount frame, \(\mathcal{M}\). The prescribed states are: r_FM_M, rPrime_FM_M, rPrimePrime_FM_M, omega_FM_F, omegaPrime_FM_F, and sigma_FM. Because this is a purely translational profiler, the states omega_FM_F, omegaPrime_FM_F, and sigma_FM are held constant in this module.

To use this module for prescribed motion purposes, it must be connected to the Module: prescribedMotionStateEffector dynamics module in order to profile the states of the secondary body. The required maneuver is determined from the user-specified scalar maximum acceleration \(a_{\text{max}}\), the mount frame axis for the translational motion, the prescribed body’s initial position vector with respect to the mount frame \(\boldsymbol{r}_{F/M}(t_0)\), and the reference position vector or the prescribed body with respect to the mount frame \(\boldsymbol{r}_{F/M} (\text{ref})\).

The maximum scalar acceleration is applied constant and positively for the first half of the maneuver and constant negatively for the second half of the maneuver. The resulting velocity of the prescribed body is linear, approaching a maximum magnitude halfway through the maneuver and ending with zero residual velocity. The corresponding translational trajectory the prescribed body moves through during the maneuver is parabolic in time.

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.

Module I/O Messages

Msg Variable Name	Msg Type	Description
prescribedTransInMsg	PrescribedTransMsgPayload	input msg with the prescribed body reference states
prescribedTransOutMsg	PrescribedTransMsgPayload	output message with the scalar prescribed body states
prescribedMotionOutMsg	PrescribedMotionMsgPayload	output message with the prescribed body states

Detailed Module Description

This translational motion flight software module is written to profile a rigid body’s motion with respect to a hub-fixed mount frame. The inputs to the profiler are the scalar maximum acceleration for the maneuver \(a_{\text{max}}\), the mount frame axis for the translational motion, the prescribed body’s initial position vector with respect to the mount frame \(\boldsymbol{r}_{F/M}(t_0)\), and the reference position vector or the prescribed body with respect to the mount frame \(\boldsymbol{r}_{F/M} (\text{ref})\). The magnitudes of the initial and final position vectors are denoted \(r_0\) and \(r_{\text{ref}}\), respectively. The prescribed body is assumed to be at rest at the beginning of the attitude maneuver.

Subtracting the initial position from the reference position vector gives the required relative position vector in the direction of translation:

\[\Delta \boldsymbol{r} = \boldsymbol{r}_{F/M}(\text{ref}) - \boldsymbol{r}_{F/M}(t_0)\]

The magnitude of the determined relative position vector gives the required translational distance \(\Delta r\). During the first half of the maneuver, the prescribed body is constantly accelerated with the given maximum acceleration. The prescribed body’s velocity increases linearly during the acceleration phase and reaches a maximum magnitude halfway through the maneuver.

The switch time, \(t_s\) is the simulation time halfway through the maneuver:

\[t_s = t_0 + \frac{\Delta t}{2}\]

The time required for the maneuver \(\Delta t\) is determined using the inputs to the profiler:

\[\Delta t = \sqrt{\frac{4 r_{\text{ref}} - 8 r_0}{\ddot{a}_{\text{max}}}}\]

The resulting trajectory of the position vector \(r = || \boldsymbol{r}_{F/M} ||_2\) magnitude during the first half of the maneuver is parabolic. The profiled motion is concave upwards if the reference position magnitude \(r_{\text{ref}}\) is greater than the initial position magnitude \(r_0\). If the converse is true, the profiled motion is instead concave downwards. The described motion during the first half of the maneuver is characterized by the expressions:

\[r^{''}_{F / M}(t) = a_{\text{max}}\]

\[r^{'}_{F / M}(t) = a_{\text{max}} (t - t_0)\]

\[r_{F / M}(t) = c_1 (t - t_0)^2 + r_0\]

where

\[c_1 = \frac{r_{\text{ref}} - r_0}{2(t_s - t_0)^2}\]

Similarly, the second half of the maneuver decelerates the prescribed body constantly until it reaches the desired position with zero velocity. The prescribed body velocity decreases linearly from its maximum magnitude back to zero. The trajectory during the second half of the maneuver is quadratic and concave downwards if the reference position magnitude is greater than the initial position magnitude. If the converse is true, the profiled motion is instead concave upwards. The described motion during the second half of the maneuver is characterized by the expressions:

\[r^{''}_{F / M}(t) = -a_{\text{max}}\]

\[r^{'}_{F / M}(t) = a_{\text{max}} (t - t_f)\]

\[r_{F / M}(t) = c_2 (t - t_f)^2 + r_{\text{ref}}\]

where

\[c_2 = \frac{r_{\text{ref}} - r_0}{2 (t_s - t_f)^2}\]

Module Testing

This unit test for this module ensures that the profiled translational maneuver is properly computed for a series of initial and reference positions and maximum accelerations. The final prescribed position magnitude r_FM_M_Final and velocity magnitude rPrime_FM_M_Final are compared with the reference values r_FM_M_Ref and rPrime_FM_M_Ref, respectively.

User Guide

The user-configurable inputs to the profiler are the scalar maximum acceleration for the maneuver \(a_{\text{max}}\), the mount frame axis for the translational motion, the prescribed body’s initial position vector with respect to the mount frame \(\boldsymbol{r}_{F/M}(t_0)\), and the reference position vector of the prescribed body with respect to the mount frame \(\boldsymbol{r}_{F/M} (\text{ref})\).

This module provides two output messages in the form of PrescribedTransMsgPayload and PrescribedMotionMsgPayload. The first guidance message, describing the prescribed body’s scalar states relative to the hub-fixed mount frame can be directly connected to a feedback control module. The second prescribed motion output message can be connected to the Module: prescribedMotionStateEffector dynamics module to directly profile a state effector’s translational motion.

This section is to outline the steps needed to setup a prescribed translational module in python using Basilisk.

1. Import the prescribedTrans class:

   from Basilisk.fswAlgorithms import prescribedTrans
   

2. Create an instantiation of a prescribed translational C module and the associated C++ container:

   PrescribedTransConfig = prescribedTrans.PrescribedTransConfig()
   PrescribedTransWrap = unitTestSim.setModelDataWrap(PrescribedTransConfig)
   PrescribedTransWrap.ModelTag = "prescribedTrans"
   

3. Define all of the configuration data associated with the module. For example:

   PrescribedTransConfig.transAxis_M = np.array([1.0, 0.0, 0.0])
   PrescribedTransConfig.scalarAccelMax = 0.01  # [m/s^2]
   PrescribedTransConfig.r_FM_M = np.array([0.0, 0.0, 0.0])
   PrescribedTransConfig.rPrime_FM_M = np.array([0.0, 0.0, 0.0])
   PrescribedTransConfig.rPrimePrime_FM_M = np.array([0.0, 0.0, 0.0])
   PrescribedTransConfig.omega_FM_F = np.array([0.0, 0.0, 0.0])
   PrescribedTransConfig.omegaPrime_FM_F = np.array([0.0, 0.0, 0.0])
   PrescribedTransConfig.sigma_FM = np.array([0.0, 0.0, 0.0])
   

The user is required to set the above configuration data parameters, as they are not initialized in the module.

1. Make sure to connect the required messages for this module.

2. Add the module to the task list:

   unitTestSim.AddModelToTask(unitTaskName, PrescribedTransWrap, PrescribedTransConfig)
   

---

Functions

void SelfInit_prescribedTrans(PrescribedTransConfig *configData, int64_t moduleID)

Import the module header file

Import other required files

This method initializes the output message for this module.

Parameters

• configData – The configuration data associated with this module

• moduleID – The module identifier

Returns

void

void Reset_prescribedTrans(PrescribedTransConfig *configData, uint64_t callTime, int64_t moduleID)

This method performs a complete reset of the module. Local module variables that retain time varying states between function calls are reset to their default values. This method also checks if the module input message is linked.

Parameters

• configData – The configuration data associated with the module

• callTime – [ns] Time the method is called

• moduleID – The module identifier

Returns

void

void Update_prescribedTrans(PrescribedTransConfig *configData, uint64_t callTime, int64_t moduleID)

This method uses the given initial and reference attitudes to compute the required attitude maneuver as a function of time. The profiled translational trajectory is updated in time and written to the module’s prescribed motion output message.

Parameters

• configData – The configuration data associated with the module

• callTime – [ns] Time the method is called

• moduleID – The module identifier

Returns

void

struct PrescribedTransConfig

#include <prescribedTrans.h>

Top level structure for the sub-module routines.

Public Members

double scalarAccelMax

[m/s^2] Maximum acceleration mag

double transAxis_M[3]

Axis along the direction of translation.

double r_FM_M[3]

[m] Position of the frame F origin with respect to the M frame origin expressed in M frame components

double rPrime_FM_M[3]

[m/s] B frame time derivative of r_FM_M expressed in M frame components

double rPrimePrime_FM_M[3]

[m/s^] B frame time derivative of rPrime_FM_M expressed in M frame components

double omega_FM_F[3]

[rad/s] Angular velocity of frame F with respect to frame M expressed in F frame components

double omegaPrime_FM_F[3]

[rad/s^2] B frame time derivative of omega_FM_F expressed in F frame components

double sigma_FM[3]

MRP attitude of frame F with respect to frame M.

bool convergence

Boolean variable is true when the maneuver is complete.

double tInit

[s] Simulation time at the start of the maneuver

double scalarPosInit

[m] Initial distance between the frame F and frame M origin

double scalarVelInit

[m/s] Initial velocity between the frame F and frame M origin

double scalarPosRef

[m] Magnitude of the reference position vector

double scalarVelRef

[m/s] Magnitude of the reference velocity vector

double ts

[s] Simulation time halfway through the maneuver

double tf

[s] Simulation time at the time the maneuver is complete

double a

Parabolic constant for the first half of the maneuver.

double b

Parabolic constant for the second half of the maneuver.

PrescribedTransMsg_C prescribedTransInMsg

Input message for the reference states.

PrescribedMotionMsg_C prescribedMotionOutMsg

Output message for the prescribed states.

BSKLogger *bskLogger

BSK Logging.