Module: hillFrameRelativeControl

Executive Summary

This module computes an inertial control force command for deputy spacecraft relative motion using a Hill-frame proportional-derivative (PD) law with additional feedforward compensation terms. The chief translational navigation input is NavTransMsgPayload, which matches the output type of simpleNav.transOutMsg.

Relative Hill-frame position and velocity can be supplied either directly via HillRelStateMsgPayload (for example from hillStateConverter) or computed internally from deputy inertial state. Exactly one of these input paths must be connected. The controller evaluates tracking error against user-provided Hill-frame references and maps the commanded acceleration back to inertial-frame force using deputy mass.

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

chiefTransInMsg

NavTransMsgPayload

chief translational navigation input message

hillStateInMsg

HillRelStateMsgPayload

deputy-relative-to-chief Hill-frame state input message (exclusive with deputyTransInMsg)

deputyTransInMsg

NavTransMsgPayload

deputy translational navigation input message (exclusive with hillStateInMsg)

deputyVehicleConfigInMsg

VehicleConfigMsgPayload

deputy mass configuration input message

forceOutMsg

CmdForceInertialMsgPayload

inertial-frame force command output message

forceOutMsgC

CmdForceInertialMsgPayload

C-wrapped inertial-frame force command output message

Detailed Module Description

Let \(\mathbf{r}_{rel,H}\) and \(\mathbf{v}_{rel,H}\) be deputy-relative-to-chief position and velocity in the chief Hill frame. Let \(\mathbf{r}_{ref,H}\) and \(\mathbf{v}_{ref,H}\) be the desired Hill-frame references. The command acceleration includes PD feedback plus feedforward compensation \(-(A_1\mathbf{r}_{rel,H} + A_2\mathbf{v}_{rel,H})\).

\[\mathbf{a}_{cmd,H} = -A_1\mathbf{r}_{rel,H} - A_2\mathbf{v}_{rel,H} -\mathbf{K}(\mathbf{r}_{rel,H}-\mathbf{r}_{ref,H}) -\mathbf{P}(\mathbf{v}_{rel,H}-\mathbf{v}_{ref,H}).\]

where

\[\begin{split}A_1 = \begin{bmatrix} 2\mu/R^3 + \dot{\theta}^2 & \ddot{\theta} & 0 \\ -\ddot{\theta} & \dot{\theta}^2 - \mu/R^3 & 0 \\ 0 & 0 & -\mu/R^3 \end{bmatrix}, \qquad A_2 = \begin{bmatrix} 0 & 2\dot{\theta} & 0 \\ -2\dot{\theta} & 0 & 0 \\ 0 & 0 & 0 \end{bmatrix}.\end{split}\]

Here, \(R\) is chief radius magnitude, \(\theta\) is chief true latitude, \(\mu\) is central-body gravitational parameter, and overdots denote time derivatives.

This formulation follows Schaub and Junkins, Analytical Mechanics of Space Systems.

The inertial command force is

\[\mathbf{F}_{cmd,N} = m_d \mathbf{C}_{NH}\mathbf{a}_{cmd,H},\]

with \(m_d\) the deputy mass from VehicleConfigMsgPayload.

Model Assumptions and Limitations

  • Deputy mass from deputyVehicleConfigInMsg.massSC must be positive.

  • mu must be set to a positive value using setMu.

  • K and P must be set before simulation start using setK and setP.

  • Exactly one of hillStateInMsg or deputyTransInMsg must be connected.

  • Chief radius and angular momentum vectors must be non-zero.

  • Gains are full 3x3 matrices in Hill frame and must be symmetric positive definite.

User Guide

The module is created in Python using:

1from Basilisk.fswAlgorithms import hillFrameRelativeControl
2
3ctrl = hillFrameRelativeControl.HillFrameRelativeControl()
4ctrl.ModelTag = "hillFrameRelativeControl"

Then connect messages for one of the following two modes:

  1. direct deputy navigation input mode

1ctrl.chiefTransInMsg.subscribeTo(chiefSimpleNav.transOutMsg)
2ctrl.deputyTransInMsg.subscribeTo(deputySimpleNav.transOutMsg)
3ctrl.deputyVehicleConfigInMsg.subscribeTo(vehicleConfigMsg)

  1. precomputed Hill-state input mode

1from Basilisk.fswAlgorithms import hillStateConverter
2
3hillConv = hillStateConverter.hillStateConverter()
4hillConv.chiefStateInMsg.subscribeTo(chiefSimpleNav.transOutMsg)
5hillConv.depStateInMsg.subscribeTo(deputySimpleNav.transOutMsg)
6
7ctrl.chiefTransInMsg.subscribeTo(chiefSimpleNav.transOutMsg)
8ctrl.hillStateInMsg.subscribeTo(hillConv.hillStateOutMsg)
9ctrl.deputyVehicleConfigInMsg.subscribeTo(vehicleConfigMsg)

Configure gains, references and gravitational parameter:

