. . . . . . . . . .

Microcosm, Inc. 401 Coral Circle El Segundo, CA 90245 MC 99-0201 (REV A)

Microcosm, Inc

AttSim User Manual

. . . . . . . . . .

The Satellite Attitude Simulator with Software-in- the-Loop Verification Capability

Microcosm Proprietary Do Not Distribute Without Permission

Table of Contents
1. AttSim Introduction__________________________________________________ 4 2. Installation_________________________________________________________ 6 3. AttSim Configuration ________________________________________________ 7 4. Module Dynamics.c__________________________________________________ 9
4.1. 4.2. 4.3. 5.1. 5.2. 5.3. 5.4. 6.1. 6.2. 6.3. 6.4. The Data Structures___________________________________________________ 11
Units __________________________________________________________________ 13 Euler angles _____________________________________________________________ 15 4.1.1. 4.2.1.

Coordinate Systems ___________________________________________________ 13 Integration __________________________________________________________ 15 Input File Format_____________________________________________________ 17 Initialization Function _________________________________________________ 18 Keyboard commands __________________________________________________ 20 Command line parameters _____________________________________________ 21 Zero-Momentum Control1.C__________________________________________ 25
The B-Dot Law __________________________________________________________ 27

5. Module Siminit ____________________________________________________ 17

6. Module(s) Control.c ________________________________________________ 23

6.1.1.

Inertial Scanner Control2.C __________________________________________ 27 Momentum Biased Control3.c _________________________________________ 29

Momentum Management Routines ___________________________________________ 31

6.3.1.

Gravity Gradient Control4.c __________________________________________ 31

7. Output File Format _________________________________________________ 33 8. References ________________________________________________________ 36

Microcosm Proprietary Do Not Distribute Without Permission

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 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 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 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

Microcosm Proprietary Do Not Distribute Without Permission

1. AttSim Introduction
AttSim is an attitude simulator developed for spacecraft attitude control design and verification. 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 addition, AttSim can be used as a system engineering tool to ensure correct torquer sizing, wheel sizing, 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 disturbances. 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 original 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. Another advantage is that the Borland C compiler produces stable code and allows easy and reliable 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 parameters, 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)

AttSim Functional Diagram

Orbit Simulation

Environmental Models (Density, Geomagnetic Field)

Attitude Simulation

Control Module

Output (File and Screen)

Output (File and Screen)

After being adapted to the flight computer specific environment 4

Microcosm Proprietary Do Not Distribute Without Permission

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 satellite is in the center of this unit sphere, and its axes are tracing a path onto the sphere to visualize 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 unitsphere, 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 vehicle'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 a white 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 controller telemetry data. Window 4 shows the Nadir angle in the vehicle coordinate frame, illustrating 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.

Microcosm Proprietary Do Not Distribute Without Permission

2. Installation
To install AttSim: 1. 2. 3. Install Turbo-C 3.0 first, preferably in a directory called TC. Copy the folder KACST from the AttSim disk into this folder, thereby creating the subfolder KACST under TC Change directory into that folder, and type TC ATTSIM.PRJ. This will load Turbo C and the AttSim project at the same time. If the project file is not visible, check Windows, 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 can be 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.

Microcosm Proprietary Do Not Distribute Without Permission

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 recommended 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 modules is well with comments.
Table 1: AttSim Modules Overview

Module Cira.c

Main Function MSIS 86 atmospheric model

Remarks No changes required usually; code is kept close to the FORTRAN code, e.g. variable names are similar. Semi-empirical model with many parameters No changes required usually; contains data required for Cira.c

Cira.h

MSIS 86 atmospheric model parameters Flight Control Code

Controlx.c

