Useful Areas of Involvement in General

This is not an exclusive list, I suppose.  If you have a notion that doesn't fall into any of these categories, you can contact me directly.

A Unique Time-Limited Opportunity to Help (Now Fully Subscribed!)

This current opportunity has now come to an end, so you've lost out, alas!  However, I'm so in love with my own words that I'll let the description persist for a while, and you can read it below.  With luck, more such opportunities may present themselves in the future.

Scan, Baby, Scan!

Most of this web-page covers things you can do to help in a very general way, but it so happens that right now there is a very specific way in which we'd like to get your help.

Right now, a very large (by our standards) set of very rare AGC-related material has become available to us from the personal keepsakes of Hugh Blair-Smith and Don Eyles, who were among the original developers of the AGC.  Some of you may recall Don Eyles as the hero programmer of Apollo 14.  That story has been told and retold many places on the web, so I won't repeat it here, but for example, there's a Rolling Stone article about it.

To acquire this material and present it here online, however, it must be scanned, and scanning costs money, and that's where we'd like your help.

No, don't send us money, please!  The materials will be scanned by archive.org, and anybody who is kind enough to help out will be billed directly by archive.org after the scanning takes place.

What we are looking for, for each one of the documents we need to scan, is a "sponsor" who will commit to paying for that scanning.  So what we'd like for you to do is to choose which particular document you'd like to sponsor, from the list in the next section, and to drop me an email (Ron Burkey <info@sandroid.org>) with your name, physical address, and telephone number.  If two or more people want the same document, the first email I receive wins it, so if you have a second choice, include that in the email.  I'll fill out the paperwork for archive.org, and we'll keep you apprised of the progress.

The amount you can expect to pay is $3 plus $0.25/page, so the list in the next section includes page counts to help you figure out the total.  If you are not in the U.S., that is fine with archive.org as long as your email address is valid.

The Document List

Here's the list of documents we are trying to acquire.  You'll notice that some of them already have sponsors, and indeed, some of them have already been scanned.  Don't choose one of those.  Incidentally, after the documents are scanned, archive.org will continue to host them online at quite a high resolution, and you can examine our Virtual AGC "collection" of documents at archive.org to better understand what you're helping to accomplish.

Document Name
Page Count
Description
Sponsor/Scan
AURORA 12
760
A very early version of the Lunar Module software, prior to any flown missions.  It is very important for us, because it is the last version of AGC software to contain the complete test suite that have been developed to check out the CPU and other aspects of the spacecraft.  It is thus invaluable for validating the correct behavior of AGC simulators.
Mike Stewart (already scanned)
YUL
730
The source code for the original AGC assembler program used in converting AGC software source code into "rope memories" for use in the actual AGC.
Ron Burkey (already scanned)
RETREAD 44
304
The earliest version of the Lunar Module software, prior even to the AURORA 12 software mentioned above.  Actually, this is the earliest version of AGC software of any kind (CM or LM, Block I or Block II) that we presently have any prospect of getting, by more than a year compared to the closest contender.
Mike Higgins (already scanned)
SUNBURST 120
1284
The software for the unmanned Apollo 5 mission.
Mike Stewart (already scanned)
SHEPATIN (SUNBURST 37)
1223
An earlier version of the SUNBURST 120 software mentioned above.  This is interesting because, while it isn't flown software, it's our first chance to see significant development within a single AGC program, namely SUNBURST ... and I'm told that the development between SUNBURST 37 and 130 was indeed quite significant.
Peter McDermott
(already scanned)
LUMINARY 69

Lunar Module software for Apollo 10
Onno Hommes
(already scanned)
1969 Digital Simulation of Apollo 11 landing
994

Matthew Fite
(already scanned)
1971 Digital Simulation of Apollo 11 landing
759

Fabrizio Bernardini
(already scanned)
LUMINARY 116

