Module: waypointReference

Executive Summary

Module that reads the reorientation maneuver of a spacecraft from a text file, likely created outside of Basilisk, and outputs an Attitude Reference Message. This module makes it possible to reproduce on Basilisk attitude orientation maneuvers computed externally. The module outputs an Attitude Reference Message that follows the sequence of waypoints contained in the text file. The text file must be formatted appropriately for the module to be able to read the information correctly: see Module Assumptions and Limitaions for a detailed explanation on how to do this.

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




Output Attitude Reference Message.

Module Assumptions and Limitations

The module assumes that the text file is written in a compatible form, which means that each piece of information must be provided in the correct order. Each line of text should contain information relative to one and only one waypoint along the maneuver: such information must be in the following order: time, attitude parameters, angular rates, angular acceleration. There must be a delimiter between each piece of information and the next one, as well al between different elements of the same piece of information (for example between consecutive entries of the 3-dimensional angular rate vector). Using MRP to represent the attitude \(\sigma_{\mathcal{R/N}}=[\sigma_1, \sigma_2, \sigma_3]\), expressing angular rates \({}^{\mathcal{N}}\omega_{\mathcal{R/N}}=[\omega_1, \omega_2, \omega_3]\) and accelerations \({}^{\mathcal{N}}\dot{\omega}_{\mathcal{R/N}}=[\dot{\omega}_1, \dot{\omega}_2, \dot{\omega}_3]\) in the inertial frame, and using the comma as a delimiter, one waypoint is correctly read if presented as a line like the following

\[t, \sigma_1, \sigma_2, \sigma_3, \omega_1, \omega_2, \omega_3, \dot{\omega}_1, \dot{\omega}_2, \dot{\omega}_3\]

The module is conceptually very simple and makes no further assumptions. However, the user might want to use a sampling frequency in the Basilisk simulation that is equal or higher than the frequency of the waypoints. For lower sampling frequencies, the module output does not give a trustworthy representation of the maneuver.

Detailed Module Description

The module reads a sequence of time-tagged waypoints. Defining \(t=[t_0,...,t_N]\) the times of the N+1 waypoints, and \(t_{sim}\) the simulation time, we have that:

  • for \(t_{sim} < t_0\): the attitude is held constant and equal to the attitude of the first waypoint; angular rates and acceleration are kept at zero;

  • for \(t_0 \leq t_{sim} \leq t_N\): attitude, angular rates and accelerations are the result of linear interpolation between the closest two waypoints;

  • for \(t_{sim} > t_N\): the attitude is held constant and equal to the attitude of the last waypoint; angular rates and acceleration are kept at zero.

When reading from the data file, the module always maps the attitude to the short rotation MRP set, regardless of the attitude type. This means that, for a data file that describes large attitude rotations (larger than 180 deg), the attRefOutMsg.sigma_RN will present a discontinuity. When two subsequent waypoints are mapped into different MRP sets, the interpolation is carried out in that time interval between the first waypoint and the shadow set of the second waypoint. This allows for a non-singular attitude description.

User Guide

The module assumes the data file is in plain text form and the following format:

  • time (seconds)

  • attitude parameters (MRPs or EPs)

  • angular rates (rad/s) either expressed in inertial frame or reference frame

  • angular accelerations (rad/s^2) either expressed in inertial frame or reference frame

where each line contains information about only one intermediate point of the maneuver.

The required module configuration is:

waypointReferenceConfig = waypointReference.WaypointReference()
waypointReferenceConfig.ModelTag = "waypointReference"
waypointReferenceConfig.dataFileName = dataFileName
waypointReferenceConfig.attitudeType = 0
unitTestSim.AddModelToTask(unitTaskName, waypointReferenceConfig)

Note that for attitudeType, a valid input must be provided by the user: 0 - MRP, 1 - EP or quaternions (q0, q1, q2, q3), 2 - EP or quaternions (q1, q2, q3, qs). No default attitude type is used by the module, therefore faliure to specify this parameter results in breaking the simulation.

The module is configurable with the following optional parameters:

Module Optional Parameters






delimiter string that separates data on a line



if true, reads angular rates and accelerations in the reference frame instead of inertial frame



number of header lines in the data file that should be ignored before starting to read in the waypoints

class WaypointReference : public SysModel
#include <waypointReference.h>

waypoint reference module class

Public Functions


This is the constructor for the module class. It sets default variable values and initializes the various parts of the model


Module Destructor.

void Reset(uint64_t CurrentSimNanos)

A Reset method to put the module back into a clean state


CurrentSimNanos – The current sim time in nanoseconds

void UpdateState(uint64_t CurrentSimNanos)

Update this module at the task rate


CurrentSimNanos – The current sim time

Public Members

std::string dataFileName

Name of the attitude waypoint data file.

std::string delimiter

delimiter string that separates data on a line, defaulted to comma “,”

int headerLines

Number of header lines in the file, defaulted to 0.

int attitudeType

0 - MRP, 1 - EP or quaternions (q0, q1, q2, q3), 2 - EP or quaternions (q1, q2, q3, qs)

bool useReferenceFrame

if true: angular rates and accelerations in the file are expressed in the reference frame; defaulted to false

Message<AttRefMsgPayload> attRefOutMsg

attitude reference output msg

BSKLogger bskLogger

BSK Logging

Private Functions

double pullScalar(std::istringstream *iss)

pull a double from the input stream

void pullVector(std::istringstream *iss, double*)

pull a 3-d set of double values from the input stream

void pullVector4(std::istringstream *iss, double*)

pull a 4-d set of double values from the input stream

void pullDataLine(uint64_t *t, AttRefMsgPayload *attRefMsg_t)

Pull one line of dataFileName and stores time t and relative attitude in attRefMsg_t

void linearInterpolation(uint64_t t_a, double v_a[3], uint64_t t_b, double v_b[3], uint64_t t, double *v)

linearly interpolate between two vectors v_a and v_b

Private Members

std::ifstream *fileHandle

pointer to the file that is to be read

bool endOfFile

boolean that indicates if the last line of file has been reached

uint64_t t_a

[ns] time t_a in the data file

uint64_t t_b

[ns] time t_b in the data file

AttRefMsgPayload attRefMsg_a

attitude at time t_a

AttRefMsgPayload attRefMsg_b

attitude at time t_b