File has to be changed for each satellite model; contains attitude controller and hardware models for each axes. The "x" is replaced by a number, 1,2... This module contains the main function, driving AttSim. Contains the file output function, and the screen output toplevel function. The integration intervals and the simulation duration is adjusted here, but changes should be limited to these parameters No changes required usually, provided to facilitate documentation only. This module is not part of AttSim. Draws the unitsphere on the screen, and vectors and great circles onto it. Allows a variety of different drawing styles and should not be changed. 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. Function prototypes, definitions (#define), and data structure definitions.

Dynamics.c

Main module with orbit and attitude integration

Gifsave.c

Saves the screen as a *.gif file Unit sphere functions

Ehkbs.c

Siminit.c

Initialization functions

Sim.h

Header file for all modules

Microcosm Proprietary Do Not Distribute Without Permission

Solarflux.c

Module for historic F10.7 cm solar flux and Ap magnetic activity Object file

No changes required usually; Module contains only the function to interpolate historic solar flux F10.7 cm values and corresponding Ap magnetic index.(2)

Svga.obj

No changes required; Driver for the Borland Graphics Interface (BGI) No changes required; Contains utility functions such as vector and matrix functions, coordinate transformations, and other mathematical functions. List of source and object files, with preferences. Use caution with compiler and linker options! File that contains the configuration for Ehkbs.c, e.g. the rotation of the unit sphere and the colors. Not required to run AttSim, but makes changing the perspective of the unit spheres easier. Satellite file provided as input to AttSim on the command line. Contains the satellite orbit and the initial attitude in inertial (!) space.(3)

Utility.c

Module for utility functions

Attsim.prj

Project file

Attsim.cfg

Configuration file

*.sat

Satellite file(s)

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

Microcosm Proprietary Do Not Distribute Without Permission

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 simtime faststep fasttime slowstep slowtime filestep filetime = = = = = = = = 0.1; 0.0; 1.0; 0.0; 2.0; 0.0; 10.0; 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 normalization 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.

Microcosm Proprietary Do Not Distribute Without Permission

Figure 3: Main Function Schematic

The function calls in the slow loop, the fast loop and the file loop do not have to be synchronized, 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 determination with either Kepler's equation or a numerical integration, and the IGRF magnetic field
10

Microcosm Proprietary Do Not Distribute Without Permission

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 incorporated 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 keyboard command is "r", which suppresses most of the screen output and speeds up the simulation significantly.

4.1. The Data Structures

The 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], MATRIX 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 is stored 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 Anomaly double mm,i,e,w; // Mean Motion, Incl., Excentr.,Perig. double W,ut,a,b; // RAAN, Period, Semimajor and -minor Axis double rp,p; // Radius Perigee, Orbit parameter double epoche; // JD of Epoch of orbital element, double epodata; // Epoch of original dataset, constant double lastperi; // Last perigee, JD double firstperi; // First perigee, JD, old double gha; // Greenwich Hour Angle, might not be up to date double 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.

The definition double[4] defines u[0], u[1], u[2] and u[3]; u[4] would be a violation. 11

Microcosm Proprietary Do Not Distribute Without Permission

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. GMT ORBIT *ce; // Classical elements // Radiusvector in varius coordinate systems VECTOR rr,rp,rq,rb,re,rs; // Velocityvector in varius coordinate systems VECTOR vr,vp,vq,vb,ve,vs; // Magnetic field vector in varius coordinate systems VECTOR br,bp,bq,bb,be,bs; // -------------------------------------------------------------VECTOR fa; // Aerodynamic Forces (in inertial coordinates) VECTOR fs; // Solar Pressure Forces ( " ) VECTOR offa; // Vector from CoM to CoP VECTOR offs; // Vector from CoM to solar CoP VECTOR offd; // Vector of magnetic Dipolmoment of satellite VECTOR dm; // Dipolemoment of torquer, if any VECTOR mc; // Control torque VECTOR ma; // Aerodynamic torque VECTOR ms; // Solar torque VECTOR mg; // Gravity gradient torque VECTOR mb; // Magnetic torque VECTOR m; // Sum of all disturbance torques VECTOR w; // Angular velocity in body coordinates VECTOR hw; // Angular momentum of wheels.... VECTOR ww; // Wheel speed VECTOR mt; // Motor torque of the wheel VECTOR h; // Angular momentum of total satellite in body coordinates VECTOR q; // Quaternion VECTOR euler; // Euler angle, for better interpretation MATRIX I,W; // Moment of inertia (I) and its invers (W) MATRIX ab; // Body Matrix double IW; double mass; double area; double cd; } SATELLITE; // Moment of inertia of wheel, 4 Nms

There are numerous position and velocity vectors in a variety of coordinate systems, to be explained briefly. The second letter after r or v corresponds to the coordinate system. The control and disturbance torques, if not otherwise indicated, are given in the satellite body coordinates. 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 only used 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 describes the vehicles attitude. The general idea behind the consolidation of all relevant vehicle data into one single structure
12

