This guide describes software set-up for the PiTrex Developer_Release. See the hardware guide for the PiTrex hardware configuration.

For a bare-bones command-by-command walk through of one potential installation process, see Linux_Example.

Step 1 - Installing the OS Image

This requires a PC with some form of MicroSD card reader, or a full-size SD card reader and a MicroSD-SD card adapter. It should support SDHC SD cards to be able to access cards over 2GB in storage size, SDXC for cards greater than 32GB.

Installing Linux to your MicroSD Card

Most Linux distributions available for the Raspbery Pi are suitable for running and developing PiTrex software. Raspberry Pi OS (formerly Raspbian) is the official Raspberry Pi distribution, so we will focus on that, however the process should be similar or identical for installation of any Linux distro that has support for the Raspberry Pi.

A desktop environment isn't required for running or developing PiTrex software. The required tools are all command-line based, and load on the Pi itself should be minimised while PiTrex software is running. As such the minimal "Raspberry Pi OS (32-bit) Lite" image can be downloaded from the Raspberry Pi OS download page outlink.

Installation of the Raspberry Pi OS Lite SD card image should be to a MicroSD card between 4GB and 256GB in size (other distros may fit on MicroSD cards with less than 4GB). The official installation guide outlink describes how to do this using either the Raspberry Pi Imager program, or using common command-line tools such as "dd" on Linux/Mac.

Other distros that have been used:

  • PiCore outlink port of Tiny Core Linux (small, fast start-up)
  • RealtimePi outlink (real-time patched kernel and generally optimised for embedded applications)

Step 2 - Installing PiTrex Bare-Metal Binaries

Note: All PiTrex software now runs fine in Linux (after configuration described in Step 5). If you don't want to run bare-metal yet then skip to step 4. Bare-Metal binaries can be installed later following these same instructions.

With the Linux SD Card image installed to your MicroSD card, remove and reinsert the card so that your PC detects the new partitions and file systems configuration. The first partition (possibly the only one visible in Windows and MacOS) is where the bare-metal software needs to be installed (when accessing from the Pi0 itself, this will be mounted as "/boot").

Bare-Metal binaries are available in the "to_baremetal" directory of the PiTrex Beta tarball (except for some arcade emulators which may need to be compiled with the original ROMs). Download this from the GitHub releases page outlink and copy the files to the root directory of that partition. So that the Bare-Metal menu program will load instead of Linux at boot time, add this line to the config.txt file which came with the Linux installation:

kernel pitrex.img

Note that right now there isn't really much besides the emulators for Bare-Metal, just Gyrocks. Zblast and Hyperoid only run in Linux.

Step 3 - Booting the Bare-Metal Environment and Linux

With the Pi0 inserted in the PiTrex cartridge's GPIO header socket (see hardware guide), insert your freshly baked MicroSD card into the Pi0. Now when you insert the PiTrex cartridge in your Vectrex and turn the Vectrex on, the LED on the Pi0 should flicker for a bit before the PiTrex menu loads (with its own verbal exclaimation!) and displays a list of options on the screen.

Each entry in the menu runs a bare-metal binary (".img" file) from the first partition of the MicroSD card. While running these, buttons 1+2 can often bring up a Calibration menu, and pressing all 1+2+3+4, or the Vectrex's Reset button, should return to the menu. The bottom-most option in the menu boots the Linux distro that you installed earlier (this may not work with all Linux distros, Raspberry Pi OS recommended).

Step 4 - Connecting to the Pi0

As your Linux distro isn't set up for the PiTrex, it won't display anything on the Vectrex automatically after start-up, the idea is that you connect to a terminal (command prompt) via one of the methods in the hardware guide.

Unless you're accessing the Pi0 directly via the video output and a USB or Bluetooth keyboard, you'll need software on your PC for accessing the Pi0 remotely.

In Raspberry Pi OS the default username is "pi" and the password is "raspberry".

Direct Connection

Terminal Access

