Introduction: Retro CP/M Stand Alone Emulator

This project uses the VGA32 ESP v1.4 module to run a combination or RunCPM and FabGL to provide a stand alone computer running an equivalent system to CP/M 2.2. Popular during the 1980's as an operating system for small computers. You can go back in time and revisit old software such as Wordstar, Supercalc, Adventure and Zork.

It's standalone courtesy of the FabGL project that provided the software to run a standard VGA monitor and PS/2 Keyboard.

The main OS is a modified Version of RunCPM, it's been forked from the original work on Github and I have added the FabGL library to enable it to be used on a screen instead of on a serial console.

I'd just like to say a big thanks to both projects. Keep up the good work!

The software has been tested on at least two versions of hardware. One the VGA32 ESP v1.4 (as sold ready made). Second my old version, I built from a Wroom ESP32 Module and scrap bits from old computers.

The Github site below contains important info on these setups as well as the modified ready-to-install software.

This project is about installing the software, not about the hardware.


An VGA32 ESP module V1.4 (tested). Found on eBay / aliexpress /amazon etc

The Arduino IDE installed on a computer, I assume if your reading this you already have this.

Install the ESP32 support pack for Arduino IDE. See step 1

The FabGL library you don't need to download anything, the arduino IDE can do this for us, see step 2.

Download a copy of the modified RunCPM from

Step 1: Install ESP32 Support for Arduino (optional)

You may well have already done this, if you have you can skip this step.

visit and follow the instructions on installing using boards manager, like this:

Installation instructions using Arduino IDE Boards Manager

Stable release link:

Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the Arduino website.

Start Arduino and open Preferences window.

Enter one of the release links above into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas.

