# How to Simulate and Run the Apollo 11 Guidance Software: Complete Setup Guide > Simulate and run the Apollo 11 guidance software using the original source code from the chrislgarry/Apollo-11 repository with the Virtual AGC emulator. Get your complete setup guide now. - Repository: [Chris Garry/Apollo-11](https://github.com/chrislgarry/Apollo-11) - Tags: how-to-guide - Published: 2026-03-04 --- **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`](https://github.com/chrislgarry/Apollo-11/blob/main/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: ```bash 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`](https://github.com/chrislgarry/Apollo-11/blob/main/tools/assemble.sh) to automate this process using the yaAGC assembler: ```bash ./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`](https://github.com/chrislgarry/Apollo-11/blob/main/apollo2.cfg) or [`v2.cfg`](https://github.com/chrislgarry/Apollo-11/blob/main/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: ```bash 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`](https://github.com/chrislgarry/Apollo-11/blob/main/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`](https://github.com/chrislgarry/Apollo-11/blob/main/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`](https://github.com/chrislgarry/Apollo-11/blob/main/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.