If you've got a monitor and keyboard connected, all should be pretty obvious once the OS has booted up. If the display doesn't come up, consult the HDMI Configuration guide outlink for Raspberry pi OS and/or the video options outlink in config.txt.

File Transfer

Pulling out the SD card will mean rebooting the system, so often that's not a practical option for moving files about when running Linux.

You'll probably want to connect a USB storage device. For this you'll need an adapter from the Pi0's MicroUSB port to a USB Type-A socket, and it might need to be an FFC type one as noted in the hardware guide. If that's how you've got your keyboard connected, then you'll probably notice the lack of other USB ports (the outer one is just for power, remember), so it'll be time to grab a USB hub to connect everything through.

If powering the Pi0 from the Vectrex, remember that the USB storage device will be powered from it too. A regular USB flash drive shouldn't draw too much power, but an external HDD would definately be pushing things.

Network Connection


If you plan to connect to the Pi0 over WiFi, the network settings for your WiFi access point need to be configured before-hand. See the official guide for headless WiFi configuration outlink with Raspberry Pi OS.

Alternatively you could use a direct connection or serial connection while access is easier without the PiTrex and Vectrex attached, in order to configure WiFi from the command line outlink in advance of using the PiTrex cartridge.

Terminal Access

Linux and Mac commonly come with a built-in command-line SSH client. Simply type "ssh pi@<Pi0 IP address>" or "ssh pi@raspberrypi" (you might use "raspberrypi.local" as the hostname if using a USB OTG/Gadget mode network connection).

Windows users will likely need to install an SSH client such as PuTTY outlink (also available for Linux and Mac).

File Transfer

Various methods are available for transferring files between your PC and the Pi0 without having to remove the MicroSD card and therefore reboot the system. You can use a USB drive as described for Direct Connection, but it may be more convenient to transfer files over the network. On Linux and Mac, scp, ftp, sftp, and rsync are likely to be installed. Windows includes a command-line FTP client and PuTTY outlink includes command-line scp and sftp clients. Filezila outlink is a GUI FTP client that also supports SFTP and runs in Windows/Linux/Mac. With all these options, the best choice might be the one that you already know.

You can also use Network File System (NFS) to share a directory on the Pi with other PCs, so that files on the Pi0 can be accessed directly from software running on your PC. There is an official guide outlink for setting this up with Raspberry Pi OS.

Serial Connection

Serial connection is recommended for developing software in the Bare-Metal environment because it is required in order to access the debugging interface.

The baud rate used is 115200, this, along with the serial port device name (eg. /dev/ttyUSB0 on Linux), must be configured in any serial comms software that you use to connect from your PC.

Terminal Access

Some Linux distros come with a serial terminal program such as Minicom installed. There are a variety that can be installed for Linux/Mac. PuTTY outlink for Windows/Linux/Mac can connect to a serial terminal. You'll need to work out the device name of your serial interface, eg. /dev/ttyUSB0 on Linux, and tell this to the program.

File Transfer

USB storage devices can be used, as described for Direct Connection.

To avoid physically swapping a storage device back and forth requires a protocol such as Kermit outlink by which files can be transferred over the serial connection. Software for this will probably need to be installed on the Pi0 in advance, so you'll have to download the required packages manually using a PC and put them on the SD card or a USB drive so that they can be installed with "sudo dpkg -i <package file names>". Then follow the instructions for the software that you've chosen to use.

Network Connection over Serial Connection

With Point-toPoint Protocol (PPP) it is possible to establish a network connection over a serial connection to another PC, allowing all of the options for communicating over network connections to be used. See the eLinux RPi serial connection guide outlink. This could also be used to establish an internet connection to the Pi0, with corresponding configuration on the connected PC.

Step 5 - Setting up Linux

Some particular configuration is required so that PiTrex software runs under Linux without tiny delays in execution causing random glitches on the Vectrex display. If not using the HDMI or Composite video output, then this is most simply acheived using the PiTrex configuration script outlink:

