Module | TatungBytes

Why this matters

You are going to be assembling and running code hundreds of times over this course, so the loop between writing a line and seeing its effect needs to be short. Set up properly once and it stays out of your way: you press one button, and a second or two later your program is running on an Einstein.

This section is the only one with no assembly in it. By the end you will have an Einstein booting on your own machine, ready for the first program in S3.

What you are installing

Five pieces, all free.

Piece	What it does
Visual Studio Code	The editor you write in.
The Tatung Einstein extension	Adds the Run button. Assembles your source, starts the Einstein if it is not already running, and loads your program into it.
z80asm	The assembler. Turns your source into a `.COM` file the Einstein can execute.
MAME	The emulator. Given the right ROM, it behaves like an Einstein.
The Einstein ROM	The machine's own built-in software. MAME cannot be an Einstein without it.

The extension drives the assembler and the emulator for you, so once everything is installed you will rarely think about them again.

Installing the tools

These steps are for macOS.

1. Homebrew

Homebrew installs the assembler and the emulator in one command each. If you do not already have it, follow the instructions at brew.sh.

Check it is working:

brew --version

2. The assembler and the emulator

brew install z80asm mame

Then confirm both are there:

z80asm --version
mame -version

You should see Z80 assembler version 1.8 and a MAME version number. The course is written against MAME 0.289.

3. Visual Studio Code

Download it from code.visualstudio.com, open the .dmg file that downloads, and drag the Visual Studio Code icon inside it to your Applications folder.

4. The Einstein extension

Download the extension from the Downloads page. You will get a .zip file - unzip it to get the .vsix file inside.

In VS Code, open the Extensions view (View > Extensions), click the ... menu at the top of that panel, choose Install from VSIX..., and select the .vsix file you just unzipped.

You will know it worked when the status bar at the bottom of the window shows Einstein: Stopped.

5. The Einstein ROM

MAME looks for the Einstein's ROM in a file called einstein.zip. Create a folder called roms in your home folder and put it there:

~/roms/einstein.zip

The extension checks that location automatically, so if the file is there, no configuration is needed.

6. Check it

mame -rompath ~/roms einstein -window -skip_gameinfo

A window opens and, after a moment, the Einstein boots:

*** EINSTEIN ***
Insert disc in drive 0 and
press Ctrl-BREAK to load

TATUNG/xtal MOS 1.2      (C) 1983 1984

Ready
>

That > is the machine waiting for you. Close the window when you have seen it. Setup is done.

A note on other Einstein code

The assembler you have just installed is one of several that can build Z80 code, and they do not all accept the same syntax. The instructions are the same everywhere - they belong to the processor - but the way you write a number, or name a block of data, differs from one tool to the next.

This matters the first time you find an Einstein listing somewhere else and it will not assemble. Usually the listing is fine and just needs a small translation. Appendix II - Assemblers are not all the same has the specifics, including one difference that fails silently rather than reporting an error. Worth a look before you paste in code you did not write.

Telling the extension where things are

If a tool is installed somewhere unusual, you can point the extension at it directly instead of relying on PATH. Open VS Code's settings and search for Tatung Einstein:

Setting	What to put in it
Z80asm Path	Full path to the assembler, if it is not found automatically.
MAME Path	Full path to MAME, likewise.
ROM Path	The folder holding `einstein.zip`, if it is not `roms` in your home folder.
Run On Save	Turn this on to assemble and run every time you save. Off by default.

Leave all three paths blank unless something is actually not being found.

When it goes wrong

What you see	What it means
`MAME was not found. Set Einstein: MAME Path in Settings.`	MAME is not on your PATH. Either fix the PATH or set MAME Path.
`z80asm was not found. Set Einstein: Z80asm Path in Settings.`	Same, for the assembler.
`mos12.i023 NOT FOUND (tried in einstein)` followed by `Fatal error: Required files are missing, the machine cannot be run.`	MAME found no usable `einstein.zip`. Check the filename, and check the folder you set as the ROM path.
`The active file is not a .asm file`	The Run button works on the `.asm` file you are editing. Click into the editor tab first.
Nothing happens, no error	Open the Einstein output channel from the status bar to see what MAME and the assembler actually said.

Summary

You have an assembler, an emulator, an editor and the extension that joins them together.
The extension finds the assembler and MAME on your PATH, and looks for the ROM in a roms folder in your home directory. Nothing needs configuring if they are in those places.
You have booted an Einstein and seen its Ready prompt.

S3. Your first program. Getting a character onto that screen - which means meeting the Z80's registers, and the way the Einstein lets a program ask it for something.

← Previous Next →

Setting up