GettingStarted

Paul Kimpel edited this page Apr 7, 2018 · 6 revisions

Getting Started With the retro-205 Emulator

The retro-205 emulator is an implementation of the ElectroData/Burroughs Datatron 205 computer system. The 205 was a mid-1950s vacuum tube, decimal, drum-memory system. This page describes how to set up the emulator.

The emulator runs in a standard graphical web browser. It is written entirely in Javascript, with HTML and CSS used to define the user interface. The emulator opens a series of browser windows that display and model the consoles and input/output peripheral devices for the system. You operate and interact with the emulated 205 through these windows. The intent is that you work with the emulator in much the same way you would have with a real 205.

Quick-start Overview

To set up and use the web-based emulator, you will need to do the following things, which are discussed in more detail in the sections below:

  • Use a suitable web browser -- at present, that means Mozilla Firefox, Google Chrome, or Apple Safari. See following section on The Web Browser.
  • Optionally, download and set up the emulator files on a web server. Instead of using your own web server, you can run the emulator from our hosting site. See the following sections on The Web Server and The Emulator Files.
  • In your web browser, access the webUI/D205.html home page from the web server to run the emulator. See the following section on Starting the Emulator.

The Web Browser

The retro-205 emulator pushes the limits in several areas of current web-browser technology. We are taking advantage of many features in HTLM5, its related DOM APIs, and CSS 3. As a result, not every web browser is capable of hosting the emulator. We rely, at a minimum, on the following advanced features:

  • ArrayBuffer, DataView, and Blob APIs
  • File, FileList, and FileReader APIs
  • postMessage API
  • performance.now() API
  • JSON API
  • LocalStorage API
  • Promise API
  • HTML <meter> element
  • IndexedDB API (used only with the DataFile tape unit)

The emulator has been tested and works in Mozilla Firefox (version 21 and above) and Google Chrome (version 35 and above) for Windows, Linux, and Apple OS X. Somewhat earlier versions of these browsers may also work. The emulator has also been tested and works in Apple Safari 9.0.2 for OS X, and may work in some versions of Safari 8. The emulator does not presently work in Microsoft Internet Explorer (at least through IE11) and Edge (in Windows 10).

Note that the windows the emulator opens are considered by most browsers to be "pop-ups." Most browsers are configured by default to inhibit pop-up windows from opening, but allow you to override this for specific web sites. Thus, you will need to disable pop-up blocking for the site from which you run the emulator.

You will need a reasonably powerful workstation for the browser. Emulation of the 205 instructions requires almost nothing, but update of the panels and I/O device windows can be very graphics-intensive, and requires a fair amount of horsepower. Any standard PC manufactured since 2010 should be adequate. It also helps to have a good-sized display, as the two control panel windows are rather large.

The Web Server

The easiest way to use the emulator is to load it from the web site we have set up on a hosting service. Just point your browser to the following URL:

http://www.phkimpel.us/ElectroData-205/

The web server is needed only to load the emulator into your local workstation. Once the emulator is loaded and running, it requires no further access to the server.

The emulator can also run off-line after it is initially loaded, without continued access to the web server from which it is hosted. Off-line operation is automatic when the browser supports the HTML5 "Application Cache" standard and it is operating without a network connection or cannot otherwise contact the web server. See the appendix Off-Line Operation for details on how this works.

If you choose not to use our hosting site, or some other site that is already set up to serve the emulator files, you will need to configure a web server and load the emulator files to it. See the appendix Setting Up a Web Server for the necessary information.

Starting the Emulator

This section describes how to run the emulator and prepare it to run 205 programs.

To run the emulator from our hosting site:

  • In your browser, access the page at http://www.phkimpel.us/ElectroData-205/.
  • Click the "205 Emulator Home Page" link on that page.
  • On the resulting page, click the blue Start the Emulator button.

To run the emulator from another web server:

  • Open the webUI/D205.html page under the URL for the virtual directory you have set up.
  • On the resulting page, click the blue Start the Emulator button.

The emulator home page should look similar to this:

retro-205 Emulator Home Page