Microcosm Proprietary Do Not Distribute Without Permission

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. Units
AttSim uses SI units, with a few exceptions. Time is measured in seconds, except for the Julian 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 coefficients for satellites are extremely difficult to estimate and depend on many parameters, such as surface material and temperature.

4.2. Coordinate Systems

The 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.

See Wertz, [1] page 20 13

Microcosm Proprietary Do Not Distribute Without Permission

Table 2: Coordinate Systems Definitions

Letter r p

Name Not used Orbit Plane Coordinate System Inertial System (ECI) Body System

Definition N/A Origin in geocenter; +X to perifocus, and +Z perpendicular to the orbital plane to orbital normal. (earth-centered, inertial) Origin in geocenter; +X to vernal equinox, +Z to North Pole. Defined by the user input of the moments of inertia and other paremeters, such as wheel orientation (earth-centered, earth-fixed) Origin in geocenter; +X to the Greenwich meridian, +Z to the North Pole. 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. Describes the position vector in geographical latitude, longitude, and altitude above the earth ellipsoid.

Remark System 8 in [2], p. 144

System 2 in [2], p. 135; used for right ascension and declination Does not have to be aligned with the principal axes System 3 in [2], p.135

ECEF

s in combination with b-vector s in combination with r-vector

Spherical

Used for the geomagnetic field model

Spherical

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 defined by the inclination i, the argument of perigee w, and the argument 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 into earth 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 km into geographical latitude, longitude and altitude. Altitude is above the ellipsoid, in km. Lat/long is in radians. s stand for spherical, output is xs.

14

Microcosm Proprietary Do Not Distribute Without Permission

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 between 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 angles

Euler 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 corresponds 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 tricky6, 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. Integration

AttSim uses a 4th order Runge-Kutta algorithm with a fixed step-size to integrate the dynamical 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 routine 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 significantly. It can, in fact, stabilize an otherwise unstable attitude control configuration, or stabilize 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<5;i++) hn[i] = 0.0;

6

Nevertheless, this 3-1-3 rotation survived almost 10 years and has never been changed. When using an existing rotation, the initial attitude can be experimentally found. Alternatively, simplified constellations of orbit and attitude can be found. 7 In fact, I do not recall such a case in almost 10 years operation with this particular routine. 15

Microcosm Proprietary Do Not Distribute Without Permission

for (i=0;i<4;i++) qn[i] = 0.0; for (i=0;i<4;i++) a[i] = 0.0; // Assumption for the damping damp[X] = -0.0001*s->w[X]; damp[Y] = -0.0001*s->w[Y]; damp[Z] = -0.0001*s->w[Z]; // Damping is primarily proportional to angular velocity s->m[X] += damp[X]; s->m[Y] += damp[Y]; s->m[Z] += damp[Z]; // Integration of equation of motion

etc.

16

Microcosm Proprietary Do Not Distribute Without Permission

5. Module Siminit
5.1. Input File Format
AttSim 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 Here 1994 ; Year 2 ; Month 9 ; Day 19 ; Hour 23 ; Minute 19.000000 ; Seconds 7321.557960 ; Semimajor axis A in km 33.083100 ; Mean anomaly in degrees 50.0 ; Inclination in degrees .000385 ; Eccentricity 21.109100 ; Argument of perigee 170.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 comments, 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 format uses the position state vector as follows:
Satellite Name Here 1994 ; Year 2 ; Month 9 ; Day 19 ; Hour 23 ; Minute 19.000000 ; Seconds 7321.557960 ; Semimajor axis A in km 33.083100 ; Mean anomaly in degrees 50.0 ; Inclination in degrees .000385 ; Eccentricity 21.109100 ; Argument of perigee 170.0 ; Right Ascension of ascending node -3541.887081 ; X in km -3438.500950 ; Y in km 4572.212109 ; Z in km 6.495895685 ; dX/dt in km/s -1.668515243 ; dY/dt in km/s 3.775988954 ; dZ/dt in km/s -60.0 ; Angle about Z0 -125.0 ; Angle about X1 -35.0 ; Angle about Z2

17

Microcosm Proprietary Do Not Distribute Without Permission

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 Function

