nashsclay / konrad Goto Github PK

KONRAD - Kerbal Operations, Naughty Rockets, Aerial Debris

A telemachus control panel with a retro feel.  Built on curses technology.

License
-------
KONRAD is licensed under the GNU General Public License version 2,
incorporated herein by reference.

Dependencies
------------
* Python
  - tested with 2.7.11 but should work on any 2.6 or later
  - doesn't work with Python3 yet
* curses
* websocket-client, https://pypi.python.org/pypi/websocket-client/
  - can be found in Debian package "python-websocket"
* Telemachus, https://github.com/richardbunt/Telemachus

Arguments
---------
For details of command line arguments, run with -h or --help.

Consoles
--------
konrad.py must always be run with a 'consname' argument, indicating which
console it should display.  So far we have the following:
* fd
    Flight Director.  Summarises key vehicle state.
    Inputs:
    - t/r/b/g for SAS/RCS/BRK/GEAR
    - space for staging
    - 1-9 and 0 for action groups
    - ! (shift-1) for Abort!  (NOTE!  Not the same key as in KSP!)
* traj
    Trajectory.  The guy who's steering probably wants this one.  If you want
    remote control, pass option --mj to enable MechJeb commands
    Pass option --target-alt or both of --target-apo and --target-peri to get
    nice FractionGauges.  Note: --target-alt=X does not mean the same thing
    as --target-apo=X --target-peri=X; the former will have a target velocity
    of the Vcirc at altitude X, while the latter will have a target velocity
    dependent on your current altitude (determined from vis-viva equation),
    just like it would if target apo and target peri were different.
    VOR and ILS are for landing approach, where the --init-lat and --init-long
    specify the runway threshold; VOR gives (great-circle) bearing to the
    runway, while ILS shows distance short of threshold for touchdown at
    current descent rate.
    Inputs: < (retrograde) and > (prograde) control AoA gauge behaviour.  The
    rest are MechJeb commands:
    - P/R to select (orbital) Prograde or Retrograde hold
    - O/I to select Radial Plus ('O'utward) or Minus ('I'nward)
    - +/- to select Normal Plus or Minus
    - Enter to select Fixed (uses the Input Orientation PIT/HDG/RLL)
    - s/w to change Input PIT by ±10°; S/W for ±1°
    - d/a to change Input HDG by ±10°; D/A for ±1°
    - e/q to change Input RLL by ±10°; E/Q for ±1°
    - ` (backtick) to cycle fine controls (COARSE is as above, NORMAL and then
      FINE divide by 10 per step)
    - ? to copy current Orientation into Input Orientation
    A warning about Fixed mode: while the controls may appear to be the same
    as in-game, *they are not*!  For instance, if you are rolled 90° right,
    pressing 's' in KONRAD will effectively yaw left (same as pressing 'a' in-
    game), as that is what is required to increase your pitch.
* boost
    Booster.  Track remaining fuel and delta-V.
    Requires an accurate JSON Booster file, supplied with --booster.  See the
    section "JSON Booster" below for more information.
    Inputs:
    - x to cut throttle
    - 1-9 for 10-90% throttle
    - z for 100% throttle
    - space for staging
    - ? to refresh stage detection
    - / to override stage detection with a staging event (i.e. cause konrad to
      pretend the vehicle has staged even though it doesn't believe it has.)
* retro
    Retrograde Guidance.  For judging landings on airless bodies.
    See section "Landings" below for more information.
    Pass option --ground-map=<csvfile> to supply a SCANsat CSV map of ground
    elevation, or --ground-alt=<altitude> to assume a fixed value.
    Pass option -b <body-id> for the body you're landing on.
    Requires an accurate JSON Booster file, supplied with --booster.  See the
    section "JSON Booster" below for more information.
    Inputs:
    - f to select 'Fixed' mode (assume vehicle holds current pitch)
    - r to select 'Retro' mode (assume retrograde hold)
    - PgUp/PgDn to increment/decrement Reserved Stages
    - x to cut throttle
    - 1-9 for 10-90% throttle
    - z for 100% throttle
    - space for staging
    - ? to refresh stage detection
    - / to override stage detection
* r3d
    Retrograde Guidance 3D.  Like retro, but works in 3 dimensions, so can
    handle off-retrograde headings, compute lat/long of landing site, etc.
    Same inputs as retro, but different displayed info.
* asc
    Ascent Guidance.  For judging launches to orbit (ignores air drag).
    See section "Ascent Guidance" below for more information.
    Requires an accurate JSON Booster file, supplied with --booster.  See the
    section "JSON Booster" below for more information.
    Inputs:
    - f to select 'Fixed' mode (assume vehicle holds current attitude)
    - p to select 'Progd' mode (assume prograde hold)
    - PgUp/PgDn to increment/decrement Reserved Stages
    - x to cut throttle
    - 1-9 for 10-90% throttle
    - z for 100% throttle
    - space for staging
    - ? to refresh stage detection
    - / to override stage detection
* a3d
    Ascent Guidance 3D.  Like asc, but works in 3 dimensions, so can handle
    off-prograde headings, compute inclination or relative inclination, etc.
    Same inputs as asc, but different displayed info.
* mnv
    Astrogation.  Orbital transfer burns (only really useful for TLI so far).
    See section "Astro-what?" below for more information.
    Pass option -t <body-id> for the target body, usually 10 (Moon).
    Requires an accurate JSON Booster file, supplied with --booster.  See the
    section "JSON Booster" below for more information.
    Inputs:
    - f to select 'Fixed' mode (attitude specified with PIT/HDG boxes)
    - l to select 'Live Fixed' mode (assume vehicle holds current attitude)
    - p to select 'Progd' mode (assume prograde hold)
    - r to select 'Retro' mode (assume retrograde hold)
    - PgUp/PgDn to increment/decrement Reserved Stages
    - x to cut throttle
    - z for 100% throttle
    - w/a/s/d to set PIT/HDG boxes (shift for fine)
    - ` (backtick) to cycle fine controls (COARSE is as above, NORMAL and then
      FINE divide by 10 per step)
    - @ to copy current orientation into PIT/HDG input boxes
    - space for staging
    - (/) to change start time in 1s increments
    - [/] to change start time in 10s increments
    - {/} to change start time in 100s increments
    - # (toggle) to scale the above three by 1000x
    - ,/. to change burn duration in 1s increments (NORMAL; others scale 5x)
    - </> to change burn duration in 10s increments (NORMAL; others scale 5x)
    - 0 to set burn duration to zero
    - B to unlimit burn duration (i.e. 'until burnout')
    - N to fix burn end (i.e. start counting down once Start is passed)
    - ? to refresh stage detection
    - / to override stage detection
