.. _MultiSatBskSim_scenariosMultiSat_scenario_AttGuidMultiSat:

scenario_AttGuidMultiSat
========================

Overview
--------

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

#. introduce the flight software class,
#. show how one can change the active flight mode on the run, and
#. discuss how this script takes advantage of the new BSK Sim structure.

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

      python3 scenario_AttGuidMultiSat.py

This simulation is based on the :ref:`scenario_BasicOrbitMultiSat` with the addition of flight software modules. It also
takes some cues from :ref:`scenario_AttGuidance`, but with several spacecraft and more possible flight modes.

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 identical to those used in :ref:`scenario_BasicOrbitMultiSat`.


Custom FSW Configurations Instructions
--------------------------------------

In this example, all spacecraft inherit the same flight software class defined in :ref:`BSK_MultiSatFsw`. Four flight
modes are implemented through the use of events and are described below:

#. ``standby``: the spacecraft has no attitude requirements.
#. ``inertialPointing``: the spacecraft points at some inertially fixed location.
#. ``sunPointing``: the spacecraft points at the Sun.
#. ``locationPointing``: the spacecraft aims at a ground location on Earth.

The attitude is controlled using a set of four reaction wheels that are set up in :ref:`BSK_MultiSatDynamics`. The
``mrpFeedback`` is used for the control law and ``rwMotorTorque`` interfaces with the reaction wheels. The
``attTrackingError`` module is used with all modes to convert from a reference message to a guidance one.

The events can be set using the ``modeRequest`` flag inside the FSW class. It is crucial that all events call the
``setAllButCurrentEventActivity`` method. This function is called in a way such that all events' activity is made active
except for the current one. Without this command, every event could only be made active once. The method also makes
sure it only affects the events specific to each spacecraft. For more information, see :ref:`SimulationBaseClass`.

No formation flying control is done in this scenario. To see a more complete example which includes formation geometry
control, see :ref:`scenario_StationKeepingMultiSat`.

In this scenario, it is shown how the flight software events are set up, and how to change them on-the-fly.

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

.. image:: /_images/Scenarios/scenario_AttGuidMultiSat_attitude.svg
   :align: center

.. image:: /_images/Scenarios/scenario_AttGuidMultiSat_rate.svg
   :align: center

.. image:: /_images/Scenarios/scenario_AttGuidMultiSat_attitude_tracking_error.svg
   :align: center

.. image:: /_images/Scenarios/scenario_AttGuidMultiSat_tracking_error_rate.svg
   :align: center

.. image:: /_images/Scenarios/scenario_AttGuidMultiSat_rw_motor_torque.svg
   :align: center

.. image:: /_images/Scenarios/scenario_AttGuidMultiSat_rw_speeds.svg
   :align: center