Most 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 additional explanations is given below:
//------------------------------------------------------------------void initacs(SATELLITE *s) { // Moments of inertia, full matrix s->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 now s->IW = 0.01; // -------------------------------------------------// Angular momentum of wheels s->hw[X] = 0.0; s->hw[Y] = 2.0; s->hw[Z] = 0.0; // Angular momentum of satellite body s->h[X] = s->hw[X]; // + 0.5; // KICK s->h[Y] = s->hw[Y]; s->h[Z] = s->hw[Z]; // Magnitudes s->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 initilisation s->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 18

Microcosm Proprietary Do Not Distribute Without Permission

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 wheels s->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 body system s->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 attitude s->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 input 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 vector s->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. 19

Microcosm Proprietary Do Not Distribute Without Permission

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 estimate, 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 implementing a new satellite model. Note that the moments of inertia might very well have deviation 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 implementation is shown below:
/* Definitions in Sim.h : #define ZeroMomentum #define InertialScanner #define MomentumBiased #define GravityGradient 1 2 3 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, AttSim will not run properly.

5.3. Keyboard commands

During a simulation run, AttSim responds to keyboard inputs as shown in Table 3.

In some cases, aerodynamic models may be available; for control code development, offset vectors are a good approximation 20

10

Microcosm Proprietary Do Not Distribute Without Permission

Table 3: Keyboard Commands

Key r

Action Freezes the screen output except for the axes on the unit sphere

Remark Speeds up the simulation significantly, but causes the GIF file saved at the end of a simulation to represent an old screen.

p z

Pause; press any key to continue 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 distorted for higher zoom ratios. Causes empty windows if used in combination with r

Zoom reset. Looses all information that has been drawn on the screen. Saves the current screen as GIF picture Returns to DOS; return to AttSim with exit Quit. A small dialog is displayed, asking whether the screen should be saved as GIF file and if the user really wants to quit.

Do not use without prior testing!

5.4. Command line parameters

When 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 satellite input file (*.sat file), and without an input file, AttSim terminates with a warning message. The input file can be followed by a parameter as shown in Table 4.

21

Microcosm Proprietary Do Not Distribute Without Permission

Table 4: Command Line Parameters

Command +d -d +c -c

Function File output No file output Control on No control

Remarks Default

Default (inoperative do not use)

?, +g, -g -k +k

Old functions do not use Use numerical integration for position 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 development, when the simulator is used to test changes to the control code.

22

Microcosm Proprietary Do Not Distribute Without Permission

6. Module(s) Control.c
The control module contains the flight code of the satellite attitude determination and control 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 work properly. 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 Shadow sonne(s->tjd,sun); dark = shadow(s->rq,sun); // Call control module if (first) {for (k=0;k<50;k++) controlbuffer[k] = 0.0;}; preparebuffer(s,controlbuffer,sun,simtime); control(controlbuffer); evaluatebuffer(s,controlbuffer,simtime); // Screenoutput buffer[1] = simtime; buffer[2] = density; if (option[4]) screenoutput(s,buffer,controlbuffer,simtime); fasttime = floor(simtime)+faststep; }

Fasttime is the time variable that drives the controller call, and after an update on the sun status, the controlbuffer is prepared in a separate function. The content of the control buffer has been different depending on the type of controller used; an earth oriented spacecraft needs other (simulated) sensor data than an inertial pointing spacecraft. The control buffer is documented in the source code of control.c. Note that the module returns the sensor data it uses, to allow comparison of the data created by the simulator and the sensor model data, which include noise. In general, Control.c uses hardware interface functions to add errors and bias to the sensor data, as shown in Figure 4. These functions are defined in the header file hardware.h; although every control module contains all hardware interface functions, only a few are used.

23

Microcosm Proprietary Do Not Distribute Without Permission

Figure 4: Control Module Integration

Prepare Buffer Sensor Interface Functions Input Data Horizon Sensor Sun Sensor Magnetometer etc..

Controller Main Function Output Data Evaluate Buffer

Actuator Interface Functions Momentum Wheel Torquer etc.

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 momentum wheel torque or a dipole moment to the magnetic torquer is processed by similar functions, 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, too double TC_hard_min; // Hard lower limit double TC_soft_min; // Soft lower limit double TC_soft_max; // Soft upper limit double TC_hard_max; // Hard upper limit double TC_ry_gain; // Commandable Gain for Roll/Yaw double TC_nut_gain; // Nutation control gain; double TC_irad; // Moment of inertia wheel double TC_torque_pause; // Minimum time between torque commands double TC_angle; // Maximum angle between pitch and torque double TC_trod; // Dipolements double TC_coil_on; // Time the torquer is usually on, 10s (?) double TC_w_estimate; // Note that this is only the estimate 24

Microcosm Proprietary Do Not Distribute Without Permission

double TC_period;

// Period in seconds

Upon initial call, AttSim repeats the input file, and adds orbital parameters that are not directly specified, but of interest to the user, such as the apogee and perigee height. 4 different control modules are supplied with AttSim: 1. 2. A three axis stabilized, zero-momentum spacecraft with 3 reaction wheels and an accurate star sensor. An inertial scanner, momentum biased, with the wheel axis pointing into the sun, and the telescope axis rotating at a pre-determined, slow speed (once per orbit). It uses a fine sun sensor and a rate gyro. A momentum biased, earth oriented spacecraft with a pitch and roll horizon sensor, and the wheel pointing into the pitch axis. This spacecraft does not measure yaw, but relies on roll-yaw coupling. A gravity gradient satellite, with magnetic torquers damping the spacecraft using the magnetometer.

3.

4.

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 below). Note that the name of the satellite type is case sensitive and has to be typed correctly. In the Turbo-C project window, remove the old controller and insert the controller, that corresponds the desired satellite type (e.g. control1.c for "ZeroMomentum"). Make sure, that the input arguments to AttSim (under "Run" and "Arguments" in Turbo C) show the correct satellite file; use KACST1.SAT and KACST2.SAT for controller 1,3, and 4, and KACST3.SAT for the inertial controller. In case of the inertial scanner, please note that some of the output data have no meaning because it uses a different set of error angles. The correct error angles must be changed in the source code of the module Dynamics.c.

2. 3.

4.

Siminit.c, satellite type definition

/* Definitions in Sim.h : #define ZeroMomentum #define InertialScanner #define MomentumBiased #define GravityGradient 1 2 3 4 */

