Home
yaAGS et al.
Download
Links
Change log
Bug and issues
Developer info
FAQ
Virtual AGC and AGS
  Peripheral Components for Use with yaAGC 

yaAGC
yaYUL
yaDSKY
yaOtherStuff
Luminary
Colossus
Language Manual
Physical Implementations

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
Main screen
System inputs
Inputs from system
Crew inputs
Inputs from crew
Outputs
Outputs
IMU stuff
IMU
DSKY LITE and yaDSKY side-by-side
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:
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 yaACAyaACA 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

LM telemetry monitor

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.