swh:1:snp:79c9132b4a8931e989e318225e00e088ef6f383d
Tip revision: a8fa8f03b50a72034009439908f1339f4ce94518 authored by Ron Burkey on 06 June 2021, 12:28:21 UTC
Fixed more hyperlinks.
Fixed more hyperlinks.
Tip revision: a8fa8f0
yaTelemetry.html
<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Virtual AGC Peripheral Components</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="author" content="Ron Burkey">
<link rel="icon" type="image/png" href="favicon.png">
<meta name="author" content="Ron Burkey">
<script type="text/javascript" src="Header.js"></script>
</head>
<body style="background-image: url(gray3.jpg);">
<script type="text/javascript">
document.write(headerTemplate.replace("@TITLE@","Peripheral Components").replace("@SUBTITLE@","for use with yaAGC"))
</script>
<h2>Table of Contents</h2>
<ul>
<li><a style="font-weight: bold;" href="#VirtualAGC">VirtualAGC</a></li>
<ul>
<li><a href="#The_Basics">The Basics</a></li>
<li><a href="#Running_the_Simulation_">Running the Simulation</a><br>
</li>
<li><a href="#All_About_Settings">All About Settings</a></li>
<ul>
<li><a href="#The_Simulation_Type_settings_">The Simulation
Type settings</a></li>
<li><a href="#The_Interfaces_settings">The Interfaces settings</a></li>
<li><a href="#The_LM_Abort_Computer_AEA_settings">The LM Abort
Computer (AEA) settings</a></li>
<li><a href="#The_Options_settings">The Options settings</a><br>
</li>
</ul>
<li><a href="#Browsing_AGC_or_AEA_Source_Code">Browsing AGC or
AEA Source Code</a></li>
<li><a href="#Assembling_AGC_or_AEA_Source_Code">Assembling AGC
or AEA Source Code</a><br>
</li>
<li><a href="#How_to_Create_Equivalent_Command-Line">How to
Create Equivalent Command-Line Shell Scripts or Batch Files</a></li>
<li><a href="#Getting_the_Simulation_to_a_Known_State">Getting
the Simulation to a Known State</a></li>
<ul>
<li><a href="#Digital_Uplinks">Digital Uplinks</a></li>
<li><a href="#Core_Dumps">Core Dumps</a></li>
</ul>
<li><a href="#Scripted_operation_for_tutorials_museum">Scripted
operation for tutorials, museum exhibits, and other demo
purposes</a><br>
</li>
</ul>
<li><a href="#Contributed_Code">Contributed Code</a></li>
<ul>
<li><a href="#LM_Simulator_by_Stephan_Hotto"><span
style="font-weight: bold;">LM-Simulator</span>, by Stephan
Hotto</a></li>
<li><a href="#Game_Pack_by_John_Pultorak"><span
style="font-weight: bold;">Game Pack</span> by, John
Pultorak</a><br>
</li>
</ul>
<li style="font-weight: bold;"><a href="#yaUniverse">yaUniverse</a></li>
<li style="font-weight: bold;"><a href="#yaACA">yaACA<span
style="font-weight: normal;">, <span style="font-weight:
bold;">yaACA2</span>, and</span> yaACA3</a></li>
<ul>
<li style="font-weight: bold;"><a
href="#Joystick_configuration_for_use_with_the"><span
style="font-weight: normal;"><span style="font-weight:
bold;">jWiz</span>, the GUI front-end for joystick
configuration</span></a></li>
<li style="font-weight: bold;"><span style="font-weight:
normal;"><a href="#How_the_selection_and_configuration">How
the selection and configuration process works</a><br>
</span></li>
</ul>
<ul>
<li><a href="#Usage_of_yaACA3">Command-line usage of <span
style="font-weight: bold;">yaACA3</span></a></li>
<li><a href="#Command-line_usage_of_yaACA2">Command-line usage
of</a> <span style="font-weight: bold;"><a
href="#Command-line_usage_of_yaACA2">yaACA2</a><br>
</span></li>
<li style="font-weight: bold;"><a href="#Usage_of_yaACA2"><span
style="font-weight: normal;">Command-line usage of <span
style="font-weight: bold;">yaACA</span></span></a><span
style="font-weight: bold;"><br>
</span></li>
</ul>
<li style="font-weight: bold;"><a href="#yaTelemetry">yaTelemetry</a></li>
</ul>
<hr style="width: 100%; height: 2px;"> <br>
<h2><a name="VirtualAGC" id="VirtualAGC"></a>VirtualAGC</h2>
<h3><a name="The_Basics" id="The_Basics"></a>The Basics<br>
</h3>
You may recall seeing an extremely abbreviated description of the <span
style="font-weight: bold;">VirtualAGC</span> program <a
href="index.html#Running_the_Emulator">on the Virtual AGC project
home page</a>.<span style="font-weight: bold;"><span
style="font-weight: bold;"><br>
<br>
</span> VirtualAGC</span> is a GUI front-end which allows you to
choose almost any reasonable set of options related to the
emulation, and then to run all of the emulation programs needed, in
a way that allows those programs to intercommunicate properly.
<span style="font-weight: bold;">VirtualAGC</span> does little for
you that you couldn't have done from a command line using the
various programs and their command-line options described on this
page and on the <a href="yaAGS.html">yaAGS</a>, <a
href="yaAGC.html">yaAGC</a>, <a href="yaYUL.html">yaYUL</a>, and
<a href="yaDSKY.html">yaDSKY</a> pages of this website, but it's
safe to say that it will almost always be easier to accomplish any
given task using <span style="font-weight: bold;">VirtualAGC</span>
than using equivalent command-line operations.<br>
<br>
Depending on the version of the <b>VirtualAGC</b> program, the
basic <span style="font-weight: bold;">VirtualAGC</span> screen may
depend on your display size or on the command-line options you use
when you invoke the program. In many cases, you'll get a
screen that looks something like the following. In the upper
left, where you see "AGC Simulation Type" is a drop-down box where
you select the Apollo mission and LM vs CM AGC code you want to run
or to view.<br>
<br>
<div align="center"><img src="Screenshot-VirtualAGC-radio.jpg"
alt="" width="717" height="657"><br>
</div>
<br>
Traditionally, a larger, fancier version of the program was used if
you had a big enough display screen for it (or in latest versions of
the software, if you ran <b>VirtualAGC</b> with the --radio-buttons
command-line option), and it's what's shown below. This used
to be the default (or only!) version of the interface, so it's
what's used throughout much of this website for illustrative
purposes.<br>
<br>
<div style="text-align: center;"> <img style="border: 2px solid ;"
alt="Screenshot of VirtualAGC program."
src="Screenshot-VirtualAGC.jpg" width="1147" height="966"><br>
</div>
<br>
<br>
Finally, if you're really, really strapped for space — say on an
800×480 Raspberry Pi touchscreen — you can run <b>VirtualAGC</b>
with the --squish command-line option. This reduces the
interface to its minimal size and form:<br>
<br>
<div align="center"><img src="Screenshot-VirtualAGC-squished.jpg"
alt="" width="636" height="447"><br>
</div>
<br>
Regardless of which of the versions you use, however, the main
screen is the one and only window of the <span style="font-weight:
bold;">VirtualAGC</span> program. There are no menus,
toolbars, hot-buttons, or other controls. While a large number
of options are presented, you don't necessarily need to change any
of the selected options. The defaults are as shown, and if you
simply click the "Run!" button at the bottom of the window, the
simulation will run. <br>
<h3><a name="Running_the_Simulation_" id="Running_the_Simulation_"></a>Running
the
Simulation<br>
</h3>
When you actually do run the simulation by hitting the "Run!"
button, the large <span style="font-weight: bold;">VirtualAGC</span>
screen shown above politely disappears in order to free up the
screen space it's using, and instead the a tiny window that looks
like this replaces it:<br>
<br>
<div style="text-align: center;"> <img style="border: 2px solid ;
width: 395px; height: 192px;" alt="Simulation-running window."
src="Screenshot-VirtualAGC-running.jpg" width="395" height="192"><br>
</div>
<br>
This window is gimicked to stay atop all of the other windows open
on the screen, but you can minimize it to make it disappear if you
don't like seeing it. Note, however, that while the simulation
is running you won't be able use <span style="font-weight: bold;">VirtualAGC</span>'s
controls
to open a new browser window for viewing the source code,
so if you want to do that you'll need to do it before hitting
"Run!". <br>
<br>
To end the simulation, simply exit from any of the visible elements
of the simulation, such as the simulated DSKY. Within a few
seconds all of the other elements of the simulation will
automatically terminate and the large <span style="font-weight:
bold;">VirtualAGC</span> window will return. On some
platforms, there may be curious exceptions to this behavior that
result in some windows needing to be explicitly manually closed, but
closing the DSKY is a good recommendation for all platforms.
The small simulation screen depicted in the screenshot above cannot
itself be closed manually, so do not expect that the simulation can
be ended by closing this screen.<br>
<br>
We'll discuss the <a href="#How_to_Create_Equivalent_Command-Line">"More",
"Less"</a>, and <a href="#Digital_Uplinks">"Uplink"</a> buttons
later. You don't need to know about them for basic operation.<br>
<h3><a name="All_About_Settings" id="All_About_Settings"></a>All
About Settings<br>
</h3>
If you change any of the settings on the <span style="font-weight:
bold;">VirtualAGC</span> screen, the program will remember those
changes and the settings you've selected will be the ones that
appear the next time you run <span style="font-weight: bold;">VirtualAGC</span>.
On
the other hand, you could click the "Defaults" button at the
bottom of the window to restore all of the settings to their
defaults. <br>
<br>
There is, however, a subtle distinction between closing the <span
style="font-weight: bold;">VirtualAGC</span> main window using the
"Exit" button at the bottom of the window, and using the
operating-system-supplied controls on the border of the
window. The settings are saved only when the "Exit" button is
used. They'll not be saved if the window's border controls are
used instead.<br>
<br>
All of the settings are intelligent, in the sense that not all
settings are reasonable in combination with other settings, and so
illegal settings are grayed out and disabled. As you change
some settings, it may cause other settings to become enabled or
disabled. So it's hard to choose a combination of settings
that don't work reasonably well together.<br>
<h4><a name="The_Simulation_Type_settings_"
id="The_Simulation_Type_settings_"></a>The Simulation Type
settings</h4>
The left-hand pane of the screen is used to select the specific
software to be run on the simulated AGC. Included are all of
the versions of the <a href="Colossus.html">Colossus</a> and <a
href="Luminary.html">Luminary</a> AGC programs that have been made
available to the Virtual AGC project. The grayed-out
mission/spacecraft combinations in this area are the ones for which
the original software isn't yet available, but in many cases is
known to exist in museums or private collections. But we
maintain hope that they'll eventually be made available to the
admiring public, so we put them on the list anyway! <br>
<br>
The "Validation Suite" choice was not, of course, used in any actual
Apollo mission. However, at one time there was a software
validation suite that checked out the AGC CPU registers and
instructions for proper behavior. (I surmise that this code
was originally intended to be included in the flight software as
part of the built-in self-test, but was mostly removed due to memory
constraints.) While that software no longer exists, as far as
I know, <a href="hrst/archive/1705.pdf">the program documentation
for it does exist</a>, and the Validation Suite program was
created by closely following the documentation of the original
validation suite. And a good thing, too, since in doing so a
number of implementation errors were uncovered that might have
lingered to cause mysterious problems later! <br>
<br>
You'll also notice a box for selecting "custom" software. This
would be software you had written yourself, or perhaps acquired from
enthusiasts. Normally all of the selections in the Simulation
Type pane are expected to be executable binary code which has been
pre-assembled from source code, so if you have your own AGC source
code you'll want to read below about <a
href="#Assembling_AGC_or_AEA_Source_Code">how to assemble</a> it.<br>
<h4><a name="The_Interfaces_settings" id="The_Interfaces_settings"></a>The
Interfaces
settings</h4>
The middle pane of the screen is mostly devoted to selecting the
particular set of peripheral devices—in most cases, interfaces to
the simulated CPUs—which you wish to simulate. <br>
<br>
Here's a brief description of all of the devices appearing in the
interface pane:<br>
<ul>
<li>The "Guidance Computer" is, of course, the simulated AGC CPU
which is described so thoroughly on <a href="yaAGC.html">the <span
style="font-weight: bold;">yaAGC</span> program</a>
page. We assume that you'll always want to include this in
the simulation, so we don't actually allow you to deselect it.</li>
<li>And the "DSKY", of course, is the simulated display/keypad
unit which is the principal user interface to the AGC, described
on <a href="yaDSKY.html">the yaDSKY or yaDSKY2 program</a>
page. As with the AGC simulation, we assume you'll always
want a DSKY and therefore it is always selected.</li>
<li>The "Attitude Controller Assembly" (ACA) is a joystick
interface simulating the LM pilot's (or more accurately, the
mission commander's) control stick in the LM. Since it is
used only for the LM, it is not selectable in a CM
simulation. The functionality is described in more detail
below in the section covering <a href="#yaACA">the yaACA
program</a>.</li>
<li>The "Telemetry Downlink Monitor" is an interface that lets you
see the telemetry information continually being transmitted from
the AGC to mission control. The functionality is described
below in more detail, in the section covering <a
href="#yaTelemetry">the yaTelemetry program</a>.</li>
<li>The "LM Abort Computer" (sometimes known as the AEA or AGS) is
computer used in the LM, but of a different design and software
than the AGC, which served to back up the AGC but only during
landing aborts. Since it appears only in the LM, it is not
selectable for CM simulations. This is described in much
more detail on <a href="yaAGS.html">the yaAGS program</a> page.</li>
<li>The "DEDA" is the display/keypad unit providing the principal
user interface to the LM abort computer, and is therefore
selectable only when "LM Abort Computer" is also selected.
In fact, we assume that if you have the abort computer, you will
definitely want the DEDA, so we don't allow you to deselect
it. It's described in more detail as <a
href="yaAGS.html#yaDEDA_the_AGS_User-Interface">the yaDEDA or
yaDEDA2 program</a>.</li>
<li>The "AGC CPU Bus/Input/Output Monitor" is an interface which
continually displays information about various i/o channels of
the AGC CPU and allows you to log the data. (Note that the
Monitor interface has a quirk which may be slightly confusing,
in that it waits about 30 seconds after the remainder of the
simulation starts up before it and its associated interfaces
listed below start up.) The Monitor is useful for either
CM or LM simulations. However, its main importance is that
it is the main window of <a
href="#LM_Simulator_by_Stephan_Hotto">Stephan Hotto's <span
style="font-weight: bold;">LM-Simulator</span> program</a>.
The
other elements of <span style="font-weight: bold;">LM-Simulator</span>
are presently of very limited usefulness for CM simulations, and
so aren't selectable except for LM simulations, nor are they
selectable if "AGC CPU Bus/Input/Output Monitor" isn't
selected. However, any of them can be started from the
menu system in <span style="font-weight: bold;">LM-Simulator</span>
at runtime, so selecting or deselecting these elements merely
affects whether or not they are started <span
style="font-style: italic;">automatically</span> when the
simulation begins. Those other elements comprise the
remaining selections in the Interfaces pane:</li>
<ul>
<li>The "Intertial Measurement Unit" (IMU) provides two
important things: the IMU itself, which contintually
tracks the rotation and acceleration of the spacecraft, and
the FDAI (8-ball), which is a graphical representation for the
pilot of the spacecraft orientation.</li>
<li>The "Discrete Outputs" interface continuously displays the
states of various output channels of the AGC.</li>
<li>The "Discrete Inputs (crew)" interface allows setting
various signals read by the AGC on its input channels that
would normally controlled by the crew by means of switches on
the LM control panel. There is no attempt to visually
mimic the appearance of the switches or the control panel.</li>
<li>The "Discrete Inputs (system)" interface allows setting
various signals read by the AGC on its input channels that
would normally be supplied by the spacecraft itself rather
than being directly controlled by the crew.</li>
<li>The "Propulsion/Fuel/Thrust Monitor" interface provides a
continuous display of the current fuel supply and thruster
statuses.<br>
</li>
</ul>
</ul>
You'll also notice a couple of buttons in the Interfaces pane.
The "Novice" button is a short-cut that simply deselects everything
except the minimal set of devices, namely the AGC and DSKY
simulations. Conversely, the "Expert" button is a short-cut
that selects every device that's reasonable with the spacecraft and
mission type you've selected in the "Simulation Type" pane.<br>
<h4><a name="The_LM_Abort_Computer_AEA_settings"
id="The_LM_Abort_Computer_AEA_settings"></a>The LM Abort
Computer (AEA) settings</h4>
Here you can select the specific software set which will be run on
the Abort Guidance System (AGS or AEA) simulated CPU. It would
have been more logical to include this in the "Simulation Type"
area, but alas! there's only so much space available. In the
screen-shot above, this area is completely grayed-out because the
"LM Abort computer (AEA)" box is not checked in the "Devices" area,
so the AGS/AEA simulation would not actually be run. If it
were enabled, however, <a href="yaAGS.html#AGS_Flight_Software">any
AEA flight program to which the Virtual AGC project has been given
access</a> could be selected. Other versions of the AEA
flight software which are believed to have existed (and hoped to
still exist) appear also on the selection list, but are disabled and
grayed out until the happy time when the Virtual AGC project
acquires access to them.<br>
<br>
As with the AGC software selection, it's possible to select custom
software in place of actual mission software if you wished to write
your own AEA software. As with the custom AGC software, it is
expected that the software you select is a pre-assembled executable
binary. But also see below about <a
href="#Assembling_AGC_or_AEA_Source_Code">assembling AEA source
code</a>.<br>
<h4><a name="The_Options_settings" id="The_Options_settings"></a>The
Options settings</h4>
The right-hand area of the screen allows you to set various minor
options associated with the exact manner in which the various
emulated devices are run. I won't bother to explain most of
these in great detail since they're pretty self-explanatory, but
here are a few words of explanation anyway:<br>
<ul>
<li>AGC "Restart program, wiping memory." This option
provides a completely clean boot. You should note that
this would not have been the normal behavior of a real AGC,
since the ferrite core memory of the AGC would have retained its
state in spite of power-cycling. However, it is the
appropriate default for a non-experienced user.</li>
<li>AGC "Restart program, preserving memory." This option
preserves the contents of volatile memory, but not of the CPU
program counter, interrupt state, and other CPU central
registers, so the program starts from its entry vector even
though the values of all variables are preserved from the prior
run(s).</li>
<li>AGC "Resume from ending point of prior run." This option
preserves not only the contents of volatile memory, but also the
CPU state, so that execution picks up from some point in the
midst of the program rather than from the entry vector. It
should be noted that neither this option nor the preceding
option can really do exactly what they claim, since the contents
of memory are not written to the Linux/Windows/Mac filesystem on
a machine-cycle to machine-cycle basis. Rather, the memory
is snapshotted at regular intervals (nominally 10 seconds), and
therefore the state of the machine is only accurate to the point
of the last snapshot.</li>
</ul>
<table summary="" style="text-align: left; width: 60%; margin-left:
auto; margin-right: auto;" cellspacing="2" cellpadding="2"
border="1">
<tbody>
<tr>
<td style="vertical-align: top;">It's important to note that
halting the simulation and then resuming it later is not
like the pause feature in a video game, because Virtual AGC
is not a computer game. The ability to resume program
execution is not something that has been layered atop the
simulation ... rather, it is simply a characteristic of the
computer memories used at that time: the AGC retained the
contents of memory across power cycles, and therefore
Virtual AGC does as well.<br>
<br>
If your only interest is in the guidance computer itself,
then this distinction is unimportant. However, if you
are interested in the system as a whole, then the
distinction is important because it means that only the
state of the AGC is preserved, and <span style="font-style:
italic;">not</span> the state of the entire
simulation. In particular, the states of the <a
href="#LM_Simulator_by_Stephan_Hotto">IMU, FDAI,
propulsion system, discrete inputs, etc., from the
LM-Simulator program</a> are not preserved. For
example, if you stopped the simulation in the middle of a
descent to the lunar surface, when you resumed it later the
AGC would think it was still in the middle of the landing,
but the orientation of the spacecraft would have changed,
the fuel tanks suddenly would be full, etc.<br>
</td>
</tr>
</tbody>
</table>
<ul>
<li>AGC "Custom" program resumption is a more flexible form of
"Resume from ending point of prior run". Because of the
relative complexity of this option, <a href="#Core_Dumps">an
entire section ("Core Dumps") is devoted to it below</a>.<br>
</li>
<li>"Full" DSKY. This is the default option when a large display
screen is available<br>
</li>
<li>"Half" DSKY. This is the default option when only a
small display screen is available.<br>
</li>
<li>"Lite" DSKY. This option bypasses the default DSKY
simulation provided by <a href="yaDSKY.html">the yaDSKY or
yaDSKY2 program</a>, and instead uses the DSKY simulation
provided by <a href="#LM_Simulator_by_Stephan_Hotto">Stephan
Hotto's LM-Simulator program</a>. The rationale for this
is that <span style="font-weight: bold;">LM-Simulator</span>
was at one time portable to a greater range of platforms than <span
style="font-weight: bold;">yaDSKY</span>, however this is
probably no longer true, and it is likely that you will have
equal or greater luck running <span style="font-weight: bold;">yaDSKY</span>
on most platforms. Nevertheless, the option remains
available and may be useful in some cases.</li>
<li>"Normal" Downlink. This is the default when a Telemetry
Downlink Monitor is selected, and has the most flexibility,
particularly with smaller display-screen sizes.<br>
</li>
<li>"Retro" Downlink. This has nothing to do with
retro-rockets. It is an alternate way of displaying the
Telemetry Downlink Monitor, which somewhat resembles a CRT
display, and (to my eyes) has an amusingly pleasing retro
appearance. However, it is very wasteful of screen space,
without being resizable, and therefore is really only usable on
large display screens. The two telemetry styles are
compared side by side below. These half-size screenshots
aren't completely legible, but the difference in screen
real-estate and style is apparent; I might add that the
resizable style (if the screenshot had not been reduced by 50%)
would have been legible at an even smaller font size, and the
difference in screen real-estate would have been even more
dramatic.<br>
</li>
</ul>
<div style="text-align: center;">
<table summary="" style="text-align: left; margin-left: auto;
margin-right: auto;" cellspacing="20" cellpadding="2" border="0">
<tbody>
<tr>
<td style="vertical-align: middle;"> <img style="border:
2px solid ; width: 281px; height: 306px;" alt="Resizable
telemetry screen"
src="Screenshot-Telemetry-resizable.jpg" width="281"
height="306"><br>
<div style="text-align: center;"> <span
style="font-style: italic;">"Resizable" Telemetry
Style</span><br>
</div>
</td>
<td style="vertical-align: middle;"> <img style="width:
514px; height: 500px;" alt="" retro"="" telemetry=""
screen"="" src="Screenshot-Telemetry-retro.jpg"
width="514" height="500"><br>
<div style="text-align: center;"> <span
style="font-style: italic;">"Retro" Telemetry Style</span><br>
</div>
</td>
</tr>
</tbody>
</table>
<br>
</div>
<ul>
<li>AGC "Normal". In this default mode, the simulated AGC
has no visual component at all. It exists merely to
service the peripheral devices such as the DSKY, but has no
on-screen presence.<br>
</li>
<li>AGC "Debug". In this mode, the <a
href="yaAGC.html#Debugging">simulated AGC is run in
"debugging" mode</a> within a terminal window, which allows
you to do such stuff to the AGC code as single-step, set
breakpoints, examine or change the values of variable,
etc. This is obviously not for casual use, but is
certainly very handy when AGC code is inoperative in some
way. It should be noted that when started in this mode a
breakpoint occurs at the first instruction encountered, so
peripherals such as the DSKY will be completely unresponsive
until the AGC program run actually is started up manually from
the debugger. In the screenshot below, I've trimmed the
image down, but the default debugging screen is quite a bit
taller.<br>
</li>
</ul>
<div style="text-align: center;"> <img style="border: 1px solid ;
width: 691px; height: 201px;" alt="AGC debugger"
src="Screenshot-AGC-debugger.jpg" width="691" height="201"><br>
</div>
<ul>
<li>"Normal" DEDA vs. "Half" DEDA. As with the simulated
DSKY, the simulated DEDA comes in two sizes, useful for
different display-screen sizes.<br>
</li>
<li>AEA "Normal" vs. AEA "Debug". As with the simulated AGC,
<a href="yaAGS.html#Debug">the simulated AEA also has a debugger
option</a>. </li>
</ul>
<div style="text-align: center;"> <img style="width: 679px; height:
195px;" alt="Screenshot of AEA debugger"
src="Screenshot-AGS-debugger.jpg" width="679" height="195"><br>
</div>
<h3><a name="Browsing_AGC_or_AEA_Source_Code"
id="Browsing_AGC_or_AEA_Source_Code"></a>Browsing AGC or AEA
Source Code<br>
</h3>
Having chosen the AGC software suite which you wish to emulate, you
might like to actually view the software listing as well.
That's what the "AGC" button under the "Browse Source Code" heading
is for. Pressing the button displays an assembly listing for
the selected software in the default browser (such as Mozilla
Firefox, Internet Explorer, or Safari) of your computer. At
present, this won't display the Apollo 15-17 CM software, because
even though we have a verifiable executable for it, we do not yet
have the full source code. Nor will it display your custom
software, since we assume you know how to display that
yourself! However, it will show the source code for any of the
other valid software selections.<br>
<br>
Similar comments apply to browsing the AEA source code.<br>
<h3><a name="Assembling_AGC_or_AEA_Source_Code"
id="Assembling_AGC_or_AEA_Source_Code"></a>Assembling AGC or AEA
Source Code</h3>
A fun thing to do (in an über-geekish way) is to write <span
style="font-style: italic;">your own</span> AGC software, just as
I have written the Validation Suite. So naturally, one of the
options mentoned above is to run your own custom
software. If you simply type a filename into the box
which is supposed to contain the filename of your custom software,
it's expected to be a binary file which has already been run through
the assembler. However, if instead of typing in a filename you
use the <img alt="" ..."="" button"="" src="BrowseButton.jpg"
style="width: 39px; height: 31px;" width="39" height="31"
align="middle"> button located next to the filename-entry box to
select a file by means of a file-selection dialog, you can select
either a binary file <span style="font-style: italic;">or</span> an
AGC source-code file. If you choose an assembly-language
source file, then <span style="font-weight: bold;">VirtualAGC</span>
will thoughtfully run the <a href="yaYUL.html"><span
style="font-weight: bold;">yaYUL</span></a> program to assemble
it for you automatically and will place the name of the binary
executable file it creates into the filename selection box.<br>
<br>
Similar comments apply to selection of custom AEA programs: If
you select custom source code rather than custom binary code via the
<img style="width: 39px; height: 31px;" alt="" ..."="" button"=""
src="BrowseButton.jpg" width="39" height="31" align="middle">
button in the AEA-program selection area, then <span
style="font-weight: bold;">VirtualAGC</span> will automatically
run the <a href="yaAGS.html#yaLEMAP_the_AGS_Cross-Assembler"><span
style="font-weight: bold;">yaLEMAP</span></a> program to
assemble it for you and place the name of the newly-created
executable binary in the filename selection box.<br>
<h3><a name="How_to_Create_Equivalent_Command-Line"
id="How_to_Create_Equivalent_Command-Line"></a>How to Create
Equivalent Command-Line Shell Scripts or Batch Files</h3>
In <a href="#Running_the_Simulation_">the small simulation window</a>
that pops up while the simulation is running, there are two buttons
labeled "More" and "Less". <br>
<br>
The "More" button can be used to expand the simulation window so
that it displays the contents of a shell script (or a Windows batch
file) that could be used to run the simulation from a command-line
(or by other means) without needing to invoke <span
style="font-weight: bold;">VirtualAGC</span>. <br>
<br>
<div style="text-align: center;"> <img style="border: 1px solid ;
width: 514px; height: 708px;" alt="Screen shot of simulation
window expanded by using the " more"="" button."=""
src="Screenshot-VirtualAGC-script.jpg" width="514" height="708"><br>
</div>
<br>
This information would also be useful to you if you wanted to create
a custom setup too complex for <span style="font-weight: bold;">VirtualAGC</span>
to handle, such as running a Command Module simulation that had two
DSKYs, or if you wanted to run the simulation on several PCs ganged
together via a network. The displayed commands can be cut-and-pasted
into a text editor for subsequent modification. Clicking the
"Less" button causes this extra display to disappear again from
view.<br>
<br>
Not only that, but running the simulation from the command line
using scripts can be very helpful if troubleshooting needs to be
performed. In normal operation, <span style="font-weight:
bold;">VirtualAGC</span> tries to hide as much complexity from you
as possible, and one thing which it hides from you is the messages
printed out by the various programs in the Virtual AGC suite.
These messages include such helpful information as socket connects
and disconnects (as the various peripheral devices try to
communicate with the simulated CPUs), and the joystick positions
being reported by the ACA simulation to the AGC. The latter
are helpful to know because there are some joystick-related
configuration differences from platform to platform and joystick to
joystick. When running the simulation directly from the
command line via a script, all of these messages become visible.<br>
<br>
You could, of course, reconstruct all this information yourself by
examining the documentation of the various component programs, but
it's much simpler to adapt an existing script rather than to create
one from scratch.<br>
<h3><a name="Getting_the_Simulation_to_a_Known_State"
id="Getting_the_Simulation_to_a_Known_State"></a>Getting the
Simulation to a Known State<br>
</h3>
One thing that quickly becomes apparent in running the AGC
simulation is that setting up the AGC to a given state can be very
time-consuming, so it is helpful to have a method of automating that
process. VirtualAGC actually provides two separate
methods of setting up the simulated AGC to a known state:
Digital Uplinks and resumption from core-dumps. Each of these
methods has advantages and disadvantages relative to the other, so
it is not possible to provide a blanket recommendation for just one
of them. There may even be cases where a combination of the
methods is the best approach. In general, the disadvantages of
the Digital Uplink are that it is slower to use and more cumbersome
to set up than core dumps. The disadvantages of the core dump
are that although the CPU state is restored, the states of
peripheral devices are less likely to be in sync and that it is
impossible to combine core dumps (whereas it is possible to combine
different digital uplinks) containing initialization of different
subsystems. <br>
<h4><a name="Digital_Uplinks" id="Digital_Uplinks"></a>Digital
Uplinks</h4>
Digital Uplink was a method that could be used by mission control to
transmit data to the AGC, and is the complement of the "digital
downlink" for transmitting data from the AGC to mission control
discussed in <a href="#yaTelemetry">the yaTelemetry section</a>
below.<br>
<br>
What the digital uplink implemented was essentially a stream of DSKY
keycodes. Thus, any condition in the AGC which could be set up
via the DSKY could also be set up via digital uplink. I'm not
sure exactly how this was done in the original missions—a DSKY in
the control room? a paper tape?—but in <span style="font-weight:
bold;">VirtualAGC</span> it is accomplished by creating a file
containing a script of DSKY keycodes. The digital uplink is
the single piece of functionality provided by <span
style="font-weight: bold;">VirtualAGC</span> itself rather than by
other yaPrograms, so if you need a digital uplink there's presently
no way to provide it without interactively running <span
style="font-weight: bold;">VirtualAGC</span>.<br>
<br>
To send a digital uplink, you click the "Uplink" button in <a
href="#Running_the_Simulation_">the simulation window</a>, and
then select the DSKY-keycode script you'd like to use from the
file-selection dialog which pops up. Once you've done so, the
"Uplink" button changes to a "Cancel" button, and the simulation
window acquires a new pane which shows the status of the uplink in
progress:<br>
<br>
<div style="text-align: center;"> <img style="border: 1px solid ;
width: 490px; height: 694px;" alt="Screenshot of digital-uplink
status screen." src="Screenshot-VirtualAGC-uplink.jpg"
width="490" height="694"><br>
</div>
<br>
Eventually, this method may be used for uplinks to the AEA as well
as to the LM or CM AGC, but at present I don't know enough about the
uplink system for the AEA to implement it. <br>
<br>
Here are the rulea for creating DSKY-keycode scripts for digital
uplinks to LM or CM AGC simulations:<br>
<ul>
<li>The type of simulation for which the uplink script is targeted
is determined by the first character in the file, namely:</li>
<ul>
<li>'C' for a CM uplink.</li>
<li>'L' for an LM uplink.</li>
<li>'A' for an AEA uplink.</li>
</ul>
<li>Comments beginning with '#' are ignored. In other words,
everything between a '#" character and the end of the line is
ignored.</li>
<li>Text strings between an '!' character and the end of line have
a special purpose <a
href="#Scripted_operation_for_tutorials_museum">that is
described later</a>, but don't affect the uplink or the
simulation in any way.<br>
</li>
<li>The following characters are translated directly into DSKY
keycodes:</li>
<ul>
<li>'0'—the 0-key</li>
<li>'1'—the 1-key<br>
</li>
<li>'2'—the 2-key<br>
</li>
<li>'3'—the 3-key<br>
</li>
<li>'4'—the 4-key<br>
</li>
<li>'5'—the 5-key<br>
</li>
<li>'6'—the 6-key<br>
</li>
<li>'7'—the 7-key<br>
</li>
<li>'8'—the 8-key<br>
</li>
<li>'+'—the + key<br>
</li>
<li>'-'—the - key</li>
<li>'V'—the VERB key</li>
<li>'N'—the NOUN key</li>
<li>'E'—the ENTR key</li>
<li>'C'—the CLR key</li>
<li>'R'—the RST key</li>
<li>'K'—the KEY-REL key</li>
<li>Note that the DSKY does not report the PRO key to the AGC by
means of a keycode, so the PRO can cannot be transmitted via
digital uplink.</li>
</ul>
<li>Since the AGC responds to digital-uplinks just as it responds
to the DSKY, you can't assume that it responds instantly to all
uplinked commands. In other words, some delays may be
necessary to give the AGC time to process the commands it
receives. I'm not certain how this was handled in the real
hardware, but <span style="font-weight: bold;">VirtualAGC</span>
provides a two-step method for adding delays to uplink data:</li>
<ul>
<li>A delay of 0.2 seconds is automatically inserted by <span
style="font-weight: bold;">VirtualAGC</span> between the
transmission of any two keycodes.</li>
<li>Any place the space character (' ') appears in the script,
an extra delay of 0.5 seconds is inserted. (This applies
only to literal spaces, and not to other whitspace such as
tabs or newlines.)</li>
</ul>
<li>If the character 'Z' is placed in the script, it causes a
special code to be transmitted which clears uplink errors.
However, since it is impossible for the simulated uplink to be
corrupted as a real transmission might be, the 'Z' character
should probably never be used.</li>
<li>All other characters are transparently discarded.<br>
</li>
</ul>
If you try to relate this information to the screenshot above,
showing an actual uplink in progress, it's pretty straightforward to
do so. The only point worth mentioning is that the dots
appearing in the screenshot are where additional 0.5 second delays
appeared in the script.<br>
<br>
There are, however, a few subtleties which the rules above impose on
the scripts which may not be obvious, so let's illustrate this with
a real script:<br>
<br>
<table summary="" style="text-align: left; margin-left: auto;
margin-right: auto;" cellspacing="2" cellpadding="2" border="1">
<tbody>
<tr>
<td style="vertical-align: top; background-color: rgb(204,
255, 255);"> <span style="font-family: Courier
New,Courier,monospace;">L
# For LM</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V05N09E
# Show
program alarms</span><br style="font-family: Courier
New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V91E
# Commence showing
memory-bank checksums.</span><br style="font-family:
Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V16N36E
#
Commence showing time.</span><br style="font-family:
Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay
5 seconds.</span><br>
</td>
</tr>
</tbody>
</table>
<br>
The first subtlety is that since the space character is used to
insert extra transmission delays, while the tab character is not,
and yet tabs and spaces are visually indistinguishable, it's not
immediately obvious in looking at the script where the extra delays
have been inserted. I've handled it in this script by
enclosing the spaces in quotes. The quote character is simply
discarded when the script is parsed, and so its presence causes no
harm. There are many other methods which could be used, of
course.<br>
<br>
The second subtlety is that if you like to format the script nicely,
by doing things like aligning the comments, you'd better do so using
tab characters only or else you'll have lots of unwanted delays
added to the transmission.<br>
<br>
The extra delay at the very end of the script has no functional
significance, but allows the status display to remain on the screen
5 seconds after transmission of the "V16N36E" command, rather than
disappearing instantly on transmission of that command. I did
this merely to make the status message readable.<br>
<br>
<span style="font-weight: bold;">Note:</span> The AGC is not
able to properly accept digital uplinks at arbitrary times, and must
be prepared in advance to do so. I'm not sure at this writing
exactly what preparation is required, but (at least after a clean
power-up) a DSKY-test a "goto pooh" command (V37E00E) entered
directly from the DSKY keypad seems to do the trick. After the
DSKY test completes, a digital uplink is accepted.<br>
<h4><a name="Core_Dumps" id="Core_Dumps"></a>Core Dumps</h4>
An alternative to Digital Uplinks in getting the simulated AGC CPU
to a known state is to use the method of "core dumps" instead.<br>
<br>
<a href="#The_Options_settings">As mentioned above</a>, when the
simulated CM or LM AGC is running, it saves a snapshot of its
simulated ferrite-core memory periodically. Nominally, these
"core dump" files are saved at 10-second intervals. The
core-dump files are named "CM.core" or "LM.core", depending on
whether it is a CM or an LM simulation being run. One of the
items under the Options Settings, "Resume from ending point of prior
run", allows you to start the next simulation run with the memory
contents and CPU state of the last relevant core-dump file.
(In other words, a CM simulation can be started from the last
CM.core, and an LM simulation from the last LM.core.) Thus, to
get the AGC into a desired state you could use the DSKY to set it
up, and then resume the simulation later with those settings.<br>
<br>
The difficulty, of course, is that after you had resumed the
simulation, execution of the simulation might result in an
alteration of your setups, so if you resumed the simulation still
later you would no longer have the same setups.<br>
<br>
This is handled by an additional item ("Custom") in the AGC Startup
area in <span style="font-weight: bold;">VirtualAGC</span>'s Option
Settings pane. What this item does is to let you save <span
style="font-style: italic;">named</span> copies of your LM.core or
CM.core files (using the "Save" button), and then to later resume
execution of the AGC simulation from your named core-dump files
rather than from the generic LM.core or CM.core files. The
core-dumps made after resumption of the simulation are still called
LM.core or CM.core, so your named core-dump file is not affected by
the continuing simulation and could still be used later to exactly
duplicate your setups.<br>
<br>
You can make as many saved core-dump files as you like, and the area
under Options Settings allows you to either type in the name of the
file directly, or else to browse for it using the "..." button.<br>
<br>
It is perhaps worth noting also that while LM.core and CM.core are
created automatically at 10-second intervals, if you are running AGC
under its debug monitor then you can use debug-monitor commands to
manually save core-dump files (with names of your own choosing) that
are accurate to the machine-cycle at which they are saved. By
default, <span style="font-weight: bold;">VirtualAGC</span> likes
to save and look for core-dump files in the scenarios/ folder, so if
you save core-dump files from the debugger it is best to prefix the
names with "scenario/".<br>
<h3><a name="Scripted_operation_for_tutorials_museum"
id="Scripted_operation_for_tutorials_museum"></a>Scripted
operation for tutorials, museum exhibits, and other demo purposes</h3>
(For related functionality that can be used interactively rather for
unattended operation, see the <a href="yaDSKY.html#SpecialEffects">yaDSKY
page</a>.)<br>
<br>
The <a href="#Digital_Uplinks">Digital Uplink capability described
above</a> has a special feature that could be used in a variety of
instructional settings, of which a few are listed in the title of
this section. Specifically, it is possible to embed commands
in the digital upload script which cause programs of your choice to
be run when those positions in the script are reached.
Specifically, when the uplink script finds an '!' character, any
text between the '!' and the end of line is treated as a command
which would be suitably run from your operating system's
command-line.<br>
<br>
Interesting software which might be run in this fashion includes:<br>
<ul>
<li>Audio-playback commands.</li>
<li>Commands which pop up a window containing descriptive text.</li>
<li>Commands which provide remote control of lighting or
industrial automation.<br>
</li>
</ul>
For example, you could imagine creating a tutorial on some
particular sequence of operations on the DSKY, where at each
critical point a window opened up to describe the operation that was
being performed. Or you could imagine a museum display with a
simulated DSKY on an LCD screen, and an audio commentary
synchronized to the operations being performed on the DSKY.<br>
<br>
Here is the example digital uplink script used earlier, but with
embedded commands for audio playback using the <span
style="font-weight: bold;">madplay</span> mp3-player program found
on many Linux computers:<br>
<br>
<table summary="" style="text-align: left; margin-left: auto;
margin-right: auto;" cellspacing="2" cellpadding="2" border="1">
<tbody>
<tr>
<td style="vertical-align: top; background-color: rgb(204,
255, 255);"> <span style="font-family: Courier
New,Courier,monospace;">L
# For LM<br>
!madplay DescriptionOfProgramAlarms.mp3</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V05N09E
# Show
program alarms</span><br style="font-family: Courier
New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 10
seconds.<br>
!madplay ShowingMemoryBankChecksums.mp3<br
style="font-family: Courier New,Courier,monospace;">
</span> <span style="font-family: Courier
New,Courier,monospace;">V91E
# Commence showing
memory-bank checksums.</span><br style="font-family:
Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">V33E
# Show next memory bank.</span><br
style="font-family: Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay 5 seconds.<br>
!madplay MonitoringTimeSincePowerup.mp3<br
style="font-family: Courier New,Courier,monospace;">
</span> <span style="font-family: Courier
New,Courier,monospace;">V16N36E
#
Commence showing time.</span><br style="font-family:
Courier New,Courier,monospace;">
<span style="font-family: Courier New,Courier,monospace;">"
"
# Delay
5 seconds.</span><br>
</td>
</tr>
</tbody>
</table>
<br>
<br>
As of yet there is no feedback to the digital uplink that could be
used to pause the uplink or branch to alternate possible uplinks,
but if anyone has a serious use for this kind of capability, I'm
sure it could be added.<br>
<br>
<hr style="width: 100%; height: 2px;"> <br>
<h2><a name="Contributed_Code" id="Contributed_Code"></a>Contributed
Code</h2>
<h3><a name="LM_Simulator_by_Stephan_Hotto"
id="LM_Simulator_by_Stephan_Hotto"></a>LM-Simulator, by Stephan
Hotto</h3>
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. 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 <span style="font-weight: bold;">LM-Simulator</span>
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 (<span style="font-weight:
bold;">yaAGC</span>).<br>
<br>
<span style="font-weight: bold;">LM-Simulator</span> is provided in
the Virtual AGC developer snapshot and all of the binary packages,
and is completely integrated into the <span style="font-weight:
bold;">VirtualAGC</span> GUI. So you don't have to do
anything special to get it or to run it. The program is
written in the Tcl/Tk script language, however, so you do have to
have Tcl/Tk installed. Like most of the rest of Virtual AGC, <span
style="font-weight: bold;">LM-Simulator</span> is licensed under
the GPL. <br>
<br>
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.<br>
<br>
<div style="margin-left: 40px;"> 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 <span style="font-weight:
bold;">VirtualAGC</span> GUI can automatically start <span
style="font-weight: bold;">LM-Simulator</span>, so you really
don't need to start it explicitly, but you can also explicitly
start it as described.]<br>
<br>
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.]<br>
<br>
The program is split into the following modules which can be
called by the menu of the main program:<br>
<br>
<table summary="" style="width: 100%; text-align: left;
margin-left: auto; margin-right: auto;" cellspacing="2"
cellpadding="2" border="0">
<tbody>
<tr>
<td style="vertical-align: top;">lm_simulator.tcl</td>
<td style="vertical-align: top;">Main Program for the LM
version of the program<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;"> lm_simulator.ini<br>
</td>
<td style="vertical-align: top;">The default configuration
file.<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">AGC_Crew_Inputs.tcl</td>
<td style="vertical-align: top;">Nearly all Crew Switches
connected to the AGC</td>
</tr>
<tr>
<td style="vertical-align: top;">AGC_Outputs.tcl</td>
<td style="vertical-align: top;">All binary AGC outputs
interpreted by showing their status</td>
</tr>
<tr>
<td style="vertical-align: top;"> AGC_System_Inputs.tcl</td>
<td style="vertical-align: top;">All binary LM->AGC
System Inputs</td>
</tr>
<tr>
<td style="vertical-align: top;">AGC_IMU.tcl</td>
<td style="vertical-align: top;">First steps into the IMU
& FDAI (not completely working, need some more
counters)</td>
</tr>
<tr>
<td style="vertical-align: top;"> AGC_Attitude.tcl<br>
</td>
<td style="vertical-align: top;">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.)<br>
</td>
</tr>
<tr>
<td style="vertical-align: top;">AGC_DSKY.tcl<br>
</td>
<td style="vertical-align: top;">A DSKY simulation that can
be used in place of <span style="font-weight: bold;">yaDSKY</span>.<br>
</td>
</tr>
</tbody>
</table>
<br>
</div>
Stephan has also provided a <span style="font-style: italic;
font-weight: bold;">helpful tutorial</span>. The tutorial
will be found in the Contributed/LM_Simulator/doc directory of the
developer snapshot, or can be activated from the <span
style="font-weight: bold;">LM-Simulator</span> main menu when
actually running the program.<br>
<br>
Here are some (possibly out-of-date) screenshots from the program.<br>
<br>
<div style="text-align: center;">
<table summary="" style="text-align: left; width: 100%;"
cellspacing="20" cellpadding="2" border="0">
<tbody>
<tr>
<td style="text-align: center; vertical-align: middle;"> <a
href="Hotto_LM_main.jpg"><img title="Click to enlarge"
alt="Main screen" src="Hotto_LM_main-thumb.jpg"
style="border: 2px solid ; width: 225px; height:
215px;" width="225" height="215"></a><br>
<span style="font-style: italic;">Main screen</span><br>
</td>
<td style="text-align: center; vertical-align: middle;"> <a
href="Hotto_LM_sysin.jpg"><img alt="System inputs"
title="Click to enlarge"
src="Hotto_LM_sysin-thumb.jpg" style="border: 2px
solid ; width: 185px; height: 160px;" width="185"
height="160"></a><br>
<span style="font-style: italic;">Inputs from system</span><br>
</td>
<td style="text-align: center; vertical-align: middle;"> <a
href="Hotto_LM_crewin.jpg"><img alt="Crew inputs"
title="Click to enlarge"
src="Hotto_LM_crewin-thumb.jpg" style="border: 2px
solid ; width: 295px; height: 195px;" width="295"
height="195"></a><br>
<span style="font-style: italic;">Inputs from crew</span><br>
</td>
</tr>
<tr>
<td rowspan="1" style="text-align: center;
vertical-align: middle;"><a href="Hotto_LM_out.jpg"><img
alt="Outputs" title="Click to enlarge"
src="Hotto_LM_out-thumb.jpg" style="border: 2px solid
; width: 315px; height: 215px;" width="315"
height="215"></a><br>
<span style="font-style: italic;">Outputs</span></td>
<td style="text-align: center; vertical-align: middle;"> <a
href="Hotto_LM_imu.jpg"><img alt="IMU stuff"
title="Click to enlarge" src="Hotto_LM_imu-thumb.jpg"
style="border: 2px solid ; width: 225px; height:
233px;" width="225" height="233"></a><br>
<span style="font-style: italic;">IMU</span><br>
</td>
<td style="text-align: center; vertical-align: middle;"> <a
href="Hotto_LM_propulsion.jpg"><img
alt="Propulsion-system status screenshot"
src="Hotto_LM_propulsion-thumb.jpg" style="border: 2px
solid ; width: 135px; height: 190px;" width="135"
height="190"></a><br>
<span style="font-style: italic;">Propulsion-system status<br>
</span></td>
</tr>
<tr>
<td style="vertical-align: top;"><br>
</td>
<td style="vertical-align: top;">
<div style="text-align: center;"> <a
href="yaDSKYandLITE.png"><img alt="DSKY LITE and
yaDSKY side-by-side" title="Click to enlarge"
src="thumb-yaDSKYandLITE.jpg" style="border: 0px
solid ; width: 267px; height: 200px;" width="267"
height="200"></a> </div>
<div style="text-align: center;"> <span
style="font-style: italic;"><span style="font-weight:
bold;">DSKY Lite</span> with <span
style="font-weight: bold;">yaDSKY</span></span><br>
</div>
</td>
<td style="vertical-align: top;"><br>
</td>
</tr>
</tbody>
</table>
<br>
</div>
The program has a configuration file called "lm_simulator.ini" which
can be used to configure some aspects of <span style="font-weight:
bold;">LM-Simulator</span>'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 <span
style="font-weight: bold;">yaAGC</span>, and determines which of <span
style="font-weight: bold;">LM-Simulator</span>'s windows to
automatically open at startup.<br>
<br>
As of 2005-06-19, the usage of <span style="font-weight: bold;">LM-Simulator</span>
is as follows:<br>
<br>
<div style="margin-left: 40px;"> <span style="font-family:
monospace;">cd <span style="font-style: italic;">InstallationDirectory</span></span><br
style="font-family: monospace;">
<span style="font-family: monospace;">lm_simulator [OPTIONS]</span><br>
</div>
<br>
The currently-recognized command-line options are:<br>
<br>
--port=<span style="font-style: italic;">PortNum</span><br>
<div style="margin-left: 40px;"> Changes the port number (by
default, 19801) used to connect to <span style="font-weight:
bold;">yaAGC</span>. This can also be changed in the
configuration file.<br>
</div>
<br>
--cfg=<span style="font-style: italic;">IniFilename</span><br>
<div style="margin-left: 40px;"> 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.<br>
</div>
<br>
If you discover problems with <span style="font-weight: bold;">LM-Simulator</span>,
or want to cooperate on it, you'll probably want to contact Stephan
directly. (His contact info is in the source code.) <br>
<br>
<hr style="width: 100%; height: 2px;">
<h2><a name="Game_Pack_by_John_Pultorak"
id="Game_Pack_by_John_Pultorak"></a>Game Pack, by John Pultorak<br>
</h2>
John Pultorak, of <a href="Pultorak.html">Block 1 AGC
hardware-simulator</a> fame, has provided a <span
style="font-weight: bold;">Game Pack</span> containing a 1- or
2-player tic-tac-toe game and a Simon game. This is in the
source tree under Contributed/GamePack/. Unfortunately, it
does not yet run on <span style="font-weight: bold;">VirtualAGC</span>
for a couple of reasons. If anybody cares to fix it up, I'd be
ever so grateful.<br>
<ol>
<li>It is written in the syntax of John's assembler rather than <span
style="font-weight: bold;">yaYUL</span>, so it cannot be
assembled; and</li>
<li>It depends on the presence of <span style="font-weight:
bold;">Colossus</span> rather than being a standalone program,
but there is no room left in <span style="font-weight: bold;">Colossus</span>
in which to fit it.<br>
</li>
</ol>
The reason it depends on <span style="font-weight: bold;">Colossus</span>
is for such stuff as accessing the DSKY, which it could do by
directly accessing the DSKY through i/o channels.<br>
<br>
<hr style="width: 100%; height: 2px;">
<h2><a name="yaUniverse" id="yaUniverse"></a>yaUniverse</h2>
<p><font color="#999999"><font color="#000000"><i>Note that while
the program described in this section does exist, and does
do some of the things talked about, it has never reached a
useful level of functionality, and is unlikely to ever do so
now that satisfactory integrations of </i><i><b>yaAGC</b></i><i>
into spacecraft simulator programs exist without it.</i></font><br>
</font></p>
<font color="#999999"><span style="font-weight: bold;">yaUniverse</span>
is 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, <span style="font-weight: bold;">yaUniverse</span>
is able to calculate the position and orientation of the
spacecraft
and heavenly bodies at all times relevant to the mission. At
present, the program exists and accounts for gravitational
influences, but is not integrated with other Virtual AGC software
such as the (currently non-existent) <span style="font-weight:
bold;">yaIMU</span> program that would be the principal consumer
of the data.<br>
<br>
Eventually, all of the forces acting on the spacecraft might be
accounted for, such as:<br>
</font>
<ul>
<li><font color="#999999">(Required) Gravitation from the
Earth, Moon, Sun, etc.</font></li>
<li><font color="#999999">(Required) Thrust applied by the
spacecraft
itself. (It should be noted that thrust expends fuel,
and
thus reduces the mass and the changes the inertia tensor—i.e.,
the rotational characteristics—of the spacecraft.)<br>
</font></li>
<li><font color="#999999">(Optional) Atmospheric drag for
launch or reentry.</font></li>
<li><font color="#999999">... and any other forces we might like
to imagine (such as
outgassing from an exploding Apollo 13 oxygen tank).</font></li>
</ul>
<font color="#999999">
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 <span style="font-style: italic;">initial</span>
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<br>
</font>
<div style="margin-left: 40px;">
<pre><font color="#999999">telnet ssd.jpl.nasa.gov 6775</font></pre>
</div>
<font color="#999999">
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.<br>
<br>
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. <span
style="font-weight:
bold;">yaUniverse</span> provides the data for this to <span
style="font-weight: bold;">yaAOT</span>, and thus must be able
to
simultaneously track the CSM and the LM.<br>
<br>
Like <span style="font-weight: bold;">yaAGC</span>, <span
style="font-weight: bold;">yaUniverse</span> would be a server
from which <span style="font-weight: bold;">yaIMU</span> and <span
style="font-weight: bold;">yaAOT</span> obtain data. A TCP
socket interface is used for this, though the data protocol is
presently TBD.<br>
<br>
<span style="font-weight: bold;">yaUniverse</span> 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.<br>
<br>
The barest beginning of <span style="font-weight: bold;">yaUniverse</span>
exists. It is presently capable only of numerically
integrating the positions of the heavenly bodies and spacecraft,
but
not of communicating this information to <span
style="font-weight:
bold;">yaAGC</span>.<br>
<br>
The syntax is:<br>
</font>
<div style="margin-left: 40px;"> <font color="#999999"><span
style="font-family:
monospace;">yaUniverse [OPTIONS]</span><br>
</font></div>
<font color="#999999"><br>
The recognized options are:<br>
<br>
<span style="font-family: monospace;">--help</span><br>
</font>
<div style="margin-left: 40px;"><font color="#999999"> Displays
textual info similar to
that shown here.<br>
</font></div>
<font color="#999999"><br>
<span style="font-family: monospace;">--mission=<span
style="font-style: italic;">Name</span></span><br>
</font>
<div style="margin-left: 40px;"><font color="#999999"> 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 <span
style="font-weight: bold;">yaUniverse</span>'s ability to
perform numerical integrations of planetary positions.<br>
</font></div>
<font color="#999999"><br>
<span style="font-family: monospace;">--ephem-read<br>
</span></font>
<div style="margin-left: 40px;"><font color="#999999"> Causes <span
style="font-weight:
bold;">yaUniverse</span> 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.<br>
</font></div>
<font color="#999999"><br>
<span style="font-family: monospace;">--ephem-int<br>
</span></font>
<div style="margin-left: 40px;"><font color="#999999"> Causes <span
style="font-weight:
bold;">yaUniverse</span> 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).<br>
<br>
</font></div>
<font color="#999999"><span style="font-family: monospace;">--runge-kutta=<span
style="font-style: italic;">N</span></span> <br>
</font>
<div style="margin-left: 40px;"><font color="#999999"> The order of
the Runge-Kutta
numerical integration. <span style="font-style: italic;
font-family: monospace;">N</span>=2 or 4 (default is 4).<br>
<br>
</font></div>
<font color="#999999"><span style="font-family: monospace;">--planets=<span
style="font-style: italic;">N</span></span> <br>
</font>
<div style="margin-left: 40px;"><font color="#999999"> The number of
planetary bodies used
in the numerical integration. <span style="font-family:
monospace; font-style: italic;">N</span>=3-15, and is 7 by
default:<br>
</font>
<div style="margin-left: 40px;"> <font color="#999999"><span
style="font-family:
monospace; font-style: italic;">N</span>=3
Earth,
Moon, and Sun.<br>
<span style="font-family: monospace; font-style: italic;">N</span>=4
Same
as <span style="font-family: monospace; font-style:
italic;">N</span>=3, plus Jupiter.<br>
<span style="font-family: monospace; font-style: italic;">N</span>=5
Same
as <span style="font-family: monospace; font-style:
italic;">N</span>=4, plus Saturn.<br>
<span style="font-family: monospace; font-style: italic;">N</span>=6
Same
as <span style="font-family: monospace; font-style:
italic;">N</span>=5, plus Venus.<br>
<span style="font-family: monospace; font-style: italic;">N</span>=7
Same
as <span style="font-family: monospace; font-style:
italic;">N</span>=6, plus Mars.<br>
<span style="font-family: monospace; font-style: italic;">N</span>=11
Same
as <span style="font-family: monospace; font-style:
italic;">N</span>=7, plus Ganymede, Io, Europa, &
Callisto.<br>
<span style="font-family: monospace; font-style: italic;">N</span>=15
Same
as <span style="font-family: monospace; font-style:
italic;">N</span>=11, plus Titan, Tethys, Rhea, & Dione.<br>
</font></div>
<font color="#999999">
The addition of Titan <span style="font-style: italic;">et al</span>.
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. <span style="font-weight: bold;">Note:</span>
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.<br>
</font></div>
<font color="#999999"><br>
<span style="font-family: monospace;">--timestep=<span
style="font-style: italic;">T</span> </span> <br>
</font>
<div style="margin-left: 40px;"><font color="#999999"> 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.</font><br>
</div>
<br>
<small><small><small><font size="+3"><small><small></small></small></font></small></small></small>
<hr style="width: 100%; height: 2px;">
<h2><a name="yaACA" id="yaACA"></a>yaACA, yaACA2, and yaACA3</h2>
The Attitude Controller Assembly (ACA)—also known as the rotational
hand-controller (RHC)—is used by astronaut to affect the pitch,
roll, and yaw of the LM. José Portillo has described the
interaction between the ACA and AGC in great detail in a paper (<a
href="http://www.klabs.org/mapld04/papers/g/g202_portillo_p.pdf">klabs.org/mapld04/papers/g/g202_portillo_p.pdf</a>)
which is the basis of all ACA-related work in Virtual AGC.
Refer to the <a href="developer.html#Fictitious_IO_Channels">developer
page</a> and to the <a
href="assembly_language_manual.html#CPU_Architecture_Registers">assembly-language
manual</a> if you're interested in knowing more about the
integration between the ACA simulation and <span
style="font-weight: bold;">yaAGC</span>. Note that <span
style="font-weight: bold;">yaAGC</span> retransmits any
input-channel data received from the ACA simulation, so other
onboard devices (such as <span style="font-weight: bold;">yaAGS</span>)
wishing to receive RHC data automatically receive this data even
though not connected to the ACA simulation.<br>
<br>
In Virtual AGC, the ACA is simulated by one of three essentially
equivalent programs called (surprise!) <span style="font-weight:
bold;">yaACA</span>, <span style="font-weight: bold;">yaACA2</span>,
and <span style="font-weight: bold;">yaACA3</span>. Since you
are unlikely have an <span style="font-style: italic;">actual</span>
ACA unless you're very, very lucky indeed, the simulated ACA instead
uses a 3D joystick like that used for many computer games. The
ACA simulation interacts with the joystick and sends the simulated
AGC CPU information related to the displacement of the joystick from
its neutral position.<br>
<br>
Why three separate programs? Well, it has turned out to be
much more difficult (for me, anyway!) to write a joystick program
that I can be confident works on all supported platforms than it has
been to make sure that the remainder of Virtual AGC is portable
across platforms. Therefore, as time went on, I found the need
to experiment and to create several such programs.
Technically, the three programs differ in using different underlying
libraries (not written by me) to access the joystick, but what's
important to you as a user is that if one of the <span
style="font-weight: bold;">yaACA<span style="font-style: italic;">x</span></span>
programs doesn't work for your operating system or joystick, another
might. So I pass all of them along to you and let you choose.<br>
<br>
At the present time, <span style="font-weight: bold;">yaACA3</span>
is regarded as the default and best of the programs, since it
appears to work on all supported platforms. <span
style="font-weight: bold;">yaACA2</span> presently does not work
on Mac OS X and <span style="font-weight: bold;">yaACA</span>
presently does not work properly on Windows. Neither <span
style="font-weight: bold;">yaACA</span> nor <span
style="font-weight: bold;">yaACA2</span> works on FreeBSD, or at
least I haven't jumped through whatever hoops might be needed to
make them work.<br>
<br>
As far as joystick selection is concerned, I use a Logitech Extreme
3D Pro, and all configuration defaults have been tailored for that
model. In theory, any twist-handle joystick should be usable,
though possibly with some reconfiguration. Only the most basic
3D joystick is needed, since only 3 degrees of freedom (roll, pitch,
and yaw) are used, and no buttons are used.<br>
<br>
Selection between <span style="font-weight: bold;">yaACA</span>, <span
style="font-weight: bold;">yaACA2</span>, and <span
style="font-weight: bold;">yaACA3</span> and reconfiguration
related to different joystick models <span style="font-style:
italic;">can</span> be done from a command-line, but to me that
seems to be making a difficult chore even more difficult than it
needs to be. So I've provided a GUI front-end (<span
style="font-weight: bold;">jWiz</span>) for this chore, as
described in the next section.
<h3><a name="Joystick_configuration_for_use_with_the"
id="Joystick_configuration_for_use_with_the"></a>jWiz, the GUI
front-end for joystick configuration<br>
</h3>
As mentioned above, three separate joystick-handler programs are
provided, and we <span style="font-style: italic;">hope</span> that
by default the best one of them is automatically used by <span
style="font-weight: bold;">VirtualAGC</span> and that the default
joystick settings of that joystick-handler program are
correct. But what if they're not? Then you have to do a
little work to correct the joystick settings. On the <span
style="font-weight: bold;">VirtualAGC</span> main screen, you may
have noticed an unexplained button labeled "Handler":<br>
<br>
<div style="text-align: center;"> <img style="width: 344px; height:
219px;" alt="" src="Screenshot-handler-detail.jpg" width="344"
height="219"><br>
<br>
<div style="text-align: left;"> In the screenshot above, this
button is disabled because the "Attitude Controller Assembly"
checkbox is empty. If it was checked, then the button
would be enabled, and if you clicked the button a screen like
this would appear:<br>
<br>
<div style="text-align: center;"> <img style="width: 1017px;
height: 537px;" alt="" src="Screenshot-jWiz.jpg"
width="1017" height="537"><br>
</div>
</div>
</div>
<br>
This is the main screen for a program <span style="font-weight:
bold;">jWiz</span>, which helps guide you through the joystick
reconfiguration process. At "Step #1", "Step #2", and "Step
#3" you can configure one of the three joystick handlers. You
only need to configure one of them, since only one of them can be
used by the simulation at any given time. Step #1 is the
preferred handler, and if it doesn't work for you then you can
proceed to the next-best handler at Step #2, and if that doesn't
work for you then you can proceed to the fallback handler at Step
#3. Not all of these steps will necessarily be available to
you, since some of the handlers don't work on some operating
systems, and therefore may be grayed out and disabled.<br>
<br>
The big red checkmark on "Step #1" indicates that the primary
joystick-handler is currently set and will be used by <span
style="font-weight: bold;">VirtualAGC</span>. If you change
the setup, then the checkmark moves to a different handler.<br>
<br>
Wherever there is a "Default" button, you can use it to restore the
settings for that handler to their original defaults. Wherever
there is a "Test/Set" button, it allows you to both test the
joystick configuration for that handler and (at the same time) set
it for use by <span style="font-weight: bold;">VirtualAGC</span>.
Where
there are separate "Test" and "Set" buttons, it means that the
settings for that handler can be tested without selecting that
handler for use by <span style="font-weight: bold;">VirtualAGC</span>,
and that you have to click the "Set" button as an extra step after
testing.<br>
<br>
When you click one of the "Test" or "Test/Set" buttons, one of the
following windows will open up:<br>
<br>
<table summary="" style="text-align: left; width: 100%;"
cellspacing="2" cellpadding="2" border="0">
<tbody>
<tr>
<td style="text-align: center;"><img style="width: 484px;
height: 316px;" alt="" src="Screenshot-yaACA3.jpg"
width="484" height="316"><br>
<span style="font-style: italic;">Step #1: Configuring</span><span
style="font-weight: bold; font-style: italic;">yaACA3</span><br>
</td>
<td style="text-align: center;"><img style="border: 1px solid
; width: 349px; height: 688px;" alt=""
src="Screenshot-yaACA2.jpg" width="349" height="688"><br>
<span style="font-style: italic;">Step #1: Configuring</span><span
style="font-weight: bold; font-style: italic;">yaACA2</span></td>
<td style="text-align: center;"><img style="width: 460px;
height: 524px;" alt="" src="Screenshot-yaACA.jpg"
width="460" height="524"><br>
<span style="font-style: italic;">Step #1: Configuring</span><span
style="font-weight: bold; font-style: italic;">yaACA</span></td>
</tr>
</tbody>
</table>
<br>
You'll notice, I'm sure, that <span style="font-weight: bold;">yaACA2</span>,
which had no adjustable parameters on the main <span
style="font-weight: bold;">jWiz</span> screen, has adustable
parameters as well as "Default" and "Set" buttons, so all three
handlers have effectively the same kinds of adjustments. One
difference is that <span style="font-weight: bold;">yaACA3</span>
and <span style="font-weight: bold;">yaACA2</span> have only two
adjustable parameters ("Axis number"/"Axis" and "Polarity"/"Sense")
while <span style="font-weight: bold;">yaACA</span> has four
adjustable parameters ("Stick", "Axis", "Scale", and
"Offset"). Thus, <span style="font-weight: bold;">yaACA</span>
is harder to configure than the others, which is part of the reason
the others are preferred.<br>
<br>
But the three handlers are all similar in that they display the
current pitch, roll, and yaw readings. The aim is to find an
appropriate combination of settings so that:<br>
<ul>
<li>Maximum left roll is -57.</li>
<li>Maximum right roll is +57.</li>
<li>Maximum downward pitch is -57.</li>
<li>Maximum upward pitch is +57.</li>
<li>Maximum right yaw is -57.</li>
<li>Maximum left yaw is +57.</li>
</ul>
You can experiment with the settings directly in <span
style="font-weight: bold;">yaACA2</span> (by hitting the "Set"
button for every combination of settings you want to test), but in <span
style="font-weight: bold;">yaACA3</span> or <span
style="font-weight: bold;">yaACA</span> you need to exit and
return to <span style="font-weight: bold;">jWiz</span> every time
you want to change the settings. In Mac OS X, by the
way, these screens are shown to you inside of a program called <span
style="font-weight: bold;">Terminator</span>, and you need to exit
<span style="font-weight: bold;">Terminator</span> from its main
menu.<br>
<br>
For most joysticks, you should find that the pitch and roll settings
are correct, or very nearly so, but that there is less certainty
about the yaw settings. Therefore, I'll discuss only how to
change the yaw settings; for the pitch and roll settings, the
principles are identical. Here is the procedure I'd recommend:<br>
<ol>
<li>If there is no movement of the joystick that can cause the yaw
value to change, then it probably means the wrong axis is
set. In <span style="font-weight: bold;">yaACA3</span>
and <span style="font-weight: bold;">yaACA2</span>, the
joystick has a collection of axes, identified as 0, 1, 2,
.... The numbering is a little different in <span
style="font-weight: bold;">yaACA</span>, where the joystick
has a collection of "sticks" 0, 1, 2, ..., each one of which has
two "axes" 0 and 1. For example, if you look at the <span
style="font-weight: bold;">yaACAx</span> screenshots above,
you'll see that my Logitech Extreme 3D Pro has either 6 axes or
else 3 sticks of two axes each. Nevertheless, the
principle is the same. Any given axis (or stick/axis)
provides only a single reading—in other words, if it was used
for roll or pitch, it wouldn't provide a yaw reading—so step
through the unused axes (or stick/axis pairs) until you find the
one whose readings change with yaw. If there is no such
setting, try a different joystick handler.</li>
<li>If the sense of an axis is wrong—i.e., if the yaw increases
where it should decrease and vice versa—then the "Polarity" or
"Sense" of <span style="font-weight: bold;">yaACA3</span> or <span
style="font-weight: bold;">yaACA2</span> is wrong, or the
algebraic sign of the "Scale" is wrong for <span
style="font-weight: bold;">yaACA</span>. Change plus to
minus or minus to plus.</li>
<li>If the readings are not symmetric about zero—e.g., if the
readings were 0 to 255 rather than -128 to +127—then the
"Offset" in <span style="font-weight: bold;">yaACA</span> is
wrong. Change the Offset to equal the center of the range
you are observing. (This problem cannot occur in <span
style="font-weight: bold;">yaACA3</span> or <span
style="font-weight: bold;">yaACA2</span>, so there is no
adjustment needed for them.)</li>
<li>If the size of the range is wrong—e.g., if the reading varies
from -128 to 127 rather than from -57 to +57—then the "Scale" in
<span style="font-weight: bold;">yaACA</span> is wrong.
The Scale is a multiplier in units of 0.01, so a Scale of 100
has no effect, a Scale less than 100 (in magnitude) decreases
the size of the range, and a Scale greater than 100 increases
the size of the range. (Again, this problem cannot occur
in <span style="font-weight: bold;">yaACA3</span> or <span
style="font-weight: bold;">yaACA2</span>, so there is no
adjustment needed for them.)</li>
</ol>
<span style="color: rgb(0, 0, 0);">Once you're all done configuring
within <span style="font-weight: bold;">jWiz</span>, a partial
double-check can be made by running the simulation itself after
doing this configuration. One of the items in the LM
telemetry display is the current octal value of input channel 31,
part of which indicates the direction (but not the magnitude) of
displacement of the ACA from its detent. The last two octal
digits are:<br>
</span>
<ul>
<li>75 for pitch down</li>
<li>76 for pitch up</li>
<li>37 for roll left</li>
<li>57 for roll right</li>
<li>73 for yaw left</li>
<li>67 for yaw right</li>
</ul>
So you should be able to move the joystick and see the downlink
telemetry change accordingly, keeping in mind of course that the
telemetry downlink occurs at several-second intervals and so the
telemetry display can't respond instantly to joystick movements.<br>
<h3><a name="How_the_selection_and_configuration"
id="How_the_selection_and_configuration"></a>How the selection
and configuration process works<br>
</h3>
If you wish to bypass <span style="font-weight: bold;">jWiz</span>
for some reason, and to configure joysticks from the command line,
it's certainly possible to do so. The principle involved is
that each of the three programs <span style="font-weight: bold;">yaACA</span>,
<span style="font-weight: bold;">yaACA2</span>, and <span
style="font-weight: bold;">yaACA3</span> store their configuration
parameters in files (respectively, yaACA-0.cfg, yaACA2-0.cfg, and
yaACA3-0.cfg). These configuration parameters are selected by
the <span style="font-weight: bold;">yaACA2</span> GUI or from the
command-line for <span style="font-weight: bold;">yaACA</span>/<span
style="font-weight: bold;">yaACA3</span>, but once safely stored
in the configuration files the command-line parameters are no longer
needed. (The details of the command-line parameters are
described in the following 3 sections.) What VirtualAGC does
is simply to choose which <span style="font-weight: bold;">yaACA<span
style="font-style: italic;">x</span></span> program is needed on
the basis of what configuration files it finds:<br>
<ul>
<li>If yaACA2-0.cfg exists, then <span style="font-weight: bold;">yaACA2</span>
is used; otherwise,</li>
<li>If yaACA-0.cfg exists, then <span style="font-weight: bold;">yaACA</span>
is used; otherwise,</li>
<li><span style="font-weight: bold;">yaACA3</span> is used,
whether or not yaACA3-0.cfg exists. (If yaACA3-0.cfg
doesn't exist, then <span style="font-weight: bold;">yaACA3</span>
uses its own built-in configuration defaults.)<br>
</li>
</ul>
Creating the configuration files is a matter of running the
appropriate <span style="font-weight: bold;">yaACAx</span> program
with the desired command-line switches. Getting rid of
configuration files is a simple matter of deletion. However,
actually running the appropriate <span style="font-weight: bold;">yaACAx</span>
program isn't always so simple because you have to be in the proper
working directory, and have to supply the proper path for the
program, as follows:<br>
<ol>
<li>From a command line, 'cd' to <span style="font-weight: bold;">VirtualAGC</span>'s
working
directory. This happens to be the directory in
which the configuration files mentioned above are stored.
If you have installed in the default locations, the command will
be:</li>
<ul>
<li><span style="font-style: italic;">In Linux or FreeBSD:</span>
<span style="font-family: monospace;">cd
~/VirtualAGC/Resources</span></li>
<li><span style="font-style: italic;">In Windows:</span> <span
style="font-family: monospace;">cd "\Program Files\Virtual
AGC\Resources"</span></li>
<li><span style="font-style: italic;">In Mac OS X: </span><span
style="font-family: monospace;">cd
~/Desktop/VirtualAGC.app/Contents/Resources</span></li>
</ul>
<li>Attach your 3D joystick.</li>
<li>Run <span style="font-weight: bold;">yaACA</span>, <span
style="font-weight: bold;">yaACA2</span>, and <span
style="font-weight: bold;">yaACA3</span> with your chosen
command-line options. The only relevant options are
--pitch, --roll, and --yaw, as described below <a
href="#Usage_of_yaACA2">for <span style="font-weight: bold;">yaACA</span></a>
or <a href="#Usage_of_yaACA3">for <span style="font-weight:
bold;">yaACA3</span></a>. <span style="font-weight:
bold;">yaACA2</span> needs no switches, since you select the
options from its own built-in GUI. The appropriate command
lines will be:</li>
<ul>
<li><span style="font-style: italic;">In Linux:</span><br>
</li>
<ul>
<li><span style="font-family: monospace;">../bin/yaACA
--pitch=... --roll=... --yaw=...</span></li>
<li><span style="font-family: monospace;">../bin/yaACA2<br>
</span></li>
<li><span style="font-family: monospace;">../bin/yaACA3</span><span
style="font-family: monospace;">--pitch=... --roll=...
--yaw=...</span></li>
</ul>
<li style="font-style: italic;">In FreeBSD:</li>
<ul>
<li><span style="font-weight: bold;">yaACA</span> will not
work.<br>
</li>
<li><span style="font-weight: bold;">yaACA2</span> will not
work.</li>
<li><span style="font-family: monospace;">../bin/yaACA3</span><span
style="font-family: monospace;">--pitch=... --roll=...
--yaw=...</span></li>
</ul>
<li><span style="font-style: italic;">In Windows:</span></li>
<ul>
<li><span style="font-weight: bold;">yaACA</span> will pretend
to work here, but don't try it since it won't actually work
with the simulation.</li>
<li><span style="font-family: monospace;">..\bin\aACA2</span><br>
</li>
<li><span style="font-family: monospace;">..\bin\yaACA3</span><span
style="font-family: monospace;">--pitch=... --roll=...
--yaw=...</span></li>
</ul>
<li><span style="font-style: italic;">In Mac OS X:<br>
</span></li>
<ul>
<li><span style="font-family: monospace;">../MacOS/yaACA</span><span
style="font-family: monospace;">--pitch=... --roll=...
--yaw=...</span></li>
<li><span style="font-weight: bold;">yaACA2</span> will not
work.<br>
</li>
<li><span style="font-family: monospace;">../MacOS/yaACA3</span><span
style="font-family: monospace;">--pitch=... --roll=...
--yaw=...</span></li>
</ul>
</ul>
<li>Experiment with the pitch, roll, and yaw switches. (Note
that to <span style="font-style: italic;">change</span> the
switches in <span style="font-weight: bold;">yaACA</span> or <span
style="font-weight: bold;">yaACA3</span>, you need to exit the
program and re-run it. To exit, hit the Ctrl-C key on your
keyboard. On Mac OS X, you will also need to close the <span
style="font-weight: bold;">Terminator</span> program from its
menu.) You need to try different combinations until you
see the following readings printed out when moving the joystick:</li>
</ol>
<ul>
<ul>
<li>Maximum left roll is -57.</li>
<li>Maximum right roll is +57.</li>
<li>Maximum downward pitch is -57.</li>
<li>Maximum upward pitch is +57.</li>
<li>Maximum right yaw is -57.</li>
<li>Maximum left yaw is +57.</li>
</ul>
</ul>
<span style="color: rgb(0, 0, 0);">Note that <span
style="font-weight: bold;">yaACA2</span> and <span
style="font-weight: bold;">yaACA3</span> display joystick
readings as translated to the range acceptable to</span> <span
style="color: rgb(0, 0, 0);">the AGC (namely, -57-+57).</span><span
style="color: rgb(0, 0, 0);"> <span style="font-weight:
bold;">yaACA</span> differs in that it shows <span
style="font-style: italic;">both</span> the raw readings
obtained from the joystick (usually 0-255 or else -128-+128) <span
style="font-style: italic;">and</span> the translated
readings. The latter will appear in parentheses following
the former, and are the ones which you need to check. <br>
<br>
A partial double-check can be made by running the simulation
itself after doing this configuration. One of the items in
the LM telemetry display is the current octal value of input
channel 31, part of which indicates the direction (but not the
magnitude) of displacement of the ACA from its detent. The
last two octal digits are:<br>
</span>
<ul>
<li>75 for pitch down</li>
<li>76 for pitch up</li>
<li>37 for roll left</li>
<li>57 for roll right</li>
<li>73 for yaw left</li>
<li>67 for yaw right</li>
</ul>
Finally, note that (in theory) multiple joystick controllers could
be attached to the computer, and that each of the <span
style="font-weight: bold;">yaACAx</span> programs allows access to
these different joystick controllers. The configuration files
are separate for the different joystick controllers so that (for
example) if joystick controller 1 was used, then the configuration
files would have a name like yaACA3-1.cfg rather than
yaACA3-0.cfg. However, <span style="font-weight: bold;">VirtualAGC</span>
make no such provision: it always assumes that joystick
controller 0 is used. Therefore, to use a different controller
you will have to bypass <span style="font-weight: bold;">VirtualAGC</span>
and use your own startup procedure for the simulation.<br>
<h3><a name="Usage_of_yaACA3" id="Usage_of_yaACA3"></a>Command-line
usage of yaACA3</h3>
The syntax is:<br>
<div style="text-align: left; margin-left: 40px;"> <span
style="font-family: monospace;">yaACA3 [OPTIONS]</span><br>
</div>
<br>
The recognized options are:<br>
<br>
<span style="font-family: monospace;">--help</span><br>
<div style="margin-left: 40px;"> Displays textual info similar to
that shown here.<br>
<br>
</div>
<span style="font-family: monospace;">--roll=<span
style="font-style: italic;">N</span></span><br
style="font-family: monospace;">
<span style="font-family: monospace;">--pitch=<span
style="font-style: italic;">N</span></span><br
style="font-family: monospace;">
<span style="font-family: monospace;">--yaw=<span style="font-style:
italic;">N</span></span><br>
<div style="margin-left: 40px;"> These options allow you to
configure how the roll/pitch/yaw degrees of freedom map to the
"axes" of the joystick as recognized by the computer's operating
system. In general, the operating system views a 3D joystick
as possessing a certain number of axes, identified as axis 0, axis
1, etc. I deduce from my readings that axis 0 will almost
always correspond to roll and axis 1 will almost always correspond
to pitch. However, the axis used for yaw is likely to
vary. For example, I have seen cases where it is 2 and cases
where it is 3. I have chosen defaults based strictly on my
own convenience (i.e., for my Logitech Extreme 3D pro joystick),
and I have no theoretical basis for assuming that they'll work for
you. In addition to choosing which axis belongs to which
degree of freedom, these command-line switches also allow you to
choose the <span style="font-style: italic;">sense</span>.
For example, you may indeed find that axis 1 corresponds to pitch,
but that it pitches up where you expect it to pitch down, and
vice-versa. In this case, simply put a minus sign before the
number, as in "--pitch=-1". (And if you have to do this for
axis 0, don't worry: "--roll=-0" treated differently than
"--roll=0"!)<br>
</div>
<br>
<span style="font-family: monospace;">--ip=<span style="font-style:
italic;">Hostname</span></span><br>
<div style="margin-left: 40px;"> The <span style="font-weight:
bold;">yaACA3</span> program and the <span style="font-weight:
bold;">yaAGC</span> Apollo Guidance Computer simulation exist in
a "client/server" relationship, in which the <span
style="font-weight: bold;">yaACA3</span> program needs to be
aware of the IP address or symbolic name of the host computer
running the <span style="font-weight: bold;">yaAGC</span>
program. By default, this is "localhost", meaning that both
<span style="font-weight: bold;">yaACA3</span> and <span
style="font-weight: bold;">yaAGC</span> are running on the same
computer.<br>
</div>
<br>
<span style="font-family: monospace;">--port=<span
style="font-style: italic;">Portnumber</span></span><br>
<div style="margin-left: 40px;"> By default, <span
style="font-weight: bold;">yaACA3</span> attempts to connect to
the <span style="font-weight: bold;">yaAGC</span> program using
port number 19803. However, if more than one instance of <span
style="font-weight: bold;">yaACA</span>3 is being run, or if <span
style="font-weight: bold;">yaAGC</span> has been configured to
listen on different ports, then different port settings for <span
style="font-weight: bold;">yaACA3</span> are needed. Note
that by default, <span style="font-weight: bold;">yaAGC</span>
listens for new connections on ports 19697-19706, but that the
recommended port range when using <span style="font-weight:
bold;">yaAGC</span> in the LM is 19797-19806.<br>
</div>
<br>
<span style="font-family: monospace;">--delay=</span><span
style="font-style: italic; font-family: monospace;">Milliseconds</span><br>
<div style="margin-left: 40px;"> Adds a delay at start-up, so that <span
style="font-weight: bold;">yaACA</span> does not immediately
begin attempting to communicate with <span style="font-weight:
bold;">yaAGC</span>. The current defaults are 0 ms. in
Linux/Mac OS X and 500 ms. in Win32. This "feature" has been
added as a temporary work-around for <a href="buglist.html">problem
report</a> #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.<br>
<br>
</div>
<span style="font-family: monospace;">--controller=<span
style="font-style: italic;">N</span></span><br>
<div style="margin-left: 40px;"> In case more than one joystick
controller is attached to the PC/Mac, this allows selection of
just one of them. The default is <span style="font-style:
italic;">N</span>=0.<br>
</div>
<br>
<h3><a name="Command-line_usage_of_yaACA2"
id="Command-line_usage_of_yaACA2"></a>Command-line usage of
yaACA2</h3>
The syntax is:<br>
<div style="text-align: left; margin-left: 40px;"> <span
style="font-family: monospace;">yaACA2 [OPTIONS]</span><br>
</div>
<br>
The recognized options are:<br>
<br>
<span style="font-family: monospace;">--help</span><br>
<div style="margin-left: 40px;"> Displays textual info similar to
that shown here.<br>
<br>
</div>
<span style="font-family: monospace;">--ip=<span style="font-style:
italic;">Hostname</span></span><br>
<div style="margin-left: 40px;"> The <span style="font-weight:
bold;">yaACA3</span> program and the <span style="font-weight:
bold;">yaAGC</span> Apollo Guidance Computer simulation exist in
a "client/server" relationship, in which the <span
style="font-weight: bold;">yaACA3</span> program needs to be
aware of the IP address or symbolic name of the host computer
running the <span style="font-weight: bold;">yaAGC</span>
program. By default, this is "localhost", meaning that both
<span style="font-weight: bold;">yaACA3</span> and <span
style="font-weight: bold;">yaAGC</span> are running on the same
computer.<br>
</div>
<br>
<span style="font-family: monospace;">--port=<span
style="font-style: italic;">Portnumber</span></span><br>
<div style="margin-left: 40px;"> By default, <span
style="font-weight: bold;">yaACA3</span> attempts to connect to
the <span style="font-weight: bold;">yaAGC</span> program using
port number 19803. However, if more than one instance of <span
style="font-weight: bold;">yaACA</span>3 is being run, or if <span
style="font-weight: bold;">yaAGC</span> has been configured to
listen on different ports, then different port settings for <span
style="font-weight: bold;">yaACA3</span> are needed. Note
that by default, <span style="font-weight: bold;">yaAGC</span>
listens for new connections on ports 19697-19706, but that the
recommended port range when using <span style="font-weight:
bold;">yaAGC</span> in the LM is 19797-19806.<br>
</div>
<br>
<span style="font-family: monospace;">--delay=</span><span
style="font-style: italic; font-family: monospace;">Milliseconds</span><br>
<div style="margin-left: 40px;"> Adds a delay at start-up, so that <span
style="font-weight: bold;">yaACA</span> does not immediately
begin attempting to communicate with <span style="font-weight:
bold;">yaAGC</span>. The current defaults are 0 ms. in
Linux/Mac OS X and 500 ms. in Win32. This "feature" has been
added as a temporary work-around for <a href="buglist.html">problem
report</a> #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.<br>
<br>
</div>
<span style="font-family: monospace;">--controller=<span
style="font-style: italic;">N</span></span><br>
<div style="margin-left: 40px;"> In case more than one joystick
controller is attached to the PC/Mac, this allows selection of
just one of them. The default is <span style="font-style:
italic;">N</span>=0. </div>
<br>
<h3 style="color: rgb(0, 0, 0);"><a name="Usage_of_yaACA2"
id="Usage_of_yaACA2"></a>Command-line usage of yaACA<br>
</h3>
<span style="color: rgb(0, 0, 0);">The syntax is:</span><br
style="color: rgb(0, 0, 0);">
<div style="text-align: left; margin-left: 40px; color: rgb(0, 0,
0);"> <span style="font-family: monospace;">yaACA [OPTIONS]</span><br>
</div>
<br style="color: rgb(0, 0, 0);">
<span style="color: rgb(0, 0, 0);">The recognized options are:</span><br
style="color: rgb(0, 0, 0);">
<br style="color: rgb(0, 0, 0);">
<span style="font-family: monospace; color: rgb(0, 0, 0);">--help</span><br
style="color: rgb(0, 0, 0);">
<div style="margin-left: 40px; color: rgb(0, 0, 0);"> Displays
textual info similar to that shown here.<br>
<br>
</div>
<span style="font-family: monospace; color: rgb(0, 0, 0);">--roll=<span
style="font-style: italic;">J,S,A,F,O</span></span><br
style="font-family: monospace; color: rgb(0, 0, 0);">
<span style="font-family: monospace; color: rgb(0, 0, 0);">--pitch=<span
style="font-style: italic;">J,S,A,F,O</span></span><br
style="font-family: monospace; color: rgb(0, 0, 0);">
<span style="font-family: monospace; color: rgb(0, 0, 0);">--yaw=<span
style="font-style: italic;">J,S,A,F,O</span></span><br
style="color: rgb(0, 0, 0);">
<div style="margin-left: 40px; color: rgb(0, 0, 0);"> 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. <span style="font-style:
italic; font-family: monospace;">J</span> is the joystick device
number (in case multiple joystick devices are installed), <span
style="font-style: italic; font-family: monospace;">S</span> is
the stick number within the joystick, and <span
style="font-style: italic; font-family: monospace;">A</span> is
the axis within the stick. <span style="font-style: italic;
font-family: monospace;">F</span> is a factor which the joystick
reading is multiplied by, and <span style="font-style: italic;
font-family: monospace;">O</span> 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:<br>
</div>
<div style="text-align: left; margin-left: 80px; color: rgb(0, 0,
0);"> Roll = 0, 0, 0, 1.0, 0<br>
Pitch = 0, 0, 1, 1.0, 0<br>
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)<br>
</div>
<div style="text-align: left; color: rgb(0, 0, 0);">
<div style="margin-left: 40px;"> These defaults are based strictly
on my own convenience (i.e., for my Logitech Extreme 3D pro),
and I have no theoretical basis for assuming that they're any
good generally. Incidentally, the explanation above would
seem to imply that you could theoretically use different
joystick controllers for different axes; you really can't.<br>
</div>
</div>
<br style="color: rgb(0, 0, 0);">
<span style="font-family: monospace; color: rgb(0, 0, 0);">--ip=<span
style="font-style: italic;">Hostname</span></span><br
style="color: rgb(0, 0, 0);">
<div style="margin-left: 40px; color: rgb(0, 0, 0);"> The <span
style="font-weight: bold;">yaACA</span> program and the <span
style="font-weight: bold;">yaAGC</span> Apollo Guidance Computer
simulation exist in a "client/server" relationship, in which the <span
style="font-weight: bold;">yaACA</span> program needs to be
aware of the IP address or symbolic name of the host computer
running the <span style="font-weight: bold;">yaAGC</span>
program. By default, this is "localhost", meaning that both
<span style="font-weight: bold;">yaACA</span> and <span
style="font-weight: bold;">yaAGC</span> are running on the same
computer.<br>
</div>
<br style="color: rgb(0, 0, 0);">
<span style="font-family: monospace; color: rgb(0, 0, 0);">--port=<span
style="font-style: italic;">Portnumber</span></span><br
style="color: rgb(0, 0, 0);">
<div style="margin-left: 40px; color: rgb(0, 0, 0);"> By default, <span
style="font-weight: bold;">yaACA</span> attempts to connect to
the <span style="font-weight: bold;">yaAGC</span> program using
port number 19803. However, if more than one instance of <span
style="font-weight: bold;">yaACA</span> is being run, or if <span
style="font-weight: bold;">yaAGC</span> has been configured to
listen on different ports, then different port settings for <span
style="font-weight: bold;">yaACA</span> are needed. Note
that by default, <span style="font-weight: bold;">yaAGC</span>
listens for new connections on ports 19697-19706, but that the
recommended port range when using <span style="font-weight:
bold;">yaAGC</span> in the LM is 19797-19806.<br>
</div>
<br style="color: rgb(0, 0, 0);">
<span style="font-family: monospace; color: rgb(0, 0, 0);">--delay=</span><span
style="font-style: italic; font-family: monospace; color: rgb(0,
0, 0);">Milliseconds</span><br style="color: rgb(0, 0, 0);">
<div style="margin-left: 40px;"> <span style="color: rgb(0, 0, 0);">Adds
a
delay at start-up, so that</span> <span style="font-weight:
bold; color: rgb(0, 0, 0);">yaACA</span> <span style="color:
rgb(0, 0, 0);">does not immediately begin attempting to
communicate with</span> <span style="font-weight: bold; color:
rgb(0, 0, 0);">yaAGC</span><span style="color: rgb(0, 0, 0);">.
The
current defaults are 0 ms. in Linux and 500 ms. in
Win32. This "feature" has been added as a temporary
work-around for</span> <a style="color: rgb(0, 0, 0);"
href="buglist.html">problem report</a> <span style="color:
rgb(0, 0, 0);">#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.</span><br>
</div>
<br>
<hr style="width: 100%; height: 2px;">
<h2><a name="yaTelemetry" id="yaTelemetry"></a>yaTelemetry<br>
</h2>
<h3><small><a href="LmTelemetry.jpg"><img
src="LmTelemetry-thumb.jpg" title="LM telemetry monitor --
click to expand." alt="LM telemetry monitor" style="border:
2px solid ; width: 240px; height: 160px;" width="240"
vspace="5" hspace="10" height="160" align="left"></a></small></h3>
In normal use the AGC periodically transmitted telemetry information
which was displayed on monitors in Mission Control. Naturally
the virtual <span style="font-weight: bold;">yaAGC</span>
periodically transmits telemetry data as well, using virtual radio
waves, and with appropriate software to simulate a ground-based
receiver it is possible to view this information. The
characteristics of the digital uplink and downlink can be explored
by reading section 2 of the <span style="font-style: italic;">Guidance
System
Operations Plan</span> (GSOP) for the <a
href="NARA-SW/R-567-sec2-rev8.pdf">LM</a> or the <a
href="NARA-SW/R-577-sec2-rev2.pdf">CM</a>. The data consists
of a conglomeration of many of the internal state variables used by
the AGC, and is capable of conveniently giving a much more detailed
picture of the state of the AGC and of the spacecraft than the AGC
can give to the astronauts.<br>
<br>
Prior to the creation of a dedicated <span style="font-weight:
bold;">yaTelemetry</span> program, I cobbled telemetry-viewing
capability onto the <span style="font-weight: bold;">yaDSKY</span>
program, even though it is completely unrelated functionality.
If <span style="font-weight: bold;">yaDSKY</span> is started with
the switches <a href="yaDSKY.html#TestUplink">"--test-downlink"
and/or "--test-uplink"</a>, then you can use it to view the
digital downlinks or to create uplink data, respectively.
Using <span style="font-weight: bold;">yaDSKY</span> in this way
has several drawbacks. One drawback is that some people like
to use an alternate DSKY simulation (such as the "DSKY Lite" built
into <a href="#LM_Simulator_by_Stephan_Hotto">Stephan Hotto's <span
style="font-weight: bold;">LM-Simulator</span></a> described
above), rather than to use <span style="font-weight: bold;">yaDSKY</span>,
and in those cases <span style="font-weight: bold;">yaDSKY</span>
isn't present. Another drawback is that to see the downlink
data, <span style="font-weight: bold;">yaDSKY</span> must be
started in a console of an appropriate size and on some platforms
(Windows, Mac OS X 10.4) this is either not possible, or else (Mac
OS X 10.5) not possible without running the X-window system.<br>
<br>
<span style="font-weight: bold;">yaTelemetry</span>, on the other
hand, is a dedicated program that does nothing other than to provide
a monitor for displaying telemetry information downlinked from the
AGC. <br>
<br>
The accompanying photo is actually not a photo of a mission-control
CRT; rather, it is a screen capture from the "Apollo 11" episode of
the great HBO mini-series <span style="font-style: italic;">From
the Earth to the Moon</span>. You can appreciate the care
that the creators of the show must have taken with this, since many
of the items on the screen clearly do relate to downlinked
data. If you enlarge the image by clicking on it, and squint
at the upper left-hand corner of the display, you'll note that it
refers to LM099; <span style="font-weight: bold;">Luminary</span>
version 099 was the AGC software build used for Apollo 11.
Nevertheless, however convincing the film-makers' art was, this
display does not seem to match any of the documented records we've
found of the appearance of the actual mission control CRT
displays. At present, what you get with <span
style="font-weight: bold;">yaTelemetry</span> (or <span
style="font-weight: bold;">yaDSKY</span>) is simply a list of all
variables and their values appearing in the downlinked data
stream. I hope to provide more accurate display formats in the
future.<br>
<br clear="all">
In addition to telemetry downlinks—i.e., reception by ground control
of data from the AGC—digital uplinks are also possible.
Uplinks were (and continue in the virtual system to be) handled by
the simple expedient of transmitting <a href="yaDSKY.html">DSKY</a>
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. At the present time, <span
style="font-weight: bold;">yaTelemetry</span> doesn't attempt to
duplicate this uplink capability, but <a
href="#Getting_the_Simulation_to_a_Known_State">VirtualAGC does
provide a handy mode for uplinking</a>. Also, the
"--test-uplink" switch for <span style="font-weight: bold;">yaDSKY</span>
causes keycodes to be transmitted to the AGC via the digital-uplink
data-stream rather than via the virtual wiring it normally uses, and
thus provides a proof-of-concept that the uplink is implemented
correctly. It would be interesting to know what kind of
equipment mission control used for this purpose. Perhaps they
used an actual DSKY.<br>
<br>
But enough about <span style="font-weight: bold;">yaDSKY</span>
already! As far as <span style="font-weight: bold;">yaTelemetry</span>
is concerned, the usage-syntax is:<br>
<br>
<div style="text-align: left; margin-left: 40px;"> <span
style="font-family: monospace;">yaTelemetry [OPTIONS]</span><br>
</div>
<br>
The recognized options are:<br>
<br>
<span style="font-family: monospace;">--help</span><br>
<div style="margin-left: 40px;"> Displays textual info similar to
that shown here.<br>
</div>
<br>
<span style="font-family: monospace;">--delay=<span
style="font-style: italic;">Milliseconds</span></span><br>
<div style="margin-left: 40px;"> Adds a delay at start-up, so that <span
style="font-weight: bold;">yaTelemetry</span> does not
immediately begin attempting to communicate with <span
style="font-weight: bold;">yaAGC</span>. The current
defaults are 500 ms. in Win32 and 0 ms. otherwise (Linux/Mac OS
X).<br>
</div>
<br>
<span style="font-family: monospace;">--ip=<span style="font-style:
italic;">Hostname</span></span><br>
<div style="margin-left: 40px;"> The <span style="font-weight:
bold;">yaTelemetry</span> program and the <span
style="font-weight: bold;">yaAGC</span> Apollo Guidance Computer
simulation exist in a "client/server" relationship, in which the <span
style="font-weight: bold;">yaTelemetry</span> program needs to
be aware of the IP address or symbolic name of the host computer
running the <span style="font-weight: bold;">yaAGC</span>
program. By default, this is "localhost", meaning that both
<span style="font-weight: bold;">yaTelemetry</span> and <span
style="font-weight: bold;">yaAGC</span> are running on the same
computer.<br>
</div>
<br>
<span style="font-family: monospace;">--port=<span
style="font-style: italic;">Portnumber</span></span><br>
<div style="margin-left: 40px;"> By default, <span
style="font-weight: bold;">yaTelemetry</span> attempts to
connect to the <span style="font-weight: bold;">yaAGC</span>
program using port number 19800. However, if more than one
instance of <span style="font-weight: bold;">yaTelemetry</span>
is being run, or if <span style="font-weight: bold;">yaAGC</span>
has been configured to listen on different ports, then different
port settings for <span style="font-weight: bold;">yaTelemetry</span>
are needed. Note that by default, <span style="font-weight:
bold;">yaAGC</span> listens for new connections on ports
19697-19706, which is the recommended range for virtual CM
equipment, but that the recommended port range when using <span
style="font-weight: bold;">yaAGC</span> for the LM is
19797-19806. Thus, yaTelemetry would normally used either
with port 19800 (LM) or 19700 (CM).<br>
</div>
<br>
<span style="font-family: monospace;">--spacecraft=CM<br>
</span> <span style="font-family: monospace;">--spacecraft=LM</span><br>
<div style="margin-left: 40px;"> Self-explanatory, I think.<br>
</div>
<br>
<span style="font-family: monospace;">--font-size=<span
style="font-style: italic;">Points</span></span><br>
<div style="margin-left: 40px;"> The <span style="font-weight:
bold;">yaTelemetry</span> display window is not provided in a
way that allows it to be resized. This means that if
downlink data does not fit within the display window, the only
option is to change the size of the text, and not to change the
size of the window. The default font size is chosen with the
expectation that adjustment isn't needed. However, it's
possible that the default won't be appropriate on some platforms,
so adjustment can be achieved via the --font-size switch.
Because of platform variations, the default size actually varies
from platform to platform (Linux, Windows, Mac) and according to
whether or not the --simple switch (see below) is used.<br>
</div>
<br>
<span style="font-family: monospace;">--undecorated</span><br>
<div style="margin-left: 40px;"> <span style="font-weight: bold;">yaTelemetry</span>
is gimicked-up to look something like a CRT display.
However, this takes a lot of space on the computer screen, and you
may be unwilling to expend the extra space needed to achieve this
retro appearance. The --undecorated switch removes the
decorations, and reduces the telemetry display to little more than
a rectangle filled with text. If the screen size is too
small to display the decorations, this switch is activated
automatically and so you do not need to do so manually.
Also, the switch is always in effect in Mac OS X, because the
decorated display has not (yet) been made to work correctly.<br>
</div>
<br>
<span style="font-family: monospace;">--simple</span><br>
<div style="margin-left: 40px;"> Although by default <span
style="font-weight: bold;">yaTelemetry</span> displays its
downlink-data within a console intended to resemble a CRT, and
although the --undecorated switch is available to remove that
decorative trimming, the --simple switch is probably a better
choice in practice. The --simple switch overrides both the
default and the --undecorated mode to provide a simple textual
display with no flourishes except for two buttons which can
enlarge the font size or decrease it. The size of the
display is always automatically adjusted so that the downlink data
always appears within it without scrollbars being needed,
regardless of the font size. I would recommend always using
the --simple switch in place of the defaults.<br>
</div>
<br>
<hr style="width: 100%; height: 2px;">
<center> <br>
<span style="color: rgb(84, 89, 93); font-family: sans-serif;
font-size: 11.05px; font-style: normal; font-variant: normal;
font-weight: normal; letter-spacing: normal; line-height:
16.575px; orphans: auto; text-align: center; text-indent: 0px;
text-transform: none; white-space: normal; widows: 1;
word-spacing: 0px; -webkit-text-stroke-width: 0px; display:
inline !important; float: none; background-color: rgb(255, 255,
255);"> This page is available under the <a
href="https://creativecommons.org/publicdomain/zero/1.0/">Creative
Commons
No Rights Reserved License</a></span><br>
<i><font size="-1">Last modified by <a
href="mailto:info@sandroid.org">Ronald Burkey</a> on
2019-05-11.<br>
<br>
<a href="http://www.ibiblio.org"><img style="border: 0px solid
; width: 300px; height: 100px;" alt="Virtual AGC is hosted
by ibiblio.org" src="hosted.png" width="300" height="100"></a><br>
</font></i> </center>
<br>
</body>
</html>