More on the control modules is described below.

6.1. Zero-Momentum Control1.C

This spacecraft represents the highly accurate, high cost attitude control solution. The controller consists of 3 PID control loops, one for each axis. Cross-coupling is treated as a disturbance, and fair amount of angular momentum can be stored in the reaction wheels, before it

25

Microcosm Proprietary Do Not Distribute Without Permission 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 degrees, indicating a nutation. The following angular rates are in RPM, and apart from the y axis, 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 satellite 12 This depends on the distance between the torquer and the magnetometer, and the way the B-Dot measurement is made.

26

Microcosm Proprietary Do Not Distribute Without Permission

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 semimajor 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 measured, 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 commanded 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 management system. 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 Law

The 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 angular 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 recommended to give the spacecraft an angular momentum kick in Siminit.c, function Initacs().

6.2. Inertial Scanner Control2.C

The 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 momentum simultaneously.

27

Microcosm Proprietary Do Not Distribute Without Permission

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.

28

Microcosm Proprietary Do Not Distribute Without Permission

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.

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.c

This 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 sensor, 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. Controller gains had not been optimized and should be verified for optimal performance and longterm stability.

29

Microcosm Proprietary Do Not Distribute Without Permission

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.

Figure 9: Momentum Biased Spacecraft Simulation Results

The controller usually requires information on the yaw and roll rate, in order to damp out nutation. Since there is no yaw sensor in this case, only the roll rate is available, and even this
30

Microcosm Proprietary Do Not Distribute Without Permission

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 approach would be a gyrocompass configuration, which would require a gyro package and better 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 Routines

Like 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 momentum. 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.c

This 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 gradient 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 angular 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, with possibly destabilizing effects.

31

Microcosm Proprietary Do Not Distribute Without Permission

Figure 10: Gravity Gradient Simulation Results

32

Microcosm Proprietary Do Not Distribute Without Permission

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 exited13. The files are ASCII files, values separated by spaces, and can be read by 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 MISC

Function Miscellaneous data, usually attitude error, shadow, nutation angle Position data, altitude, latitude and longitude Dynamical data, such as density, torques (aero, sun, magnetic), torquer dipole commands Quaternion

Remark Typically the most important file, and frequently changed Repeats the input file (*.sat) in the first lines for documentation Magnitude of the disturbance torques

POSI

DYNA

LAGE

May be useful for hardware in the loop tests14. Important file for the angular momentum management of the wheels Only occasionally useful

RATE

