Home
yaAGS et al.
Download
Links
Change log
Bug and issues
Developer info
FAQ
Virtual AGC and AGS
  Home Page
Project Overview

yaAGC
yaYUL
yaDSKY
yaOtherStuff
Luminary
Colossus
Language Manual
Physical Implementations

This Project

The purpose of this project is to provide an emulation of the onboard Apollo guidance computers, along with some ancillary items needed to make the emulation do something interesting.  "Interesting" is, of course, a subjective notion, and there are plenty of additional components one might want to add to the simulation to make it more interesting.  (Click here for examples.)

Contents

What are the "AGC" and "AGS"?

"AGC" stands for Apollo Guidance Computer.  The AGC was the principal onboard computer for NASA's Apollo missions, including all of the lunar landings.  Both the Command Module (CM) and the Lunar Module (LM) had AGCs, so two AGCs were used on most of the Apollo missions, but with differing software.   The computer and its software were developed at MIT's Instrumentation Laboratory, also known as Draper Labs.

The "block II" AGC, employing the AGC4 instruction set, is the particular computer model in which we're interested. The block II AGC was used not only on Apollo 7 through Apollo 17 (including all actual lunar landings), but also on three Skylab missions, on the Apollo-Soyuz test mission, and on a fly-by-wire research project using F-8 aircraft. Nevertheless, only 57 AGCs were constructed---and 138 display-keyboard units (DSKYs) for them---and all of the ones installed in the Lunar Modules were not returned to the Earth---so they are definitely collector's items.

There was also the "block I" model of the AGC, which predated the block II model.  The block I model was supposed to fly in Apollo 1 and 2.  But since Apollo 1 was tragically destroyed by fire, and Apollo 2 never flew, the block I model was never used in any manned mission.

Finally, "AGS" stands for Abort Guidance System, also known as the Abort Electronics Assembly (AEA).  The AGS was a completely separate computer system from the AGC, with a different architecture, different instruction-set, and different runtime software.  It was in the LM as a kind of backup for the AGC, but was only supposed to be used (as the name implies) in case of an aborted landing. 

What "Virtual AGC" Is

Virtual AGC is a computer model of the AGC.  It does not try to mimic the superficial behavioral characteristics of the AGC, but rather to model the AGC's inner workings.  The result is a computer model of the AGC which is itself capable of executing the original Apollo software on (for example) a desktop PC.  In computer terms, Virtual AGC is an emulator

The Virtual AGC software has been designed to work in Linux, in Windows, and (as of 08/28/2004) in Mac OS X 10.2 or later.  However, since I personally work in Linux, I have the most confidence in the Linux version.

What Virtual AGC Is Not

