xeger/kos-ramp

Relatively Adequate Mission Planner: a rudimentary, scriptable autopilot for kOS.

Introduction

Relatively Adequate Mission Planner (RAMP) is a set of kOS programs that aims to improve your KSP experience in several ways:

• Maximize the precision of your maneuvers
• Let you focus on the fun parts of spaceflight by automating the drudgework
• Teach you about orbital mechanics and physics

You can use the scripts as a kind of autopilot or poke into them to see how everything works, learn about the underlying science, or customize them to your needs.

Getting Started

RAMP scripts have a naming pattern: one-word scripts can be executed without any parameters, and multi-word scripts require parameters. Comments at the top of every script explain what it does and which parameters it needs.

Run the launch program to ascend to a circular orbit a few hundred km above your local atmosphere:

run launch.

After you reach a stable orbit, select a target. Use the transfer or rendezvous script to reach your target.

set target to vessel("My Other Vessel").
run rendezvous. // travel to another vessel

set target to body("Mun").
run transfer. // or, travel to a moon

The boot, rendezvous and transfer scripts are idempotent: you can safely run them at any time; they either make progress toward your goal, or error out with an explanation as to why they can't. The universal boot leader is customizable per ship.

Maneuvers

Other idempotent scripts include:

run circ.             // circularize at nearest apsis
run circ_alt(250000). // circularize to specific altitude of 250km
run approach.         // get close to target and stop
run match.            // match velocity at closest approach to target
run dock.             // dock with your target

Planning Burns by Hand

You can also plan and execute on-orbit maneuvers by hand using the node_* scripts.

run node_apo(1000000). // plan to make our apogee huge!
run node.              // make it so

Automating a Mission

If you want to script your entire mission end-to-end, it is highly suggested that you choose boot as the boot script for your vessel's main CPU. When your ship is on the pad, run initialize. to create a sample Mun mission for your craft. Finally, reboot. to perform the automated sample mission.

To change the mission profile, just edit the startup script that now lives under start/YourCraftName.ks and launch a fresh craft of the same name. The sample mission is not very robust or interesting; under the mission/ subfolder, RAMP provides several other example missions that you can copy into start/ and edit to your liking.

You can learn more about bootstrapping in this file.

Preparing for Launch

If your ship will travel farther than 100km from KSC, you should install a CPU with enough space on the vessel and run boot to copy the mission software onto the primary volume. Running archive scripts is fine in low orbit, but a space probe needs to be able to think for itself!

Contributing & Customizing

Clone my repo. Hack to your enjoyment. Pull requests are gladly accepted!

WARNING: notice the control flow between programs is fairly flat. I try never to call more than 2-3 programs deep. This is because the kOS VM seems to have bugs with programs and functions calling one another. Specifically:

1. Local variables from inner programs sometimes overwrite same-named variables from the outer program
2. Function libraries don't seem to work when they are compiled code

See comments in node_apo/node_peri for an example of #1. Try to compile lib_ui and run it from another program for an example of #2.

Design Principles

RAMP's code should be:

1. Safe: scripts should check for errors and harmful conditions
2. Modular: each script accomplishes a specific purpose
3. Reusable: scripts call library functions rather than copy-pasting code
4. Educational: comments explain each script and provide science and math background
5. Ethical: anything copied or derived from an outside work includes a link to the original

Program Naming

One-word programs should require no parameters so they can be run from the console. Multi-word programs may accept many parameters and must be called like a function (generally by another program, or possibly from the console).

Program names must be as short as possible while still conveying the purpose of the program.

Names must follow lexical ordering, i.e. all programs related to maneuver-node management begin with node: node_apo, node_peri and so forth. The program simply named node is standalone; it executes the next node, then halts.

The additional words of a program name should convey what the program accomplishes for single-purpose programs, and when during the mission the program needs to run, for more complex or long-running program.

1. node_apo: create node to change apoapsis
2. launch_asc: perform ascent phase of launch

Parameter Passing

Whenever possible, programs and functions should accept parameters with "ordinary" units and frames of reference. The name of the parameter should convey its unit of measure. Suggested units/frames are:

1. Name of ship orbital position e.g. "apoapsis"
2. Universal time (UT) in seconds after the epoch
3. Altitude (ALT) in meters above SoI surface

Function Libraries

Programs beginning with lib_ contain reusable functions and are invoked by other programs using run once or runoncepath().

Beware that libs cannot run other libs! If two library scripts depend on one another's functions, then you must make sure to run once both scripts from every top-level program that uses either oft hem!

Comments and Documentation

Every program should begin with comments explaining what the program does. Functions should be likewise commented. Every parameter (to a program or a function) needs a comment explaining the purpose of the parameter.

kos-ramp's Issues

There is no "Transfer to another planet" script

Jebediah need to boldly go where no kerbal was gone before!

Allow node_apo() to place node at a time other than periapsis

The comments below apply to both node_apo() and node_peri(), obviously.

I recently wanted to change my apoapsis at a point in my orbit that was not my periapsis.

My script lifts heavily from node_apo.ks and looks like this:

