Skip to content

The System-5 emulator in a GitHub Codespace

A Codespace is a computer in the cloud with this repository on it, opened in your browser. This repository sets one up to run the System-5 emulator: nothing to install, and it works from any computer with a browser.

Start it

  1. On github.com, open the repository, then Code -> Codespaces -> Create codespace on main.
  2. Wait for it to build. The first time takes a few minutes, because it makes the CF card image (ELF/OS 0.2.6, 15 MB).
  3. The emulator starts by itself and opens in a new browser tab. If the tab does not open, go to the Ports panel and click the globe beside System-5 emulator (port 8802).

The next time, use Code -> Codespaces and pick the same Codespace: it keeps the CF card image, and the emulator starts again with it.

Use it

  • The Machine tab is the System-5: the 64 x 16 screen and the keyboard. Click the screen and type.
  • The machine starts in HBIOS's monitor, at the test> prompt. Boot ELF/OS types @FF00 and Enter. Then try DIR or FREE.
  • In a Codespace the ROM is HBIOS 1.0.5 (the line under the screen says which ROM runs): its monitor adds H (the list of commands), B (boot), D start:end (disassemble) and Q1 / Q0. The real machine still has 1.0.4.
  • Clock sets the emulated CPU clock: as fast as the Codespace can go, 2 MHz, 1.76 MHz, or 500 kHz, the speed of the machine as it stands today.
  • Reset is the CPU card's reset button.
  • Below the screen is the IO panel card, designed for the new 36-pin System-5 but not built: eight LEDs and two hex displays that show what a program writes with OUT 4, eight toggles that INP 4 reads, an INPUT button (EF1 while held), RUN, LOAD, and the Q light (Q1 / Q0 in HBIOS 1.0.5's monitor turn it on and off). To toggle a program in, as on a COSMAC ELF: RUN off, LOAD on; for each byte set the toggles and press INPUT; then LOAD off and RUN on, and it runs from 0000. Reset boots the ROM again. Try E1 F8 20 A1 6C 64 21 30 04: it copies the toggles to the LEDs.
  • HBIOS 1.0.5 has a panel demo built in: at test> type @F1C0. The LEDs follow the toggles and Q lights while INPUT is held, until Reset.
  • The Debugger tab has the registers, the code at PC, memory, breakpoints and the debugger's command line (help lists the commands).

The CF card lives in the emulator's memory while it runs. To keep what ELF/OS wrote to it, type save in the Debugger tab's command line. That writes software/s5emu/disks/elfos.img, which stays in the Codespace and is never committed.

Update, stop and restart

These go in the Codespace's terminal, the panel under the editor (Ctrl-` opens one if it is hidden). It starts in the repository's top folder, which is where these commands expect to be run.

A Codespace keeps the copy of the repository it was made with. After something new is pushed to GitHub (a new ROM, a change to the emulator or its page), three steps bring the Codespace up to date:

  1. Update: get the new version from GitHub.

    git pull

  2. Stop the running emulator. It goes on running the old version until it is stopped.

    software/s5emu/web-start.sh --stop

  3. Start it again, with the new version.

    software/s5emu/web-start.sh

Or all three as one line:

git pull && software/s5emu/web-start.sh --stop && software/s5emu/web-start.sh

Then reload the emulator's browser tab. If that tab was closed, open the Ports panel and click the globe beside System-5 emulator.

  • Stopping the emulator throws away what ELF/OS wrote to the CF card since the last save (Debugger tab), so type save first if it matters.
  • git log --oneline -1 shows which version the Codespace has; the line under the emulator's screen names the ROM.
  • Steps 2 and 3 alone restart the emulator without updating, for example after it hangs.

What a browser refresh does

The emulator is a program running inside the Codespace; its browser tab is only the machine's screen and keyboard. So a refresh shows the machine again, and starts it only when the Codespace itself had stopped.

What you refresh What happens
The emulator's tab, with the Codespace running The page reloads and shows the machine exactly where it was: still in a program, or at the ELF/OS prompt. Nothing is started or reset.
The Codespace's own tab (the editor), with the Codespace running The editor reloads and connects again. The emulator goes on running; it is not started a second time.
The Codespace's own tab, after the Codespace has stopped (30 minutes without use, or stopped by hand) GitHub starts the Codespace again (press Restart codespace if it asks), and that starts the emulator: a fresh machine at test>, with the CF card as it was at the last save. If its tab does not open, use the globe in the Ports panel.
The emulator's tab, after the Codespace has stopped An error page: this tab cannot start the Codespace. Start it from the Codespace's own tab or from Code -> Codespaces, then refresh.
  • A refresh never updates. It does not run git pull, and a running emulator keeps the version it started with: use the three steps above.
  • After web-start.sh --stop, the emulator's tab shows an error on a refresh until the emulator is started again (step 3 above).

Other ways to start it

Stop the emulator first (step 2 above), then start it with a setting in front:

S5_CLOCK=1.76m software/s5emu/web-start.sh

starts it with another clock (max, 2m, 1.76m or 500k).

S5_ROM=software/s5emu/roms/hbios-1.0.4.rom software/s5emu/web-start.sh

starts it with HBIOS 1.0.4, the ROM in the real machine.

S5_PANEL=none software/s5emu/web-start.sh

starts it without the IO panel card.

rm software/s5emu/disks/elfos.img

throws the CF card away; the next start makes a fresh one.

Cost

A Codespace counts against your GitHub account's monthly Codespaces hours, and stops by itself after 30 minutes without use. Stop or delete it from Code -> Codespaces when you are done.

On a Mac

The same script works there:

software/s5emu/web-start.sh --fg

then open http://127.0.0.1:8802/.