Editing Vessel Tutorial 2

= Take out the Trash =

== Aerodynamic Model ==

// Calculate lift coefficient [Cl] as a function of aoa (angle of attack) over -Pi ... Pi

// Implemented here as a piecewise linear function

double LiftCoeff (double aoa)

{

  const int nlift = 9;

  static const double AOA[nlift] = {-180*RAD,-60*RAD,-30*RAD,-1*RAD,15*RAD,20*RAD,25*RAD,60*RAD,180*RAD};

  static const double CL[nlift]  = {      0,      0,  -0.1,    0,  0.2,  0.25,  0.2,    0,      0};

  static const double SCL[nlift] = {(CL[1]-CL[0])/(AOA[1]-AOA[0]), (CL[2]-CL[1])/(AOA[2]-AOA[1]),

                                  (CL[3]-CL[2])/(AOA[3]-AOA[2]), (CL[4]-CL[3])/(AOA[4]-AOA[3]),

                    (CL[5]-CL[4])/(AOA[5]-AOA[4]), (CL[6]-CL[5])/(AOA[6]-AOA[5]),

                    (CL[7]-CL[6])/(AOA[7]-AOA[6]), (CL[8]-CL[7])/(AOA[8]-AOA[7])};

  for (int i = 0; i < nlift-1 && AOA[i+1] < aoa; i++);

  return CL[i] + (aoa-AOA[i])*SCL[i];

}

  SetCW (0.3, 0.3, 0.6, 0.9);

  SetWingAspect (0.7);

  SetWingEffectiveness (2.5);

  SetCrossSections (_V(10.5,15.0,5.8));

  SetRotDrag (_V(0.6,0.6,0.35));

  if (GetFlightModel() >= 1) {

    SetPitchMomentScale (1e-4);

    SetBankMomentScale (1e-4);

  }

  SetTrimScale (0.05);

  SetLiftCoeffFunc (LiftCoeff);

== Hover engine ==

  th_hover = CreateThruster (_V(0,-1.5,0), _V(0,1,0), PB_MAXHOVERTH, ph_vernier, PB_ISP);

  CreateThrusterGroup (&th_hover, 1, THGROUP_HOVER);

  AddExhaust (th_hover, 8, 1, _V(0,-1.5,1), _V(0,-1,0));

  AddExhaust (th_hover, 8, 1, _V(0,-1.5,-1), _V(0,-1,0));

== Fancy Exhaust ==

  // ***************** thruster definitions *******************

  AddExhaustStream (th_hover, _V(0,-3, 1), &contrail_hover);

  AddExhaustStream (th_hover, _V(0,-3,-1), &contrail_hover);

  AddExhaustStream (th_vernier, _V(0,0.3,-10), &contrail_main);

  AddExhaustStream (th_hover, _V(0,-2, 1), &exhaust_hover);

  AddExhaustStream (th_hover, _V(0,-2,-1), &exhaust_hover);

  AddExhaustStream (th_vernier, _V(0,0.3,-5), &exhaust_main);

== Docking Port ==

Surveyor has no docking point, so delete the definition of it:

  SetDockParams (_V(0,1.3,-1), _V(0,1,0), _V(0,0,-1));

== Translation RCS ==

Many modern and historical spacecraft have only limited translational capability. For example, the Cassini orbiter only has translation forward. Surveyor had no translation RCS at all. Instead it relies on the vernier engines. So let's ditch the translation thruster groups. We will leave the thrusters, but just remove the capability to use them as translation thrusters, while retaining them as rotation thrusters. Cut the following code chunks:

  th_group[0] = th_rcs[9];

  th_group[1] = th_rcs[11];

  CreateThrusterGroup (th_group, 2, THGROUP_ATT_RIGHT);

  CreateThrusterGroup (th_rcs+13, 1, THGROUP_ATT_BACK);

Compile and test. Now when you fly, you can switch to translational engines, but they don't do anything.

= Propellant Resources =

Notice that even though in reality the vernier fuel and oxidizer need to be kept in separate tanks (they are hypergolic), in Orbiter, they are both treated as "propellant" and are both kept in the same propellant resource. This is because each engine can only use one propellant resource at a time.

  PROPELLANT_HANDLE ph_vernier = CreatePropellantResource (VERNIER_PROP_MASS);

  PROPELLANT_HANDLE ph_rcs    = CreatePropellantResource(RCS_PROP_MASS);

const double RCS_PROP_MASS=2;

const double RCS_ISP = 630.0;

const double RCS_THRUST = 0.25;

const double RCS_RAD = 1;

const double RCS_STA = -0.5;

const double RCS_SPACE = 0.1;

  PRPLEVEL 0:1.000 1:1.000 2:1.000   