1ctrl.setMu(3.986004418e14)  # [m^3/s^2]
2ctrl.setK([2e-6, 0.0, 0.0, 0.0, 2e-6, 0.0, 0.0, 0.0, 2e-6])  # [1/s^2]
3ctrl.setP([2e-3, 0.0, 0.0, 0.0, 2e-3, 0.0, 0.0, 0.0, 2e-3])  # [1/s]
4ctrl.setReferencePosition([100.0, 0.0, 0.0])  # [m]
5ctrl.setReferenceVelocity([0.0, 0.0, 0.0])  # [m/s]
class HillFrameRelativeControl : public SysModel
#include <hillFrameRelativeControl.h>

Computes an inertial control force command from Hill-frame relative position and velocity errors.

Public Functions

HillFrameRelativeControl()

Constructor.

This is the constructor for the module class. It sets default variable values.

~HillFrameRelativeControl()

Destructor.

Module Destructor

void Reset(uint64_t currentSimNanos) override

Reset module and validate required input message wiring.

This method is used to reset the module and checks that required input messages are connected.

Parameters:

currentSimNanos – [ns] Current simulation time

void UpdateState(uint64_t currentSimNanos) override

Read messages, compute command, and write output.

This is the main method that gets called every time the module is updated.

Parameters:

currentSimNanos – [ns] Current simulation time

void SelfInit() override

Initialize C-wrapped output messages.

This method self initializes the C-wrapped output message.

void setK(const std::vector<double> &gain)

Set Hill-frame position feedback gain matrix.

Sets the position feedback gain matrix.

Parameters:

gain – [1/s^2] Position-error gain matrix in row-major order (length 9)

void setP(const std::vector<double> &gain)

Set Hill-frame velocity feedback gain matrix.

Sets the velocity feedback gain matrix.

Parameters:

gain – [1/s] Velocity-error gain matrix in row-major order (length 9)

void setReferencePosition(const std::vector<double> &rRef_H)

Set Hill-frame relative position reference.

Sets the Hill-frame relative position reference.

Parameters:

rRef_H – [m] Relative-position reference vector in Hill frame

void setReferenceVelocity(const std::vector<double> &vRef_H)

Set Hill-frame relative velocity reference.

Sets the Hill-frame relative velocity reference.

Parameters:

vRef_H – [m/s] Relative-velocity reference vector in Hill frame

void setMu(double mu)

Set central-body gravitational parameter.

Parameters:

mu – [m^3/s^2] Gravitational parameter used in A1 feedforward dynamics

std::vector<double> getK() const

Get Hill-frame position feedback gain matrix.

Returns:

[1/s^2] Position-error gain matrix in row-major order

std::vector<double> getP() const

Get Hill-frame velocity feedback gain matrix.

Returns:

[1/s] Velocity-error gain matrix in row-major order

std::vector<double> getReferencePosition() const

Get Hill-frame relative position reference.

Returns:

[m] Relative-position reference vector in Hill frame

std::vector<double> getReferenceVelocity() const

Get Hill-frame relative velocity reference.

Returns:

[m/s] Relative-velocity reference vector in Hill frame

double getMu() const

Get central-body gravitational parameter.

Returns:

[m^3/s^2] Gravitational parameter

Public Members

ReadFunctor<NavTransMsgPayload> chiefTransInMsg

chief translational nav input message

ReadFunctor<HillRelStateMsgPayload> hillStateInMsg

optional deputy-relative-to-chief Hill-frame state input message

ReadFunctor<NavTransMsgPayload> deputyTransInMsg

optional deputy translational nav input message (exclusive with hillStateInMsg)

ReadFunctor<VehicleConfigMsgPayload> deputyVehicleConfigInMsg

deputy mass configuration input message

Message<CmdForceInertialMsgPayload> forceOutMsg

inertial force command output message

CmdForceInertialMsg_C forceOutMsgC = {}

C-wrapped inertial force command output message.

BSKLogger bskLogger

BSK logging object.

Private Functions

void readMessages()

Read all subscribed input messages into local buffers.

Reads the input messages

void computeForceCommand()

Compute inertial force command from Hill-frame tracking errors.

Computes the inertial force command from Hill-frame relative-state tracking errors.

void writeMessages(uint64_t currentSimNanos)

Write inertial force command output message.

Writes the output message

Parameters:

currentSimNanos – [ns] Current simulation time

Private Members

NavTransMsgPayload chiefNavBuffer

chief nav input message buffer

HillRelStateMsgPayload hillStateBuffer

Hill relative state input message buffer.

NavTransMsgPayload deputyNavBuffer

deputy nav input message buffer

VehicleConfigMsgPayload deputyVehicleBuffer

deputy vehicle config buffer

double K[3][3] = {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}}

Hill-frame position feedback gain matrix [1/s^2].

double P[3][3] = {{0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}, {0.0, 0.0, 0.0}}

Hill-frame velocity feedback gain matrix [1/s].

bool setKFlag = false

flag to check if K has been set

bool setPFlag = false

flag to check if P has been set

std::array<double, 3> rRef_H = {0.0, 0.0, 0.0}

reference Hill-frame relative position [m]

std::array<double, 3> vRef_H = {0.0, 0.0, 0.0}

reference Hill-frame relative velocity [m/s]

double mu = 0.0

[m^3/s^2] gravitational parameter used in feedforward dynamics

double forceCmd_N[3] = {0.0, 0.0, 0.0}

commanded force in inertial frame [N]