|
|
|
Virtual
AGC and AGS
Peripheral
Components for Use with yaAGC |
|
|
|
Table of Contents
Contributed Code
LM_Simulator, by
Stephan Hotto
This is a kind of proof-of-concept program, which is in the process of
becoming an IMU simulation. It's pretty close to being complete,
though we're still working out a few problems. But the program
is useful
even without a complete IMU simulation, as a nifty little monitor for
the CPU's i/o
channels. You can use it to see the output on output channels, to
generate input on input channels, or else to simply monitor or generate
arbitrary messages on the socket interface. At the moment, it's
specifically targeted towards the Lunar Module simulation, but because
there is a very great overlap between the way peripherals like the IMU
were implemented in the LM and CM, you can profitably use LM_Simulator with the Command Module
simulation as well. Nevertheless, be aware that not everything
you see in the CM version of the program is actually present in the
CM! Also, at present the program interacts only with the AGC
simulation (yaAGC); in the
future, it will undoubtedly interact with the AGS simulation (yaAGS) as well.
To get LM_Simulator, you have
to download the development-snapshot tarball; the program itself is in
the directory Contributed/LM_Simulator, and is licensed under the GPL. At
the present writing (06/18/05), the SimLuminary131
and SimColossus249 scripts
used to start up the the AGC simulation automatically start LM_Simulator for you.
Here are some notes from Stephan on its use, as edited somewhat freely
by me. The program is a moving target, and I'm combining text
from a number of different emails here, so you can blame me for any
incoherence.
As a by-product [of the IMU
development] I've created a small Tcl/Tk program to monitor the
activity of the output channels and to manipulate dedicated bits of the
input channels, which is probably useful in developing the
different interfaces. Because it is written in an interpreter
language you can use it on Linux/Windows/MAC without any change. The
only pre-condition is an installed Tcl/Tk environment. For example
under LINUX you can simply type "wish
lm_simulator.tcl". [The
SimLuminary131
or
SimColossus249 script
automatically
starts
LM_Simulator, so you
really don't need to start it explicitly, but
you can also explicitly start it as described.]
The monitor connects to the localhost on port 19801 (IMU reserved port)
[or port 19701 for the CM] and is focused on the Luminary 131(1C)
channel allocation. If
you, for example, want to simulate a "Temperature of Stable Member out
of Design Limits" then you can set the input channel 30 to
"100000000000000" and the DSKY Temperature warning will go on.
[After he wrote this, Stephan implemented a checkbox for this
particular input, so it's actually much easier than he says, but what
he says here still works.]
The program is split into the following modules which can be called by
the menu of the main program:
| lm_simulator.tcl |
Main Program for the LM version
of the program
|
lm_simulator.ini
|
The default configuration file.
|
| AGC_Crew_Inputs.tcl |
Nearly all Crew Switches
connected to the AGC |
| AGC_Outputs.tcl |
All binary AGC outputs
interpreted by showing their status |
| AGC_System_Inputs.tcl |
All binary LM->AGC System
Inputs |
| AGC_IMU.tcl |
First steps into the IMU &
FDAI (not
completely working, need some more counters) |
AGC_Attitude.tcl
|
For manually feeding
acceleration or changes in physical attitude into the IMU.
(Eventually, of course, this will be accomplished by modeling the
thrust and rotation of the spacecraft.)
|
AGC_DSKY.tcl
|
A DSKY simulation that can be
used in place of yaDSKY.
|
Stephan has also provided a helpful tutorial.
The tutorial will be found in the Contributed/LM_Simulator/doc
directory.
Here are some screenshots from the program. (LM_Similator is changing so fast,
that I can't keep up with it, and some of the screens may look
substantially different now than when I created the screenshots.
I'll update them when the rate of change slows down somewhat.)

Main screen
|

Inputs from system
|

Inputs from crew
|

Outputs |

IMU
|

DSKY
Lite with yaDSKY
|
The program has a configuration
file called "lm_simulator.ini" which can be used to configure some
aspects
of LM_Simulator's
operation. The program has built-in configuration options, but
these can be overridden with the configuration file, which in turn can
be overridden by command-line options. I won't bother to describe
this configuration file in detail, since
you'll see how it works if you look at it. Basically, it tells
you which port to use to connect to yaAGC,
and determines which of LM_Simulator's
windows to automatically open at startup.
As of 2005-06-19, the usage of LM_Simulator
is as follows:
cd
InstallationDirectory
lm_simulator [OPTIONS]
The currently-recognized command-line options are:
--port=PortNum
Changes the port number (by default,
19801) used to connect to yaAGC.
This can also be changed in the configuration file.
--cfg=IniFilename
Used to change the name of the
configuration-file used. By default, the file is
lm_simulator.ini, in the installation directory. With this
option, you can change the name or directory of the file.
If you discover problems with LM_Simulator,
or want to cooperate on it, you'll probably want to contact Stephan
directly. (His contact info is in the source code.)
yaUniverse
yaUniverse would be a program
that physically models the motion of the spacecraft and of the heavenly
bodies visible to the spacecraft or affecting it. From knowing
the initial time,
position, and velocity of the spacecraft, and application of physical
laws, yaUniverse would be able
to calculate the position and orientation of the spacecraft and
heavenly bodies at all times relevant to the mission. The forces
on the spacecraft which would be accounted for would be:
- (Required) Gravitation from the Earth, Moon, Sun, etc.
- (Required) Thrust applied by the spacecraft itself.
(It should be noted that thrust expends fuel, and thus reduces the mass
and the changes the inertia tensor --- i.e., the rotational
characteristics --- of the spacecraft.)
- (Optional) Atmospheric drag for launch or reentry.
- ... and any other forces we might like to imagine (such as
outgassing from an exploding Apollo 13 oxygen tank).
Originally I intended not to calculate the positions of heavenly bodies
in real time, but rather to use pre-calculated or pre-tabulated
ephemeris data. However, the amount of ephemeris data is pretty
large, so I've instead decided to use the
laws of physics to track the heavenly bodies as well as the
spacecraft. Note that the initial
positions and velocities of the
heavenly bodies still need to be obtained somehow, but they can simply
be gotten
for any given mission epoch by downloading them from the Jet Propulsion
Laboratory's HORIZONS system at
telnet ssd.jpl.nasa.gov 6775
I'll do all of the downloading, of course, though at present
(2004-09-23) I include only Apollo 8 data in the development snapshot.
An additional complication is that even though I've spoken above of
"the spacecraft", there is not just a single spacecraft. Rather,
there several spacecraft, which at any given time in the mission may be
docked or separated: the CM, the SM, the LM's descent stage, the
LM's ascent stage, the Saturn stages, and various combined versions of
these. The motion of each must be tracked. For example, it
may be necessary in the course of the mission for the the astronaut to
use the CSM's AOT (see below) to mark the position of the
LM. yaUniverse
provides the data for this to yaAOT,
and thus must be able to simultaneously track the CSM and the LM.
Like yaAGC, yaUniverse would be a server from
which yaIMU and yaAOT obtain data. A TCP
socket interface is used for this, though the data protocol is
presently
TBD.
yaUniverse requires no user
interface, other than a way to define the starting time, positions,
velocities, and physical characteristics of the spacecraft.
However, it would be convenient to have at least some kind of running
printout of positions, velocities, orientations, and masses.
The barest beginning of yaUniverse
exists. It is presently capable only of numerically integrating
the positions of the heavenly bodies and spacecraft, but not of
communicating this information to yaAGC.
The syntax is:
yaUniverse
[OPTIONS]
The recognized options are:
--help
Displays textual info similar to that
shown here.
--mission=Name
Selects the name of the mission, which
determines the initial positions of the Earth, Moon, Sun, Venus, Mars,
Jupiter, and Saturn for the
mission, and thus the gravitational influences on the spacecraft.
The mission names, by convention, are "Apollo8" (without quotes),
"Apollo9", etc. The default is "Apollo8". The actual
ephemeris files used have names like
"Ephemeris-Earth-Apollo8.txt", "Ephemeris-Moon-Apollo8.txt", and
"Ephemeris-Sun-Apollo8.txt", but this is transparent to the user.
The Apollo8 mission is special, in that it contains complete ephemeris
data (rather than mere initial conditions) and hence can be
used for testing yaUniverse's
ability to perform numerical integrations of planetary positions.
--ephem-read
Causes yaUniverse
to display ephemeris data and then quit. It's purpose is really
just to test that it can correctly read ephemeris files. It
forces --mission=Apollo8.
--ephem-int
Causes yaUniverse
to print a report testing its numerical integration algorithms and then
quit. It forces --mission=Apollo8. Specifically, what it
does is this: From the
initial positions and velocities of the supported heavenly bodies
(Earth, Moon, Sun, Jupiter, etc.), it computes locations
of all heavenly bodies for the complete Apollo 8 mission epoch.
It then compares these with the pre-tabulated ephemeris. Only the
error in the Earth/Moon positions is really interesting, since that's
the region of space in which the Apollo spacecraft operated. At
present, with the default settints, the cumulative error in Earth/Moon
positions at
the end of the 9-day epoch is about 0.35 km (which I consider
acceptable,
but
which I'd like to improve in the future).
--runge-kutta=N
The order of the Runge-Kutta numerical
integration. N=2 or 4
(default is 4).
--planets=N
The number of planetary bodies used in
the numerical integration.
N=3-15, and
is 7 by default:
N=3
Earth, Moon, and Sun.
N=4
Same as N=3,
plus Jupiter.
N=5
Same as N=4,
plus Saturn.
N=6
Same as N=5,
plus Venus.
N=7
Same as N=6,
plus Mars.
N=11
Same as N=7,
plus Ganymede, Io, Europa, & Callisto.
N=15
Same as N=11,
plus Titan, Tethys, Rhea, & Dione.
The addition of Titan
et al.
makes a big difference in the error of Saturn's position, but has no
obvious effect on the inner solar system. Similar comments apply
to Galileans and their effects on Jupiter and the inner solar
system. Mercury and Uranus also have no obvious effect at
all.
Note: If the
Galileans are added, you will need to adjust the timestep (see below)
downward, say to 7200, to account for the very short orbital periods of
some satellites.
--timestep=T
The time, in seconds, used as the
timestep for the numerical integration when only gravitational effects
present, and the spacecraft are not close to the planetary
bodies. The default is 6 hours (21600 seconds). The value
must be either an exact divisor or exact multiple of 3600.
Intermediate values (at times between the timesteps) are obtained by
interpolation.
yaIMU
Since
Stephan Hotto's contributed LM_Simulator program provides an
IMU, a separate yaIMU program
is no longer planned. However, if you're interested in providing
one, feel free to proceed. (Independent implementations are
always useful for verification.)
|
yaAOT
yaAOT is a simulation of the
Alignment Optical Telescope (AOT). yaAOT is a client of both the yaAGC and yaUniverse servers. From
the orientation of the spacecraft (obtained from yaUniverse), and from the
orientation of the telescope with respect to the spacecraft (which is
initially driven by yaAGC), yaAOT is able to compute the
direction which the telescope is pointing. From starcharts, it is
able to display a star-field on the PC. The astronaut then
manually adjusts the orientation of the telescope (i.e, the star-field)
to point at the objects he is attempting to mark; these objects can be
stars, reference points such as the Earth horizon, or the other
spacecraft --- i.e., the LM or CM. The new orientation of the
telescope is then read back by yaAGC.
Star-data is available online and, as nearly as I can tell, the Centre
de Données astronomiques de Strasbourg is the generally-recognized place from
which to download them.
yaACA
yaACA is a simulation of the
Attitude Controller Assembly --- i.e., of the rotational
hand-controller (RHC), used by astronaut to affect the pitch, roll, and
yaw
of the LM. It is a client of the yaAGC
server, and sends the CPU information related to the displacement of
the hand-controller from its neutral position. I envisage the use
of
a 3D joystick, as used for many computer games.
The yaACA program is now complete and operational,
although the usage of it within the system as a whole has not yet been
verified (2005-07-09), so further changes to it are likely.
José Portillo has described the interaction between the ACA and
AGC in great detail in the following paper: klabs.org/mapld04/papers/g/g202_portillo_p.pdf.
This was the principal resource used implementing yaACA and integrating it into the
Virtual AGC system. The actual methods of implementation involve
the use of fictitious i/o channels 0166-0170, and true i/o channel
031. Refer to the developer
page and to the assembly-language
manual for more details. Note that yaAGC echoes input-channel
information received from yaACA,
so other peripheral devices (such as yaAGS)
wishing to receive RHC data can do so via their communication with the yaAGC server.
The program defaults have been set for a Logitech Extreme 3D Pro "twist
handle" joystick, since that's what I purchased for development
purposes. The program should hopefully should work for
any twist-handle joystick, though command-line switches may be needed
for proper configuration. Only 3 degrees of freedom (roll, pitch,
and yaw) and no buttons are used by yaACA.
yaACA displays a lot of data
about the characteristics of the joystick used, as well as displaying
the raw roll/pitch/yaw displacements in real time, so I hope that
debugging new types of joysticks should be relatively easy.
The syntax is:
yaACA [OPTIONS]
The recognized options are:
--help
Displays textual info similar to that
shown here.
--roll=J,S,A,F,O
--pitch=J,S,A,F,O
--yaw=J,S,A,F,O
These options allow you to configure
how the roll/pitch/yaw degrees of freedom map to the characteristics of
the joystick as recognized by the computer's operating system. J is the
joystick device number (in case multiple joystick devices are
installed), S
is the stick number within the joystick, and A is the
axis within the stick. F is a
factor which the joystick reading is multiplied by, and O is an
offset added to the joystick reading (after multiplication is
completed). The factor is useful (for example) in swapping
right-to-left, back-to-front, or clockwise-to-counter-clockwise.
The offset would be useful when the the joystick provides unsigned
readings (0-255) rather than the desired signed readings (-127 to
127). A reading of -127 represents maximum left roll, downward
pitch, or counter-clockwise yaw; a reading of +127 represents maximum
right roll, upward pitch, or clockwise yaw. (Actually, maximum
values of 127 seem to occur in Linux, whereas maximum values of 128
seem to occur in Win32.) The defaults are:
Roll = 0, 0, 0, 1.0, 0
Pitch = 0, 0, 1, 1.0, 0
Yaw = 0, 1, 0, 1.0, 0 (Linux) or 0, 1, 0, 1.0, -128 (Win32) or
0,2,0,1.0,0 (Mac OS X)
These defaults are based strictly on my
own convenience (i.e., for my Logitech Extreme 3D pro), and I have no
theoretical basis for assume that they're any good generally.
--ip=Hostname
The yaACA
program and the yaAGC Apollo
Guidance Computer simulation exist in a "client/server" relationship,
in which the yaACA program
needs to be aware of the IP address or symbolic name of the host
computer running the yaAGC
program. By default, this is "localhost", meaning that both yaACA and yaAGC are running on the same
computer.
--port=Portnumber
By default, yaACA attempts to connect to the yaAGC program using port number
19803. However, if more than one instance of yaACA is being run, or if yaAGC has been configured to listen
on different ports, then different port settings for yaACA are needed. Note that by
default, yaAGC listens for new
connections on ports 19697-19706, but that the recommended port range
when using yaAGC in the LM is
19797-19806.
--delay=Milliseconds
Adds a delay at start-up, so that
yaACA
does not immediately begin attempting to communicate with
yaAGC. The current defaults
are 0 ms. in Linux and 500 ms. in Win32. This "feature" has been
added as a temporary work-around for
problem
report #23, and probably has no other sensible purpose. Even
on Win32 it isn't usually needed, but it's here for the 10% (or
whatever) of the time it's needed.
yaTelemetry

yaTelemetry would be a
computer program that provides a monitor or terminal capable of
displaying telemetry information downlinked from the Apollo Guidance
Computer (AGC). The AGC periodically transmitted telemetry
information, which was displayed on monitors in Mission Control.
Similarly, the virtual yaAGC
periodically transmits telemetry data, using virtual radio waves
consisting of a communication channel (socket), and yaTelemetry would be capable of
receiving
this information. The characteristics of the digital uplink and
downlink can be explored by reading section 2 of the Guidance System Operations Plan
(GSOP) for the LM or the CM.
The accompanying photo is actually a screen capture from the "Apollo
11" episode of the great HBO mini-series From the Earth to the Moon. I
have so far been unable to find actual photographs or specifications of
the telemetry displays.
In addition to telemetry downlinks---i.e., reception by ground control
of data from the AGC---digital uplinks also possible. Uplinks
were (and are) handled by the simple expedient
of transmitting DSKY
keycodes, encoded in a triply-redundant format to allow detection of
errors. The AGC flight software treats DSKY and
uplink keycodes in a very similar fashion, so ground control could
remotely perform
any task which the astronaut could perform at the DSKY keypad,
including data entry, entry of short program patches into memory, and
activation of programs.
In the absence of a working yaTelemetry
program, the yaDSKY program
can be used with the switches "--test-downlink"
and/or "--test-uplink"
to view the digital downlinks or to uplink data.
This page was last modified by Ronald Burkey on 2007-04-25.