SatellitePlayground.jl API

The API all revolves around the simulate function which has two modes of running:

Software in the loop: A separate program pretends to be a satellite, and the simulator and program communicate sensor/control data between them. This is useful for testing your true satellite software to make sure the guidance, navigation, and controll code still works despite all the other things it is doing.
Control function: A function is passed a measurement (by default the state, parameters, and time in body frame) and returns the magnetorquer control input. This is useful for directly testing attitude control schemes.

SatellitePlayground.simulate — Function

simulate(control::Function)
simulate(launch::Cmd)
simulate(control::Function; log_init=default_log_init, log_step=default_log_step,
    terminal_condition=default_terminate, max_iterations=1000, dt=0.5,
    initial_condition=nothing, measure=default_measure, model=default_model,
    environment=default_environment, silent=false)

Runs a simulation from a random initial condition (or from initial_condition) if given. The simulation runs for max_iterations steps.

The model specifies things like the mass, inertia, drag coefficient of the satellite and control type (magnetorquer, reaction wheel, etc). The environment specifies things like the magnetic field.

The control input is computed via control(measurement) where measurement is the output of the measurement function. Or it is computed by an external process using GNCTestClient.py if launch is given.

By default the controller recieves the (state, environment) in the body frame. But this can be changed by setting the measurement function measure.

The simulation logs the state of the satellite at each time step by default. This can be changed by setting the log_* functions.

source

Other Simulation Modes

For simulating multiple satellites at once use:

SatellitePlayground.simulate_multiple — Function

simulate_multiple(controls::AbstractArray{Function})
simulate_multiple(controls::AbstractArray{Function}; log_init=default_log_init, log_step=default_log_step,
    terminal_condition=default_terminate, max_iterations=1000, dt=0.1,
    initial_conditions=nothing, measures=nothing,
    models=nothing, initial_environment=default_environment)

source

Dynamics

There are two ways to change the dynamics of the simulation:

Change the invidual satellite model (mass, inertia, control type, etc.)
Change the environment model (e.g. earth gravity model, solar radiation pressure model, etc.)

State

SatellitePlayground.RBState — Type

Based on: https://github.com/RoboticExplorationLab/RobotDynamics.jl/blob/master/src/rbstate.jl

RBState{T} <: StaticVector{13,T}

Represents the state of a rigid body in 3D space, consisting of position, linear_velocity, attitude, and angular velocity, respresented as a vector stacked in that order, with the rotation represented as the 4 elements unit quaternion.

Implements the StaticArrays interface so can be treated as an SVector with additional methods.

Constructors

RBState{T}(r, v, q, ω)
RBState{T}(x)
RBState(r, v, q, ω)
RBState(x)

where r, v, and ω are three-dimensional vectors, q is either a Rotation or a four-dimenional vector representing the parameters of unit quaternion, and x is a 13-dimensional vector (or tuple),

source

Defaults

SatellitePlayground.default_measure — Function

default_measure(state::RBState, env::Environment)

Default measurement function used by simulate, returns the state and environment.

source

SatellitePlayground.default_terminate — Function

default_terminate(state::RBState, env::Environment, i::Int)

default termination condition for simulate, always returns false.

source

Useful Helper Functions

SatellitePlayground.initialize_orbit — Function

initialize_orbit(; r=nothing, v=nothing, a=nothing, q=nothing, ω=nothing, Rₑ=6378.137e3, μ=3.9860044188e14)

Initializes a random, viable orbit given a few different terms, usually a position 'r' in Cartesian coordinates. Initial velocity may be specified, but if specified it will not necessarily result in a stable orbit.

The initial starting position, velocity, semi-major axis, orientation, and angular velocity may be either specified or determined randomly.

Arguments:

r: (Optional) Height above ground that the satellite will start its orbit at | Scalar
v: (Optional) Magnitude of initial velocity | Scalar
a: (Optional) Semi-major axis | Scalar
q: (Optional) Initial attitude, as a unit quaternion | [4,]
ω: (Optional) Initial angular velocity | [3,]

Returns:

x: Initial state, as (r, v, q, ω) | State

source

SatellitePlayground.world_to_body — Function

world_to_body(::RBState, ::Vector)

Returns the vector in the body frame

source

SatellitePlayground.vec_to_mat — Function

vec_to_mat(hist)

Converts a vector of vectors to a matrix. Useful for converting the output of a simulation to a format that can be plotted.

source