Apple3rtr on macOS, Ubuntu and Raspbian

Apple3rtr is the quickest path to set up an Apple III emulator on modern platforms.  The Drop /// Inches podcast discusses details about apple3rtr and other Apple III-related topics.

In some platforms, however, it is a bit tricky to install the prerequisite software (MAME, SDL, etc.) properly.  This article describes the steps to install apple3rtr on the following platforms:

1. apple3rtr on macOS Mojave 10.14.6
2. apple3rtr on Ubuntu 18.04.3 LTS
3. apple3rtr on Raspbian Buster

Note: Info on this page was verified as of October 2019.

1. Apple3rtr on macOS Mojave 10.14.6

It is a straightforward task to set up apple3rtr on macOS.  The step-by-step instruction is found in apple3rtr Readme (see "SDL and MAME Installation").

a. Install MAME0214

Download SDLMAME v0.214 64-bit.zip from http://sdlmame.lngn.net/. 

Unzip the file and install the binary:

unzip mame0214-64bit.zip
cd mame0214-64bit
sudo cp mame64 /usr/local/bin
sudo chmod +x /usr/local/bin/mame64

b. Install SDL2

Download SDL2-2.0.10.dmg (or the latest dmg) from http://www.libsdl.org/download-2.0.php. 

Then run:

open SDL2-2.0.10.dmg
sudo cp -r /Volumes/SDL2/SDL2.framework /Library/Frameworks

You may be required the admin password.

c. Clone apple3rtr repository

git clone https://github.com/datajerk/apple3rtr

d. Start MAME + apple3rtr

cd apple3rtr
mame64 apple3 -window -skip_gameinfo -volume -24 -resolution 1024x768 -effect Scanlines0x4 -sl1 cffa2 -hard apple3.hd -sl2 thclock -sl3 applicard -ramsize 512k -flop1 demodisk.dsk

The option -flop1 specifies the boot floppy image.  Apple3rtr includes several boot images.  To quit apple3rtr, press F1 and then Esc.

2. Apple3rtr on Ubuntu 18.04.3 LTS

On Ubuntu, you need to build MAME from the source code, as the MAME from apt package doesn't seem to work with apple3rtr.

a. Install prerequisite packages

sudo apt-get update
sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev qt5-default

b. Download MAME 0214 source

mkdir mame0214; cd mame0214
wget https://github.com/mamedev/mame/releases/download/mame0214/mame0214s.zip
unzip mame0214s.zip
unzip mame.zip 

c. Build MAME 0214

make NOWERROR=1 REGENIE=1 -j3

When done, install mame64:

sudo cp mame64 /usr/local/bin/
sudo chmod +x /usr/local/bin/mame64

d. Clone apple3rtr repository

git clone https://github.com/datajerk/apple3rtr

e. Start MAME + apple3rtr

cd apple3rtr
mame64 apple3 -window -skip_gameinfo -volume -24 -resolution 1024x768 -effect Scanlines0x4 -sl1 cffa2 -hard apple3.hd -sl2 thclock -sl3 applicard -ramsize 512k -flop1 demodisk.dsk

The option -flop1 specifies the boot floppy image.  Apple3rtr includes several boot images.  To quit apple3rtr, press F1 and then press Esc.

3. Apple3rtr on Raspbian Buster

At least a Raspberry Pi 3b+ is required to build MAME from the source.  Raspbian Buster, Kernel 4.19, Sep. 2019 or newer is recommended.

The latest MAME as of Sep. 2019, MAME 0214, somehow did not work with apple3rtr.  I rolled back to MAME 0187 for a successful build. 

Due to the RAM size and other resource limitations in the system, a couple of additional steps are required:

1. Use SOURCES make parameter to limit the number of files to compile.

2. Temporarily increase the swap space.

Detailed steps are described below.

a. Prepare Raspbian system SD memory card

Download the system image from the Raspberry Pi download page.  As of September 2019, Raspbian Buster kernel 4.19 is the latest.  A 32GB SD card is recommended.  You can use etcher tool to write the image on your SD card. 

b. Configure Raspberry Pi environment

Some additional configuration of the Raspberry Pi will be useful for build of MAME.  You may want to:

• Enable Wifi, ssh and vnc
• Setup keyboard locale
• Boot in console

These tasks can be done using raspi-config. 