= Surveyor RCS =

It is a fundamental principle of attitude control that you need a minimum of two thrusters for each control direction. This is so that the linear forces of each thruster cancel out and only the torques remain. For a total of three axes (pitch, yaw, roll), and two control directions for each (plus and minus), you would seem to need 2*3*2=12 thrusters at a minimum for rotational RCS.  

This is because the designers of Surveyor were primarily concerned with simplicity on board the spacecraft. They put on one thruster for plus roll and one for minus roll. These engines were installed up on Leg 1, pointing to +X and -X (left and right). Using one of these engines creates both a roll torque and a linear force. Burn one of these engines long enough, and you may deflect your landing site or miss the moon completely. Back in the day, the guys on the ground calculating the mid-course correction had to take into account this imbalance of force. This kept with the philosophy of spacecraft simplicity by shifting the complexity to the big, room-sized computers on the ground. Fortunately since the RCS is weak, this force is small. Also, once the spacecraft settles into a particular attitude, one would expect to use about the same amount of + and - control to keep it stable. Thus, the linear forces mostly cancel out anyway.

Surveyor has two thrusters on Leg 2 and two on Leg 3. Both pairs have one member pointing at +Z (forward) and one at -Z (back). These are used to control pitch and yaw. To yaw, one +Z engine on one leg and one -Z engine on the other leg are fired. These are balanced, resulting in a perfect yaw control system. To pitch, either both +Z or both -Z engines are fired. This generates a pitch torque, but also a linear thrust, which again must be accounted for on the ground.