* esc, clo, fba
    Escape, Close-Approach and Fly-By Astrogation (respectively).
    Same inputs as mnv, but different displayed info.
    See section "More Astrogation" below for more information.
* xfer
    The Transfer Window planning console is in a separate program, xfer.py,
    because it doesn't use telemetry.  It generally works like a close-approach
    astrogation console, except that rather than specifying the burn from a
    parking orbit, you specify the hyperbolic excess velocity (also known, not
    entirely correctly, as the C₃ velocity).  The delta-V to attain this from a
    180km parking orbit (assuming no plane change) is also calculated and
    displayed.
    Note that this isn't designed to compute a burn for a specific vehicle;
    consequently it does not require (or accept) a JSON Booster file.
    Inputs:
    - f to select 'Fixed' mode (attitude specified with PIT/HDG boxes)
    - p to select 'Progd' mode (assume prograde hold)
    - r to select 'Retro' mode (assume retrograde hold)
    - w/a/s/d to set PIT/HDG boxes (shift for fine)
    - ` (backtick) to cycle fine controls (COARSE is as above, NORMAL and then
      FINE divide by 10 per step)
    - (/) to change start time in 1-minute or 1-day increments
    - [/] to change start time in 30-minute or 10-day increments
    - {/} to change start time in 6-hour or 100-day increments
    - # (toggle) to switch between the two modes for the above three
    - ,/. to change burn duration in 1s increments (NORMAL; others scale 5x)
    - </> to change burn duration in 10s increments (NORMAL; others scale 5x)
    - 0 to set burn duration to zero

Global Inputs
-------------
The following inputs are recognised by any console:
- Ctrl-X to exit
- (/) to select prev/next body (if autodetection fails)

Useful Notes
------------
There are two kinds of FractionGauge: Mode 3 and Mode 2.  (Naturally.)
Mode 3 gauges simply fill up from left to right, mostly green, with red and
yellow denoting a 1/3 and 2/3 filled block respectively.  They are used either
where an overshoot is physically impossible (e.g. >100% fuel reserve) or for
angle gauges, where the values wrap around (and may become negative; these
gauges will use the absolute value in this situation).
Mode 2 gauges are used when there is an (implicit or explicit) target for the
value being displayed (e.g. altitude, apsides or velocity).  These gauges also
fill up with green, with yellow denoting a 1/2 block.  However, once they
overshoot the target, they 'bounce off' the end in red.  So a bar 3/4 green and
the rest red indicates a value 125% of the target.

JSON Booster
------------
A way of telling KONRAD some things about your rocket that it can't get from
the telemetry.  The information is specified in JSON format, according to the
following layout:
The top-level item is a Booster, which consists of a list of Stages.
A Stage is a dictionary, with the following items:
  "props": list of Propellants
  "isp": main engine Isp in seconds
  "dry": stage dry mass in tons
  "thrust": main engine thrust in kN
  "minThrottle": optional main engine minimum throttle setting in percent
                 (defaults to 100, i.e. unthrottleable).
A Propellant is a dictionary, with the following items:
  "name": the KSP resource name of the propellant
  "volume": the volume of the tank (this is in litres if using RealismOverhaul)
  "density": the propellant density.  Look in resource files for this
  "mainEngine": optional boolean (defaults to true) indicating whether this
                 propellant is consumed by the main engine (and is thus part of
                 the interpretation of the Isp figure)
  "ratio": optional volume flow fraction consumed by engine(s) of stage.  If
            this is omitted, it will be calculated from the tank volumes in the
            stage on the assumption that the engine depletes all mainEngine
            propellants equally.  Normally this assumption is fine, but if you
            have added extra, say, LH₂ to allow for boil-off, then it will lead
            to overestimation of the stage delta-V.  Note that "ratio" should
            be specified for _all_ mainEngine propellants in the stage, as
            otherwise incorrect calculations will result.
Some examples are in the jb_examples/ directory:
* WAC.  Three TinyTim boosters and an Aerobee sustainer.
* AtlasAgena.  An Agena-D (with hydrazine RCS) on an Atlas SLV-3.  This example
   exhibits one of the main limitations of the format: it can't comprehend
   Atlas-style parallel staging.  But that's OK, because there's no way for us
   to figure out from the telemetry whether the booster engines have been
   dropped _anyway_, as Telemachus won't give us staging information directly -
   we have to deduce it by noticing that tanks have been dropped, which of
   course doesn't work for Atlas.  (However, it turns out that the booster
   engines have TEATEB tanks, meaning that we _can_ detect the staging event.)
* MercuryAtlas.  An example of how to make parallel staging work, based on
   FASA's Mercury and Atlas parts.  Note how (a) the sustainer propellants are
   listed under the third stage, even though they're in the same tank as the
   others; (b) the TEATEB tanks on the LR-89 booster engines are used to detect
   when those engines are dropped; (c) the escape tower is treated as dead
   weight because in a nominal launch it will be jettisoned rather than fired.
   The delta-V for the booster stage will be a slight underestimate, because
   the concurrent sustainer burn is at a higher Isp; strictly speaking we
   should use an average Isp weighted by fuel flow rate, but this would be very
   close to the booster engine Isp, so the errors should be small.

As it's somewhat annoying to have to work out all these values (particularly
 the dry masses), it would be nice to have a way to export a JSON Booster
 specification from the game.  That's something I plan to look into in the
 not-too-distant future.  (Unfortunately, the tricks we use for Atlas would
 still need to be done by hand.)
You can, however, avoid having to look up all the densities: just set the
 environment variable KSPPATH to point at your KSP top-level directory, and
 KONRAD will read GameData/ModuleManager.ConfigCache to find them out.  That
 way, you can leave the "density" key out of Propellant specifications.

Landings
--------
The Retro console may seem rather intimidating at first, with its large array
of poorly-labelled numbers.  But don't panic, the layout is very logical and
it's quite simple to use.  The first thing to notice is that there are two
blocks with similar layout, for "At current throttle" and "At 100% throttle".
This is so that you know if full throttle suffices to prevent lithobraking.
Now, for each of those two throttle settings, KONRAD will run a simulation.
It will assume either that you maintain your current pitch (Fixed mode) or
that you hold surface retrograde (Retro mode), and that your heading is that
corresponding to surface retrograde.  This simulation takes into account the
decreasing mass of your craft as propellants are burned, the curvature of the
target body, etc.  There are four 'events' of interest which the simulation
will record:
* Horizontal - the horizontal component of velocity becomes zero.  (If using
  Fixed mode, from this point the sim will assume a pitch of 90°.)
* Vertical - the vertical component of velocity becomes zero.
* Surface - the altitude above terrain becomes zero.
* Burnout - the vehicle is emptied of all propellants.  (If your vehicle has a
  separate ascent stage, like the Apollo LEM, you can use 'Rsvd.Stg.' - i.e.
  reserved stages - to exclude it, so that this event correctly shows burnout
  of the descent stage.)
For each of these events, various parameters are recorded, a selection of
which are displayed (different for each event).
T: time after simulation start
Y: altitude above terrain
X: distance downrange from simulation start
V: vertical speed (upwards positive)
H: horizontal speed
The various displayed numbers will mostly be coloured red or green to tell you
whether they are bad or good news.  For instance, if Vertical Y is negative,
this means you won't stop descending before you hit the ground, which is Bad.
There's also 'Touchdown' - which is 'Surface' if it happens, 'Horizontal'
otherwise - at which the latitude and longitude are recorded.  These can be
used for targeting a specific landing site.

So how does one use this information?  Assuming you're on a sub-orbital
trajectory, point retrograde, select Fixed mode, look at the "full throttle"
output, then increase pitch until Vertical Y is green (positive).  Check that
Burnout T is green (greater than Surface T) - if not, you'll run out of fuel
before landing at this rate, which probably means you need to wait a while and
descend further before running the engine.
Check that Horizontal T is green (less than Vertical T) - if not, you need to
point at a higher pitch to increase the time you have for
horizontal braking.
Assuming everything's green, throttle up to 100% and watch the descent.  The
numbers should all remain roughly constant, except that X decreases and T
counts down.
Wait until your retrograde marker passes through your current pitch (i.e.
you're descending more steeply than you're pointing).  At this point, switch
your SAS to Retrograde Hold, and switch KONRAD into Retro mode (by pressing
'r').  You should find that the board is still green (except maybe for
Horizontal T, which should now be equal to Vertical T), but that Vertical Y is
now rather larger than it was.  Throttle down until Vertical Y is only just
above zero - you want to aim for about 40 metres.  (At this point you may need
to start making an adjustment for errors in your terrain map.  This is because
unfortunately SCANsat maps only have ½° resolution, which does not always
capture enough terrain detail on a cratered moon.  You also, of course, need
to start looking at the "At current throttle" board.)
Once your vertical speed is suitably low, throttle back further; try and keep
your Vertical Y at a few seconds' descent above the surface.  Once you're
descending vertically at a good landing speed, throttle back to bring your TWR
as close to 1 as you can.  After a few more seconds you should touch down
gently on the surface; cut your engine, sit back, and relax.  Congratulations,
you've landed!

Ascent Guidance
---------------
The Ascent console is based on the same principle as Retro, namely running a
simulation based on certain assumptions, and recording motion parameters at
various events.  The AscentSim recognises three events:
* Orb-Vel - the horizontal component of velocity reaches the velocity for a
  circular orbit at the current altitude.
* Vertical - the vertical component of velocity becomes zero.
* Burnout - the vehicle is emptied of all propellants, excluding any reserved
  stages.
The following variables are shown at one or more events:
T: time after simulation start
Y: altitude above MSL / geoid
V: vertical speed (upwards positive)
H: horizontal speed
A: apoapsis
P: periapsis
Because the AscentSim ignores atmospheric drag, it won't be useful until the
air thins out.  On the other hand, you won't have much freedom to steer
anyway while in thick air, because aerodynamic forces will destroy a rocket
that doesn't stick pretty closely to a gravity turn.  (Judging the pitch kick
to start your gravity turn is a separate problem, which AscentSim can't help
you with.  Try running some simulations in Kerbal Construction Time.)
If you just want to reach a circular orbit, and don't care too much about the
altitude, select Fixed mode and aim to get Orb-Vel V close to zero.  This
means that on reaching orbital velocity, your vertical speed will be zero, so
you will be in a circular orbit at that altitude.
Conveniently, the Orb-Vel section also displays altitude (Y), so if you want
to target a specific (circular) orbit, you can aim either above or below the
angle for circularisation to slowly 'pull' your final orbital altitude one way
or the other.  This can take a bit of practice and judgement (or just an
intuitive understanding of the underlying dynamics) to get right, though.
And remember to keep an eye on Burnout time!

The Ascent Guidance 3D console (a3d) uses the same (3D) simulation engine as
the astrogation consoles (see below), enabling it to also output the following
variables at each event:
i: inclination
ri: relative inclination (to target specified with -t <body-id>
L: longitude of ascending node
There is also a fourth event, 'Now', which displays the current state; as well
as the above, it also displays the longitude in reference co-ordinates (which
is not the same thing as the geographic longitude!) as 'lon'.

Astro-what?
-----------
OK, this is the weird one.  The Astrogation console ('mnv') assumes you start a
burn at some fixed time (which you can put in the future), which continues at
full throttle until burnout (excluding any reserved stages).  It then converts
the resulting position and velocity back into Keplerian orbital elements, and
figures out your time and position of apoapsis.  Then, it works out where the
target body will be at that time, displaying the altitude and phase angle.  It
also works out the change in phase angle from burn time to apoapsis, which you
can compare to the phase angle at burn time (this may be more accurate due to
inclination differences).
The readouts are:
event Start: time the burn is set to begin (change with () [] {}).
T: time from now
Y: vessel altitude
p: phase angle to target (defined as angle subtended at parent-body centre)
j: target true anomaly (this is probably not interesting)
ApT: time to next apoapsis
PeT: time to next periapsis
lat: latitude
hdg: heading of prograde vector
event End: burnout
T: time from now
Y: vessel altitude
V: vessel vertical speed
A: apoapsis altitude
P: periapsis altitude
D: orbital period
J: true anomaly to apoapsis (= 180° - current true anomaly)
event Apo: next apoapsis after burn
T: time after End (*not* time from now!)
Z: target altitude
q: phase angle change relative to End
*: phase angle to target (again, angle subtended at parent body)
i: relative inclination (angle between orbit normal vectors)
   (if target_body not set, this will just be vessel orbital inclination)
Tgt (not really an event): target state
target name
J: vessel true anomaly at Start
Q: phase angle now (calculated a different way, by KSP itself)
RL: relative LAN now
RI: relative inclination now

Other displays: Vac.DeltaV should be obvious.  TWR is thrust-to-weight ratio at
current throttle, measured in local g.  MAX is TWR at full throttle.
Rsvd. Stg. is the usual 'reserved stages' (PgUp/PgDn to set).  Mode sets
steering assumptions for the sim, and can be set with the following keys:
f   Fixed mode: steer according to the PIT and HDG values dialled in with wasd.
i   Inertial mode: start at the PIT and HDG values, but don't actively steer
    after start (so orbital motion will transform them).
l   Live Fixed: use vessel's current pitch and heading.
k   Live Inertial: start as Live Fixed but, like Inertial, don't steer.
p   Prograde: follow orbital prograde vector.
r   Retrograde: follow orbital retrograde vector.
'Burn' indicates whether the burn lasts until propellant depletion ('Full') or
is a specified duration ('Timed').  The latter will generally be less accurate
as it relies on the user cutting the throttle at just the right moment, while
the displays only have a 0.2s resolution (and there is a bit of telemetry lag).

How to use this?  Let's say you've got a probe on top of a 3100m/s kick stage,
with the whole thing in LEO connected to an upper stage that's empty except for
RCS and some small solid motors to spin it up (the kick stage lacking avionics
of its own).  Your aim is a lunar impactor, and you've conveniently launched
from the Cape into a 240km-ish orbit inclined about 0.3° to the Moon.
You put the astrog console into Fixed mode and set it to due east, and you see
that that takes you to well over 400Mm - too high.  Also it gives you a crazy
inclination, but we'll worry about that later.  You gradually increase PIT
(by pressing 's' or 'S') until the apoapsis height (End A) roughly matches the
target height at apoapsis (Apo Z).  Now you look at delta phase angle (Apo q)
and see it's about 108° whereas phase angle now (Tgt Q) is, let's say, 260°.
So you push the burn time (Start T) into the future with ), ] and } (steps of
1s, 10s and 100s respectively) until the phase angle at burn (Start p) is
roughly 108° (the delta phase angle we prepared earlier).  Now that you have
approximately the right burn time, you can adjust the burn heading to minimise
relative inclination (Apo i); this heading will be close to prograde at burn
time, but probably not exactly the same.  But now your post-burn apoapsis is
too high because you're not wasting any delta-V on a huge normal component, so
you re-adjust pitch (W/S, possibly switching to Fine controls with `) until it
(End A) is just right.  You don't actually want End A to equal Apo Z, because
once you enter the Moon's SOI it will pull you outwards a bit, so you want to
aim for a point a few Mm short (finding the right fudge factor takes practice;
if you want Konrad to do the patched conics for you you'll need to use one of
the more advanced astrogation consoles, probably 'clo').  When you finally get
it spot on, the phase angle will probably be slightly wrong - you want to fine-
tune it to minimise the apoapsis phase angle (Apo *), which you do by adjusting
the burn time.  This in turn slightly changes the prograde heading (and
possibly the orbital velocity, if your parking orbit is quite eccentric), so
now you need to tweak HDG and maybe PIT again.  After a few rounds of
successive approximation, you should be able to get phase angle (Apo *) and
inclination (Apo i) under 0.1°.  Read off the PIT and HDG values and give them
to whoever's steering the vessel (e.g. Traj console with MJ Fixed mode).  Now
patiently wait for Start T to count down.
About four minutes before burn time (i.e. Start T = 240), have them start
actively steering the vessel to the specified pitch and heading, then set your
astrog console to LiveF mode (press 'l').  Now instead of using the pitch and
heading you entered in, the simulations will run based on the vessel's current
attitude.  As the burn time counts down towards zero, try to get a feel for how
the parameters are varying - typically they will oscillate around the target as
the steering oscillates around the desired attitude.  When all the numbers look
good (i.e. Apo * and Apo i well under 1°, End A near Apo Z minus fudge factor),
and Start T is close to zero (or has just reached zero), fire your spin-up /
ullage motors, then light your stage, and wait for burnout.  When the tanks are
empty, in theory you should be on a collision course with the Moon!