c. Install prerequisite packages

sudo apt-get update
sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev qt5-default

d. Download and unzip MAME0187 source tree

mkdir mame0187; cd mame0187
wget https://github.com/mamedev/mame/releases/download/mame0187/mame0187s.zip
unzip mame0187s.zip
unzip mame.zip

e. Build MAME0187

Before building MAME, increase the swap size temporarily.  Edit the swap configuration file:

sudo vi /etc/dphys-swapfile

And modify this line:

CONF_SWAPSIZE=100

to:

CONF_SWAPSIZE=2048

then save the file and restart Raspberry Pi.  After restart, use free command to verify that the swap size is increased:

pi@raspberrypi3:~ $ free -m
               total        used        free      shared  buff/cache   available
Mem:            926         167         461          14         296         691
Swap:          2047           0        2047

Now you can build MAME:

cd mame0187
make NOWERROR=1 SUBTARGET=apple3 SOURCES=src/mame/drivers/apple3.cpp,src/mame/machine/apple3.cpp -j2

If you previously ran the make command with different options, add the option REGENIE=1 as well.

It will take about two to four hours for the command to finish.  After the command is done, verify that the binary file named apple3 is created.  Install it:

sudo cp apple3 /usr/local/bin/
sudo chmod +x /usr/local/bin/apple3

Now the build is done, set the swap size back to the original.  Edit CONF_SWAPSIZE value in /etc/dephys-swapfile:

CONF_SWAPSIZE=100

Save file, quit editor, and restart Raspberry Pi.

f. Clone apple3rtr repository

git clone https://github.com/datajerk/apple3rtr

g. Start MAME + apple3rtr

cd apple3rtr
apple3 apple3 -skip_gameinfo -nowindow -volume -24 -resolution 512x384 -sl1 cffa2 -hard apple3.hd -sl2 thclock -sl3 applicard -ramsize 512k -flop1 demodisk.dsk

The option -flop1 specifies the boot floppy image.  Apple3rtr includes several boot images.  To quit apple3rtr, press F1 and then Esc.

4. Programming in Apple III Business Basic

1. Boot apple3rtr with bosboot.dsk
2. From BOS main menu choose Business Basic
3. Try this code (mandelbrota3.ba3)

Reference: Apple III Business BASIC Reference Manual Vol 2 

Apple IIe Zero-Spindle Configuration

As of 2018, there are a number of options available for Apple II computers to replace conventional spindle drives. Some of the solutions even provide some sort of network capability. Using these options, you can build a network-based cross development platform for the Apple II.

Currently, the following solid-state storage devices are attached to my Apple IIe:

- Floppy Emu Model B by Big Mess O' Wires

Floppy Emu can be connected directly to the Disk II Interface card.

- Apple II Pi by Dave Schmenk with Raspberry Pi Zero W

Apple II Pi built on a prototype card

Based on these two solid-state storage devices, I am building a cross development environment for the Apple IIe using a Mac and a Raspberry Pi.

My current configuration is like this:

1. Floppy Emu - Slot #6, Drive 1

This is the boot drive. Usually I set the Apple2pi startup disk: A2PI-1.6.PO.

2. Apple II Pi card - Slot #2, Drive 1 and Drive 2

These are the virtual drives hosted by PiDrive running on the Raspberry Pi Zero W.

3. Sound card (under development) - Slot #4

This is the development target. I am writing the driver programs for it.

Slot 2: Apple II Pi, Slot 4: Sound card, Slot 6: Disk II card to Floppy Emu.

So, what are the benefits of this configuration? Many potential benefits can be found, but to me, there are two major things:

1. Apple IIe is connected to the wifi via Raspberry Pi. I don't need to lay a long USB-serial cable from one side of the room (Mac) to the other side (Apple IIe).

2. The virtual drives on Apple II Pi can be unmounted, updated and then re-mounted using PiDrive and AppleCommander.

Note that on Raspberry Pi, you can mount/unmount the virtual drives, using the PiDrive tool commands. These commands can be executed from Mac via ssh.

Once unmounted, those drives are simply disk image files on the Raspberry Pi. If the directory is shared using SMB, you can add any file on the Mac to the disk image files.

Using all of the above, the cross development steps can be totally controlled from Mac:

