C Module: celestialTwoBodyPoint

Executive Summary

This module points one reference-frame axis towards a primary celestial object. The secondary goal is to point a second reference-frame axis as closely as possible towards another celestial object while maintaining the primary alignment.

For example, the reference can guide a sensor towards a planet while keeping a solar panel normal as close as possible to the Sun direction. 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 diagram and table list all the module input and output messages. The module message connection is set by the user from Python. The message 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
attRefOutMsg	AttRefMsgPayload	attitude reference output message
transNavInMsg	NavTransMsgPayload	spacecraft translation motion input message
celBodyInMsg	EphemerisMsgPayload	primary celestial body information input message
secCelBodyInMsg	EphemerisMsgPayload	(optional) secondary celestial body information

Module Assumptions and Limitations

The module sets the accelerations of both bodies relative to the spacecraft to zero. Its rate and acceleration outputs therefore describe the instantaneous reference motion under that assumption. Nonzero relative accelerations are not available in the input messages.

If the secondary message is absent, or its direction is within singularityThresh of parallel or antiparallel to the primary direction, the module uses the primary relative position crossed with its relative velocity as the secondary direction. This fallback requires a nonzero cross product; the primary relative position must also be nonzero.

Angular Velocity and Acceleration

The arrays r1_hat_N, r2_hat_N, and r3_hat_N contain the reference basis vectors in inertial N-frame components. Their first and second derivatives are inertial time derivatives, also expressed in N. The rows of dcm_RN are these basis vectors, so this matrix maps N-frame components to R-frame components.

Writing these component arrays as \(\boldsymbol q_i\), the reference-frame components of angular velocity and angular acceleration are

\[\begin{split}{}^R\boldsymbol\omega_{R/N} = \begin{bmatrix} \boldsymbol q_3 \cdot \dot{\boldsymbol q}_2 \\ \boldsymbol q_1 \cdot \dot{\boldsymbol q}_3 \\ \boldsymbol q_2 \cdot \dot{\boldsymbol q}_1 \end{bmatrix}, \qquad {}^R\dot{\boldsymbol\omega}_{R/N} = \begin{bmatrix} \dot{\boldsymbol q}_3 \cdot \dot{\boldsymbol q}_2 + \boldsymbol q_3 \cdot \ddot{\boldsymbol q}_2 \\ \dot{\boldsymbol q}_1 \cdot \dot{\boldsymbol q}_3 + \boldsymbol q_1 \cdot \ddot{\boldsymbol q}_3 \\ \dot{\boldsymbol q}_2 \cdot \dot{\boldsymbol q}_1 + \boldsymbol q_2 \cdot \ddot{\boldsymbol q}_1 \end{bmatrix}.\end{split}\]

Differentiating a projection onto a rotating basis also introduces \(\boldsymbol\omega_{R/N}\cdot\dot{\hat{\boldsymbol r}}_i\). This term vanishes because \(\dot{\hat{\boldsymbol r}}_i = \boldsymbol\omega_{R/N}\times\hat{\boldsymbol r}_i\). It must not be evaluated by dotting R-frame rate components with N-frame basis-vector derivatives.

Both outputs are transformed to N-frame components with the transpose:

\[{}^N\boldsymbol\omega_{R/N} = [RN]^T\,{}^R\boldsymbol\omega_{R/N}, \qquad {}^N\dot{\boldsymbol\omega}_{R/N} = [RN]^T\,{}^R\dot{\boldsymbol\omega}_{R/N}.\]

These are the omega_RN_N and domega_RN_N fields of attRefOutMsg.

Validation

In addition to the single-body and two-body reference checks, the unit tests use central finite differences along straight-line body trajectories. They differentiate the published attitude basis to check the angular rate and the published rate to check angular acceleration. The cases cover a moving secondary body and the absent, parallel, and antiparallel secondary-direction fallbacks at two sample times. A 0.1 s difference step is used with absolute tolerances of \(10^{-11}\) rad/s for rate and \(10^{-13}\) rad/s² for acceleration.

Functions

void SelfInit_celestialTwoBodyPoint(celestialTwoBodyPointConfig *configData, int64_t moduleID)

This method initializes the configData for the nominal delta-V maneuver guidance. It checks to ensure that the inputs are sane and then creates the output message

Parameters:

configData – The configuration data associated with the celestial body guidance
moduleID – The ID associated with the configData

void Update_celestialTwoBodyPoint(celestialTwoBodyPointConfig *configData, uint64_t callTime, int64_t moduleID)

This method takes the spacecraft and points a specified axis at a named celestial body specified in the configuration data. It generates the commanded attitude and assumes that the control errors are computed downstream.

Parameters:

configData – The configuration data associated with the celestial body guidance
callTime – The clock time at which the function was called (nanoseconds)
moduleID – The ID associated with the configData

void Reset_celestialTwoBodyPoint(celestialTwoBodyPointConfig *configData, uint64_t callTime, int64_t moduleID)

void parseInputMessages(celestialTwoBodyPointConfig *configData, int64_t moduleID)

This method takes the navigation translational info as well as the spice data of the primary celestial body and, if applicable, the second one, and computes the relative state vectors necessary to create the restricted 2-body pointing reference frame.

Parameters:

configData – The configuration data associated with the celestial body guidance
moduleID – The ID associated with the configData

void computeCelestialTwoBodyPoint(celestialTwoBodyPointConfig *configData, uint64_t callTime)

This method takes the spacecraft and points a specified axis at a named celestial body specified in the configuration data. It generates the commanded attitude and assumes that the control errors are computed downstream.

Parameters:

configData – The configuration data associated with the celestial body guidance
callTime – The clock time at which the function was called (nanoseconds)

struct celestialTwoBodyPointConfig

#include <celestialTwoBodyPoint.h>

Data structure for module to compute the two-body celestial pointing navigation solution.

Public Members

double singularityThresh: (r) Threshold for when to fix constraint axis*‍/

double R_P1B_N[3]: [m] planet 1 position vector relative to inertial frame, in N-frame components

double R_P2B_N[3]: [m] planet 2 position vector relative to inertial frame, in N-frame components

double v_P1B_N[3]: [m/s] planet 1 velocity vector relative to inertial frame, in N-frame components

double v_P2B_N[3]: [m/s] planet 2 velocity vector relative to inertial frame, in N-frame components

double a_P1B_N[3]: [m/s^2] planet 1 acceleration vector relative to inertial frame, in N-frame components

double a_P2B_N[3]: [m/s^2] planet 2 acceleration vector relative to inertial frame, in N-frame components

AttRefMsg_C attRefOutMsg: The name of the output message*‍/.

EphemerisMsg_C celBodyInMsg: The name of the celestial body message*‍/.

EphemerisMsg_C secCelBodyInMsg: The name of the secondary body to constrain point*‍/.

NavTransMsg_C transNavInMsg: The name of the incoming attitude command*‍/.

int secCelBodyIsLinked: flag to indicate if the optional 2nd celestial body message is linked

AttRefMsgPayload attRefOut: (-) copy of output reference frame message

BSKLogger *bskLogger: BSK Logging.