This script sets up three 6-DOF spacecraft orbiting the Earth in formation. The goal of this scenario is to

  1. introduce formation flying control with desired orbital element differences,

  2. evidence how the module can conciliate attitude requests with thruster requirements, and

  3. show how one can choose whether the chief of the formation is a spacecraft or the formation’s barycenter.

The script is found in the folder basilisk/examples/MultiSatBskSim/scenariosMultiSat and is executed by using:


This simulation is based on the scenario_AttGuidMultiSat with the addition of station keeping control. Attitude mode requests are processed in the same way as before, but now there is the added complexity of introducing formation control, which can influence attitude requests.

The user can choose whether to use the zeroth index spacecraft or the formation’s barycenter as the formation’s chief. On that note, some geometries are not possible when using the barycenter as a reference point for the formation. This is because the barycenter is influenced by the spacecraft reorienting themselves, and so only some geometries are feasible. Failure to take this into account results in the spacecraft continuously correcting their orbits without ever converging.

For simplicity, the script plots only the information related to one of the spacecraft, despite logging the necessary information for all spacecraft in the simulation.

Custom Dynamics Configurations Instructions

The dynamics modules required for this scenario are the same used in scenario_BasicOrbitMultiSat and scenario_AttGuidMultiSat. However, this example takes full advantage of all the features of the dynamics class, which includes thrusters for orbit corrections.

Custom FSW Configurations Instructions

As stated in the previous section, the BSK_MultiSatFsw class used in this example is the same as the one used in scenario_AttGuidMultiSat. The main difference is that the station keeping module is now used, which allows for relative orbit geometry control.

If no station keeping is desired, then the FSW stack works exactly as in scenario_AttGuidMultiSat. However, if station keeping is set properly, the FSW events work as follows. First, the attitude reference is set given the pointing requirements. Then, the station keeping module computes the information regarding the necessary corrective burns, such as point in orbit, duration, thrust, attitude requirements, etc. With this information, the module then chooses whether the spacecraft is in a point in orbit where a burn is required. If it is, the attitude reference from the pointing requirement is overruled in favor of the necessary attitude to complete the current burn. If it is not, the reference attitude passes through unchanged.

The control law used to drive the formation to its intended orbital element differences is guaranteed to converge if the chief has Keplerian motion. This might not be the case when the chief is the formation’s barycenter, as its orbital elements change in accordance to how each spacecraft is maneuvering. One way to help with convergence is to make sure that the barycenter has invariant orbital elements. This can be achieved by guaranteeing that the following equation holds:

\[\sum_i m_i\Delta oe_i = 0\]

Activation of the station keeping mode is done through the stationKeeping flag. If set to True, formation control will be activated.

Due to the fact that the spacecraftReconfig module only accepts messages of the type AttRefMsgPayload, the locationPointing module always outputs a reference message and the attTrackingError module is always called, unlike how it happens in scenario_AttGuidMultiSat.

Illustration of Simulation Results

Since three spacecraft are simulated, and to prevent excessively busy plots, only the information pertaining to one spacecraft is plotted per simulation.

show_plots = True, numberSpacecraft=3, relativeNavigation=False
../../../_images/scenario_StationKeepingMultiSat_attitude.svg../../../_images/scenario_StationKeepingMultiSat_rate.svg../../../_images/scenario_StationKeepingMultiSat_attitudeTrackingError.svg../../../_images/scenario_StationKeepingMultiSat_trackingErrorRate.svg../../../_images/scenario_StationKeepingMultiSat_attitudeReference.svg../../../_images/scenario_StationKeepingMultiSat_rateReference.svg../../../_images/scenario_StationKeepingMultiSat_rwMotorTorque.svg../../../_images/scenario_StationKeepingMultiSat_rwSpeeds.svg../../../_images/scenario_StationKeepingMultiSat_orbits.svg../../../_images/scenario_StationKeepingMultiSat_relativeOrbits.svg../../../_images/scenario_StationKeepingMultiSat_oeDifferences.svg../../../_images/scenario_StationKeepingMultiSat_power.svg../../../_images/scenario_StationKeepingMultiSat_fuel.svg../../../_images/scenario_StationKeepingMultiSat_thrustPercentage.svg, numberSpacecraft, relativeNavigation)[source]

The scenarios can be run with the followings setups parameters:

  • showPlots (bool) – Determines if the script should display plots

  • numberSpacecraft (int) – Number of spacecraft in the simulation

  • relativeNavigation (bool) – Determines if the formation’s chief is the barycenter or the zeroth index spacecraft

class scenario_StationKeepingMultiSat.scenario_StationKeepingFormationFlying(numberSpacecraft, relativeNavigation)[source]

Bases: BSK_MultiSatMasters.BSKSim, BSK_MultiSatMasters.BSKScenario


Developer must override this method in their BSK_Scenario derived subclass.


Developer must override this method in their BSK_Scenario derived subclass.

pull_outputs(showPlots, relativeNavigation, spacecraftIndex)[source]

Developer must override this method in their BSK_Scenario derived subclass.