Step 1. Assemble Apple II program into a bin file (ca65/ld65 - CC65)
Step 2. Write the bin file into a disk image file (ac.sh - AppleCommander)
Step 3. Mount the disk image file on PiDrive (a2setvd - PiDrive/AppleIIPi on Raspberry Pi, command issued from Mac via ssh)

Now everything can be executed from the Mac, it is easy to automate the cross development steps. You can write a GNU Makefile, or any other build script for your development platform (Atom build, for example).

SBC6800

Last month, I built the SBC6800 single board computer. 

SBC6800 was designed and programmed by Tetsuya Suzuki, the author of the Japanese book:『モトローラ 6800 伝説』(“The Legends of Motorola 6800”). In fact, I read this book before building the SBC6800. So, I will write a bit about the book first.

 ***

The book starts by depicting a historic electronics shop in Akihabara, where the author finds that some vintage chips, including the original Motorola 6800, were still in stock. He purchases a few of them. 

He outlines the birth and early history of the microprocessors in the 70’s (“4004” - “8080” - “6800”), moving on to several computer kits that featured Motorola's first 8bit processor (Altair 680, SWTPC 6800, and Sphere), and then to a couple of early personal computers in Japan as well: Hitachi Basic Master L2 (6800) and Fujitsu FM-8 (6809). This book covers several notable 6800 software, such as VTL, Tiny Basic, and Robert Uiterwyk’s Micro Basic. Also a parallel computing project developed by the researchers of the universities in Japan is described, where a cluster of MC6800 processors was used as a processor array.

All the chapters of this book include a lot of pictures from the documents and magazines, or of the actual hardware, of those days. You might be familiar with them. When you look closely at the pictures of inside of the hardware, you can find the Motorola product numbers printed on the chips.

The highlight of this book is, however, development of his own single board computers. He designs the SBC6800 and the SBC6809, using MC6800 and MC6809 processors, respectively (his blog reveals the chronological record of development). Each of these SBCs uses a minimum set of chips—an MPU (MC6800/6809), a 6850 ACIA, a 2764 EPROM, a 6264 SRAM, and a few clock/glue logic chips. Thanks to the limited number of chips, these SBCs fit within a 3 x 4 inch PCB, which can be ordered at PCB fabs at the lowest price.

Next, the author develops a modified version of Mikbug (the system monitor program originally developed by Motorola), as the firmware for SBC6800. According to him, the 6850 ACIA was not in production yet when the original Mikbug was written, and that was why the 6820 PIA was specified in Mikbug for serial communication. He carefully rewrites the I/O routines so that the code will drive the 6850 on his SBC, instead of the 6820, without altering the major entry addresses from the original Mikbug. 

***

As soon as I finished the book, I ordered the PCB and some of the vintage chips for the SBC6800. Waiting for the components to arrive, I installed the 6800 cross-assembler on my Mac and downloaded the source code of his modified Mikbug. After adjusting some syntax differences (for example, I needed to type ‘STAA 0,X’, instead of ’STA A X’ as printed in the original Mikbug source code), the source code passed the assembler and the S-format file was generated. [Note: the Mikbug S-format file is provided by the author in SBC6800 data pack]

Finally, the vintage chips arrived. I built my SBC6800, burned the Mikbug into an EPROM, connected the serial port to my Mac, and then turned on the SBC. The glorious prompt from Mikbug:

was printed on the terminal window. The first program that I loaded, “Hello, world,” successfully ran on the vintage chip!

As of writing this, information necessary to build the SBCs is available only in Japanese. Google Translate might help. If not, please ask me. The good news is that the required components can be ordered from US, as I already did. Probably the components are available also in some other regions where online/vintage electronics suppliers, such as Mouser and eBay, are accessible.

If you speak Japanese, I strongly recommend reading the book first, which will increase your excitement when you build and run the SBCs. Or, the book will be interesting and fun on its own, if you dare not solder electronic components.

I will enjoy retroprogramming on these small SBCs, for the next couple of months, at least.

Book:『モトローラ 6800 伝説』Rutles (Publisher) | Amazon Japan

SBC6800 Technical Doc (pdf)

SBC6800 Data Pack (zip)

Shield Block Diagram

In this post, I will describe the functional blocks of USB Keyboard Shield for VT100.

