Rendezvous and Docking with MechJeb 2

[Scarecrow71]

Greetings, one and all!  During a recent mission while going through the Kerpollo Challenge, I realized that there just wasn’t a full-length tutorial on how to use MechJeb 2 for docking.  I had never attempted docking before doing this challenge, and so I scoured the forums and Reddit and Facebook and every other nook and cranny on the internet, hoping to find something that would help me use MJ to dock.  I was able to find pieces of information here and there, but nothing that was full and in-depth.   And so, because I have received tons of help here from the fine folks playing this wonderful game, I am here now to give back with the information I’ve compiled in a tutorial that should, I hope, help anyone interested in using MJ to dock.

I would like to state before we get started that there is a lot of great information out there, and that this tutorial is not meant in any way to downplay what others have already done.  @Snark has a wonderful tutorial on docking that is great if you want to do this by hand.  I just wanted to give people the option of how to do this using MechJeb.

Assumptions

In order to run through and/or perform the steps in this tutorial, I am going to assume that:

1. You, the reader, know how to build a rocket.
2. You, the reader, know how to launch said rocket.
3. You, the reader, know how to achieve a circularized orbit.
4. You, the reader, have MechJeb2 installed.

This tutorial is not designed to teach rocket design, or give steps on how to get into orbit; if you don’t know either of those things, it is highly suggested you learn that first.

Pre-Requisites

Pre-requisites?  Didn’t I just cover Assumptions above?  Yes, I did.  In addition to the knowledge that you should have before you pull off the stuff in this tutorial, you should also have the following in whichever career game you are playing:

1. Level 2 Mission Control
2. Level 2 Tracking Station
3. Advanced Flight Control
4. Miniaturization

These are the minimum requirements in order to use MJ to the fullest extent in this tutorial.  If you have more than this unlocked, great!  If you don’t have these unlocked, well, keep playing until you do and then come back!

Versions

For the sake of posterity, the versions of the different pieces of software I am using:

• Kerbal Space Program 1.8.3
• MechJeb2 2.12.3.0

I do have Breaking Ground and Making History installed, but neither of these is of import to docking with MJ.  I also will not be using any parts from any other mods, sticking instead to the stock docking port from Miniaturization.  If you wish to use other docking ports from mods or other unlocked nodes in the Technology Tree, the concepts and tips here will work.

Now, with all the legalese out of the way, let’s get started!

PART I – THE SETUP

Rendezvous and docking maneuvers are quite possibly the most challenging things to learn how to do in this game.  I won’t lie and say that everything up to this point is easy – it’s not.  And while these 2 concepts are close to the last things you will learn how to do, they are, in my estimation, the most complex.  You are, to put it simply, attempting to take one object in motion and move it close to another object in motion, get the speed (velocity) of both moving objects to be equal, and then take one object and lock it into place on the other object.  And you are trying to do this without crashing or blowing up.  This is not an easy thing to do manually.  Thankfully, we can take advantage of the computer to get this done.

What you’ll need here is:

1. A ship in orbit with a docking port; and
2. A ship to be launched with a docking port.

We are going to be using the Clamp-o-Tron Docking Port Jr. on both of the example ships here:

In order to dock, you need a docking port on each ship.  And the ports need to be installed properly to do this.  At the top of the above image is what I call a “shiny ring”, while at the bottom of the image is what I’m going to refer to as “the curtain”.  I call the top the shiny ring because it looks like a shiny ring, while the curtain looks like a semi-folded curtain.  At least, that’s what they look like to me.  Anyhow, the docking port needs to be installed properly on both the ship in orbit and the ship to be launched.  The curtain is the part that attaches to the ship, while the shiny ring is pointed outwards away from the ship.  This is because, when you eventually do dock, the shiny ring from the ship in orbit will attach to the shiny ring from the ship being launched, locking the 2 ships together.

For this tutorial, I will be sending the following ship into orbit as our target ship.  In the first shot from the VAB, you can see that I’ve highlighted the docking port; notice the orientation of it as I mentioned above:

What a name!  Target Ship!  It’s actually really good practice to name your vessels so that when you’ve got multiple ships up there and you are trying to deal with docking or rendezvous or other maneuvers, you know which ship you are dealing with.  Don’t want to have to revert to launch all the time!  Anyhow, once we’ve got our target in orbit, we can start thinking about what we forgot and why we need to dock.

You’ll see in the shot there that I’ve circularized the orbit at ~128,000m.  It isn’t required, but it is HIGHLY recommended that the orbit of the target ship is circular around whatever celestial body it is orbiting.  Having the orbit circularized makes the rendezvous much easier to deal with.