local mu is body:mu.
local br is body:radius.
local vom is ship:obt:velocity:orbit:mag.
// local r is ship:body:altitudeof(positionat(ship, time:seconds)) + br.
local r is br + altitude.
local v1 is velocityat(ship, nodetime):orbit:mag.

// ugh v2 is hard.
local sma1 is obt:semimajoraxis.
local r2 is ship:body:altitudeof(positionat(ship, nodetime)) + br.

local sma2 is (tgtapo + br + r2)/2.
local v2 is sqrt(vom^2 + (mu * (2/r2 - 2/r + 1/sma1 - 1/sma2))).

local deltav is v2 - v1.
local nd is node(nodetime, 0, 0, deltav).
add nd.

I know that this code "works" in the sense that the node created will place the apoapsis at the right distance at the right time. Would it be worth merging this code into node_apo() and creating a second optional argument for node time (with default value TIME:SECONDS+ETA:PERIAPSIS)? I'm willing to submit a PR if it has a chance of being accepted.

landvac not working

Hi there,

Been using your library for a few days and I find it one of the most complete set of scripts out there! However, I’m having problems getting landvac.ks to work. When attempting to (using any method), my ships get to the stage of the final descent, however, my ships seem to be oriented horizontally (or close to), and therefore the suicide burn is not oriented correctly and my ships crash land (again, horizontally). I’ve mostly attempted this around Minmus. I can’t for the life of me figure out what I’m doing wrong.

Any help would be appreciated.

Launch script fails to work often

When I use launch_asc.ks to get a relatively normal rocket to orbit, maybe seven times out of eight it fails to follow the launch-turn-circularize pattern. The problem appears to be the apoapsis not quite reaching the target value, stopping at around 199,900 meters for a 200,000 meter launch.

I'm tinkering with potential fixes and will submit a pull request if I get anything reliable.

Implement protections against career limits

I have a craft with antennas which I launched with the scripts here.

The script crashed when attempting to extend the antennas, because I do not yet have my VAB upgraded to permit additional action groups.

https://ksp-kos.github.io/KOS_DOC/general/career_limits.html describes the limits, and offers a test to protect :DOACTION() calls with Career():CANDOACTIONS.

Hohmann transfer is imprecise

Need to test a couple remaining cases (rendezvous up, transfer down) to ensure the heuristic works well enough.

The approach-distance code also sucks. It needs to be a function of target mu and approach vel, or something like that.

Docking RCS inputs are catastrophically inconsistent

Something about the relationship between vWantX, vel:X and ship:control:starboard is inconsistent between ships, causing the RCS input to accelerate in the WRONG direction sometimes. There's obviously a sign error somewhere.

Streamline startup process

Instead of downloading all the scripts on the archive to the ship (wasting memory), why not have the startup script download just the appropriate library files based on the mission? The user will need to specify which library files to download.

There is no "Return from a moon" script

"We have to go back" - SHEPPARD, Jack

node_vel_tgt is imprecise

We always end up with residual velocity. Why?

1. Rounding error ... seems unlikely; eliminate this hyp with some testing.

2. We plan the burn for time of closest approach, but it takes some time to perform. Maybe the target's velocity changes enough during that interval to create the error? Also seems unlikely as the error is rather large (~10 m/s at 200km orbit).

node_alt seems to only work with eta:apoapsis/periapsis or low eccentricity

1. Why was the vom changed from velocityAt(ship,burnTime) to ship:velocity? What could current velocity possibly have to do with some future burn?

2. Was it tested with other than eta:apoapsis/periapsis with orbit:eccentricity > 0.1 or even greater?

3. What is the math behind it? I was trying to use similar math to patch node_hoh, still not successful. What crossed my mind was, that if I want to change the orbit at some arbitrary time, then it could be necessary to add radialOut factor.

https://en.wikipedia.org/wiki/Orbital_speed#Precise_orbital_speed
v = sqrt(body:mu*(2/r-1/orbit:semiMajorAxis))
but that only gives the magnitude, not the direction, for that you will need tangent,
which could have different direction from the original (starting orbit)
and that leads to complicated stuff I was not able to crack.

P.S.: Note: The tangent line always makes equal angles with the generator lines (from the point to both foci). Should not be that hard to get the direction (get the angle between generator lines, 180-that, divide by two). Then normalize and multiply with equation above. Substract original speed vector, separate normal, radial and prograde (normal should be zero), add node.

Need an approach program

node_vel_tgt is good at roughly canceling velocities, but we need something subtler that knows about RCS. Pseudocode:

1. while transverse velocity to target > 25 m/s, loop { node_vel_tgt. node. }
2. point ship opposite to linear velocity to target (prepare to use engine)
3. cancel transverse velocity using RCS & establish forward velocity @ speed limit
4. maintain forward velocity @ ever-lowering speed limit using RCS
5. stop when distance < approach_dist

Updates of the repo

I found this fork very useful https://github.com/MartinDomig/kos-ramp
Any plans to merge changes from it into the repository?

Transfer into a target orbit?