One more thing to remember: The legs are well behind the spacecraft center of mass. Because of this, the roll jets will induce a certain amount of yaw, as well as roll.

  th_rcs[ 0] = CreateThruster (_V( 1,0, 3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 1] = CreateThruster (_V( 1,0, 3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 2] = CreateThruster (_V(-1,0, 3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 3] = CreateThruster (_V(-1,0, 3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 4] = CreateThruster (_V( 1,0,-3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 5] = CreateThruster (_V( 1,0,-3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 6] = CreateThruster (_V(-1,0,-3), _V(0, 1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 7] = CreateThruster (_V(-1,0,-3), _V(0,-1,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 8] = CreateThruster (_V( 1,0, 3), _V(-1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[ 9] = CreateThruster (_V(-1,0, 3), _V( 1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[10] = CreateThruster (_V( 1,0,-3), _V(-1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[11] = CreateThruster (_V(-1,0,-3), _V( 1,0,0), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[12] = CreateThruster (_V( 0,0,-3), _V(0,0, 1), PB_MAXRCSTH, ph_vernier, PB_ISP);

  th_rcs[13] = CreateThruster (_V( 0,0, 3), _V(0,0,-1), PB_MAXRCSTH, ph_vernier, PB_ISP);

  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWRIGHT);

Now, add the following code in its place:

  th_rcs[ 0] = CreateThruster (_V(-RCS_SPACE,RCS_RAD,RCS_STA), _V( 1,0,0), RCS_THRUST, ph_rcs, RCS_ISP);

  th_rcs[ 1] = CreateThruster (_V( RCS_SPACE,RCS_RAD,RCS_STA), _V(-1,0,0), RCS_THRUST, ph_rcs, RCS_ISP);

  th_rcs[ 2] = CreateThruster (_V( sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA-RCS_SPACE), _V(0, 0, 1), RCS_THRUST, ph_rcs, RCS_ISP);

  th_rcs[ 3] = CreateThruster (_V( sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA+RCS_SPACE), _V(0, 0,-1), RCS_THRUST, ph_rcs, RCS_ISP);

  th_rcs[ 5] = CreateThruster (_V(-sqrt(3.0)/2*RCS_RAD,-0.5*RCS_RAD,RCS_STA+RCS_SPACE), _V(0, 0,-1), RCS_THRUST, ph_rcs, RCS_ISP);

  th_group[0] = th_rcs[3];

  CreateThrusterGroup (th_group, 2, THGROUP_ATT_PITCHDOWN);

  th_group[0] = th_rcs[2];

  th_group[1] = th_rcs[4];

  th_group[0] = th_rcs[0];

  CreateThrusterGroup (th_group, 1, THGROUP_ATT_BANKRIGHT);

  th_group[1] = th_rcs[4];

  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWRIGHT);

  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWLEFT);

This creates the six thrusters. The geometry is similar to the vernier engines. The difference is that there is also a constant RCS_SPACE, which spaces them a certain distance apart from the other thruster on the same leg. It also organizes them into control groups. With these groupings, all the rotational controls will work, and so should rotational autopilots like killrot, prograde, etc.

These are cold gas jets, and so are invisible, but you may want to add exhaust flames just for debugging purposes. The next, totally optional block, will add them. If you want, add the following code block after the previous one:

  for (int i=0;i<6;i++) {

    AddExhaust(th_rcs[i],0.1,0.05);

Compile and test, and see that now the spacecraft turns '''very''' slowly. The real Surveyor had a turn rate of 0.5deg/sec, or 12 full minutes to turn a circle. It takes several seconds of thrusting to get up to even this slow rate.

If you turn the verniers on, note that the spacecraft becomes much more maneuverable. This is because the vernier engines are providing a power assist to the RCS. Also note that the rotation autopilots use the verniers just as well as you can use them manually.

= Spacecraft Empty Mass =

The total mass of the spacecraft is continually tracked by Orbiter, and consists of the declared empty mass of the spacecraft and the total mass in all the propellant resources. The empty mass is normally constant, but things like jettisons will change the mass. Let's put the mass determination into a separate function. This will help out later when we start jettisoning parts.

Add the following code to the class definition, to define the new method

  double CalcEmptyMass();

const double LANDER_EMPTY_MASS = 289.10; //Basic bus plus payload minus AMR minus retro case

const double AMR_MASS = 3.82;

  double EmptyMass=0;

  EmptyMass+=LANDER_EMPTY_MASS;

  return EmptyMass;

So, why are we making such a simple function? Why is it more complicated than it needs to be? And why are we setting the mass at every time step? All these and more will be answered when we get to jettisoning parts.

Compile and test. You may notice that the spacecraft is a little bit more maneuverable now. A little.

Let's put the actual gear under the visual landing pads, so that when we land, the spacecraft will be sitting upright on its legs.

  SetTouchdownPoints( _V( 0,LEG_RAD,LEG_STA), _V( sqrt(3.0)/2*LEG_RAD,-0.5*LEG_RAD,LEG_STA), _V(-sqrt(3.0)/2*LEG_RAD,-0.5*LEG_RAD,LEG_STA));

This uses the same geometry as the vernier and RCS engines. Add the appropriate constants to the top of the file with the rest:

const double LEG_RAD = 1.5;

Surveyor is much smaller than ShuttlePB. Set its radius and moments of inertia to something smaller. Surveyor's moments of inertia are not documented, but an analysis by the OrbiterSDK ShipEdit program reveals that they are about 0.5 (normalized) and approximately equal about all three axes. Change the SetPMI and SetSize lines as follows:

  SetPMI (_V(0.50,0.50,0.50));

Since the empty mass is calculated at every time step, we can delete the mass setting here:

  SetEmptyMass(500.0);

 

 

 

 

 

 

 

 

 

 

 

 

Compile and test. Notice how much heavier the spacecraft is now. If you are in the air, you probably can't land safely anymore, and if you are on the surface, you probably can't take off. Also, the retro engine is there, ready to be fired, but what button fires it? Right now, none. You can't control the retro at all. Let's fix that. Add another method to the class definition

 

 

 

 

 

 

 

Compile and test. Press L to fire the retro. With a full retro, you can launch a Surveyor from the surface of the moon all the way into orbit or escape. Or you can land from 200km with a downward speed of 2.4km/s. Take your favorite maneuverable spacecraft up to above 200km, point it down, rev up to 2.4km/s, then turn retrograde. Quit and edit the current state to replace that ship with Surveyor, and make sure to fill tanks 0, 1, and 2.

 

 

 

 

The AMR hardware is located inside the main retro nozzle. It is shot out like a bullet when the retro fires. Let's simulate that by only having the AMR mass count towards the total vehicle mass if the main retro has a full load of propellant in it. After the main retro burns out, it is immediately jettisoned. Let's simulate that by only having the retro casing mass count towards the total vehicle mass if the main retro has some propellant in it.

 

First, we have to change the propellant handle variable for the retro engine from a local in clbkSetClassCaps to a class field. Add this line to the class definition:

 

 

 

 

 

This way, if the retro propellant grain has at least 1kg of fuel left, the mass of the retro casing is added to the mass of the spacecraft. If the retro propellant grain is more than 99.9% full, then the mass of the AMR is added to the mass of the spacecraft. In general, it is a bad idea to test floating-point numbers for exact equality to anything.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

So, now we can call SetupMeshes whenever we originally set up the vehicle state in clbkSetClassCaps, and whenever the configuration changes, like in Jettison. Replace the AddMesh line there with a call to SetupMeshes:

 

 

Also, add this line to the bottom of the Jettison method, after the case statement.

 

Compile and test. Now before you light the retro, you should see the large spherical retro at the center of Surveyor.