Now that we have a target ship in orbit, we can continue with our mission.  But wait!  We forgot to pack enough snacks for Jeb to snack on!  Oh, we can’t let Jeb sit in orbit for too long without snacks; we better send a supply ship up to him and make sure he’s got enough chips and soda for whatever long flight he has in front of him.  Or, well, whatever other reason you want to devise for needing to rendezvous and dock.

The supply ship, like the target ship, has to have a docking port in the correct orientation.  It also must have some RCS (Reaction Control Systems) thrusters, and a few monopropellant tanks.  While we use liquid fuel engines to get into space, we don’t want to use them to try and dock lest we wish to go too fast and crash.  Monopropellant tanks and thrusters allow for quick, short, controlled bursts without gaining too much speed; they are the right tool for this job.  And so we end up with a snack supply ship that looks thusly:

I gave 2 shots here, primarily because the docking port is a bit hidden under the TD-12 decoupler.  Once we get this thing rendezvoused with Target Ship, we are going to lose all of the fuel tanks and engines and, hopefully, dock without too much issue.  And away we go.

And we have a circularized orbit at ~112,000m.  You’ll notice 2 things that are very different here from the first orbit we achieved.

1. The Snack Ship’s orbit is closer to Kerbin’s surface than the Target Ship’s orbit.  When putting the ship you are going to dock into orbit, you want to be at a circular orbit that does not match the orbit of the target ship.  This is due to, again, not wanting to accidentally crash into the target ship.  By being closer to the surface, we can make the assumption that we won’t crash…although accidents do happen sometimes.
2. The plane the Snack Ship is on is not the same as the plane the Target Ship is on.  While this was by design in this tutorial (I could have very easily just gotten to an equatorial orbit for both ships), you will find when exploring other bodies that you will almost never have the same plane for your orbits.  So to make this as close to what will happen as possible, I intentionally shifted the plane of the Snack Ship so you can see what happens.

And we are all set up to do our rendezvous now.  So let’s get to it!

PART II – THE RENDEZVOUS

Now that we’ve got our ships in orbit, we have to get them so they are:

• On the same plane
• At the same (approximate) distance from the surface
• Moving at the same speed

You can absolutely do all of this by hand…but that’s not the point of this tutorial.  I certainly cannot do any of these by hand, and I rely upon MJ to do this for me.  And that’s what we are going to do here.  So, the first thing you want to do is to set the Target Ship as the target.  Basically, in the map view, click on the Target Ship and select “Set as Target”.

You’ll notice that the orbit of the Target Ship turned from white to yellow.  This is a visual cue to let you know that yes, you have set this object as the target.  You can do this with any object the tracking station is monitoring, from ships in orbit to planets to moons…pretty much anything in outer space.

The next thing to do is to transfer the orbit of the Snack Ship to be aligned (somewhat) with the orbit of the Target Ship.  To do this, open the MJ menu (it’s in the top-right of my screen; it may be elsewhere in yours, depending on your settings) and click on Maneuver Planner:

In the Maneuver Planner window that pops up, change where it says (for me) “Circularize” to “bi-impulsive (Hohmann) transfer to target”.  Then click on Create Node, and check to see how long before the node executes, like so:

 

In my case, this will take 1 day, 3 hours, and 28 minutes.  Which means we can either sit here and let the game churn away for this amount of time, or we can warp ahead.  And we’ve got several options on how to do that:

1. We can make sure Auto-warp is selected in the Maneuver Planner window and then click on Execute Next Node; OR
2. We can use the warp controls that are part of the MET button in the upper-left corner; OR
3. We can navigate to the Tracking Station and warp ahead using the controls there.

I prefer to use the Tracking Station to closer to the time when warping.  Why?  Because the Tracking Station shows you how long until the next maneuver for any/all ships.  Like this:

Notice under Snack Ship it shows “MNV T – 1d, 3h, 28m”?  That’s the amount of time it takes to get to the next maneuver node.  So what I’ll do here is click the blue button in the upper-left corner to warp to the next morning, and see how close we are to the time.  And after doing that, I’m still 5 hours and change away, so I’m going to use the warp arrows to speed ahead until I’m within 30-60 minutes of the maneuver node:

I’m within 56 minutes of the node, so now what I’ll do is make sure Auto-warp is clicked in the Maneuver Node Planner window, and then click Execute Node.  What this will do is force MJ to take over, and then the game will Auto-warp to and then execute the node.  And we end up with the following orbit when we are done:

Our orbit is now a bit more closely aligned with the Target Ship…but we aren’t quite there yet.  What we want to do next is to fine tune our approach to get even closer to the right orbit.  So, with the Maneuver Node Planner window open, change that drop-down so it says “fine tune closest approach to target”.  Before you click on Create Node, take a look at the value in the Closest Approach Distance box.  It should default to 200m, but I always try to get closer than this.  I generally aim for somewhere from 25m – 50m, and in this case, I’ve set it to 50.  Once you are happy with the value you’ve set, click Create Node and see how long until the node gets executed.