Lunar Module software for Apollo 12
Ron Burkey
(already scanned)
LUMINARY 131
1735
Lunar Module software for Apollo 13.  This is, in principle, something we've already had for many years, and is already online many places on the web, including at this site.  However, the version which has been available these many years was digitally mutilated by an OCR process and the original high-quality scans discarded.  Consequently, the available scans are barely readable.  This would be a new, clean, unmutilated scan.  A similar thing happened with the Colossus 249 (Apollo 9 Command Module) scans that have been available in mutilated form for many years:  they were eventually replaced by a clean, legible scan.  That's actually a factor, because our current tools for proofing/correcting program comments (which tend to have thousands of errors in any given program version if merely proof-read in a normal fashion by people) depend on a nice, clean scan, and thus our existing transcription of Luminary 131 source code is bound to be riddled with them!
Ron Burkey
(already scanned)
ZERLINA 56
1735
Don Eyles offers this explanation:  "ZERLINA was my personal non-flight testbed for developing new capabilities, some of which later moved to the main line LUMINARY. Its main feature was a new version of the Servicer job in which the guidance period was allowed to stretch beyond the nominal 2 seconds — part of the overall effort in response to the CPU overload on 11. Variable Servicer would have been necessary if new capability was required that would have further reduced our CPU margin, such as something called P66 LPD, also implemented in ZERLINA, based on an idea of John Young's, that would have facilitated making very accurate landings. This capability is described in Draper Lab report E-2581, which I can at some point make available. Neither Variable Servicer nor P66 LPD was ever approved for LUMINARY. Things developed first in ZERLINA that DID make the jump to LUMINARY included the a priori terrain model (needed to land in more mountainous terrain), and also a new version of the "landing analog displays," the same mentioned in the Tindallgram of July 24, 1970. In my view ZERLINA 56 still represents the state of the art for manned landings on the Moon."  Paul Fjeld has also told me, although Don doesn't mention it, that John Young also worked with this in the LM simulator.

By the way, LUMINARY Memo #138 describes what Don was doing with the Variable Servicer, which (among other things) eliminated the infamous 1201 and 1202 alarms.  At the very least, the memo is a very funny read, and very short.
Linden Sims
(already scanned)
Digital Simulation of ZERLINA lunar landing
395
A simulation of ZERLINA would be particularly interesting, because since ZERLINA was intended to improve the landing process, the simulation is what would show whether or not that was true!
Niklas Beug and Alex Bart
(already scanned)
LUMINARY 210

Lunar Module software for Apollo 15-17.
Jim Lawton (already scanned)
Digital Simulation of Apollo 17 landing
628

Fabrizio Bernardini
(already scanned)
Digital Simulation of Apollo 12 landing
805

Matthew Fite
(already
scanned)

LUMINARY 99
1750
Lunar Module software for Apollo 11.  Now, we already have a digitized version of LUMINARY 99 from the MIT Museum, so why do we need another one?  Well, while I can't claim dire necessity, I'll point out that:
  • This would be a higher-quality digitization than our previous one.
  • That it would have whatever hand-written notes Don Eyles had chosen to scrawl in it.
  • That a page or so was actually missing from our original copy, and this printout has that material.  (Though, admittedly, we had already reconstructed it long ago from LUMINARY 131, and that Don has since sent us snapshots of the relevant pages, and it turns out to be 100% identical with what we had already reconstructed.)
  • We will probably be able to use it to get rid of a few typos in our existing transcription of Luminary 99 that continue to linger even though considerable effort has been put into eliminating them in recent months.

The printout is interesting, in that rather than being called LMY99 BY NASA as our 1969 version is, it is called AP11ROPE BY EYLES and is from late 1970.  However, we already know that the memory-bank checksums are identical, so there's every reason to believe (though no guarantee) that the entire contents are identical as well.  I'm not quite sure why Don has it, but my guess is that it's the companion to the 1971 digital simulation listed above; I suspect that Don wanted compare the behavior of ZERLINA to the Apollo 11 baseline, since some of the changes test-bedded in ZERLINA were targeted at eliminating the CPU overloads which triggered the infamous 1201 and 1202 alarms.

At the very least, it's a nice piece of Americana, and if you want to sponsor it, you can brag that you helped pay for the Apollo 11 lunar lander software!

Vipin Rathor
(already scanned)
AC Delco LM manual, volume 1
550

Fabrizio Bernardini
(already scanned)
AC Delco LM manual, volume 2
550

Mike Stewart
(already scanned)

There are also other possible sources on the horizon, which may or may not materialize within the time-frame of this special offer.

In case you wonder what a "digital simulation" is, we did too, so Don Eyles has also given us a pretty detailed description:

"I'm not sure why I saved all these simulations. These days I guess their chief value would be to anyone actually trying to run a simulation of an Apollo descent.

