Module: hillStateConverter

Executive Summary

This module converts two inertial spacecraft positions into a Hill-frame relative position and velocity.

Message Connection Descriptions

Module I/O Messages

Msg Variable Name

Msg Type




Chief inertial state navigation message used as basis for Hill frame definition



Deputy inertial state navigation message.



Relative position message of deputy w.r.t. chief in Hill-frame coordinates.

Detailed Module Description

This module converts a pair of spacecraft inertial positions into a relative position and velocity represented in the chief spacecraft’s hill frame.

The Hill frame relative position and velocity of the deputy spacecraft is returned in a HillRelStateMsgPayload.

The chief Hill frame is computed from the Chief navigation message by first calculating the radial and orbit angular momentum unit vectors:

\[\hat{h}_r = \frac{r}{|r|}\]
\[\hat{h}_h = \frac{r \times v}{|r \times v|}\]

These unit vectors are used to compute the final direction used to define the frame via the cross product:

\[\hat{h}_v = \hat{h}_h \times \hat{h}_r\]

Finally, these unit vectors are composed into a DCM that rotates from the inertial to Hill frames:

\[[HN] = \{\hat{h}_r, \hat{h}_v, \hat{h}_h\}\]

The relative position is computed using the difference of the inertial deputy and chief positions and this DCM:

\[\rho = [HN](r_{dep} - r_{chief})\]

To compute the relative velocities, the transport theorem is additionally used due to the rotating nature of the Hill frame:

\[\dot{\rho} = [HN](\dot{r}_{dep} - \dot{r}_{chief}) + (\omega_{HN} \times (\dot{r}_{dep} - \dot{r}_{chief}))\]

Module Assumptions and Limitations

This module makes use of the rv2hill function provided by the orbitalMotion library included with BSK, which works for arbitrary orbit geometries (i.e., it does not assume circular orbits in calculating the velocity transformation). As a result, it is broadly applicable to computing relative orbit states.

User Guide

This module is configured as a message transformer and has no user-settable parameters aside from the message inputs and outputs.

A simple example of this module’s initialization alongside a recorder to store the relative state information is provided here:

.. code-block:: python
    hillStateNavData = hillStateConverter.HillStateConverterConfig()
    hillStateNavWrap = sim.setModelDataWrap(hillStateNavData)
    hillStateNavWrap.ModelTag = "dep_hillStateNav"
    hillRecorder = hillStateNavData.hillStateOutMsg.recorder()

In addition, this module is used in the example script scenarioDragRendezvous as an input to the Module: hillToAttRef module.


void SelfInit_hillStateConverter(HillStateConverterConfig *configData, int64_t moduleID)

This method initializes the module’s hillStateOutMsg.

  • configData – The configuration data associated with this module

  • moduleID – The module identifier



void Update_hillStateConverter(HillStateConverterConfig *configData, uint64_t callTime, int64_t moduleID)

Computes the relative state of the deputy vs the chief in chief Hill-frame coordinates and writes an output message.

  • configData – The configuration data associated with the module

  • callTime – The clock time at which the function was called (nanoseconds)

  • moduleID – The module identifier



void Reset_hillStateConverter(HillStateConverterConfig *configData, uint64_t callTime, int64_t moduleID)

This message checks to see that both of the input translational state messages were connected; if not, it errors.

  • configData – The configuration data associated with the module

  • callTime – [ns] time the method is called

  • moduleID – The module identifier



struct HillStateConverterConfig
#include <hillStateConverter.h>

Top level structure for the sub-module routines.

Public Members

HillRelStateMsg_C hillStateOutMsg

Output message containing relative state of deputy to chief in chief hill coordinates.

NavTransMsg_C chiefStateInMsg

Input message containing chief inertial translational state estimate.

NavTransMsg_C depStateInMsg

Input message containing deputy inertial translational state estimate.

BSKLogger *bskLogger

BSK Logging.