Wow.  In this case, the node is going to be coming up on us fast – within the next 2 minutes.  In the event that the node ends up coming up too soon, you can always remove the node, wait a bit, and create a new node.  In this case, I’m going to let this one stand; Auto-warp is marked, so I’ll click Execute Node and end up with this for an orbit:

It doesn’t look like much changed…but it did.  See the red arrows to the left on the orbit?  That shows the approach distance; if you hover over that both before and after the maneuver, you’ll see that the values have changed.  It doesn’t look like much, but it is a big deal.

Now we have to match velocity (speed) of the Target Ship.  What this will do is perfectly align the orbits and make sure that both ships are traveling the same speed, parking the Snack Ship close to the Target Ship.  So, in the Maneuver Planner Window, change the drop-down to be “Match Velocities With Target” and click Create Node.  You’ll notice that, through all of this, I am not changing any of the defaults other than when fine tuning the approach.  You don’t need to change these…but you are free to play around with them and see what results you get.  Always remember that your mileage on this stuff may vary!  Anyhow, after creating the node, we end up with this:

It's gonna take 13.5 minutes until we reach the node, so we will leave this one and click on Execute Node.  And when that’s done, we get this:

My goodness, my goodness!  Look what we have here!  Both of our ships, right next to each other.  You will notice that they are pointed in the same relative direction, which is fine.  You could take control of the other ship for a brief moment and point it in the right direction, but we aren’t going to do that here.  We are going to let MJ take control and deal with this.  So, decouple the almost-empty fuel tanks, and go to the next section!

PART III – DOCKING

Well, we finally made it to the docking portion of this.  I told you up front this was complex and one of the most difficult things you will do in this game.  It may take some work and some time to get to this point, but it is so worth it when you finally reach the end.  Trust me when I say that you will smile from ear-to-ear every time you do this.

Anyhow, what we need to do is tell MJ that we are docking.  We start by setting the docking port on Target Ship as the target.  So right-click on that docking port – you may have to spin the camera around a bit to see it and interact with it – and then click on Set As Target:

Sometimes the menu will change to show Unset Target, and sometimes it won’t.  I haven’t figured out why this happens, so I got the screen shot showing the yellow words at the top; those will always display to show that you have set the docking port as the target.

Now we have to tell MJ what to do.  I’m going to use the commands that will be the first ones available to you when you try docking.  Again, you are free to play with all the other commands and see which ones work and which ones don’t.  So what we do now is, in the MJ menu, click on Scripting Module, which brings up the Scripting menu.

Where it says “Time”, pull that drop-down open and click on Modules.  Then to the right of that, open that drop-down and change it to MODULE Docking Autopilot.  Then click the + sign to the right.

What you’ve done here is to tell MJ that you want docking to be on autopilot, which is awesome.  But you haven’t given it the instruction to actually dock yet, so let’s take care of that.  Where it says Modules, open that drop-down and change it to Docking, and change the drop-down to the right of that to be Target Dock.  Then click the + sign again.

Leave the defaults alone here.  Both of the drop-downs say Clamp-o-Tron Docking Port Jr., which is what we want.  We can’t change the part names, which honestly would be pretty darned nice.  But leave them alone or you run the risk of messing this up and having to start over.  All that’s left to do now is click the green Start button and watch the magic happen!

We are now successfully docked!  I will state the following 2 things right here and right now:

1. Save early and often.  Just because the computer is doing this for you doesn’t mean that accidents won’t happen.  I highly recommend quick-saving after every step so that, in the event of a catastrophe, you can revert just a little ways and try again.
2. You may need to change the control point of the Snack Ship.  In this case, I had to change the control point to Reversed (which you can do by right-clicking on the command module and changing the Control Point in the menu) because the Snack Ship wanted to dock in the wrong direction.  This goes to point 1 above about saving early and often.  Note that you may need to turn on Advanced Tweakables to do this.

SUMMARY

And there you have it.  At this point, you should have been able to get 2 ships into similar orbits at similar speeds and docked them with one another.  As I pointed out at the beginning, I had to scour the internet for some of this information, and it wasn’t entirely complete.  Which is why I wanted to put this whole tutorial together:  so people could find a step-by-step of the entire process in one location.

I hope that this tutorial has helped you to learn how to dock in an easy-to-follow way.  The last thing I want is for people to be more confused here; I was so lost on this for such a long time that I avoided it.  But now that I know what to do, I find it easy and I welcome doing it.  I hope you can all say the same.

If you like this tutorial, hammer on that Like button.  If not, please leave your comments below so that I can fix whatever is wrong!

Edited November 9, 2021 by Scarecrow71