Right now when I send a scanner to a moon, I use the transfer script to end up in a low equatorial orbit, then elevate my orbit, then change the inclination. When I fly these "by hand", I use the transfer injection braking burn to place the initial periapsis at the right altitude in the right inclination (or close to it on both marks) which uses a lot less fuel. How hard is it to do this from within the transfer script?

Launch autostage doesn't works in some scenarios

In a situation like a space shuttle with liquid fuel boosters, when the boosters got empty the script didn't detect the need for staging.
Also when there are lots of separatrons for detaching SRBs, staging will not happen automatically since there is not zero solid propellant.

utilFaceBurn ruins otherwise working script (node.ks)

I am working on node.ks and have working version, but once I add utilFaceBurn it stops working correctly. I do not even have the necessary sensors, but it seems to slow things so much, that there is no time for the CPU to do what is needed.

1. JSON? Why? Why not global variable? Why reading it in LOCK EXPRESSION?! Over and over again?
2. WAIT INSIDE LOCK EXPRESSION?! KOS WARNS NOT TO DO THAT!!! ....but that is not the problem in my current testing because it actually never reaches this point.

If it is helping in some scenairo then it either has to work properly or needs some opt-in mechanism.

P.S.: Something like that should, in my opinion, be handled by balancing the engines - adjust throttle limits to make the thrust vector in line with CoM.

node.ks should never burn unless facing is correct

@fellipec said:

Anyway if the node is too soon and ship is turned completely away from its direction, it will miss the begining of burn window. Before it even start to burn to the wrong direction, I added the code just before the wait 5 so the script at least wait the ship to turn facing more or less in the direction of the burn. I think is “less worse” than begin burning in the wrong direction.

Our node program begins by facing the burn, and it does not proceed until we're facing correctly (less than 0.5 degrees of combined error):
https://github.com/xeger/kos-ramp/blob/master/node.ks#L33

However, the WAIT loop has another exit condition: it will proceed if we are about to miss our burn window, even if we aren't facing correctly. The rationale is:

1. precise timing is critical for some burns (e.g. interplanetary) but delta-v errors can be corrected mid course
2. most engines have gimbals; for a large vessel with poor control authority, beginning the burn usually helps steer the vessel toward the burn.

The problem that @fellipec pointed out, is that the mission script does not perform any mid-course corrections! Automated correction would be difficult, but without having it, the current logic can cause an automated mission to fail badly.

Also, it's a valid argument that a vessel should have good enough stability and control authority to face its burn without engine power.

I'll show my proposal for fixing both of these issues.

GET Suffix 'STATE' not found on object PART after docking.

After docking, sometimes, get error like this, when the control part changes and have not the STATE suffix.
Needs to add a check to prevent this. Maybe not the only place such can happens.

           VERBOSE DESCRIPTION
GET Suffix 'STATE' not found on object PART(crewpod-habitation-25 (MIR),uid=2271379456)
An attempt was made to get a suffix called:
    state
from an object of type:
    PartValue
when that object does not have that
suffix usable in that way.
Possible causes are:
  - No PartValue ever has a state suffix.
  - There is such a suffix, but it can't be used
      with a get operation.
  - There is such a suffix on some instances
      of PartValue, but not this particular one.
__________________________________________
__________________________________________
At 1:/lib_dock.ks, line 218
  if port:state = "PreAttached" {
          ^
Called from 1:/lib_dock.ks, line 114
    if not dockPending(ship:controlpart) {
                            ^
Called from 1:/dock.ks, line 72
        dockApproach(dockD, dockV).
                            ^
Called from 1:/rendezvous, line 58
run dock.
    ^

warp.ks needs testing w/physics, graceful transition

Use of RCS for node.ks leads to inaccurate burns

Hi there,

It seems as though this code block:

kos-ramp/ramp/node.ks

Lines 59 to 67 in b25f112

	until utilIsShipFacing(steerDir, node_bestFacing, 0.5) or
	nn:eta <= dt and utilIsShipFacing(steerDir, node_okFacing, 5) or
	ship:angularvel:mag < 0.0001 and rcs = true
	{
	if ship:angularvel:mag < 0.01 rcs on.
	stagingCheck().
	if not warped { set warped to true. physWarp(1). }
	wait 0.
	}

Is leading to some inaccurate burns. For example, when running transfer.ks to go from Kerbin to Minmus, during the execution of node_hoh.ks and node.ks, while the ship is being rotated and RCS is being used, the current orbit’s eccentricity (along with current Ap and Pe) is shifted (slightly). This results in the transfer missing the encounter as the Hohmann transfer was calculated with the previous orbit. Without RCS, the current orbit remains undisturbed and accurate burns are achieved.

Some thoughts on this:

1. Remove the use of RCS to rotating/alignment (or make it optional?).
2. Recalculate node once adjustment is made.

KSP/kOS new versions

Back from few months busy.
I installed KSP 1.4.3 and latest kOS. Noticed the RCS fine tune part and the curves of atm autopilot are doing exactly the opposite of what they used to do. Wondering if that has something to do with newer versions of KSP/kOS.