sudo ./

More Details about Linux configuration.

To run a binary that hasn't been installed in a standard binary location, use "sudo ./<binary file name>". Once installed, you should simply be able to type the name of the game/program and it will run like any other Linux program. Not all PiTrex software is currently set up for installing automatically using make, or from a pre-compiled package.

Alternatively, run "sudo ./ -configonly" so that HDMI and Composite video are not disabled. In this case always start PiTrex programs using the "START" script, provided for each PiTrex program in the Git repo with the capitalised name of the binary. For example "./TAILGUNNER" instead of "sudo ./tailgunner".

For VMMenu, the SDL library is currently required:

sudo apt-get install libsdl2-2.0-0 libsdl2-dev libsdl2-mixer-2.0-0 libsdl2-mixer-dev

The SVGAlib-Vectrex games, Zblast and Hyperoid, need the Alsa-OSS package:

sudo apt-get install alsa-oss

Installation of packages is far easier with an internet-connected Pi, though manual installation is possible by pre-determining all package dependencies and installing with "sudo dpkg -i" after copying all of them over from another computer.

Step 6 - Building PiTrex software in Linux

For now PiTrex software and the development environment is contained together in the PiTrex Git repo outlink. To get started, either use the link on the webpage to download a Zip archive and unpack with "unzip", or install git using:

sudo apt-get install git

then do:

git clone

Inside the resulting "pitrex" directory you'll find all of the PiTrex software, libraries (inside the second "pitrex" directory), and some relevant README files. Here, all of the PiTrex software can be compiled for Linux with the command "make -f Makefile.raspbian", or the same command inside individual program directories will build only those specific programs. The emulators may need MAME ROMs to be added in order for the build to work.

To compile your own PiTrex software, create your own directory. The Vectrex Interface and PiTrexio-GPIO libraries are used for controlling the Vectrex and communicating with the PiTrex cartridge, respectively, they are found in the second "pitrex" directory. Examples of using the Vectrex Interface library are in the "hello_world" directory. See Vectrex_Interface for library documentation.

The standard tools for compiling in Linux are used for the PiTrex software. GCC is the compiler used, and separate Makefiles are commonly provided for building binaries to run under either Linux or the Bare-Metal environment (see step 7).

Run your compiled Linux binaries simply by entering "sudo ./<binary file name>" at the command prompt, and use Ctrl-C to stop them if you can't exit normally via the Vectrex.

Terminal text editors such as Vim, Emacs, and Nano are able to be used on the Pi0 to edit files. Graphical editors and IDEs can potentially be installed if Linux packages are available, and used with X11 Port Forwarding over SSH ("ssh -X", or enabled in PuTTY's settings, start GUI programs from the terminal with "<program name> &" to maintain access to the command-line while the program runs). If the PC that you access the Pi0 from runs Windows, you'll need to install an X server such as Xming outlink on it for this to work (on Mac maybe something like XQuartz outlink?). On Linux this might be a simpler solution than setting up NFS if you're not happy being stuck with command-line tools or manualy transferring files from your PC.

Step 7 - Building for Bare-Metal

Bare metal software is compiled using a special set of compiling tools that is installed with this command (currently a 170MB download):

sudo apt-get install gcc-arm-none-eabi binutils-arm-none-eabi

Binaries should be copied to the first partition of the Pi0's MicroSD card which is mounted as "/boot". The file named kernel.img is booted by default on start-up, though this can be changed outlink by adding a "kernel <binary_name>.img" line to config.txt.

Developing bare-metal software on the Pi0 involves rebooting for every test. It may be easier to set up the custom compiler and PiTrex development environment on your PC and copy binaries to test onto the MicroSD card. This guide will not deal with the details of cross-compiling though.


Well how about it, you're all ready to start exploring and finding new things to do with the PiTrex. Have fun, and be sure to share what you get up to at the PiTrex developer's forum.