FSW Sims

Basilisk flight software models (FSW) are given in bsk_rl.sim.fsw.

Flight software models serve as the interface between the operation of the satellite in simulation and the Gymnasium environment. While some FSW models add additional functionality to the satellite, such as imaging instrument control in ImagingFSWModel, others replace the default control laws with a more complex algorithms, such as SteeringFSWModel vis a vis BasicFSWModel.

Actions

Each FSW model has a number of actions that can be called to task the satellite. These actions are decorated with the action() decorator, which performs housekeeping tasks before the action is executed. These actions are the primary way to control the satellite simulation from other parts of the Gymnasium environment.

Properties

The FSW model provides a number of properties for easy access to the satellite state. These can be accessed directly from the dynamics model instance, or in the observation via the SatProperties observation.

Aliveness Checking

Certain functions in the FSW models are decorated with the aliveness_checker() decorator. These functions are called at each step to check if the satellite is still operational, returning true if the satellite is still alive.

action(func: Callable[[...], None]) → Callable[[Callable[[...], None]], Callable[[...], None]]

Decorator to reset the satellite software before executing an action.

Each time an action is called, the FSW tasks and dynamics models call their reset_for_action methods to ensure that the satellite is in a consistent state before the action is executed.

Action functions are typically called by Actions to task the satellite.

Parameters:

func (Callable[[...], None])

Return type:

Callable[[Callable[[…], None]], Callable[[…], None]]

class BasicFSWModel(satellite: Satellite, fsw_rate: float, priority: int = 100, **kwargs)

Bases: FSWModel

The abstract base flight software model.

One FSWModel is instantiated for each satellite in the environment each time the environment is reset and new simulator is created.

Parameters:

• satellite (Satellite) – Satellite modelled by this model

• fsw_rate (float) – [s] Rate of FSW simulation.

• priority (int) – Model priority.

• kwargs – Passed to task creation functions

action_drift() → None

Decorated with action

Disable all tasks and do nothing.

Return type:

None

class SunPointTask(fsw, priority=99)

Bases: Task

Task to generate a sun-pointing reference.

name: str = 'sunPointTask'

setup_sun_pointing(nHat_B: Iterable[float], **kwargs) → None

Configure the solar array sun-pointing task.

Parameters:

• nHat_B (Iterable[float]) – Solar array normal vector.

• kwargs – Passed to other setup functions.

Return type:

None

action_charge() → None

Decorated with action

Charge battery by pointing the solar panels at the sun.

Return type:

None

class NadirPointTask(fsw, priority=98)

Bases: Task

Task to generate nadir-pointing reference.

name: str = 'nadirPointTask'

class RWDesatTask(fsw, priority=97)

Bases: Task

Task to desaturate reaction wheels using thrusters.

name: str = 'rwDesatTask'

setup_thruster_mapping(controlAxes_B: Iterable[float], thrForceSign: int, **kwargs) → None

Configure the thruster mapping.

Parameters:

• controlAxes_B (Iterable[float]) – Control unit axes.

• thrForceSign (int) – Flag indicating if pos (+1) or negative (-1) thruster solutions are found.

• kwargs – Passed to other setup functions.

Return type:

None

setup_momentum_dumping(hs_min: float, maxCounterValue: int, thrMinFireTime: float, desatAttitude: str | None, **kwargs) → None

Configure the momentum dumping algorithm.

Parameters:

• hs_min (float) – [N*m*s] Minimum RW cluster momentum for dumping.

• maxCounterValue (int) – Control periods between firing thrusters.

• thrMinFireTime (float) – [s] Minimum thruster firing time.

• desatAttitude (str | None) –

  Direction to point while desaturating:

  • "sun" points panels at sun

  • "nadir" points instrument nadir

  • None disables attitude control.

• kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None

Disable power draw for thrusters when a new action is selected.

Return type:

None

action_desat() → None

Decorated with action

Charge while desaturating reaction wheels.

This action maneuvers the satellite into desatAttitude, turns on the thruster power sink, and enables the desaturation tasks. This action typically needs to be called multiple times to fully desaturate the wheels.

Return type:

None

class TrackingErrorTask(fsw, priority=90)

Bases: Task

Task to convert an attitude reference to guidance.

name: str = 'trackingErrTask'

class MRPControlTask(fsw, priority=80)

Bases: Task

Task to control the satellite with reaction wheels.

name: str = 'mrpControlTask'

setup_mrp_feedback_rwa(K: float, Ki: float, P: float, **kwargs) → None

Set the MRP feedback control properties.

Parameters:

• K (float) – Proportional gain.

• Ki (float) – Integral gain.

• P (float) – Derivative gain.

• kwargs – Passed to other setup functions.

Return type:

None

setup_rw_motor_torque(controlAxes_B: Iterable[float], **kwargs) → None