Virtual AGC is not a flight simulator, nor a lunar-lander simulator, nor even a behavioral simulation of the Apollo Lunar Module (LM) or Command-Module (CM) control panels.  (In other words, if you expect a realistic LM control panel to suddenly appear on your computer screen, you'll be disappointed.)  Virtual AGC could be used, however, as a component of such a simulation, and developers of such software are encouraged to do so.  But see the FAQ for more info on this.

Principal Elements of Virtual AGC Project

Existing Elements

Hoped-For Elements

Virtual AGS Elements

Contributed Code

Licensing

PC-based programs such as yaYUL, yaAGC, and yaDSKY are copyrighted by the author, Ron Burkey, but are provided to you as "free software" under the GNU General Public License (GPL).   Validation was written by me, Ron Burkey, but is being placed in the public domain.  Luminary and Colossus are in the public domain, to the best of my non-lawyer understanding.  Newly-written or revised documentation is being placed in the public domain.  Note that if you wanted to use yaAGC or yaDSKY as components of a more-complete Apollo simulation, the modularity of the design allows them to be run as stand-alone programs (whilst communicating with your own software), and doing so does not force any particular licensing requirements upon your own code.  However, if you choose instead to incorporate yaAGC, yaDSKY, or yaTelemetry code directly into your program or to link to them, your program will itself need to be licensed under the GPL unless you feel like negotiating an alternate license with me.  (As of 2005-02-27, the yaAGC source code license also has a "special exception" as allowed/required by the GPL, allowing linking to the non-free Orbiter spacecraft-simulator SDK libraries.)  Refer to the Developer info page for more detail.

What If You Want To Help?

Well, I'll take any help I can get, of course.  What is most needed is information.  Items I particulary want at the moment are these:
  1. (By far the most important!)  Scans of assembly listings for any Apollo software versions not already on this site.  By an "assembly listing", I mean a printout showing assembly-language source code and the binary to which that source code reduces upon assembly.  As far as preparation of such documents is concerned, images (such as TIFs at 200-300 dots/inch) are more valuable than PDFs; in the case of PDFs, please do not attempt to perform optical character recognition (OCR) on them.  (Note that I cannot host such documents on this site at the present time, because of resource limitations, but I would keep them and use them, and possibly host them in the future if my hosting resources increased.)
  2. Scans of any original Apollo documents not already available here at Virtual AGC.  PDFs are fine for such documents but, as above, please do not perform OCR.  Of particular value would be software patches applied at runtime, software problems reports, mission checklists, and detailed technical documentation of hardware interfaced to the AGC.  Click here for hints of where to find such documentation.
  3. Machine-readable binary executables for any Apollo software versions not already on this site.
  4. Machine-readable source code for any Apollo software versions not already on this site.
  5. Corrections for anything bogus I may have done or said on this website.
  6. Simulations of other spacecraft equipment which can interoperate with yaAGC.  The most important of these are the Inertial Measurement Unit (IMU) and Alignment Optical Telescope (AOT).
The reason scans of assembly listings are so important is that I insist upon absolute integrity of all information presented on this site.  Without scans of original material, I have no means of detecting and eliminating the element of human error.

Quick Start

I expect that anyone who would really use Virtual AGC would likely want to adapt it quite a bit, and so any simple instructions I might give wouldn't help much.  Not to mention the burden of training yourself on the technical nitty-gritty of Apollo systems before you can actually use the AGC for anything!  :-)

The first step, of course, is to download the Virtual AGC software and install it or build it for the computer platform you're using, by following the instructions on the download page.   If you've done that, here are a few scenarios where you can quickly get to the point of seeing something happen, if not necessarily anything meaningful to our sad little earthbound minds.

Note:  The scripts named SimLuminary131, SimColossus249, and SimValidation referenced below are only present in version 20040810 and later, while SimArtemis072 is available only in version 20060109 and later.  If the DSKY graphical interface is too big for your display screen, try adding the --half-size command-line switch, as in "SimLuminary131 --half-size".  Also, if the scripts don't work at all, please read the work-around listed for problem report #23.

The "full Apollo experience" isn't available yet, since the yaAGC is (possibly) still buggy and peripheral devices like the IMU and AOT haven't been created yet.  But there are still a few things you can try that are amusing in a geekish sense:
Screenshot of yaDSKY.  Click to enlarge.
View the alarm codes
Because of some current bugs (07/19/04) in the way I initialize Colossus, there will be some program alarms at startup, and the PROG indicator will light to inform you of this.  You can view the alarms by keying in V05N09E at the DSKY.  (In normal AGC shorthand, 'V' is short for "VERB", 'N' is short for "NOUN", and 'E' is short for "ENTR".  So "V05N09E" means to hit the keys VERB 0 5 NOUN 0 9 ENTR.)

Program alarms 1105 and 1106 happen to be "downlink too fast" and "uplink too fast".  Uplinks or downlinks refer to exchange of telemetry information with ground equipment.
Screenshot of yaDSKY.  Click to Enlarge. DSKY lamp test At the DSKY, key in V35E.  This will light up all of the DSKY annunciators, flash the VERB/NOUN labels, and display 88 or +88888 in all of the numerical registers.  After about 5 seconds, the test stops --- you can tell, because the flashing stops, though the numbers remain --- and you can continue.

When the accompanying screenshot was taken, I didn't yet know how the AGC controls the DSKY's STBY and RESTART indicators, so those weren't turned on by the test.  Because of a bug in the simulator (as of 07/19/04), the PROG indicator doesn't re-light after the lamp-test completes.  Therefore, you may or may not see the PROG indicator lit if you try the sample operations below.
Screenshot of yaDSKY.  Click to enlarge.
Display memory-bank checksums The core-rope (read-only) memory is divided into 36 banks, numbered 00-43 (octal).  A so-called "bugger word" has been stuck at the end of each bank --- yes, I get the joke, so please don't send me an explanation (and if you don't get it, don't ask me) --- which causes the checksum of the bank to come out to a known value.  This known value is the same as the bank number when possible, and is the logical complement of the bank number otherwise.  (For example, the checksum of Colossus bank 00007 is 00007, but the checksum of bank 00006 is 77771.  Both are correct.)  Colossus's "show-banksum" program can be used to display the bank numbers, one by one.  You can execute the show-banksum program by keying in V91E on the DSKY.  After a few seconds, the statistics for bank 00 will be shown:  R1 (the topmost 5-digit display) will contain the computed checksum; R2 will contain the bank number; and R3 will contain the bugger word.  Each of the displays will be in octal, as indicated by the fact that the +/- sign is blank.  To advance to the next bank, key in V33E.  (Hitting the PRO key does the same thing.)  If you have the patience to advance through each of the banks, the next V33E (or PRO) after bank 43 will wrap-around to bank 00 again.  To terminate the show-banksum program, you can key in V34E.

By the way, the bank-6  bugger word shown (05143) is for Colossus 249.  If you ran the Artemis 072 program, it would have been 04275, while if you ran the Luminary 131 program, it would have been 63402.
Screenshot of yaDSKY.  Click to Enlarge.
Monitor the current time If you key in V16N36E or V16N65E, it will cause the current time to be displayed.  (Since we haven't set the time in any way, this will be the time since AGC power-up).  R1 (the topmost 5-digit display) will be in hours, R2 will be in minutes, and R3 will be in 100ths of a second.  This display is updated once per second.

In the accompanying screenshot, the time is 06:58:33.86.
Screenshot of yaDSKY.  Click to enlarge.
Setting the current time If it annoys you to see the time since power-up, you can change the time (for example, to mission time) by keying in V25N36E.  R1 will go blank, enabling you to key in the current hour.  Make sure you start with a + sign (this is how the AGC knows you're using decimal rather than octal), and make sure you enter all five digits (including the leading zeroes).  In case you make a mistake, you can clear R1 any time before pressing ENTR by using the CLR key.  After you hit the ENTR key, R2 will clear and you can enter the current minutes.  Finally, you can key in the number of seconds in R3.  Don't forget that the number of seconds is actually in 100ths of seconds, so that if (for example) you want 30 seconds you'd key in +03000E.

In the accompanying screenshot, it just happened to be 06:55:25 am., so that's how I set the clock.
Screenshot of yaDSKY.  Click to enlarge.
Examining the contents of the core-rope Key in V27N02E.  This allows you to enter the address of a word in the core-rope into R3.  This address will generally be in octal, and therefore should not be preceded by a + sign.  Also, unlike entry of decimal data, in octal you can enter just as many digits as you need, and don't need to enter a full five digits.  The addresses will be 00000-01777 for memory bank 00, 02000-03777 for memory bank 01, and so forth, up to 76000-77777 for memory bank 37.  (I'm not sure how to examine banks 40-43.)  The binary listing of the core rope is at the very back of the Colossus 249 assembly listing, which can be downloaded from MIT if you have some spare time and disk space.  (See my links page.)

In the accompanying screenshot, we see that address 4000 (octal) of Luminary's core-rope contains the value 00004.  This just happens to be the first instruction executed after power-up.  It is an INHINT instruction, and disables interrupts.  The contents of R2 (the middle 5-digit register) are not cleared, and thus are just whatever lingers from before.
Screenshot of yaDSKY.  Click to enlarge.
Examining the contents of erasable memory Key in V01N02E.  This allows you to enter the address of a word in erasable memory into R3.  The addresses will be 00000-00377 for erasable bank E0, 00400-00777 for memory bank E1, and so forth, up to 03400-03777 for memory bank E7.  Alternately, you can "monitor" a memory location (i.e., get updates for it once per second) by using VERB 11 rather than VERB 01.  For example, V11N02E25E will monitor register 25, the "TIME1" register, which is an internal counter that increments every 10 ms.  In general, of course, the numbers won't mean much unless you reference them to the Colossus 249 assembly listing.

In the accompanying screenshot, we actually do look at the TIME1 register, and discover that at that instant it contained the value 20245 (octal).  Of course, you'll see something different.  Display R2 is not changed, so it just contains whatever it contained before.
Screenshot of yaDSKY.  Click to enlarge.
Altering the contents of erasable memory Key in V21N02E, and enter an octal address as above, and then enter a new value to be stored at that address.  It goes without saying that you need to know what you're doing when you do this!

In the accompanying screenshot, I've chosen to reload the TIME1 register with the value 12345 (octal), which probably won't cause too many adverse effects.  Display R2 is not changed, so it just contains whatever it contained before.
Screenshot of yaDSKY.  Click to enlarge.
Fresh start Key in V36E.  This apparently restarts the "pinball" program --- i.e., the program that is responsible for accepting verbs and nouns and displaying stuff on the DSKY --- and it's useful for clearing garbage from the DSKY's display, as the accompanying screenshot demonstrates.

In the accompanying screenshot, a side-effect of the fresh start is the thoughtful re-display of the PROG (program alarm) which the earlier DSKY lamp-test had wiped out.
(Your picture here.)
Do-it-yourself research The file yaAGC/Colossus249/ASSEMBLY_AND_OPERATION_INFORMATION.s lists the verb and noun tables, so perhaps you can figure out some neat stuff yourself.  If you do, let me know and I'll add it to this list.
Step 0
Run the simulator
From a Win32 or Linux command-line prompt, run the SimLuminary131 script.
Screenshot of yaDSKY.  Click to enlarge.
Step 1
V35E
Starts the DSKY lamp test.  All of the indicator lamps are lit, the numerical displays show 88 or +888888 as appropriate, and things which are supposed to flash, flash.  After about 5 seconds, the lamp test automatically terminates.
Screenshot of yaDSKY.  Click to enlarge.
Step 2
V37E 00E
"Goto Pooh" --- i.e., start program P00, the idling program.  The numeric area under the PROG label will show 00.
Screenshot of yaDSKY.  Click to enlarge.
Step 3
V25E N01E 1365E 0E 0E 0E
Set the count of total failed self-tests, total started self-tests, and successfully-completed division tests to 0.
Screenshot of yaDSKY.  Click to enlarge.
Step 4
V15 N01E 1365E
Begin monitoring the self-test counts.  R1 (the top 5-digit display) shows the number of failed tests, R2 shows the number of started tests, and R3 the number of completed division tests.  Each should be +00000 ("all balls").
Screenshot of yaDSKY.  Click to enlarge.
Step 5
V21 N27E 10E
Begin background self-tests.  These tests will continue until the astronaut (you!) terminates them.  Continue at least until the number of started tests (R2) reaches 3.
Screenshot of yaDSKY.  Click to enlarge.
Step 6
V21 N27E 0E
Terminate the background self-tests.
(Looks the same,
of course.)
...

(more later)


DEDA displaying results of self-test
CLR 4 1 2 READOUT
View the results of the self-test, which are stored in the AGS CPU at (octal) location 412.  A code of +10000 means the test has passed. 

Oops! the test has failed.  That's because the self-test is pretty thorough; it tests not only memory checksums, but also the operation of various CPU instructions.   The possible error codes here are:
+000000   Test still in progress
+100000   Test passed
+300000   Logic test failure
+400000   Memory test failure
+700000   Logic and memory test failure

I was having a little problem with the instruction set when this screenshot was taken, thus the self-test failed.  Fortunately, the AGS flight programs have been written to continue operating in the case of self-test failure, even though it is "not recommended".  The current version of yaAGS actually does pass the self-test, and so you'll see a code of +100000 here.
Resetting the clock.
CLR 3 7 7 + 0 0 0 0 0 ENTR
Set the clock to 0.  The CPU uses address 377 (octal) as a counter that increments at 6-second intervals.  Before using it, though, we want to set it to a known value. 

In real life, the AGS time would be initialized by synchronizing with the AGC electronically.  However, I'm not quite yet ready with that particular feature.
DEDA display of incrementing time.
CLR 3 7 7 READOUT
Watch the clock incrementing.  Although the counter changes at 6-second intervals, and counts in units of 6 seconds, the CPU actually updates the DEDA display every 1/2 second.
More later ... however, the operations listed above are very representative from the user-interface perspective of all the other kinds of operations you can perform on the DEDA.  There are basically two classes of DEDA-based operations:
  1. Get a running display of the contents of a memory location.  The command sequence for this is CLR OctalDigit1 OctalDigit2 OctalDigit3 READOUT.  Upon receiving this command, the AGS CPU will monitor the selected memory location and display it on the DEDA every 1/2 second.  You can pause the readout by hitting HOLD, or resume it by hitting READOUT again.  The flight software will automatically scale the data or otherwise modify it (by changing units of measurement) in a way appropriate to the particular memory location before displaying the data.  If you make a mistake in the key sequence, the OPR ERR lamp will light, and you'll have to hit CLR to clear the error condition.
  2. You can change the value of a location of memory.  In doing so, the flight software may choose to interpret your action as a command to perform some further action, but I'm not up to speed on what those other actions might be.  The command sequence is CLR OctalDigit1 OctalDigit2 OctalDigit3 +/- Digit1 Digit2 Digit3 Digit4 Digit5 ENTR.   The 5-digit data may be octal or decimal, but that is dependent on the particular memory location chosen, and isn't a choice that the astronaut/user makes.  Again, a mistake in the sequence will cause the OPR ERR lamp to light.
Of course, there are operations the astronaut/user can perform that are outside of this framework, such as hitting the ABORT button or downloading the spacecraft state vector from the AGC.  However the abort button is a separate switch rather than being a part of the DEDA, and I've not perfected AGC-to-AGS communication yet.

Acknowledgements


This page was last modified by Ronald Burkey on 2007-04-25.


Virtual AGC is hosted by ibiblio.org