8/22/2019 AttSim Manual RevB
1/36
. . . . . . . . .
..........
Microcosm, Inc
AttSim User Manual
The Satellite Attitude Simulator withSoftware-in- the-Loop Verification
Capability
Microcosm, Inc.
401 Coral Circle
El Segundo, CA 90245
MC 99-0201 (REV A)
8/22/2019 AttSim Manual RevB
2/36
Microcosm Proprietary Do Not Distribute Without Permission
2
Table of Contents
1. AttSim Introduction__________________________________________________ 4
2. Installation_________________________________________________________ 6
3. AttSim Configuration ________________________________________________ 7
4. Module Dynamics.c__________________________________________________ 9
4.1. The Data Structures___________________________________________________ 114.1.1. Units __________________________________________________________________ 13
4.2. Coordinate Systems ___________________________________________________ 134.2.1. Euler angles _____________________________________________________________ 15
4.3. Integration __________________________________________________________ 15
5. Module Siminit ____________________________________________________ 17
5.1. Input File Format_____________________________________________________ 17
5.2. Initialization Function _________________________________________________ 18
5.3. Keyboard commands__________________________________________________ 20
5.4. Command line parameters _____________________________________________ 21
6. Module(s) Control.c ________________________________________________ 23
6.1. Zero-Momentum Control1.C__________________________________________ 256.1.1. The B-Dot Law __________________________________________________________ 27
6.2. Inertial Scanner Control2.C __________________________________________ 27
6.3. Momentum Biased Control3.c _________________________________________ 296.3.1. Momentum Management Routines ___________________________________________ 31
6.4. Gravity Gradient Control4.c __________________________________________ 31
7. Output File Format _________________________________________________ 33
8. References ________________________________________________________ 36
8/22/2019 AttSim Manual RevB
3/36
Microcosm Proprietary Do Not Distribute Without Permission
3
List of Figures
Figure 1: AttSim Block Diagram (Top-Level) 4
Figure 2: AttSim Screen Output 5
Figure 3: Main Function Schematic10
Figure 4: Control Module Integration 24
Figure 5: Zero-Momentum Spacecraft Simulation. The right window is a zoom on the pitch axis. Note thezoom-factor of 64 in the upper left corner of this window. 26
Figure 6: Coordinate System of the Inertial Scanner 28
Figure 7: Inertial Scanner. Note that the target window, lower middle, has no meaning for an inertial
pointing spacecraft, as have the roll, pitch and yaw angles. Satellite has been deployed with an initial error
and corrects for it. 29
Figure 8: Momentum Biased Spacecraft Coordinate System. This coordinate system is identical with the
zero-momentum and the gravity gradient system, with the exception of the wheel configuration in both
cases. 30
Figure 9: Momentum Biased Spacecraft Simulation Results 30
Figure 10: Gravity Gradient Simulation Results 32
Figure 11: Typical error plot using the error data in file miscxxx.dat 35
List of Tables
Figure 1: AttSim Block Diagram (Top-Level) ________________________________________________ 4
Figure 2: AttSim Screen Output __________________________________________________________ 5
Figure 3: Main Function Schematic ______________________________________________________ 10
Figure 4: Control Module Integration ____________________________________________________ 24
Figure 5: Zero-Momentum Spacecraft Simulation. The right window is a zoom on the pitch axis. Note the
zoom-factor of 64 in the upper left corner of this window. _____________________________________ 26
Figure 6: Coordinate System of the Inertial Scanner _________________________________________ 28
Figure 7: Inertial Scanner. Note that the target window, lower middle, has no meaning for an inertial
pointing spacecraft, as have the roll, pitch and yaw angles. Satellite has been deployed with an initial error
and corrects for it. ____________________________________________________________________ 29
Figure 8: Momentum Biased Spacecraft Coordinate System. This coordinate system is identical with thezero-momentum and the gravity gradient system, with the exception of the wheel configuration in both
cases. ______________________________________________________________________________ 30
Figure 9: Momentum Biased Spacecraft Simulation Results ___________________________________ 30
Figure 10: Gravity Gradient Simulation Results_____________________________________________ 32
Figure 11: Typical error plot using the error data in file miscxxx.dat __________________________ 35
8/22/2019 AttSim Manual RevB
4/36
Microcosm Proprietary Do Not Distribute Without Permission
4
1. AttSim Introduction
AttSim is an attitude simulator developed for spacecraft attitude control design and verifica-
tion. It specifically allows the user to develop software modules that can be used as flight
code1 and to verify control logic, controller gains and other mission critical elements. In addi-
tion, AttSim can be used as a system engineering tool to ensure correct torquer sizing, wheelsizing, sensor performance and related topics. AttSim features sophisticated environmental
models such as MSIS-86 atmospheric model (ref. 11 and 12) or the magnetic field model
IGRF (ref. 1, pp. 775), allowing a realistic simulation of atmospheric and magnetic distur-
bances.
AttSim runs on a IBM-compatible PC and is written in C, compiled with Borland Turbo C
3.0. It runs under DOS or in a DOS window under Windows 95 or 98. One of AttSim's origi-
nal functions were hardware-in-the-loop capability, which requires real-time capacity. This is
much easier to achieve under DOS than under Windows 95 or 98, and it is therefore the most
important reason why the program was never transported onto a multitasking platform. An-
other advantage is that the Borland C compiler produces stable code and allows easy and reli-
able debugging; for flight software development, these features are more important than a
graphical user interface.
AttSim uses an input file with orbital parameters and the satellite initial attitude, and creates 6
output files plus a graphical file of the screen. The satellite physical parameters, such as mass,
area, and moments of inertia are part of the program source code. Due to the number of pa-
rameters, careful documentation is required during development and test. In order to identify
the correct output files, a three-digit code number is used.
An important feature of AttSim is the separation between the control module and the attitude
simulation part of the program. There is one pipeline, or buffer which transfers data from the
simulator to the control module, and another pipeline (buffer) that transfers data from the
control module to the simulator. Both are represented by arrows between the two parts in
Figure 1.
Figure 1: AttSim Block Diagram (Top-Level)
Orbit Simulation
EnvironmentalModels (Density,Geomagnetic Field)
Attitude Simulation Control Module
AttSim Functional Diagram
Output (File and Screen) Output (File and Screen)
1 After being adapted to the flight computer specific environment
8/22/2019 AttSim Manual RevB
5/36
Microcosm Proprietary Do Not Distribute Without Permission
5
The pipelines could be bypassed by defining global variables, but this would have a negative
impact on the concept of AttSim.
Figure 2 shows a typical AttSim screen output. There are five windows, the two largest ones
(window 1 and 2) showing the near and the far side of a unit sphere in inertial space. The sat-
ellite is in the center of this unit sphere, and its axes are tracing a path onto the sphere to visu-
alize the satellites motion. The axes of the inertial coordinate system are also shown, with
negative axes as a dashed line.
Figure 2: AttSim Screen Output
As mentioned above, the unit sphere near side is shown left, and the far side is shown in the
right window, and the unit sphere represents the inertial coordinate system, with the satellite
in its center. Only two axes of the vehicles body coordinate system are shown on the unit-
sphere, to avoid confusion. Typically, the Y (or pitch) axis is a "stiff" axis, and leaves a trace
on the sphere. If the zoom function is used, it is zoomed on this axis. The other axis is the ve-
hicle's X-axis (or roll axis), which, in case of an earth oriented spacecraft in a circular orbit,
points into flight direction and follows the earth horizon. This axis does not leave a trace on
the unit sphere. In addition to the spacecraft axes, the unit spheres show the negative orbit
normal (usually the "target" for the earth oriented spacecraft) as a blue dot, and the sun as awhite circle. For long-term simulations, both would draw a trace on the screen.
Window 3 shows simulation output, or "true" data as opposed to window 5, showing con-
troller telemetry data. Window 4 shows the Nadir angle in the vehicle coordinate frame, illus-
trating the attitude error in roll and pitch. The yaw angle can't be detected in this view, as it
represents just a rotation about yaw. Note that, on the screen, the trace changes its color when
the torquer is switched on, from blue to red.
8/22/2019 AttSim Manual RevB
6/36
Microcosm Proprietary Do Not Distribute Without Permission
6
2. Installation
To install AttSim:
1. Install Turbo-C 3.0 first, preferably in a directory called TC.
2. Copy the folder KACST from the AttSim disk into this folder, thereby creating the sub-folder KACST under TC
3. Change directory into that folder, and type TC ATTSIM.PRJ. This will load Turbo Cand the AttSim project at the same time. If the project file is not visible, check Win-
dows, Project. Use the project window to edit or change files
Notes:
- Make sure that the memory model is set to Large or Huge under compiler options.
- Matlab files to read the output files are provided in the directory MATLAB. They canbe copied into the working directory, or the directory of the AttSim data files can be
specified in the Matlab routines.
- For better organization, each project should have its own subfolder.
8/22/2019 AttSim Manual RevB
7/36
Microcosm Proprietary Do Not Distribute Without Permission
7
3. AttSim Configuration
This section describes the main modules and their corresponding interfaces. Turbo C uses
project files (extension *.prj) to organize the various files belonging to a project. Table 1
gives an overview of the modules used for AttSim with introductory remarks. Note that some
modules are usually not changed when a new satellite model is integrated. It is highly recom-mended to not perform changes in these modules unless all functions are well understood. The
modules which are frequently changed are in bold letters, and the source code of these mod-
ules is well with comments.
Table 1: AttSim Modules Overview
Module Main Function Remarks
Cira.c MSIS 86 atmos-
pheric model
No changes required usually; code is kept close to the FOR-
TRAN code, e.g. variable names are similar. Semi-empirical
model with many parameters
Cira.h MSIS 86 atmos-pheric model
parameters
No changes required usually; contains data required for Cira.c
Controlx.c Flight Control
Code
File has to be changed for each satellite model; contains atti-
tude controller and hardware models for each axes. The "x" is
replaced by a number, 1,2...
Dynamics.c Main module
with orbit and
attitude integra-
tion
This module contains the main function, driving AttSim.
Contains the file output function, and the screen output top-
level function. The integration intervals and the simulation
duration is adjusted here, but changes should be limited to
these parameters
Gifsave.c Saves the screen
as a *.gif file
No changes required usually, provided to facilitate documenta-
tion only. This module is not part of AttSim.
Ehkbs.c Unit sphere
functions
Draws the unitsphere on the screen, and vectors and great cir-
cles onto it. Allows a variety of different drawing styles and
should not be changed.
Siminit.c Initialization
functions
Initializes various functions, such as the IGRF module (part of
Dynamics.c). Reads the satellite file, and initializes the satellite
structure. If changes to the satellite model are made, they
should be made in this file.
Sim.h Header file for all modules
Function prototypes, definitions (#define), and data structuredefinitions.
8/22/2019 AttSim Manual RevB
8/36
Microcosm Proprietary Do Not Distribute Without Permission
8
Solarflux.c Module for his-
toric F10.7 cm
solar flux and Ap
magnetic activity
No changes required usually; Module contains only the func-
tion to interpolate historic solar flux F10.7 cm values and cor-
responding Ap magnetic index.(2)
Svga.obj Object file No changes required; Driver for the Borland Graphics Interface
(BGI)
Utility.c Module for util-
ity functions
No changes required; Contains utility functions such as vector
and matrix functions, coordinate transformations, and other
mathematical functions.
Attsim.prj Project file List of source and object files, with preferences. Use caution
with compiler and linker options!
Attsim.cfg Configuration
file
File that contains the configuration for Ehkbs.c, e.g. the rota-
tion of the unit sphere and the colors. Not required to run
AttSim, but makes changing the perspective of the unit spheres
easier.
*.sat Satellite file(s) Satellite file provided as input to AttSim on the command line.
Contains the satellite orbit and the initial attitude in inertial (!)
space.(3)
2 This is the last function added to AttSim (except for the control functions); this is the reason while it is
a module.3 Note that most of the attitude related parameters are initialized within Siminit.c, except the attitude
given in the satellite file. Usually, many simulation runs are performed with a satellite (dynamical)
model, but for different initial attitudes or orbit configurations.
8/22/2019 AttSim Manual RevB
9/36
Microcosm Proprietary Do Not Distribute Without Permission
9
4. Module Dynamics.c
The best starting point to understand AttSim is the main() function in the module Dynamics.c.
There are 4 different loops with different time variables and time steps, driving a variety of
functions in other modules. These time variables and time steps are:
simstep = 0.1;simtime = 0.0;faststep = 1.0;fasttime = 0.0;slowstep = 2.0;slowtime = 0.0;filestep = 10.0;filetime = 0.0;
These values are given in seconds. The time variables like faststep define the time when the
corresponding functions are called again; the steps determine the time between function calls.
The outer loop is the fastest loop, with a step size of 0.1 seconds. Values below 0.2 seconds
work usually well; if the simstep value is too large, the program will report a quaternion nor-
malization error and produce erroneous results.
Before the main function starts the time loops, a few variables are intialized, among them the
structure SATELLITE. This structure contains all relevant dynamical data of the satellite, and
the function call "initialize" performs all major initialization in the module Siminit.c. Figure 3
shows, schematically, the functions of the main function.
8/22/2019 AttSim Manual RevB
10/36
Microcosm Proprietary Do Not Distribute Without Permission
10
Figure 3: Main Function Schematic
The function calls in the slow loop, the fast loop and the file loop do not have to be synchro-
nized, but it is recommended to synchronize them as much as possible for better results. The
slow loop contains the functions for the atmospheric model MSIS-86, the position determina-
tion with either Kepler's equation or a numerical integration, and the IGRF magnetic field
8/22/2019 AttSim Manual RevB
11/36
Microcosm Proprietary Do Not Distribute Without Permission
11
model. The fast loop determines the sun's position and whether the spacecraft is in the earth
shadow or sunlight (using a spherical earth model). This loop prepares the buffer (or pipeline)
to call the control module, and evaluates the buffer after the control module returns telemetry
to the main function. It then updates the screen output.
If enabled, the file loop outputs data into 6 files (see section 7,Output File Format). The file
output is disabled if a "-d" parameter is part of the command line; this feature has been incor-
porated to allow testing without using up disk space.
The sim loop then continues to integrate the attitude, to determine the forces and torques on
the satellite and to integrate the angular momentum. The keyboard is checked for input, to
determine whether the user wants to cancel the run or modify any parameter. A useful key-
board command is "r", which suppresses most of the screen output and speeds up the simula-
tion significantly.
4.1. The Data StructuresThe data structures are defined in Sim.h, which is the header file used in all modules. The two
basic data structures are VECTOR and MATRIX. VECTOR is defined as double[4], MA-
TRIX as double[4][4]. The three axes X, Y and Z are defined as 1,2, and 3, respectively4. The
variable u[X] refers to the X (or first) component of the vector u. The length of the vector isstored in u[0] and can be determined using the utility function magn(), e.g. u(0) = magn(u).
Matrices use the same indices X,Y, and Z, and the determinant of the matrix is usually stored
in m[0][0]. The row m[0][1..3] and the column m[1..3][0] are usually not used.
GRAPHSETUP is a data structure that is only used in connection with the screen output, and
can usually be ignored. An important data structure is ORBIT, defined as:
typedef struct{double ma,ea,ta; // Mean, Excentr. und True Anomalydouble mm,i,e,w; // Mean Motion, Incl., Excentr.,Perig.
double W,ut,a,b; // RAAN, Period, Semimajor and -minor Axisdouble rp,p; // Radius Perigee, Orbit parameterdouble epoche; // JD of Epoch of orbital element,double epodata; // Epoch of original dataset, constantdouble lastperi; // Last perigee, JDdouble firstperi; // First perigee, JD, olddouble gha; // Greenwich Hour Angle, might not be up to datedouble u; // w +ta...double year,month,day,dofy,gmt;long n; // Number of orbit, for information
} ORBIT;
(Note: RAAN: Right Ascension of Ascending Node, JD: Julian Date)
This structure contains all possible orbital elements, with some of them being updated only
when needed. The variable ut is frequently used to limit the length of the simulation and is the
orbital period in seconds.
4 The definition double[4] defines u[0], u[1], u[2] and u[3]; u[4] would be a violation.
8/22/2019 AttSim Manual RevB
12/36
Microcosm Proprietary Do Not Distribute Without Permission
12
The data structure ORBIT is used within the data structure SATELLITE, which contains all
vehicle data, environmental forces and torquers, the dynamical state of the vehicle and more.
typedef struct{
char name[MAXLINE];double tjd; // True decimal juliandate, incl. GMTORBIT *ce; // Classical elements// Radiusvector in varius coordinate systemsVECTOR rr,rp,rq,rb,re,rs;// Velocityvector in varius coordinate systemsVECTOR vr,vp,vq,vb,ve,vs;// Magnetic field vector in varius coordinate systemsVECTOR br,bp,bq,bb,be,bs;// --------------------------------------------------------------VECTOR fa; // Aerodynamic Forces (in inertial coordinates)VECTOR fs; // Solar Pressure Forces ( " )VECTOR offa; // Vector from CoM to CoPVECTOR offs; // Vector from CoM to solar CoPVECTOR offd; // Vector of magnetic Dipolmoment of satellite
VECTOR dm; // Dipolemoment of torquer, if anyVECTOR mc; // Control torqueVECTOR ma; // Aerodynamic torqueVECTOR ms; // Solar torqueVECTOR mg; // Gravity gradient torqueVECTOR mb; // Magnetic torqueVECTOR m; // Sum of all disturbance torquesVECTOR w; // Angular velocity in body coordinatesVECTOR hw; // Angular momentum of wheels....VECTOR ww; // Wheel speedVECTOR mt; // Motor torque of the wheelVECTOR h; // Angular momentum of total satellite in body
coordinatesVECTOR q; // QuaternionVECTOR euler; // Euler angle, for better interpretation
MATRIX I,W; // Moment of inertia (I) and its invers (W)MATRIX ab; // Body Matrix
double IW; // Moment of inertia of wheel, 4 Nmsdouble mass;double area;double cd;
} SATELLITE;
There are numerous position and velocity vectors in a variety of coordinate systems, to be ex-
plained briefly. The second letter after r or v corresponds to the coordinate system. The con-
trol and disturbance torques, if not otherwise indicated, are given in the satellite body coordi-
nates. Note that the quaternion has been defined as VECTOR, although it contains one more
(required ) entry than the other vectors. Euler angles (defined as a 3-1-3 sequence) are onlyused as input and for better visualization. These Euler angles are not identical with the roll,
pitch and yaw angles used in earth-oriented spacecraft. Beside the quaternion q, the variable h
is important because it represents the angular momentum of the total spacecraft, including all
existing wheels. The moments of inertia I are inverted early in the program, and the inverted
matrix is stored in W. The inversion allows to write the numerical integration of the angular
moment in a very clean way. One of the key results is the matrix ab, the body matrix which
transforms from the inertial coordinate system into the body coordinates. It essentially de-
scribes the vehicles attitude.
The general idea behind the consolidation of all relevant vehicle data into one single structure
8/22/2019 AttSim Manual RevB
13/36
Microcosm Proprietary Do Not Distribute Without Permission
13
is to keep the interfaces transparent, easy to use and to provide all necessary information to
other functions and modules. Note that usually the pointer to the SATELLITE structure is
passed on to other functions, which allows these functions to change data entries in this
structure. It does, however, create unusual variable names such as s->ce->ut, the pointer to
the pointer to the structure that contains the orbital period in seconds.
4.1.1. UnitsAttSim uses SI units, with a few exceptions. Time is measured in seconds, except for the Jul-
ian Date, which is measured in decimal days. Julian days start at noon5, e.g. the 4th of July,
1999 at 12:00 UTC is JD 2471365.0. Angles are measured in radians, but displayed in degrees
on the screen and in input and output files. The position vectors are in [km], not meters, to
keep the number in a reasonable range; the velocity is in [km/sec], for the same reason. The
magnetic field strength is in Nanotesla (10-9 Tesla), because the model coefficients are given
in this unit and it provides a reasonable number for the earth magnetic field (below 65,000
nT). Forces are in Newton [N], torques in [Nm], angular momentum in [Nms], and angular
rates in rad/sec. As with angles, rates are displayed differently, as rotation per minute (RPM).
The moments of inertia are given in kg-m2 , and satellite parameters such as the solar array
offset in meters. The area of the satellite is in m2, the drag coefficient CD is dimensionless
and has a typical value between 2 and 3.5 (the higher value for higher orbits). Drag coeffi-
cients for satellites are extremely difficult to estimate and depend on many parameters, suchas surface material and temperature.
4.2. Coordinate SystemsThe coordinate systems (Table 2) are symbolized by letters r, p, q, b, e, and s. q and b are the
systems that are mostly used, q is the inertial, earth-fixed frame (quasi-inertial) and b the
body frame, centered at the center of mass.
5 See Wertz, [1] page 20
8/22/2019 AttSim Manual RevB
14/36
Microcosm Proprietary Do Not Distribute Without Permission
14
Table 2: Coordinate Systems Definitions
Letter Name Definition Remark
r Not used N/A
p Orbit Plane
Coordinate
System
Origin in geocenter; +X to perifocus,
and +Z perpendicular to the orbital
plane to orbital normal.
System 8 in [2], p. 144
q Inertial Sys-
tem (ECI)
(earth-centered, inertial) Origin in
geocenter; +X to vernal equinox, +Z
to North Pole.
System 2 in [2], p. 135;
used for right ascension
and declination
b Body System Defined by the user input of the
moments of inertia and other pare-
meters, such as wheel orientation
Does not have to be
aligned with the princi-
pal axes
e ECEF (earth-centered, earth-fixed) Origin
in geocenter; +X to the Greenwich
meridian, +Z to the North Pole.
System 3 in [2], p.135
s
in combinationwith b-vector
Spherical Local system on the earth surface or
at a certain altitude; +X is radial out,+Y parallel to the surface, south, and
+Z due east.
Used for the geomag-
netic field model
s
in combination
with r-vector
Spherical Describes the position vector in geo-
graphical latitude, longitude, and
altitude above the earth ellipsoid.
Note the order
A variety of functions is used to convert between these systems. The following is part of the
module Utility.c, where these functions can be found.
void ptoq(VECTOR xq,VECTOR xp,double i,double w,double W);Function to rotate a vector in orbital coordinates (p)into a vector in inertial (ECI,q). Rotation is definedby the inclination i, the argument of perigee w, and theargument of ascending node (RAAN) W, all in radians.xq is the output.
void qtop(VECTOR xp,VECTOR xq,double i,double w,double W);Inverse function to ptoq, xp is the output.
void qtoe(VECTOR xe,VECTOR xq,double tg);Function to rotate an inertial (ECI,q) vector intoearth centered, earth fixed coordinates (ECEF, e), using
the GMT in radians. xe is the output.
void etoq(VECTOR xq,VECTOR xe,double tg);Inverse function to qtoe, xq is the output
void etos(VECTOR xs,VECTOR xe);Function to convert a position in ECEF (e) in kminto geographical latitude, longitude and altitude.Altitude is above the ellipsoid, in km. Lat/long isin radians. s stand for spherical, output is xs.
8/22/2019 AttSim Manual RevB
15/36
Microcosm Proprietary Do Not Distribute Without Permission
15
Note that the conversion between the e and the q system is somewhat simplified, because it
only involves the Greenwich hour angle; this has to be considered when an inertial attitude
determination scheme is used to derive an earth-related attitude such as roll, pitch and yaw
(e.g. using a star sensor for an earth pointing spacecraft). A more detailed transformation be-
tween the e (ECEF) and the q (ECI) system can be found in [2] or [4], if necessary. For the
purpose of developing flight software and performance analyses, the transformation used in
AttSim should be sufficient.
4.2.1. Euler anglesEuler angles are successive rotations about coordinate axes, and depend on the order of the
rotation. In AttSim, Euler angles are only used for input and output, while all computations
are performed with quaternions and attitude matrices. The initial attitude of the spacecraft if
defined as 3-1-3 sequence, or Z-X'-Z" rotation from the inertial coordinate frame. This corre-
sponds to an initial rotation about the Z axis, followed by a rotation about the new X axis, and
finally a rotation about the (about X) rotated Z axis. To rotate a satellite from inertial space
into an earth oriented attitude can be tricky
6
, because the orbit's position has to be considered.
Another use of Euler angles are the roll, pitch and yaw angles (RPY) for an earth oriented
spacecraft. In this case, RPY is not used in the simulator (except for output), and is calculated
in the interface function to the control module. RPY is defined as 3-2-1 sequence, with the
yaw axis into the negative position vector, the pitch axis into the negative orbital normal and
the roll axis building a right hand system. If the orbit is not circular (and it almost never is),
the velocity vector and the roll axis are different.
4.3. IntegrationAttSim uses a 4th order Runge-Kutta algorithm with a fixed step-size to integrate the dynami-
cal equations of motion. It allows for a full matrix of moments of inertia; this matrix should,
however, be symmetric and physically possible. Fixed step sizes have produced better results
than variable steps, which seem to get confused by spacecraft nutation. The integration rou-tine checks the quaternion against 1 +/- 10-7, and will exit the program if a larger error occurs.
With step sizes around 0.1 to 0.2 seconds, this should not happen7.
Early in the integration routine, a damping factor is defined. This factor is an attempt to
model spacecraft flexibility as observed during a real mission, and provides rate-proportional
damping at a very low level. Typically, moving parts on the spacecraft, such as antennas, or
even bearings in wheels cause friction and therefor dissipate energy. The damping factor, if
used in a wrong way, can cause severe problems because it changes the vehicle dynamics sig-
nificantly. It can, in fact, stabilize an otherwise unstable attitude control configuration, or sta-
bilize wrong (i.e. otherwise unstable) control gains. It is recommended to set this factor to 0
during stability tests.
The corresponding part in the source code is as follows:
// Initialization
for (i=0;i
8/22/2019 AttSim Manual RevB
16/36
Microcosm Proprietary Do Not Distribute Without Permission
16
for (i=0;iw[Y];damp[Z] = -0.0001*s->w[Z];
// Damping is primarily proportional to angular velocitys->m[X] += damp[X];s->m[Y] += damp[Y];s->m[Z] += damp[Z];
// Integration of equation of motion
etc.
8/22/2019 AttSim Manual RevB
17/36
Microcosm Proprietary Do Not Distribute Without Permission
17
5. Module Siminit
5.1. Input File FormatAttSim uses a satellite input file for the orbital parameters and the initial attitude. The satellite
files have the extension "*.sat", and have the following format:
Satellite Name Here1994 ; Year
2 ; Month9 ; Day19 ; Hour23 ; Minute19.000000 ; Seconds
7321.557960 ; Semimajor axis A in km33.083100 ; Mean anomaly in degrees50.0 ; Inclination in degrees.000385 ; Eccentricity
21.109100 ; Argument of perigee170.0 ; Right Ascension of ascending node-60.0 ; Angle about Z0-125.0 ; Angle about X1-35.0 ; Angle about Z2
All angles are in degrees, although internally, only angles in radians are used. The first line
contains the name of the satellite or project, and all other lines contain a value and a com-
ments, separated by a ";". The input data check is minimal, AttSim assumes that the users are
familiar with orbital parameters and don't specify nonsense data. Another valid input file for-
mat uses the position state vector as follows:
Satellite Name Here1994 ; Year
2 ; Month9 ; Day19 ; Hour23 ; Minute19.000000 ; Seconds
7321.557960 ; Semimajor axis A in km33.083100 ; Mean anomaly in degrees50.0 ; Inclination in degrees.000385 ; Eccentricity
21.109100 ; Argument of perigee170.0 ; Right Ascension of ascending node-3541.887081 ; X in km-3438.500950 ; Y in km4572.212109 ; Z in km6.495895685 ; dX/dt in km/s-1.668515243 ; dY/dt in km/s3.775988954 ; dZ/dt in km/s-60.0 ; Angle about Z0-125.0 ; Angle about X1-35.0 ; Angle about Z2
8/22/2019 AttSim Manual RevB
18/36
Microcosm Proprietary Do Not Distribute Without Permission
18
After the right ascension of ascending node and prior to the first Euler angle, the state vector
is given in km and km/sec. AttSim assumes that the user prefers numeric integration of the
position, and ignores the Keplerian elements specified before8.
5.2. Initialization FunctionMost of the satellite parameters are specified in the function initacs(s), where s is a pointer to
the SATELLITE structure explained above. The source code of this function with additionalexplanations is given below:
//-------------------------------------------------------------------
void initacs(SATELLITE *s){// Moments of inertia, full matrixs->I[X][X] = 89.0;s->I[X][Y] = 0.0;s->I[X][Z] = 0.0;s->I[Y][X] = 0.0;s->I[Y][Y] = 225.0;s->I[Y][Z] = 0.0;s->I[Z][X] = 0.0;s->I[Z][Y] = 0.0;s->I[Z][Z] = 244.0;invert(s->I,s->W); // No check// Wheel, all wheels have the same moment of inertia right nows->IW = 0.01;// --------------------------------------------------// Angular momentum of wheelss->hw[X] = 0.0;s->hw[Y] = 2.0;s->hw[Z] = 0.0;// Angular momentum of satellite bodys->h[X] = s->hw[X]; // + 0.5; // KICKs->h[Y] = s->hw[Y];s->h[Z] = s->hw[Z];// Magnitudess->h[0] = magn(s->h);s->hw[0] = magn(s->hw);
The kick in angular momentum has been used to exercise the control system and to simulate
the separation from a launcher. The moments of inertia are in kgm2, angular momentum is in
Nms. Note that the moment of inertia matrix is inverted.
// Control torques etc.s->mt[0] = s->mt[X] = s->mt[Y] = s->mt[Z] = 0.0;s->dm[0] = s->dm[X] = s->dm[Y] = s->dm[Z] = 0.0;s->mc[0] = s->mc[X] = s->mc[Y] = s->mc[Z] = 0.0;// Angular velocity initilisations->w[X] = s->W[X][X]*(s->h[X] - s->hw[X]) +
s->W[X][Y]*(s->h[Y] - s->hw[Y]) +s->W[X][Z]*(s->h[Z] - s->hw[Z]);
s->w[Y] = s->W[Y][X]*(s->h[X] - s->hw[X]) +s->W[Y][Y]*(s->h[Y] - s->hw[Y]) +s->W[Y][Z]*(s->h[Z] - s->hw[Z]);
s->w[Z] = s->W[Z][X]*(s->h[X] - s->hw[X]) +s->W[Z][Y]*(s->h[Y] - s->hw[Y]) +
8 A switch "+k" on the command line can force AttSim to use the Keplerian elements and ignore the
state vector if desired by the user
8/22/2019 AttSim Manual RevB
19/36
Microcosm Proprietary Do Not Distribute Without Permission
19
s->W[Z][Z]*(s->h[Z] - s->hw[Z]);s->w[0] = magn(s->w);// Angular velocities of wheels, all the same type of wheelss->ww[X] = s->hw[X]/s->IW;s->ww[Y] = s->hw[Y]/s->IW;s->ww[Z] = s->hw[Z]/s->IW;
The angular momentum is used to initialize the angular rates of the satellite. The satellite total
momentum is composed of the angular momentum of the body and the angular momentum of
the three wheels9.
// Build bodymatrix to transform easily from inertial space to bodysystems->ab[1][1] = cos(s->euler[3])*cos(s->euler[1])-cos(s-
>euler[2])*sin(s->euler[3])*sin(s->euler[1]);s->ab[1][2] = cos(s->euler[3])*sin(s->euler[1])+cos(s-
>euler[2])*sin(s->euler[3])*cos(s->euler[1]);s->ab[1][3] = sin(s->euler[2])*sin(s->euler[3]);s->ab[2][1] = -sin(s->euler[3])*cos(s->euler[1])-cos(s-
>euler[2])*cos(s->euler[3])*sin(s->euler[1]);s->ab[2][2] = -sin(s->euler[3])*sin(s->euler[1])+cos(s-
>euler[2])*cos(s->euler[3])*cos(s->euler[1]);s->ab[2][3] = sin(s->euler[2])*cos(s->euler[3]);s->ab[3][1] = sin(s->euler[2])*sin(s->euler[1]);s->ab[3][2] = -sin(s->euler[2])*cos(s->euler[1]);s->ab[3][3] = cos(s->euler[2]);// And now, build the quaternion for inertial space -> body// There might be better algorithms for that, depending// on the initial attitudes->q[3] = 0.5*sqrt(1+s->ab[1][1]+s->ab[2][2]+s->ab[3][3]);s->q[0] = (s->ab[2][3]-s->ab[3][2])/(4.0*s->q[3]);s->q[1] = (s->ab[3][1]-s->ab[1][3])/(4.0*s->q[3]);s->q[2] = (s->ab[1][2]-s->ab[2][1])/(4.0*s->q[3]);
The initial attitude matrix and quaternion has been built from the three Euler angles in the in-put file.
// Speedcommand deleted, use instead the telecommand list// Initialize aerodynamic offset vector:s->offa[X] = 0.0;s->offa[Y] = 0.0;s->offa[Z] = -0.56;s->offa[0] = magn(s->offa);// Initialize solar pressure offset vectors->offs[X] = 0.0;s->offs[Y] = 0.0;s->offs[Z] = -0.56;s->offs[0] = magn(s->offs);// Initialize magnetic disturbance dipole, unit Am^2
s->offd[X] = 0.0;s->offd[Y] = 0.0;s->offd[Z] = 0.0;s->offd[0] = magn(s->offd);// Various parameters of the satellite body:s->mass = 165.0;// Satellite front (and all other) area:s->area = 5.29;
9 Even if four or more wheels are present, they can be replaced by a three wheel configuration that is
perpendicular, aligned with the body coordinate system.
8/22/2019 AttSim Manual RevB
20/36
Microcosm Proprietary Do Not Distribute Without Permission
20
s->cd = 3.0;}
//-------------------------------------------------------------------
The offset vectors are an easy way to describe solar and aerodynamic disturbance torques.
They are body-fixed and point from the center of mass to the center of pressure, in meters10
.The dipole offset vector is basically a residual dipole moment, caused by magnetic material,
and typically at the order of 1-2 Am2, even for a small satellite. Its direction is difficult to es-
timate, and it should be varied to ensure proper stability. The satellite mass is in kg, the area
in m2 and the drag coefficient dimensionless.
The initialization function contains all satellite parameters that need to be changed when im-
plementing a new satellite model. Note that the moments of inertia might very well have de-
viation moments, and, again, AttSim expects the user to be familiar with these values and not
define nonsense values.
In the case of KACST, 4 different initialization routines have been developed, that correspond
with the 4 control modules. A switch at the begin of InitAcs determines which ACS system is
initialized, and the screen output shows the type of ACS system. The switch implementationis shown below:
/* Definitions in Sim.h :#define ZeroMomentum 1#define InertialScanner 2#define MomentumBiased 3#define GravityGradient 4 */
/* User Input, please : */const int sat_type = MomentumBiased;
if (sat_type == ZeroMomentum)
If the controller and the initialization routine are not for the same type of controller, AttSimwill not run properly.
5.3. Keyboard commandsDuring a simulation run, AttSim responds to keyboard inputs as shown in Table 3.
10 In some cases, aerodynamic models may be available; for control code development, offset vectors
are a good approximation
8/22/2019 AttSim Manual RevB
21/36
Microcosm Proprietary Do Not Distribute Without Permission
21
Table 3: Keyboard Commands
Key Action Remark
r Freezes the screen output except for
the axes on the unit sphere
Speeds up the simulation significantly, but causes
the GIF file saved at the end of a simulation to
represent an old screen.
p Pause; press any key to continue
z Zoom in; converts the right unit
sphere, usually representing the back
side, into a zoom of the Y-axis.
The zoom factor is shown in the zoom window,
and doubles every time the uses presses z. The
zoom function is not perfect, and the view is dis-
torted for higher zoom ratios.
Z Zoom reset. Looses all information
that has been drawn on the screen.
Causes empty windows if used in combination
with r
s Saves the current screen as GIF pic-
ture
c Returns to DOS; return to AttSim
with exit
Do not use without prior testing!
q Quit. A small dialog is displayed,
asking whether the screen should be
saved as GIF file and if the user
really wants to quit.
5.4. Command line parametersWhen called from DOS or the Turbo C debugger, AttSim accepts certain parameters. The
function selectoption in Siminit.c sorts through the input command line and switches any
flags if the right commands were given. The most important command parameter is the satel-
lite input file (*.sat file), and without an input file, AttSim terminates with a warning mes-
sage. The input file can be followed by a parameter as shown in Table 4.
8/22/2019 AttSim Manual RevB
22/36
Microcosm Proprietary Do Not Distribute Without Permission
22
Table 4: Command Line Parameters
Command Function Remarks
+d File output Default
-d No file output
+c Control on Default
-c No control (inoperative do not
use)
?, +g, -g Old functions do not use
-k Use numerical integration for position
+k Use Keplers equation Default
The parameter that has been proven useful over several years of development is the file output
command +/-d, that saves disk spaces or avoids deleting data files during control develop-
ment, when the simulator is used to test changes to the control code.
8/22/2019 AttSim Manual RevB
23/36
Microcosm Proprietary Do Not Distribute Without Permission
23
6. Module(s) Control.c
The control module contains the flight code of the satellite attitude determination and con-
trol system. This module is called from the main module in Dynamics.c, and it uses a buffer
to communicate with the simulator. This buffer is basically an array of double values, that
need to be defined in the same way in both modules in order to make the control module workproperly. In its current implementation, the control module is called at 1 Hz, which provides
sufficient control authority. For very small spacecraft and high disturbances, a faster rate may
be required, but this standard rate has been used for spacecraft between 50 kg and 2000 kg.
The function call is shown below:
//---------------------------------------------------------------if (simtime >= fasttime){// Update Shadowsonne(s->tjd,sun);dark = shadow(s->rq,sun);// Call control module
if (first) {for (k=0;k
8/22/2019 AttSim Manual RevB
24/36
Microcosm Proprietary Do Not Distribute Without Permission
24
Figure 4: Control Module Integration
Prepare Buffer
Sensor Interface Functions
Horizon Sensor
Sun Sensor
Magnetometer
etc..
Input Data
Controller MainFunction
Actuator Interface Functions
Momentum Wheel
Torquer
etc.
Evaluate Buffer
Output Data
The sensor data flow from the control buffer into sensor interface functions, which are called
by the main function in the control module. The control module then calls a variety of other
functions, depending on the control mode. The control module output typically a momen-tum wheel torque or a dipole moment to the magnetic torquer is processed by similar func-
tions, the actuator interface functions. The actuator interface functions can add errors to the
actuator commands, as it would be the case in the real world control system. Input and output
share the control buffer, with input using the first 30 entries, and output using the remaining
20 entries.
Beside the control buffer, the telecommands are global variables. All telecommands begin
with TC_, and they are initialized in the function telecommand(). The telecommands
should be sufficient to control the behavior of the control module; if the source code has to be
changed during tests, more telecommands have to be defined.
// Telecommands are global, toodouble TC_hard_min; // Hard lower limit
double TC_soft_min; // Soft lower limitdouble TC_soft_max; // Soft upper limitdouble TC_hard_max; // Hard upper limitdouble TC_ry_gain; // Commandable Gain for Roll/Yawdouble TC_nut_gain; // Nutation control gain;double TC_irad; // Moment of inertia wheeldouble TC_torque_pause; // Minimum time between torque commandsdouble TC_angle; // Maximum angle between pitch and torquedouble TC_trod; // Dipolementsdouble TC_coil_on; // Time the torquer is usually on, 10s (?)double TC_w_estimate; // Note that this is only the estimate
8/22/2019 AttSim Manual RevB
25/36
Microcosm Proprietary Do Not Distribute Without Permission
25
double TC_period; // Period in seconds
Upon initial call, AttSim repeats the input file, and adds orbital parameters that are not di-
rectly specified, but of interest to the user, such as the apogee and perigee height.
4 different control modules are supplied with AttSim:
1. A three axis stabilized, zero-momentum spacecraft with 3 reaction wheels and an accu-rate star sensor.
2. An inertial scanner, momentum biased, with the wheel axis pointing into the sun, and thetelescope axis rotating at a pre-determined, slow speed (once per orbit). It uses a fine sun
sensor and a rate gyro.
3. A momentum biased, earth oriented spacecraft with a pitch and roll horizon sensor, andthe wheel pointing into the pitch axis. This spacecraft does not measure yaw, but relies on
roll-yaw coupling.
4. A gravity gradient satellite, with magnetic torquers damping the spacecraft using the
magnetometer.
The numbers above identify the control module, e.g. the zero-momentum controller is named
control1.c. To change a controller, the following procedure has to be performed:
1. In SimInit, function initacs(), change the type of the satellite to the desired type (see be-low). Note that the name of the satellite type is case sensitive and has to be typed cor-
rectly.
2. In the Turbo-C project window, remove the old controller and insert the controller, thatcorresponds the desired satellite type (e.g. control1.c for "ZeroMomentum").
3. Make sure, that the input arguments to AttSim (under "Run" and "Arguments" in TurboC) show the correct satellite file; use KACST1.SAT and KACST2.SAT for controller 1,3,
and 4, and KACST3.SAT for the inertial controller.
4. In case of the inertial scanner, please note that some of the output data have no meaningbecause it uses a different set of error angles. The correct error angles must be changed in
the source code of the module Dynamics.c.
Siminit.c, satellite type definition
/* Definitions in Sim.h :#define ZeroMomentum 1#define InertialScanner 2#define MomentumBiased 3#define GravityGradient 4 */
More on the control modules is described below.
6.1. Zero-Momentum Control1.CThis spacecraft represents the highly accurate, high cost attitude control solution. The con-
troller consists of 3 PID control loops, one for each axis. Cross-coupling is treated as a distur-
bance, and fair amount of angular momentum can be stored in the reaction wheels, before it
8/22/2019 AttSim Manual RevB
26/36
Microcosm Proprietary Do Not Distribute Without Permission
26
disturbs the motion visibly11. A momentum dumping routine is overlaid, using the magnetic
torquers to lower the reaction wheel speed. At the same time, this routine avoids a zero speed
and keeps the reactions wheels at a minimum rate, thereby avoiding zero-rate crossings during
attitude control maneuvers.
The result of a zero-momentum simulation is shown in
Figure 5.
Figure 5: Zero-Momentum Spacecraft Simulation. The right window is a zoom on the pitch
axis. Note the zoom-factor of 64 in the upper left corner of this window.
Figure 5 is a good example to explain the text windows (lower left and lower right window).
The lower left window shows simulation results, starting with the type of attitude controller
defined in siminit.c. If the simulation produces funny results, this is a good place to check the
correct initialization. The total angular momentum is shown next (H[0]), and although the
spacecraft is a zero-momentum spacecraft, it will accumulate angular momentum, at least at
the orbital rate. The Nutation is meaningless in the zero-momentum case, but it is defined as
the angle of the angular momentum (in body coordinates) from the vehicles Z-axis. Without
nutation, this value is supposed to be 90 degrees. With nutation, it will oscillate around 90 de-
grees, indicating a nutation. The following angular rates are in RPM, and apart from the yaxis, should be close to 0. The y-axis should show the orbital rate at the given altitude, in this
case 0.0101 RPM or 1/5940.6 1/sec. The wheel rates, again in RPM, indicate a healthy state.
The wheel rates are followed by an overview of environmental torques, such as aerodynamic,
solar pressure, gravity gradient, magnetic residual, and control torque (although the later is
11 The current version, modified from a much larger satellite, uses huge momentum wheels. Should be
changed to a more appropriate wheel for a small satellite12 This depends on the distance between the torquer and the magnetometer, and the way the B-Dot
measurement is made.
8/22/2019 AttSim Manual RevB
27/36
Microcosm Proprietary Do Not Distribute Without Permission
27
not exactly an environmental torque). Note that the residual magnetic torque is set to 0 in the
simulation run shown in Figure 5.
The next column shows the simulation time in minutes and seconds, the file code (to associate
the screen shot with the data files), the remaining memory (for tests, to find memory leaks)
and a counter that counts steps executed. It continues with the magnetic field magnitude
(B[0]) in nT, and the roll, pitch and yaw angles. For information, the longitude and latitude of
the current position are shown, along with the altitude above the earth ellipsoid. The semi-
major axis is shown in km, and the flag sun or night indicates whether the spacecraft is in
sunlight or eclipse.
The right window shows controller data, or telemetry. It starts with the torque command to
each wheel on board. The zero-momentum spacecraft is the only one that uses all three
wheels, other controllers will use one wheel or none. Roll, pitch and yaw angle are as meas-
ured, i.e. with noise and, if desired, bias. These angles differ from the ones in the simulation
window because of the noise, and they actually are different in Figure 5. The entry angle is
the angle between the desired magnetic control torque and the wheel axis, and it has no
meaning in the case of the zero-momentum spacecraft. The dipole moments, or better com-
manded dipole moments are shown next. Again, these data may differ from the actual dipole
moment, because the torquer use a ramp to softly switch on or off, avoiding high currents.
NOTDEFINED refers to attitude sub-mode and the status of the momentum managementsystem. The zero-momentum controller performs a constant momentum management, and
there is only one mode defined (NOTDEFINED has been replaced by a more appropriate
NORMAL). GO/NOGO is an inhibit on the torquer in case the magnetic torque would be very
inefficient.
The Zero-Momentum spacecraft runs with either the KACST1.SAT or KACST2.SAT input
file.
6.1.1. The B-Dot LawThe B-Dot Law is a detumbling algorithm that orients the spacecraft momentum normal to the
orbital plane. It is described by References 8 and 9, and is very effective to damp initial an-
gular rates caused by a rough deploy from a launcher. The B-Dot law switches the torquers
proportional to the change in the magnetometer signal.
The detumbling algorithm, using B-Dot, exists in all controllers; for simplicity, it may neglect
the effect of the torquer on the magnetometer, which must be considered for the real flight
code12. To force the spacecraft into the detumbling mode, the mode command in the function
preparebuffer() in Dynamics.c must be set to DETUMBLE. At the same time, it is recom-
mended to give the spacecraft an angular momentum kick in Siminit.c, function Initacs().
6.2. Inertial Scanner Control2.CThe inertial scanner is a momentum biased spacecraft, that uses a sun sensor to point the
wheel axis to the sun. It rotates around that axis roughly once per orbit, to scan the sky; the
orbital motion causes a full sky survey in a few weeks, depending on the orbit. This model
uses a rate-gyro for the scanning motion, and torquers to correct the pointing and dump mo-mentum simultaneously.
8/22/2019 AttSim Manual RevB
28/36
Microcosm Proprietary Do Not Distribute Without Permission
28
Figure 6: Coordinate System of the Inertial Scanner
The controller uses angular rate estimates (by a rate gyro) to control nutation, but with a fairly
high pointing requirement, it does not have a lot of stability margin. In fact, slight changes in
the gains make the system go unstable quickly, and the current configuration has not been
tested for long-term stability with regard to momentum management and nutation damping.
This is the key reason why the moments of inertia have not been changed to either the 50 kg
or the 500 kg spacecraft; it corresponds to a 400 kg spacecraft. The time interval during which
the torquer is activated has been shortened, to account for the rather short nutation period and
provide sufficient damping.
8/22/2019 AttSim Manual RevB
29/36
Microcosm Proprietary Do Not Distribute Without Permission
29
Figure 7: Inertial Scanner. Note that the target window, lower middle, has no meaning for
an inertial pointing spacecraft, as have the roll, pitch and yaw angles. Satellite has been de-
ployed with an initial error and corrects for it.
Most of the simulation screen and file output has been set up for an earth oriented spacecraft,
and data regarding the inertial oriented spacecraft are missing on the screen (these data do
exist, however, within the simulation code).
The Inertial Scanner runs only with the KACST3.SAT input file.
6.3. Momentum Biased Control3.cThis control system is a low-cost, medium performance system. It uses horizon sensors with a
0.2 degree, 1-sigma error, and no yaw sensor at all. For the yaw axis, it relies on roll/yaw
coupling. This implies that the spacecraft has originally been oriented using a course sun sen-
sor, and uses the momentum wheel stiffness from there on. The wheel is small, 2 Nms, and
the torquer have 5 Am2 dipole moment only. The moments of inertia and the mass of the
spacecraft have been changed, to simulate a 50 kg spacecraft with a small solar array. Con-
troller gains had not been optimized and should be verified for optimal performance and long-
term stability.
8/22/2019 AttSim Manual RevB
30/36
Microcosm Proprietary Do Not Distribute Without Permission
30
Figure 8: Momentum Biased Spacecraft Coordinate System. This coordinate system is identi-
cal with the zero-momentum and the gravity gradient system, with the exception of the wheel
configuration in both cases.
Figure 9: Momentum Biased Spacecraft Simulation Results
The controller usually requires information on the yaw and roll rate, in order to damp out nu-
tation. Since there is no yaw sensor in this case, only the roll rate is available, and even this
8/22/2019 AttSim Manual RevB
31/36
Microcosm Proprietary Do Not Distribute Without Permission
31
has to be derived from the horizon sensor measurement. This cause the controller gains to be
sensitive and less stable; on the other hand, it saves an additional sensor. An alternative ap-
proach would be a gyrocompass configuration, which would require a gyro package and bet-
ter horizon sensors. The horizon sensors used in this model have 0.2 degrees 1-sigma noise,
which can be clearly seen in Figure 9, comparing the simulation and the controller results in
roll and pitch.
6.3.1. Momentum Management RoutinesLike the zero momentum spacecraft, this control system uses a momentum dumping routine
that uses three stages. If the wheel is within a specified normal speed range, the operating
mode is called NORMAL, and the system does not try to charge or discharge any momen-
tum. In this mode, the wheel supports the missing component of the magnetic torque, which
is limited to the plane perpendicular to the magnetic field. If the possible magnetic torque and
the wheel are above a certain angle, the controller considers the operation as ineffective and
cancels it (the angle is shown in controller, lower right, window as angle).
If the wheel speed goes beyond the NORMAL range, the controller enters the
SOFTCHARGE mode. In SOFTCHARGE, it only corrects the attitude if it would bring the
wheel back to NORMAL. This mode actually extends the operating mode.
6.4. Gravity Gradient Control4.cThis spacecraft model uses a long boom to create a stable, gravity-gradient attitude. It uses the
torquer to damp the initial motion, but this controller is not required to keep the system stable
(except for yaw). The controller has not been tested thoroughly, and is only part of the AttSim
package because the uncontrolled motion demonstrates the characteristics of a gravity gradi-
ent system. Reference 7 describes the controller used here. To disable the controller, set the
mode to FROZEN in preparebuffer(), Dynamics.c.
It is important to match the orbital rate in pitch after deploy. This satellite has an initial angu-
lar momentum in the pitch axis, that causes it to rotate at the angular rate of the orbital period.
A change in angular momentum, or in orbital altitude will cause a different initial rate, withpossibly destabilizing effects.
8/22/2019 AttSim Manual RevB
32/36
Microcosm Proprietary Do Not Distribute Without Permission
32
Figure 10: Gravity Gradient Simulation Results
8/22/2019 AttSim Manual RevB
33/36
Microcosm Proprietary Do Not Distribute Without Permission
33
7. Output File Format
AttSim provides a screen output as shown in Figure 2 and 6 different output files. The files
are written in the main module Dynamics.c, function fileoutput(), where changes can easily
implemented. The files are initialized in Siminit.c, and closed in Dynamics.c after the main
loop has been exited
13
. The files are ASCII files, values separated by spaces, and can be readby Excel or Matlab. Six files are created, and the filename consists of 4 letter for the filename
and 3 letters for a user-defined code, followed by the extension .dat. The files are described
in Table 5.
Table 5: AttSim Output Files
Name Function Remark
MISC Miscellaneous data, usually attitude error,
shadow, nutation angle
Typically the most important file, and
frequently changed
POSI Position data, altitude, latitude and longi-tude
Repeats the input file (*.sat) in the firstlines for documentation
DYNA Dynamical data, such as density, torques
(aero, sun, magnetic), torquer dipole
commands
Magnitude of the disturbance torques
LAGE Quaternion May be useful for hardware in the loop
tests14.
RATE Angular rates of satellite and selected
wheels
Important file for the angular momentum
management of the wheels
IGRF Magnetic field (B) in body coordinates Only occasionally useful
Each line starts with the time in seconds, followed by the data. The format of each file can be
determined from the source code, given below:
void fileoutput(SATELLITE *s, double *outbuffer, double *cb){// Output Files -----------------------------------------------------
if (fmisc!=NULL){fprintf(fmisc,"%10.2f ",outbuffer[1]);
//fprintf(fmisc,"%4d ",dark); // Shadow, 1 = TRUEfprintf(fmisc,"%10.3f ",grad(cb[1])); // True Roll
13 If AttSim is used for hardware in the loop tests, it is highly recommended to change this procedure
and to close the files after each call to fileoutput(). In the event of an error or a power surge, the results
would still be available. For software simulation only, computation time can be saved by closing the
files at the end of the program execution.14 LAGE is the German word for attitude; originally, there was a program that could re-play the quater-
nion file. Today, such a function should be implemented into Matlab, because it would allow a decent
printout of the result for documentation.
8/22/2019 AttSim Manual RevB
34/36
Microcosm Proprietary Do Not Distribute Without Permission
34
fprintf(fmisc,"%10.3f ",grad(cb[2])); // True Pitchfprintf(fmisc,"%10.3f ",grad(cb[3])); // True Yawfprintf(fmisc,"%10.5f ",grad(wwz(s->h))); // Nutation//fprintf(fmisc,"%10.3f ",grad(cb[41])); // Measured Pitchfprintf(fmisc,"\n");
}if (fposi!=NULL)
{ fprintf(fposi,"%10.2f ",outbuffer[1]/SECOFDAY);fprintf(fposi,"%10.3f ",s->rs[Z]); // Altitudefprintf(fposi,"%10.3f ",grad(s->rs[X])); // Latitudefprintf(fposi,"%10.3f ",grad(s->rs[Y])); // Longitudefprintf(fposi,"%12.5f ",s->ce->a); // Semimajor axisfprintf(fposi,"%10.5f ",s->ce->e) ; // Eccentricityfprintf(fposi,"\n");
}if (fdyna!=NULL){fprintf(fdyna,"%10.2f ",outbuffer[1]);fprintf(fdyna,"%12.4e ",outbuffer[2]); // Densityfprintf(fdyna,"%12.4e ",s->ma[0]); // Aerotorquefprintf(fdyna,"%12.4e ",s->ms[0]); // Suntorque
fprintf(fdyna,"%12.4e ",s->mg[0]); // Gravity Torquefprintf(fdyna,"%12.4e ",s->mb[0]); // Magnetic Res.fprintf(fdyna,"%6.1f " ,s->dm[X]); // Torquer Xfprintf(fdyna,"%6.1f " ,s->dm[Y]); // Torquer Yfprintf(fdyna,"%6.1f " ,s->dm[Z]); // Torquer Z
fprintf(fdyna,"\n");}if (flage!=NULL){fprintf(flage,"%10.2f ",outbuffer[1]);fprintf(flage,"%10.6f ",s->q[0]); // Quaternionfprintf(flage,"%10.6f ",s->q[X]);fprintf(flage,"%10.6f ",s->q[Y]);fprintf(flage,"%10.6f ",s->q[Z]);
fprintf(flage,"\n");}if (frate!=NULL){fprintf(frate,"%10.2f ",outbuffer[1]);fprintf(frate,"%10.5f ",RPM*s->w[X]); // Angular velocitiesfprintf(frate,"%10.5f ",RPM*s->w[Y]);fprintf(frate,"%10.5f ",RPM*s->w[Z]);fprintf(frate,"%10.2f ",RPM*s->ww[Y]);fprintf(frate,"\n");
}if (figrf!=NULL){fprintf(figrf,"%10.2f ",outbuffer[1]); // Magnetic field
in body coordinates
fprintf(figrf,"%10.3f ",s->bb[X]);fprintf(figrf,"%10.3f ",s->bb[Y]);fprintf(figrf,"%10.3f ",s->bb[Z]);fprintf(figrf,"%10.3f ",s->bb[0]);fprintf(figrf,"\n");
}}
With a basic understanding of the fprintf command and the format string, the user can under-
stand the file format. For more information on the fprintf format, refer to [6]. Matlab files to
8/22/2019 AttSim Manual RevB
35/36
Microcosm Proprietary Do Not Distribute Without Permission
35
read the AttSim data into Matlab are provided for the output files MISC, POSI, DYNA,
RATE and IGRF. These scripts should be considered as templates or starting points only, be-
cause they can easily be changed and adapted for a specific application. If the output file for-
mat is changed, the Matlab files have to be changed accordingly. Nevertheless, Matlab pro-
vides a powerful tool to process the output data and document simulation results. A typical
plot showing the result of a simulation run is shown in Figure 11.
Figure 11: Typical error plot using the error data in file miscxxx.dat
0 50 100 150 200 250 300 350 400 450
-2
0
2
Roll Error
Time (m)
0 50 100 150 200 250 300 350 400 450
-2
0
2
Time (m)
Pitch Error
0 50 100 150 200 250 300 350 400 450
-2
0
2
Time (m)
Yaw Error
It is highly recommended to use a logbook to log the simulation runs, track the changes in theprogram and the controller and the codes associated with the output file. The default output
code is 000.
In addition to the data files, AttSim saves the screen as a GIF format picture. This picture can
be read with most viewers, such as Netscape, and provides a top-level overview of the simu-
lation run results. The name of the file is sim + code + .gif.
8/22/2019 AttSim Manual RevB
36/36
Microcosm Proprietary Do Not Distribute Without Permission
8. References
[1] Wertz, James (ed.) : Spacecraft Attitude Determination and Control, 1978
[2] Escobal, Pedro R. : Methods of Orbit Determination, J. Wiley and Sons, 1965
[3] Seidelmann, K. (ed.): Explanatory Supplement to the Astronomical Almanac, University
Science Books, California, 1992
[4] Valado, D. A. : Fundamentals of Astrodynamics and Applications, McGraw-Hill, Space
Technology Series, 1997
[5] Hughes, P. C. : Spacecraft Attitude Dynamics, J. Wiley & Sons, 1986
[6] Kernighan, Ritchie : The C Programming Language, 2nd edition, Prentice-Hall, 1988
[7] Francois Martel, et.al. Active Magnetic Control System for Gravity Gradient Stabilized
Spacecraft, Utah State University Conference on Small Satellites, 1988
[8] Stickler, Alfried: Elementary Magnetic Attitude Control System, Journal Spacecraft andRockets, Vol. 13, No.5 May 1976
[9] Wolfe, Alfriend and Leonard: A Magnetic Attitude Control System for Sun Pointing Sat-
ellites, AAS 95-416, 1995
[10] Alfriend: Magnetic Attitude Control System for Dual-Spin Satellites, AIAA Journal,
Vol. 13, No.6, June 1976
[11] Hedin, Alan: MSIS-86 Thermospheric Model, JGR, Vol. 92, No. A5, May, 1987
[12] Hedin, Alan: The Atmospheric Model in the Region 90 to 2000 km, Adv. Space res.,
Vol. 8, No. 5-6, 1988