"They consist of two parts, the sim itself, and an "edit" of raw data dumped during the sim onto a MARSROT tape. The sim part consists of some pages of initialization data, then the run itself. The printout includes astronaut inputs, DSKY displays, lines called "clocks" that are printed when the code passes through certain locations, and for every two seconds of simulated time a three-line summary of data from the simulation environment including the current position, velocity, attitude, etc., etc. The edit portion includes additional sim and AGC data, also printed at two-second intervals. I'll attach photos of the sim and edit parts of the APOLLO 11 LANDING run."



What's In It For Me (by which I mean you)?

Well, you'll have the satisfaction of knowing that you did a good thing, and your name will be permanently enshrined as a sponsor (assuming you want it to be so enshrined) both at this website, and in our archive.org collection!

Not enough for you?  Well, to express my thanks, if you sponsor the scanning of one of these documents, I'll personally buy you a thank-you gift, as follows:

And so as to be fair, if you sponsor multiple smaller documents, you can add the pages counts together to go to the next higher gift category, if you like.  Or if you offered to sponsor a larger document and it had become unavailable so that you had to accept your second choice, which was smaller, it was your original good intention that determines your gift category.  Of course, you can optionally choose a lower gift category, or no gift at all (that works for me!).

After the scans are complete, and you've paid archive.org, I'll get you the exact details and get your choices (style, size, color, etc.), but you'll have a choice of some reasonable variation of the following:








I Don't Want to Pay, But I Still Want to Help (again, you)!

Well, as you may be aware, what we do with AGC software that comes to us in the form of program listings or scanned program listings is to

  1. Transcribe the source code into the form of files which can be "assembled" to create an executable memory "rope".
  2. Provide the source-code files and the "rope" to the public, so that the program can be run in an AGC simulator.

We talk more about how to do that below, but there are no "gimmes" associated with it, sorry!

Okay, so that's the end of the special offer.  If you want to continue reading the general description of what we need, then by all means proceed to the next section!

Information

First and foremost, Virtual AGC is about providing AGC/AGS related documentation that cannot (or at least, previously could not) be found elsewhere online.  Examples of items that will always be in demand are these:
  1. Legible scans or page-by-page digital photographs of assembly listings for any Apollo software versions not already on this site.  These do not have to be listings from actual missions, and could be intermediate versions.  By an "assembly listing", I mean a printout showing assembly-language source code and the binary to which that source code reduces upon assembly.
  2. Scans of any original Apollo documents not already available here at Virtual AGC or elsewhere.   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. Or even information about where such material resides, such as "Museum XYZ has a listing of Luminary 1D".
If you have such material, you'll probably want to contact me directly to determine that we don't already have that item in process, to discuss methods of preparation, to discuss means of delivery to me, etc.  These days, what we prefer to do is to have the item scanned at some local outpost of archive.org; but there are only a handful of these around the country (Boston, Washington, and so on), so it's not always applicable.  There's also a pretty-complete description of all the other available options on our "how to digitize" page.  When you contact me, a page or two of scanned or digitally-photographed images (including the title page) attached to the email might be useful.

Wiki

If you have AGC/AGS information other than original Apollo documents you'd like to make publicly available, you could do so by contacting me directly.  But in some cases you may find a better and more straightforward approach may be to contribute your knowledge to the wiki.  Examples of things that are useful are theoretical discussions, historical information or anecdotes, tutorials on how to perform certain tasks with the AGC or AGS, etc. 

Coding

If you have a simple bug-fix, it might be easiest to submit a patch directly to me.  Please be sure to tell me when you do so which development snapshot or which subversion revision you started from.

For more extensive coding, we have a code repository at GitHub and if you have ideas for new features then you can contribute them to the project via the repository. 

Some particular sore spots which could be addressed by an ambitious coder include:
While the excellent LM-Simulator contributed program by Stephan Hotto already provides a simulated IMU and FDAI, it has a couple of drawbacks in that it is written in the Tcl/Tk interpreted language, and that it is closely tailored to the LM (making it only of limited value for the CM).  The fact that it is in Tcl/Tk makes it relatively slow, and almost unusable on slower computers.  Of course, as time goes on and computers become faster and faster, this becomes less of a concern.  The unusability with the CM will remain a concern.  One possibility is to simply update LM-Simulator itself.  Another is to convert it to C/C++.  Still another is to replace it with IMU/FDAI workalikes.  Any such effort, other than the latter, would preferably be coordinated with Stephan rather than being done unilaterally without his knowledge.