The figure below shows the block diagram of USB Keyboard Shield for VT100 (the center column), along with other components necessary for the keyboard functions of VT100 (left and right columns).

Fig. USB Keyboard Shield for VT100 Block Diagram

As shown in the diagram, the shield is composed of three major functional blocks:

1. Transceiver for VT100 Keyboard Signal
2. LED Array
3. Buzzer Driver

A bit more details of each block will be discussed below.

1. Transceiver for VT100 Keyboard Signal

The VT100 keyboard cable has only one signal line, where the incoming signal (VT100 to keyboard) and the outgoing signal (keyboard to VT100) are mixed.

The transceiver circuit on the shield extracts only the incoming signal from the mixed signal line, and applies a low-pass filter to it. The resulting signal is sent to Arduino Serial RX (Arduino Uno pin 19). Arduino interprets this signal as the keyboard status bytes from VT100 terminal, and sends back a set of codes for the keys that are currently pressed down. The key code signal comes out of Serial TX (Arduino Uno pin 18). This outgoing signal is mixed into the keyboard cable signal line, after properly level-shifted.

2. LED Array

This shield has an on-board LED array. Each LED is directly connected to an output pin of the Arduino. The LEDs are turned on/off, as indicated by the keyboard status bytes from VT100 terminal.

The Arduino controls these LEDs dynamically, and up to only one LED is lit at a time, in order to reduce the power consumption by the LEDs. 

3. Buzzer Driver

The sound output (beep signal) from the Arduino is connected to an inverter on the 74LS06, which drives the piezo buzzer on the shield. A 800Hz beep sound is triggered by the Keyboard status bytes. 

Optionally, the beep signal can be routed to an external amplifier, and then the amplified signal can be fed to an external speaker attached to the keyboard cable. This routing to the external speaker is based on the original design of the VT100 keyboard cable. 

***

If you read the Keyboard section of VT100 Technical Manual, you will see that these functional blocks represent some part of the VT100 keyboard functions. The other functions, UART and the keyboard matrix, are taken care of by the Arduino UNO, the USB Host Shield and a USB keyboard.

You can find the schematic, shield sketch and other details of USB Keyboard Shield for VT100 in the GitHub repo.

USB Keyboard Shield for VT100: PCB and other components

In this post, I will describe how to obtain the PCB and necessary components for the shield.

PCB

I have a few extra PCBs of the shield (board only, no components included, see the picture above). If you would like to try one, please let me know using the form on this page.

Or, you can place an order with PCB fabs, using the Gerber file.

Other Components

I updated the BOM on GitHub repo for easy procurement.

The list of the components for the shield is found on page 1 of the BOM. If you purchase them from Mouser, the cost is around $14.

The list of the parts required outside the shield (Arduino Uno, USB Host Shield, keyboard plug/cable and connector) is on page 2 of the BOM. If purchased via Amazon, the total cost of these four items will be about $40. 

The price info above is just FYI. Taxes and shipping fees are not included. 

How to Build

Once you get all the components, please follow the instruction on Readme. If you have any questions about the shield, please let me know.

USB Keyboard Shield for VT100

About this project

The USB Keyboard Shield for VT100 project was developed to connect a standard USB keyboard to Digital's VT100 terminal. The current shield is rev 2.1 and working as intended.

Features

• All keys on VT100 keyboard are mapped to USB keyboard keys.
• The LED's and bell on VT100 keyboard are implemented on the shield.

In the demo video shown above, I demonstrated the following:

1. Turn on the VT100. Power-on self test is executed. When the self test is done, only the Online LED is lit. 
2. Press F1 (mapped to Setup) twice, turning on and off the Setup screen.
3. Logged in to OS X (connected via a USB-Serial interface), invoke vi.
4. Type something and then quit vi.
5. Type cat 1.led_all_on.txt. This file contains the escape sequences that turn on L1-L4 LEDs.
6. Press Ctrl-G twice, ringing the bell.
7. Type cat 0.led_all_off.txt. This file contains the escape sequences that turn off L1-L4.

How to get it working

I put the Readme, Gerber file, BOM, schematic and Arduino sketch for the shield on GitHub.

You will need to obtain the shield PCB, assemble/solder the parts and connect the shield to other components. Please note that this shield requires two more boards: an Arduino Uno and a USB Host Shield. For details, please see Readme on GitHub.