How to Simulate and Run the Apollo 11 Guidance Software: Complete Setup Guide

You can simulate the Apollo 11 guidance software by assembling the original source code from the chrislgarry/Apollo-11 repository and executing the binary in an external Apollo Guidance Computer (AGC) emulator such as Virtual AGC.

The chrislgarry/Apollo-11 repository hosts the authentic source code for the Block II Apollo Guidance Computer that powered the lunar landing. While the repository preserves the complete assembly language modules and build scripts exactly as used in 1969, it does not include a built-in simulator or runtime environment. To execute this historic guidance software, you must assemble the source into a binary image and load it into a compatible emulator that models the spacecraft's hardware.

What the Repository Contains

The repository provides the raw materials needed to recreate the Apollo 11 guidance system, but not the execution engine itself.

• agc/AGC-11.asm — The complete Apollo II (Block II) guidance program written in AGC assembly language
• agc/AGC-11.sym — The symbol table containing memory addresses for routines and data structures
• tools/assemble.sh — A wrapper script that invokes the AGC assembler to produce executable binaries
• doc/ — Architecture documentation and instruction set references
• data/ — Fixed lookup tables for lunar ephemeris and gravity constants

Critical limitation: The code directly addresses hardware-specific registers such as core rope memory and inertial measurement units. These interfaces are only available through emulation.

Why You Need an External Emulator

The Apollo 11 guidance software cannot run natively on modern computers because it targets the AGC's unique 15-bit word length, 1 MHz clock speed, and specialized I/O channels. The repository assumes you will use a separate emulator—typically the open-source Virtual AGC (yaAGC) project—which provides:

1. Cycle-accurate CPU emulation
2. Mocked spacecraft peripherals (IMU, rendezvous radar)
3. The DSKY (Display/Keyboard) interface for operator interaction

Step-by-Step Simulation Workflow

1. Clone and Prepare the Source Code

Retrieve the original source and navigate to the assembly directory:

git clone https://github.com/chrislgarry/Apollo-11.git
cd Apollo-11

Examine the primary source file at agc/AGC-11.asm to view the guidance equations and navigation logic.

2. Assemble the Binary with tools/assemble.sh

Convert the assembly source into a binary image that the emulator can execute. The repository includes tools/assemble.sh to automate this process using the yaAGC assembler:

./tools/assemble.sh agc/AGC-11.asm agc.bin

This produces agc.bin, a binary image containing the machine code for the guidance program, along with the symbol table data from agc/AGC-11.sym.

3. Configure the Virtual AGC Emulator

Before running, create or obtain a configuration file (e.g., apollo2.cfg or v2.cfg) that tells the emulator which peripheral models to instantiate. This file specifies:

• Inertial reference platform connections
• Rendezvous radar availability
• DSKY keyboard mappings

Standard configuration files ship with the Virtual AGC distribution in its configs/ directory.

4. Launch the Emulator and Load the Binary

Execute the binary using the yaAGC command-line interface, specifying both the binary file and configuration:

yaAGC -b agc.bin -c configs/apollo2.cfg

The -b flag points to your assembled agc.bin, while -c loads the mission-specific hardware profile.

5. Interact with the Simulated DSKY

Once running, the emulator presents the DSKY interface—the same numeric display and keyboard used by astronauts. You can initiate guidance programs using the standard verb-noun syntax:

• VERB 16 — Monitor decimal data in R1, R2, R3 registers
• NOUN 20 — Display IMU orientation angles
• Program 00 — Idle/operator control state
• Program 31-40 — Guidance equations for burns and targeting

You can verify calculations for Lunar Orbit Insertion (LOI) targeting, check burn start/stop times, and step through the same navigation routines used during the 1969 mission.

Key Source Files and Their Functions

Understanding the repository layout helps when debugging or modifying the simulation:

• README.md — Overview of the repository structure and links to external emulator projects
• agc/AGC-11.asm — Primary assembly source containing the guidance, navigation, and control (GNC) algorithms
• agc/AGC-11.sym — Symbol definitions mapping human-readable labels to absolute memory addresses in the AGC's core rope memory
• tools/assemble.sh — Bash script wrapper that handles assembler invocation and binary output generation
• data/ — Ephemeris tables and constants referenced by the guidance equations for lunar trajectory calculations

Summary

• The chrislgarry/Apollo-11 repository contains authentic assembly source code but no execution environment.
• You must use tools/assemble.sh to generate a binary image (agc.bin) from agc/AGC-11.asm.
• Virtual AGC (yaAGC) provides the necessary emulator to run the binary and simulate the DSKY interface.
• The simulation supports full interaction with historic guidance programs including LOI targeting and P31-P40 burn calculations.

Frequently Asked Questions

Can I run the Apollo 11 guidance code without installing an emulator?

No. The source code in agc/AGC-11.asm targets the Apollo Guidance Computer's proprietary architecture and hardware registers. Without an emulator like Virtual AGC to model the core rope memory and 15-bit processor, the binary cannot execute on standard x64 or ARM processors.

What is the difference between the Apollo-11 repository and Virtual AGC?

The Apollo-11 repository (chrislgarry/Apollo-11) contains the historic source code—the actual assembly listings flown on the mission. Virtual AGC is a separate project that provides the runtime environment, assembler, and DSKY simulation. You need both: this repo supplies the program logic, while Virtual AGC supplies the "hardware."

Which specific guidance programs are available in the source code?

The agc/AGC-11.asm file includes programs for P00 (operator control), P31-P40 (guidance equation sets for maneuvers), and routines for Lunar Orbit Insertion (LOI) targeting. You can invoke these via the DSKY using the original VERB/NOUN entry codes documented in the doc/ directory.

How accurate is the simulation compared to the original 1969 mission?

The simulation is cycle-accurate when using Virtual AGC, meaning the guidance software executes the same instruction sequences at the correct relative timing. However, the simulation depends on the quality of the peripheral models (IMU drift, radar characteristics). For historical fidelity, the source code itself is the original unmodified version from MIT's Instrumentation Laboratory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}