More generally, while we will likely accept any useful code that is supplied, you should keep the following suggested guidelines in mind:
  1. All programs are cross-platform, with the minimum acceptable list of supported platforms being Linux, Windows XP, and Mac OS X 10.4 (and later).
  2. Only open-source development tools are used.
  3. Non-GUI programs are preferentially written in C.
  4. GUI programs are preferentially created using the wxWidgets toolkit, in the C++ language.
  5. The compilers used are gcc and g++ (or MinGW in Windows).
  6. The code-formatting style used is the GNU style.  This doesn't necessarily mean you have to change all of your coding habits, as there is a handy program called indent readily available on most Linux systems and Mac OS X that will reformat C/C++ source files into this style.  It is also available for Windows.
  7. Primary code development is done in Linux, which means that UNIX-style line endings ("\n") are used in preference to Windows line endings ("\r\n") or Mac endings ("\r").  While this is not a problem for gcc, it may be a problem for your source-code editing software.
  8. You retain the copyright for the code you write, but you are expected to license it under the terms of the GNU GPL version 2.  The license text within the source files should quote the license as "GPL version 2 or later".
It should be noted that making choices other than these is likely to make inclusion of your code into Virtual AGC binary installer packages impractical, and that such omission is likely to greatly reduce the number of people actually using your code.

For a more-technical view of the operation of Virtual AGC code and what it might take to supply code, please visit the developer page.

Money

If there is a specific need, such as for paying scanning expenses, a notice will appear at the top of this page.  However, in general, Virtual AGC is a non-commercial project in the public interest, has never accepted monetary donations in the past, and has no mechanism for doing so in the future.  The web hosting for the project is done by other organizations in the public interest, notably ibiblio.org and archive.org.

Code Transcription or Proofing

This is an area where no technical expertise is required for participation, particularly in proofing.

A situation arises from time-to-time in which AGC assembly-listings have been received and require transcription into machine-readable form for integration into Virtual AGC.  Such conversion tasks are rather overwhelming when done by a single individual, but these days such conversions are performed by teams of volunteers, which make the work much lighter.  There is a certain pleasure involved in participating in such a conversion, because you can know that you are helping to make available for actual use code which has not seen the light of day for 40 years.  So volunteer assistance is welcomed in these cases.

Code transcription from page images to source-code files

If there are any transcription efforts in progress, you will see them as "issues" in our GitHub repository, typically with a HELP WANTED icon attached to them.  Simply add a comment to one of those issues asking for it to be assigned to you and wait for an acknowledgement.  If you are a newby to this process, say so and ask for further instructions.

Code transcription is a process wherein we take the scanned or photographed images of a hardcopy listing of an AGC  program, and convert it to source code (text files) that can be processed to created the executable software which runs on the simulated AGC CPU.  It is not necessary to understand AGC assembly language, or any computer language, to do this; but if you are somewhat familiar already with the AGC programs, you will be awarded with some small thrills along the way.

Here is a basic outline of the conversion process:
  1. The AGC source code is divided into a sequence of well-defined modules (often called "log sections"), with names such as INTERPRETER or IMU MODE SWITCHING ROUTINES.  As mentioned above, request an assignment for a specific one of these by using its associated GitHub "issue". 
  2. A starting point for the transcription of your assigned module will already exist in the GibHub repository.  At the very least it will have a file-header describing what's in the file, and often will appear to contain the actual code.  You see, the AGC code does not change much from mission to mission, or from spacecraft to spacecraft.  (For example, the software for Apollo 11 fairly similar to the software for Apollo 13, and the software for the CM is likely to be similar in many respects to the software for the LM.)  Therefore, often, the appropriate transcription technique is to start from existing source code from a different mission or spacecraft, and then to simply make whatever changes are needed.
  3. Download or examine online the appropriate scans of the assembly listings being converted.
  4. Make whatever changes are necessary for the file to conform to the scanned assembly listing.  If some thing it is wrong, fix it!  (Don't just make a note saying it's different; we don't care that it's different; we just want it to be right.)  Note certain differences between the scans and the textual source-code files (referring to the picture below):

Sometimes you will encounter areas in a program listing which are too garbled to read, or indeed simply missing entirely.  Don't panic!  Simply mark them with ##-style comments and continue.  These program listings have enough redundancy and commonality with other versions of the program that (at least so far) we can always reverse-engineer them to repair such problems, though the techniques are too intricate to detail here.

Finally, and perhaps most importantly, you'll will see many things which are obviously wrong, and which you will be tempted to "fix".  Don't do it!  Our standard is 100% agreement with the original program listing, so if you "correct" (say) WTIH to WITH or TEH to THE, you're simply forcing somebody else to come back and undo your fix later.