When you start the emulator, it will open additional windows for the Supervisory Panel and Control Console, plus a window for each of the peripheral devices in the system configuration. Some overlap of windows is inevitable, and depending on the size of your display screen, some windows may be hidden by others. All of the windows are resizable, and may be moved around your screen in any way you wish.

You may minimize any of the windows, but do not close them -- there is no way to reopen the windows later without shutting down and restarting the emulator. The emulator may display an alert if you attempt to close one if its windows, but this is browser-dependent. Most modern browsers will display a close alert only if you have previously interacted with the window in some way, e.g., clicked on one of its elements.

In addition, while the emulator is running, it is not a good idea to minimize the emulator home page or make another tab active in the window that contains the home page. Current versions of at least Firefox and Chrome slow down the execution of scripts running from minimized windows or inactive tabs, which in turn will cause the emulator to run very slowly. It is best to open the home page in its own window.

The first time you run the emulator, it will initialize with the following default configuration. This configuration has been designed to work with the software projects initially developed with the emulator.

  • Flexowriter typewriter
  • Paper-tape reader
  • Paper-tape punch
  • Cardatron control unit with:
    • Card reader unit 1
    • Card punch unit 1
    • Card punch unit 2
    • Line printer unit 3
  • Magnetic tape control unit with:
    • DataReader A, designated as unit 0 (i.e., 10).
    • DataReader D, designated as unit 3
    • DataReader E, designated as unit 4

This default configuration can be changed by clicking the blue Configure System button on the emulator home page. That button is enabled only when the emulator is in a "powered-down" state, i.e., just after it has been initially loaded, or after the red OFF button has been clicked on the Supervisory Panel.

See the Configuring the 205 Emulator page for more information on the components of the system configuration and how they can be changed.

Next Steps

The main purpose of the retro-205 emulator is to be able to run 205 software. When you load the emulator, the 205 memory is initialized with a few small demo programs. You can run these from the consoles, as described in the Using the Control Consoles page.

A few significant pieces of 205 software have been found and recovered. The source and object code for these are in the software/ directory of our GitHub project site. These can be downloaded individually and run in the emulator. These projects include:

Documentation and References

The Burroughs PDF document archive at bitsavers.org has scans of a few manuals for the 205:

Since the retro-205 emulator user interface is designed to mimic the consoles and control panels of a real 205, you must be somewhat familiar with the way those consoles and panels worked. The best guide is the 205 Operating Procedures manual cited above. Emulator operation is also described in the following articles on Tom Sawyer's 205 and 220 blog:

Several other manuals from the private collections of Tom Sawyer and Donald Knuth have been scanned are available on line:

Appendices

Setting Up a Web Server

This section describes setting up and configuring a web server to host the retro-205 emulator.

Using Your Own Server

If you use your own web server, it can run on your local workstation and serve files from there, or you can access some other server remotely over the Internet.

