Vessel Tutorial 2

From OrbiterWiki
Jump to navigation Jump to search

Go back to Vessel Tutorial 1

Take out the Trash

Now it's time to clear out all the old ShuttlePB things that we don't need any more. Remember, if you are making something other than Surveyor, you may want to adapt this stuff rather than trashing it.

Aerodynamic Model

Surveyor is a pure spacecraft, so it doesn't need an aerodynamic model. I suppose the purists out there would insist on at least giving it drag in case it fell into the Earth's atmosphere after a bad launch, but I don't care about it.

Completely get rid of this block of code: 

// 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];
}

This code was used to provide a lift model for the ShuttlePB. It appears to make ShuttlePB a lifting body with a small amount of lift.

Now, go down to Surveyor::clbkSetClassCaps and remove the following code sections: 

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

This removes the rest of the aerodynamic model. It also removes the aerodynamic trim capability. Compile and test, in case you forgot.

Hover engine

Surveyor uses its main engines to hover, and doesn't have a hover engine as such. So let's toss it. Get rid of this code: 

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

Compile and test.

Fancy Exhaust

The ShuttlePB defines all sorts of fancy particle streams, which only are used in atmospheric flight. Since we are not in an atmosphere, let's ditch these. Your spacecraft may want to customize these instead. Get rid of these code blocks: 

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

  PARTICLESTREAMSPEC contrail_main = {
    0, 5.0, 16, 200, 0.15, 1.0, 5, 3.0, PARTICLESTREAMSPEC::DIFFUSE,
    PARTICLESTREAMSPEC::LVL_PSQRT, 0, 2,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-4, 1
  };
  PARTICLESTREAMSPEC contrail_hover = {
    0, 5.0, 8, 200, 0.15, 1.0, 5, 3.0, PARTICLESTREAMSPEC::DIFFUSE,
    PARTICLESTREAMSPEC::LVL_PSQRT, 0, 2,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-4, 1
  };
  PARTICLESTREAMSPEC exhaust_main = {
    0, 2.0, 20, 200, 0.05, 0.1, 8, 1.0, PARTICLESTREAMSPEC::EMISSIVE,
    PARTICLESTREAMSPEC::LVL_SQRT, 0, 1,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-5, 0.1
  };
  PARTICLESTREAMSPEC exhaust_hover = {
    0, 2.0, 10, 200, 0.05, 0.05, 8, 1.0, PARTICLESTREAMSPEC::EMISSIVE,
    PARTICLESTREAMSPEC::LVL_SQRT, 0, 1,
    PARTICLESTREAMSPEC::ATM_PLOG, 1e-5, 0.1
  };

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

Compile and Test.

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 trhusters, while retaining them as rotation thrusters. Cut the following code chunks: 

  th_group[0] = th_rcs[0];
  th_group[1] = th_rcs[4];
  th_group[2] = th_rcs[2];
  th_group[3] = th_rcs[6];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_UP);

  th_group[0] = th_rcs[1];
  th_group[1] = th_rcs[5];
  th_group[2] = th_rcs[3];
  th_group[3] = th_rcs[7];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_DOWN);

  th_group[0] = th_rcs[8];
  th_group[1] = th_rcs[10];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_LEFT);

  th_group[0] = th_rcs[9];
  th_group[1] = th_rcs[11];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_RIGHT);

  CreateThrusterGroup (th_rcs+12, 1, THGROUP_ATT_FORWARD);
  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

ShuttlePB had only one fuel tank, filled with hyperthrustium fuel. Surveyor has three completely separate fuel systems:

  1. Vernier fuel and oxidizer
  2. RCS nitrogen
  3. Main retro solid fuel

Notice that even though in reality the vernier fuel needs 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.

First, let's recycle the ShuttlePB fuel tank as the vernier propellant tanks. We already did this above when we replaced hpr with ph_vernier. We will, however, change the mass of propellant in it. Find the line which defines ph_vernier, and change it like this: 

  PROPELLANT_HANDLE ph_vernier = CreatePropellantResource (VERNIER_PROP_MASS);