In the following pictures, some of the points mentioned above are illustrated using the first page of the SERVICER module of AGC program Luminary 131.  (It is perhaps worth pointing out that according to the scan, this is page 852, while according to the converted source-code file it is page 857.  This is because the Luminary 131 page images were originally supplied as a PDF file in which the page numbering within the PDF file did not exactly match the markings on the pages themselves.  I hope to avoid this kind of discrepancy in future conversions.)

Before

After

Make every effort to eliminate error, but take comfort in the fact that we have means of detecting and correcting errors, and thus you don't need to lose sleep about them.  However, the more errors there are, the more of a pain it is to do so, so don't let that be an excuse for doing less than your best.

Proofing of comments in source-code files

After the code-conversion activities described in the preceding sections, we have a reasonable assurance that the program code is 100% correct—i.e., that the AGC program will execute properly unless there is a bug in the AGC CPU simulator itself.  However, we also have good reason to believe from past experience that the program comments still have many errors.  Normally, computer programmers treat program comments as an afterthought, and don't worry too much about them as long as the code itself is correct.  But when trying to understand very old code such as the AGC programs, the program comments are very important.  Therefore, an extra effort is associated with making sure comment text is proof-read and corrected.

We don't actually need any special help with this at the present time, but if you have any inclination to compare the comments in our GitHub AGC source code to the scanned program listings, please do!  If you happen to find an error, note that the AGC code changes gradually from version to version, so the error you find may exist in some or all of the other AGC versions as well.  In other words, if you're careful, you might be able to kill 10-15 birds with one stone!

"Normal" Manual-Proofing Procedure

If you want to help in proofing comments in existing source files for the problematic AGC versions listed above, here are the instructions for doing so, you simply have to compare the scanned program listing and the source-code files side-by-side.

Specific instructions are TBD.

Advanced Manual-Proofing Technique

If you have the appropriate software to do so, there is a quick technique by which comment fixes that have been made in the past for one type of spacecraft or mission can be ported to the source code for other spacecraft or missions.  This is so because of the way the source-code files have been created.  We started with the source code for one mission, then modified it (via the "code conversion" technique described earlier) for another mission, then modified those files for still other missions.  Each time the code was modified, some comment-fixes may have been made, but probably were not back-ported to earlier source-code files.  So if we compare the corresponding source code for different missions, we can easily pinpoint where some corrections can be made.  While this doesn't find all of the broken comments, it can help to find a lot of them with reduced effort by leveraging work that others have already done.

For example, the Luminary 131 (Apollo 13 LM) source code hasn't really had its comment-text proofed, but we'd suppose that it was probably very similar to the Luminary 99 (Apollo 11 LM) source code.

Fortunately, there are automated techniques for locating such differences, but you need the appropriate software to do so.  On Linux, I use a (free) tool called kompare for this, but there are any number of such tools for different computer platforms that may be suitable.  Similar programs which can be had for free on Windows and Mac OS X are WinMerge and FileMerge, respectively.  I'll simply illustrate the technique using kompare.  If I run kompare on Luminary099/INTERPRETER.s and Luminary131/INTERPRETER.s (as of 2009-06-20), an excerpt of the comparison is seen below.  (Click to enlarge if it's hard to read.) 



A number of differences are immediately apparent:

But remember, just because Luminary 99 has been proofed and Luminary 131 has not, that doesn't mean that Luminary 99 is automatically right!  This is just a technique for helping you to see where errors might be likely to exist, and not to assure you of that.  You need examine the Luminary 131 scan to really know whether or not to make these changes.

Source-Code Annotation

For those who are interested in providing help that requires a much greater involvement in understanding the technical aspects of AGC/AGS source code, such as the Luminary program, there is an interest in having an on-going program of providing modern annotations to the AGC/AGS source code.  Such modern annotations can provide assistance to others examining the code, and can therefore be viewed as an educational service.  Annotating the source code can help the student in several ways:
At present (20090703), this effort has barely begun.  To get an idea of what some annotations might look like, you can look at the Apollo 11 LM PINBALL program.

In order to provide such annotations, it is necessary to understand the markup language and strategy being used, which is described here.

There is presently not total agreement as to the best method of managing the annotation efforts, so any procedure for doing so is TBD.



This page is available under the Creative Commons No Rights Reserved License
Last modified by Ronald Burkey on 2021-09-21.

Virtual AGC is hosted
by ibiblio.org