Open Boards Manager from Tools > Board menu and install esp32 platform (and don't forget to select your ESP32 board from Tools > Board menu after installation).

Step 2: Adding the FabGL Library to the IDE

Using a blank sketch in the Arduino IDE, make sure you have selected your ESP Board from the Tools menu, Boards. (At the time of writing the VGA32 ESP was not listed, I choose a generic Dev Kit board).

From the Sketch menu, choose Include Library, then choose Library manager.

In the search dialogue type FabGL and wait for it to appear in the list bellow, now click the Install button.


Step 3: Adding Additional SD-card Library Used by RunCPM

This is almost the same as the previous step but instead of FabGL search for SDFat

From the Sketch menu, choose Include Library, then choose Library manager. In the search dialogue type SDFat and wait for it to appear in the list bellow, you will probably have to scroll down the list.

You get the choice of two versions:

1, SdFat by Bill Greiman

2, SdFat - Adafruit Fork

I have tried both, they both seem to work ok. But the RunCPM project did recommend the Second option "Adafruit Fork", however on the latest notes it now says:

All boards now use the SdFat library, from here:

So now I choose the first option for this project.


Step 4: Download the Modified RunCPM Project

Visit the Github Site,

Click the CODE button and download as a ZIP file

Save this file somewhere (normally in a directory called Arduino.

Unzip the file to the same location, it will produce a folder called RunCPM-master


Step 5: Open and Review the RunCPM Program and Compile

You can now use the Arduino IDE File, Open menu. Navigate to the folder you uziped above.

Inside this folder is another called RunCPM. Open the folder.

Inside that folder is a .ino file called RunCPM.ino. This is the main project file - open it.

You can now view the project, read the comments etc. Make changes if you need to match your version of VGA32 -ESP. It should be pre-configured for V1.4 of the board.

You can now click compile and upload, assuming you have you VGA32 ESP connected it will upload the emulator to your device.

IMPORTANT: The VGA32 has can have a problem with the SD-card at this point, so do not plug it in for know. See the last step bellow for more information.

Step 6: Create an SD-card Ready to Boot Your RunCPM From

This is perhaps the most trick of steps. I suggest you read the of the Github site on how to do this. Here is my list of what to do:

I assume you have a blank SD-card or are not interested in keeping any files on the one you have, this will erase it.

1, format the SD-card as FAT-32

2, Create some folders called A,B,C D etc (up to P these will be the disk drives when running CP/M). Note they are capitals.

3, In each folder you create Create another folder named 0 (thats a zero) and optionally 1,2,3 etc (up to 15) Then folders are User Areas in the CP/M emulation. You only need the 0 folder to start off.

4, From your downloaded project folder in the arduino directory, find the folder called CCP. This contains various versions of the CP/M Command Console Proccessor. Copy the one called CCP-DR.60K to the root of your SD Card.

5, Now find the folder in the project directory called DISK, It contains a A.ZIP file, you need to unzip this file to the directory called A/0/ on your SD-card. (also see the 1streadme file for more info). Unfortunately it does not have the "0" in the folder list so you need to unzip to a temporary folder first, then copy the contents for the A folder to A/0/ on the SD card.

6, When You have done the above steps you will have an SD-Card with a structure like this:





/.... etc




If you get errors about can't load CCP etc when you try to boot from the SD-Card, double check you have everything in the right pace!

In an attempt to make this stage a bit easier, i have uploaded a ready made version of above, with addition cp/m software on it as well download it from here and just unzip it to the root of a formatted SD-Card. It should get you started then you can create your own later.

I also recommend you read the setup guid on the Github Repo, it has a description of the folders you need.

Step 7: Connect a VGA Monitor and Keyboard

Disconnect the power to the VGA32 ESP card.

Connect your VGA Monitor

Connect a PS/2 Keyboard Re-connect the power to the VGA32 ESP card, you should see the keyboard lights flash and about 10 seconds later a picture will appear on the screen with a CP/M prompt!

Important: The VGA32 has a problem when using the SD-card and soft reset, thats why it's important to TURN THE POWER OFF as the first step above, See last step for further info.

Away you go...

Step 8: Problem With SD-Card on VGA32 Module

The photo above shows my second ESP32 card (home made), this works fine and does not have the issue bellow. So I know is not a software issue, please read bellow about the VGA32 version.

On my VG32 ESP module (v1.4) the SD-card uses GPIO12, This is not recommend by Espressif Systems as this pin is used on power up to detect the working voltage for the internal memory. I do wish someone had told the guy who make this VGA32 card! It maybe different on yours, so hopefully you won't have this issue.

The problems are:

1, Unable to upload a sketch when the card is plugged in.

2, After pressing the reset button, it lock's up until the SD-card is removed. Then it boots to an error screen saying no SD-Card! You can put the card in and reset again and it will work the second time.

This issue is fixable (But has a risk) see the on

or you can always do a hard power off/on to start the board. For some reason this seems to work fine. Also if you need to re-upload the RunCPM software you must remove the SD-card first.

This is an extract from the README.MD that explains the issue. I have used the fix and it works fine, BUT due to it's nature the risk is yours, read on...

However, the settings for the VGA32 ESP seem to have a conflict on the GPIO settings for the SD card.
It does work but to upload you have to remove the SD card and after a soft reset you have to
remove the SD card and then replace it followed by another reset. It works ok from a power on or hard reset.
If you can help fix this please let me know.

UPDATE 11Oct2020: The VGA32 ESP v1.4 uses GPIO12 (MTDI, read on powerup/reset). This pin determines the voltage for the RAM, Voltage of Internal LDO (VDD_SDIO). When the SD card is present it pulls this pin high and the ESP32 thinks that the RAM voltage should be 1.8V, without the SD card this pin has internal pull-down to set the RAM voltage to 3.3V. This is actually mentioned in the notes from examples provided on the FABGL project, to quote:
notes about GPIO 2 and 12
    - GPIO2:  may cause problem on programming. GPIO2 must also be either left unconnected/floating,
              or driven Low, in order to enter the serial bootloader.
              In normal boot mode (GPIO0 high), GPIO2 is ignored.
    - GPIO12: should be avoided. It selects flash voltage. To use it disable GPIO12 detection setting efuses with:
                    python --port /dev/cu.SLAB_USBtoUART set_flash_voltage 3.3V
                       WARN!! Good for ESP32 with 3.3V voltage (ESP-WROOM-32). This will BRICK your
                              ESP32 if the flash isn't 3.3V
                       NOTE1: replace "/dev/cu.SLAB_USBtoUART" with your serial port
                       NOTE2: is downloadable from <a href="" rel="nofollow"> <a href="" rel="nofollow">

This further notes that GPIO12 should be avoided, a pitty no one told the maker of the VGA32 ESP card!

FIXED: I have tried the option of setting the flash voltage to overide the use of GPIO12 and can confirm on my vga32 ESP, it Works! Problem fixed no more issues with the SD Card. I urge you to check, double check and think carefully about creating a BRICK if you decide to try it as well. I am not recommending it as an action, but for me it worked.