Angular rates of satellite and selected wheels Magnetic field (B) in body coordinates

IGRF

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); fprintf(fmisc,"%10.3f ",grad(cb[1]));
13

// Shadow, 1 = TRUE // True Roll

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 quaternion file. Today, such a function should be implemented into Matlab, because it would allow a decent printout of the result for documentation. 33

Microcosm Proprietary Do Not Distribute Without Permission

fprintf(fmisc,"%10.3f ",grad(cb[2])); fprintf(fmisc,"%10.3f ",grad(cb[3])); fprintf(fmisc,"%10.5f ",grad(wwz(s->h))); //fprintf(fmisc,"%10.3f ",grad(cb[41])); fprintf(fmisc,"\n");

// True Pitch // True Yaw // Nutation // Measured Pitch

} if (fposi!=NULL) { fprintf(fposi,"%10.2f ",outbuffer[1]/SECOFDAY); fprintf(fposi,"%10.3f ",s->rs[Z]); // Altitude fprintf(fposi,"%10.3f ",grad(s->rs[X])); // Latitude fprintf(fposi,"%10.3f ",grad(s->rs[Y])); // Longitude fprintf(fposi,"%12.5f ",s->ce->a); // Semimajor axis fprintf(fposi,"%10.5f ",s->ce->e) ; // Eccentricity fprintf(fposi,"\n"); } if (fdyna!=NULL) { fprintf(fdyna,"%10.2f ",outbuffer[1]); fprintf(fdyna,"%12.4e ",outbuffer[2]); // Density fprintf(fdyna,"%12.4e ",s->ma[0]); // Aerotorque fprintf(fdyna,"%12.4e ",s->ms[0]); // Suntorque fprintf(fdyna,"%12.4e ",s->mg[0]); // Gravity Torque fprintf(fdyna,"%12.4e ",s->mb[0]); // Magnetic Res. fprintf(fdyna,"%6.1f " ,s->dm[X]); // Torquer X fprintf(fdyna,"%6.1f " ,s->dm[Y]); // Torquer Y fprintf(fdyna,"%6.1f " ,s->dm[Z]); // Torquer Z fprintf(fdyna,"\n"); } if (flage!=NULL) { fprintf(flage,"%10.2f fprintf(flage,"%10.6f fprintf(flage,"%10.6f fprintf(flage,"%10.6f fprintf(flage,"%10.6f fprintf(flage,"\n"); } if (frate!=NULL) { fprintf(frate,"%10.2f fprintf(frate,"%10.5f fprintf(frate,"%10.5f fprintf(frate,"%10.5f fprintf(frate,"%10.2f fprintf(frate,"\n"); } if (figrf!=NULL) { fprintf(figrf,"%10.2f in body coordinates fprintf(figrf,"%10.3f fprintf(figrf,"%10.3f fprintf(figrf,"%10.3f fprintf(figrf,"%10.3f fprintf(figrf,"\n"); } }

",outbuffer[1]); ",s->q[0]); ",s->q[X]); ",s->q[Y]); ",s->q[Z]);

// Quaternion

",outbuffer[1]); ",RPM*s->w[X]); ",RPM*s->w[Y]); ",RPM*s->w[Z]); ",RPM*s->ww[Y]);

// Angular velocities

",outbuffer[1]); ",s->bb[X]); ",s->bb[Y]); ",s->bb[Z]); ",s->bb[0]);

// Magnetic field

With a basic understanding of the fprintf command and the format string, the user can understand the file format. For more information on the fprintf format, refer to [6]. Matlab files to
34

Microcosm Proprietary Do Not Distribute Without Permission

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, because they can easily be changed and adapted for a specific application. If the output file format is changed, the Matlab files have to be changed accordingly. Nevertheless, Matlab provides 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
Roll Error 2 0 -2 0 50 100 150 200 250 Pitch Error 300 350 Time (m) 400 450

2 0 -2 0 50 100 150 200 250 Yaw Error 300 350 Time (m) 400 450

2 0 -2 0 50 100 150 200 250 300 350 Time (m) 400 450

It is highly recommended to use a logbook to log the simulation runs, track the changes in the program 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 simulation run results. The name of the file is sim + code + .gif.

35

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 and Rockets, Vol. 13, No.5 May 1976 [9] Wolfe, Alfriend and Leonard: A Magnetic Attitude Control System for Sun Pointing Satellites, 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

36