More Astrogation
----------------
These three astrogation consoles are capable of finding closest approaches and
patching conics, and can thus be used to make much more accurate transfer burns
than the 'mnv' console.  In general they start with the same burn-sim as 'mnv',
but then look for various events on the resulting trajectory; these are usually
displayed left-to-right.  The consoles are:
* esc: Escape Astrogation.  Shows SOI Exit.
* clo: Close-Approach Astrogation.  Adds Approach and SOI Entry
* fba: Fly-By Astrogation.  Adds tSOI Exit.
The events are:
* SOI Exit: this is when you leave the current SOI (typically Earth), and are
  patched into a new one (typically Sun).  Apoapsis, Periapsis and Period (D)
  are displayed, as is either Relative or Absolute Inclination (depending on
  whether a target was specified).  If your orbit does not escape, this event
  will be skipped and the next one will use the unpatched orbit.
* Approach: this is the closest approach to the target found within one synodic
  period (that is, the time it takes for you to have done one more orbit than
  the target or vice versa).  Distance d and relative velocity v are displayed,
  as are distance from Earth ('Re', useful for knowing whether you'll have
  comms when you arrive) and the last step size of the iterative search ('w', a
  rough indication of how accurate the calculations are.  Normally this should
  read zero; if not, you may find TCMs are needed later).
* SOI Entry: if you get close enough to the target to enter its SOI, you will
  be patched in.  Apoapsis, Periapsis and Inclination (i) are displayed, as are
  Earth distance (Re) and last step size (w) as above.
* tSOI Exit: patches you back out of the target's SOI into orbit around its
  primary.  Apoapsis, Periapsis, Period (D) and Inclination (i) are all
  displayed, as is Time to Periapsis (PeT).  The output for this event is
  squeezed in underneath SOI Exit, because we ran out of horizontal space.