Next, create the RCS propellant resource. Whenever there are multiple propellant resources, the order in which they are created is important. The first one created is referenced as prop resource zero, the next one is one, and so on. This order matters because when the scenario is loaded or saved, the propellant levels in each tank are referenced by this number. So, add the following line below the line which creates the vernier prop resource: 

  PROPELLANT_HANDLE ph_rcs     = CreatePropellantResource(RCS_PROP_MASS);

Add the constants which define the RCS to near the top of the file: 

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;

We will worry about the retro propellant when we define the retro engine.

In order to put fuel into the RCS fuel tank, edit the PRPLEVEL line for Surveyor in your scenario file: 

  PRPLEVEL 0:1.000 1:1.000 2:1.000

This fills resource zero, the vernier tanks, and resource one, the RCS tank. It also fills resource 2, the main retro solid fuel grain, but we haven't created this yet. No worries, since Orbiter ignores propellant resources which we don't have.

Compile and test.

Surveyor RCS

Surveyor carried a number of cold-gas thrusters for reaction control. These just used high-pressure nitrogen. These engines are weak and inefficient, but extremely simple and safe. No flammable fuel is needed for them, only a high-pressure gas tank.

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.

Surveyor only has six.

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 enoug, 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 unbalance of force. This kept with the philosophy of spacecraft simplicity by shifing 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 (foreward) 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 acconted for on the ground.

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

So, let's install these thrusters. First, get rid of the old ShuttlePB thrusters: 

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

  th_group[0] = th_rcs[0];
  th_group[1] = th_rcs[2];
  th_group[2] = th_rcs[5];
  th_group[3] = th_rcs[7];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_PITCHUP);

  th_group[0] = th_rcs[1];
  th_group[1] = th_rcs[3];
  th_group[2] = th_rcs[4];
  th_group[3] = th_rcs[6];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_PITCHDOWN);

  th_group[0] = th_rcs[0];
  th_group[1] = th_rcs[4];
  th_group[2] = th_rcs[3];
  th_group[3] = th_rcs[7];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_BANKLEFT);

  th_group[0] = th_rcs[1];
  th_group[1] = th_rcs[5];
  th_group[2] = th_rcs[2];
  th_group[3] = th_rcs[6];
  CreateThrusterGroup (th_group, 4, THGROUP_ATT_BANKRIGHT);

  th_group[0] = th_rcs[8];
  th_group[1] = th_rcs[11];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWLEFT);

  th_group[0] = th_rcs[9];
  th_group[1] = th_rcs[10];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWRIGHT);

Now, add the following code in its place: 

  //Roll (Leg1) jets
  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);

  //Leg2 jets
  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);

  //Leg3 jets
  th_rcs[ 4] = 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];
  th_group[1] = th_rcs[5];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_PITCHDOWN);

  th_group[0] = th_rcs[2];
  th_group[1] = th_rcs[4];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_PITCHUP);

  th_group[0] = th_rcs[0];
  CreateThrusterGroup (th_group, 1, THGROUP_ATT_BANKRIGHT);

  th_group[0] = th_rcs[1];
  CreateThrusterGroup (th_group, 1, THGROUP_ATT_BANKLEFT);

  th_group[0] = th_rcs[3];
  th_group[1] = th_rcs[4];
  CreateThrusterGroup (th_group, 2, THGROUP_ATT_YAWRIGHT);

  th_group[0] = th_rcs[2];
  th_group[1] = th_rcs[5];
  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 seperate 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();

Add the following constants near the top to define the empty masses: 

const double LANDER_EMPTY_MASS = 289.10; //Basic bus plus payload minus AMR minus retro case
const double RETRO_EMPTY_MASS = 64.88;
const double AMR_MASS = 3.82;

Now add the function body: 

double Surveyor::CalcEmptyMass() {
  double EmptyMass=0;
  EmptyMass+=LANDER_EMPTY_MASS;
  return EmptyMass;
}

Call it from Surveyor::clbkPreStep . Add the following line to the top of that method: 

  CalcEmptyMass();

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.

Other physical parameters

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.

Find the SetTouchdownPoints line in clbkSetClassCaps function. Change it as follows: 

  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;
const double LEG_STA =-0.6;

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

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

  SetSize (1.0);

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

  SetEmptyMass (500.0);

Compile and Test.

Main Retro

Can we land yet?

Retrieved from "https://www.orbiterwiki.org/index.php?title=Vessel_Tutorial_2&oldid=2085"