If you need a small, simple web server to host the emulator locally, we have had good success with mongoose (https://github.com/cesanta/mongoose). It can run on the same workstation as your browser to serve the emulator files using the loop-back port (localhost or 127.0.0.1). Versions are available that run under Windows, Linux, UNIX, and Mac OS. It is easy to set up. Under Windows, it can run either on demand as a user program or as a Windows Service.

The Emulator Files

Unless you are running your web server on the same workstation as your web browser, you do not need to download or store the emulator scripts on your workstation. You load it as you would any other web page.

If you want to set up your own web server, the easiest way to obtain the emulator files is to download them from our GitHub project repository. You can clone the project with Git or Subversion, or download a ZIP archive of the files. To do this, click the green Clone or download button on the right-hand side of the page:

GitHub Download

The emulator is hosted in two directories of files:

  • emulator/ contains the Processor module.
  • webUI/ contains everything else you need to run the system. In particular, it contains the Console user interfaces and the peripheral device drivers.

A third directory, software/, contains source and object code for the software projects and miscellaneous utilities that have been developed with the emulator. These are described in other wiki articles and the README files embedded within their directories.

A fourth directory, webSite/, contains the web pages for the hosting site. You are welcome to use these if you wish. The home page for the hosting site is index.html and must be located at the root of the project files. Use the "205 Emulator Home Page" link on that page to run the emulator.

Establish the Web Server

The general steps to set up the emulator files are:

  1. Create a new virtual directory for the web server, e.g., /retro-205/, to hold the emulator files.
  2. Download the emulator release as described above.
  3. Place the files in the directory on your server's file system to which the virtual directory is mapped. You will need the files from at least the emulator/ and webUI/ directories. Those directories must reside at the root of the virtual directory.
  4. If you choose to use the webSite/ files, that directory and the index.html file must also be at the root of the virtual directory.
  5. To support the web fonts used by the emulator and hosting site, you may need to create a MIME-type mapping in the web server configuration for at least one of the following file extensions: * .woff to application/font-woff * .ttf to application/font-sfnt
  6. To support the off-line "Application Cache" capability, you may need to create a mapping in the web server configuration between the ".appcache" file extension and the "text/cache-manifest" MIME type.

Off-Line Operation

Since release 0.03 it has been possible to run the emulator without access to a web server at all. The emulator is configured to load into the browser's "Application Cache." This an HTML5 feature, and is not so much a cache as a way to install all of the HTML, Javascript, images, and other resources for a web-based application into the browser and store them in your workstation's local file system. The first time you open the emulator home page from a web server, that initial load will automatically install the emulator into the Application Cache. Thereafter, you run the emulator in your browser using the same URL you used initially, but the browser will load the emulator from its local Application Cache instead of the network. You do not need an active network connection at all.

All installation and maintenance of the emulator in the Application Cache is completely automatic and happens in the background. The emulator files comprise about 4MB (most of that is font files), so the initial download may take a short while, depending on the speed of your network connection. After that, the emulator should load very quickly.

Each time you open the emulator home page in your browser, the browser will test whether it is able to contact the web server from which the emulator was originally loaded, and if so, will check whether a newer version of the application is available. If a newer version is available, the browser will download and install it into the Application Cache, but the browser will continue to use the former version of the application until the next time you reload it, at which point the newer version will take effect.

When you load the emulator into your browser, the home page will display messages above the image of the 205 site, indicating progress while the browser is checking for a newer version and downloading any updates. The last in the sequence of progress messages will remain on the page for several seconds, and then will be erased. You do not need to wait for these progress messages to go away before starting the emulator -- it can be initiated while the checking and downloading process is taking place.

You will see some combination of the following messages on the home page while it is checking and updating the Application Cache:

Message Description
Checking for emulator update... The browser has initiated the process of checking for a newer version of the emulator.
Emulator version is current. The browser determined that no newer version is available.
Initiating download for emulator update... The browser has determined that a later version of the emulator is available on the server and has initiated downloading the new files.
x of y resources downloaded thus far... This message may appear occasionally during download of new files to indicate the progress of the download.
Emulator update completed. Reload this page to activate the new version. Download of a new version completed successfully, but the browser is still using the former version of the emulator. The new version can be made available by powering-off the emulator and reloading the emulator's home page.
Emulator is now installed for off-line use. This message will appear the first time the emulator is downloaded and installed into the browser's Application Cache.
Unable to check for emulator update. The browser is unable to contact the web server or access the emulator's manifest file. The emulator will run in the off-line mode.
Emulator off-line installation has been disabled. The manifest file for the Application Cache has been removed from the server. This causes the emulator to be removed from the local Application Cache. Off-line operation of the emulator is no longer possible.
Browser reported error during emulator version check. The browser detected an error in attempting to access the Application Cache manifest file. This is usually caused by lack of a network connection or inability to connect to the web server.

Note that in order to properly serve the manifest file that enables Application Cache functionality for the emulator, your web server may need to be configured to apply the MIME type text/cache-manifest to files with a .appcache extension on their file name.

Also note that installation of a web application in the Application Cache is specific both to the browser and to the web server host name from which the application was loaded. If you use different browsers, each will have its copy of the application. If you load from different web servers, or using different host names for the same web server, each will result in a separate copy of the application in the Application Cache.

Finally, note that in late 2016 both Mozilla and Google declared the draft Application Cache web standard to be deprecated. There are as yet no specific plans to deimplement this feature in their browsers, but it is possible that may occur at some point in the future. The emulator will continue to support this feature as long as the browsers do. If your browser deimplements it, the emulator should still work, but will require an active connection to the web server each time you load it.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.