Set parameters for finding motor torque from the control law.

Parameters:

• controlAxes_B (Iterable[float]) – Control unit axes.

• kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None

MRP control is enabled by default for all tasks.

Return type:

None

class ImagingFSWModel(*args, **kwargs)

Bases: BasicFSWModel

Adds instrument pointing and triggering control to FSW.

property c_hat_P

Instrument pointing direction in the planet frame.

property c_hat_H

Instrument pointing direction in the hill frame.

class LocPointTask(fsw, priority=96)

Bases: Task

Task to point the instrument at ground targets.

name: str = 'locPointTask'

setup_location_pointing(inst_pHat_B: Iterable[float], **kwargs) → None

Set the Earth location pointing guidance module.

Parameters:

• inst_pHat_B (Iterable[float]) – Instrument pointing direction.

• kwargs – Passed to other setup functions.

Return type:

None

setup_instrument_controller(imageAttErrorRequirement: float, imageRateErrorRequirement: float, **kwargs) → None

Set the instrument controller parameters.

The instrument controller is used to take an image when certain relative attitude requirements are met, along with the access requirements of the target (i.e. imageTargetMinimumElevation and imageTargetMaximumRange as set in setup_imaging_target).

Parameters:

• imageAttErrorRequirement (float) – [MRP norm] Pointing attitude error tolerance for imaging.

• imageRateErrorRequirement (float) – [rad/s] Rate tolerance for imaging. Disable with None.

• kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None

Reset pointing controller.

Return type:

None

action_image(r_LP_P: Iterable[float], data_name: str) → None

Decorated with action

Attempt to image a target at a location.

This action sets the target attitude to one tracking a ground location. If the target is within the imaging constraints, an image will be taken and stored in the data buffer. The instrument power sink will be active as long as the task is enabled.

Args:

r_LP_P: [m] Planet-fixed planet relative target location. data_name: Data buffer to store image data to.

Parameters:

• r_LP_P (Iterable[float])

• data_name (str)

Return type:

None

action_downlink() → None

Decorated with action

Attempt to downlink data.

This action points the satellite nadir and attempts to downlink data. If the satellite is in range of a ground station, data will be downlinked at the specified baud rate. The transmitter power sink will be active as long as the task is enabled.

Return type:

None

class ContinuousImagingFSWModel(*args, **kwargs)

Bases: ImagingFSWModel

FSW model for continuous nadir scanning.

Instead of imaging point targets, this model is used to continuously scan the ground while pointing nadir.

class LocPointTask(*args, **kwargs)

Bases: LocPointTask

Task to point nadir and trigger the instrument.

setup_instrument_controller(imageAttErrorRequirement: float, imageRateErrorRequirement: float, **kwargs) → None

Set the instrument controller parameters for scanning.

As long as these two conditions are met, scanning will occur continuously.

Parameters:

• imageAttErrorRequirement (float) – [MRP norm] Pointing attitude error tolerance for imaging.

• imageRateErrorRequirement (float) – [rad/s] Rate tolerance for imaging. Disable with None.

• kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None

Reset scanning controller.

Return type:

None

action_nadir_scan() → None

Decorated with action

Scan nadir.

This action points the instrument nadir and continuously adds data to the buffer as long as attitude requirements are met. The instrument power sink is active as long as the action is set.

Return type:

None

action_image(*args, **kwargs) → None

Decorated with action

Disable action_image from parent class.

meta private:

Return type:

None

class SteeringFSWModel(*args, **kwargs)

Bases: BasicFSWModel

FSW extending attitude control to use MRP steering instead of MRP feedback.

This class replaces the simple attitude feedback control law with a more sophisticated MRP steering control law.

class MRPControlTask(fsw, priority=80)

Bases: Task

Task to control the satellite with reaction wheels.

name: str = 'mrpControlTask'

setup_mrp_steering_rwa(K1: float, K3: float, omega_max: float, servo_Ki: float, servo_P: float, **kwargs) → None

Define the control properties.

Parameters:

• K1 (float) – MRP steering gain.

• K3 (float) – MRP steering gain.

• omega_max (float) – [rad/s] Maximum targetable spacecraft body rate.

• servo_Ki (float) – Servo gain.

• servo_P (float) – Servo gain.

• kwargs – Passed to other setup functions.

Return type:

None

setup_rw_motor_torque(controlAxes_B: Iterable[float], **kwargs) → None

Define the motor torque from the control law.

Parameters:

• controlAxes_B (Iterable[float]) – Control unit axes.

• kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None

Keep MRP control enabled on action calls.

Return type:

None

class SteeringImagerFSWModel(*args, **kwargs)

Bases: SteeringFSWModel, ImagingFSWModel

Convenience type that combines the imaging FSW model with MRP steering.