====================
obtlib Documentation
====================
Apparently, many people that play Kerbal Space Program (KSP) are unaware that
real rockets, probes and rovers have always been guided by computers. This is
obtlib, a system to aid in the construction of your mission plan and fully
automate your next KSP mission.
It relies on the add-on for KSP called Kerbal Operating System (kOS) which can
be found at:
http://forum.kerbalspaceprogram.com/index.php?/topic/165628-ksp-1101-and-111-kos-v1310-kos-scriptable-autopilot-system/
Before continuing, it is necessary to be at least vaguely familiar with the kOS
language. The documentation for kOS can be found at:
http://ksp-kos.github.io/KOS/contents.html
INSTALLATION
============
Requirements:
As obtlib itself relies on kOS, refer to that add-on's documentation for it's
requirements. obtlib was started before kOS version 1.0 was released, so some
components may still work with very old versions. The majority of it was written
using, and for the KSP 1.3 series and the corresponding versions of kOS.
However, kOS has been found to be quite forwards compatible since version 1, and
there have been only a few changes in obtlib due to upgrades since then.
The most recent development versions as of writing are KSP version 1.11.2 and
kOS version 1.31.0.
There should be no requirements for add-ons or mods in the obtlib code
itself, but many of the ships in the pseudo-savegame will require both Making
History and Breaking Ground. This is simply because the author has them; the
pseudo-savegame is not technically considered to be a part of obtlib and may be
removed without notice.
Installation:
Install Kerbal Space Program.
Install the kOS add-on.
obtlib can be downloaded as a .zip file which must be unpacked in the KSP root
directory. It should result a number of kOS scripts in
Ships/Scripts/obtlib/ as well as a pseudo savegame in saves/obtlib/ and
a few files in Ships/Scrips/boot/.
In the pseudo savegame you might find a ship called Mb0R1 Chlamydia and it's
corresponding mission profile in Ships/Scripts/obtlib/sys/. This is a basic,
under 30 part rocket can be used to try out what obtlib does. Simply "fire and
forget", it should launch a kerbal of your choice near to one of Kerbin's moons
and return them home safely.
If you are playing a career mode you must unlock the corresponding parts first.
The shortest tech tree path (as of KSP v1.11.2) to follow is:
Start -> Engineering 101 -> Stability -> Flight Control
(to unlock the kOS computer)
Start -> Basic Rocketry -> General Rocketry -> Advanced Rocketry
(for the LV-909 engine)
SETTINGS
========
There are some global variables that can (and in most cases, should) be set
before running any part of obtlib:
CONFIRM - before execution of important steps, wait for input to confirm the
action (usually using the ship's brakes).
SCOTTY - use KSP warp function during long coasts.
TALIGN - time in seconds to prepare and align to an upcoming maneuvre node.
DEBUG - enables debugging. This is an internal setting. In some cases it will
drastically change expected functionality. You have been warned.
Ensure you declare them as global. If you set them otherwise kOS will not
notice. e.g.:
> GLOBAL SCOTTY to 1.
normally results in a nice, quick mission you can finish before lunch time. On
the other hand:
> SET SCOTTY to True.
will NOT "set warp factor to eleventy billion, Tsulu" and just makes you look
like a star trek dork.
COMMANDS
========
obtlib includes some "commands" that should be able to be run from the kOS
console. In many cases they simply calculate and place nodes in the orbital path
which must be executed with:
> run xnode.
or manually. They should all be small,
self-contained and are designed to be copied to the kOS disk as needed.
There are also some <mission_*> files which accomplish various things in
multiple steps. These are documented individually as they are designed to be
loaded into memory on PRELAUNCH, not stored on the kOS disk. They are largely
designed as an aid to the system files (see BOOTING).
Some commonly used commands are as follows:
circ.ks - Makes a node that circularises the orbit in the given time, at the
assumed altitude.
dock.ks - A docking autopilot. If you are close enough, set your target (and
even a docking port), and sit back and relax.
drive.ks - A minimal rover autopilot that holds a constant heading.
escsoiv.ks - Calculates a node to escape a body with the supplied relative
velocity.
facesun.ks - Aligns the ship so that at least one solar panel points directly
at the sun.
failsafe.ks - If all else fails, tries to contact Kerbal Space Centre (KSC)
and await commands. Similar to what many real probes might be doing now.
hs.ks - Hoverslam landing command. Useful in emergencies.
intercept.ks - Makes a series of nodes to intercept the current target as
efficiently as possible.
lagsvs.ks - All purpose launch system.
oneorbit.ks - Constructs a node to affect an orbit with the given parameters in
the given time.
preflight.ks - Sets up the ship for launch.
tcm.ks - Trajectory Correction Maneuvre. This should always be run after any
major engine firing, as in the real world.
vmatch.ks - Adds a node to match velocity with the current target at the
requested time.
xnode.ks - Executes the next node.
BOOTING
=======
Some files are included in Ships/Script/boot/ as part of the obtlib system. e.g.
/Ships/Scripts/boot/spap.ks, which is a simple autopilot for aeroplanes. They
can be set to boot by the kOS system in the VAB/SPH.
bootstrap.ks (bootstrap) can be set in the KSP editor on kOS parts to
autoboot. It will load and run any files found in the directory
Ships/Script/obtlib/sys/ with the same name as the ship. kOS tags can be used to
modify this so that for example, a kOS part tagged with <-rover> on a ship named
<myship> will attempt to load a file called
Ships/Script/obtlib/sys/myship-rover.ks
bootstrap.ks also includes a way of uploading new "firmware" (itself) and new
system code on-the-fly. Firmware is updated by placing a file in the
Ships/Script/boot/ directory with the ship's name + kOS tag + ".bootstrap.ks".
Upon next boot, it will update from that file, delete it and reboot.
Updating system code is done similarly, but the file should be placed in
Ships/Script/obtlib/sys/ and the extension is ".update.ks".
LIBRARIES
=========
obtlib/lib contains some libraries which include various functions available
when writing your mission's system code (see BOOTING). Each library should
have its own documentation and, as a result these are normally quite large.
They are designed to be loaded into the kOS core memory using runoncepath() at
launch.
SHIPS
=====
There are a series of ships in the pseudo savegame saves/obtlib/VAB/ and
saves/obtlib/SPH/. Many of these may not have been tested or even used in many
years, so expect problems, but you are free to try them.
These may be removed from obtlib in the future.
THANKS/REFERENCES
=================
Robert A. Braeunig - http://www.braeunig.us/space/orbmech.htm
Chris Veness - http://www.movable-type.co.uk/scripts/latlong.html
David A. Vallado - Fundamentals of Astrodynamics and Applications
Squad - http://www.kerbalspaceprogram.com/
dunberatu - a particularly effective developer of kOS.
cheerskevin - https://www.youtube.com/c/gisikw (also a kOS dev., I believe?)
Anatoly Zak - Russia in Space
NASA - for their understanding that science should always be free.
BUGS
====
If you feel like it, the ticket tracker at http://obtlib.sourceforge.net/ should
be open for public use. As always, be precise and complete if you decide to
report a bug. There are many known bugs I keep in my head already - obtlib is
far from complete - I simply haven't had the time or energy to make them
"official" by reporting them myself.
Patches are welcome, but ensure they pass the unit tests scattered everywhere
(sorry about that - that, in itself is a bug!). If you can provide your own unit
test, that is even better.
A good example can be seen at the end of obtlib/lib/obtlib_mission.ks
Make sure you use `diff -u ...`.
LICENSE
=======
There may be files copied from other sources in the obtlib repository, largely
because I intended to heavily modify them, just started over, and forgot to
remove them. All of them are under Public Domain, BSD, GPL, or CC-by-Commons.
The licenses and sources are repeated in full where they are used, as required.
obtlib itself uses some algorithms copied (often with modifications) from
other sources (see THANKS/REFERENCES) but the code is public domain.
FIXME: I think the sourceforge page says its GPL? I'm too old for this shit,
make it PD if possible.
