PiTrex Wiki

PiTrexCore

PiTrexCore is the Linux-based software environment for the PiTrex, which is installed on the Micro SD card that goes into the Raspberry Pi Zero. It allows running some software that hasn't been (and maybe won't be) ported to bare-metal, such as MAME. It also allows using WiFi, and many Bluetooth and USB controller or audio devices.

PiTrexCore is based on PiCore 13.1.0 from the Tiny Core Linux project, with some things changed and removed in order to speed up boot time and allow easy installation by unpacking a ZIP archive onto a FAT32-formatted MicroSD card.

See the release notes and the readme for the current status and basic instructions. This page will describe some aspects in more detail.

Installation

The PiTrexCore software should be installed on a MicroSD card (between 256MB and 256GB) that has been formatted FAT32. New cards are likely to be already in FAT32 format, but some larger ones may be exFAT. Windows will not format drives larger than 32GB as FAT32 using its built-in format tool, so if you have a MicroSD card larger than 32GB and it's not already FAT32 formatted, a 3rd party tool such as FAT32format GUI can be used. On Mac it may be possible to format FAT32 using the "Disk Utility" program, or you may have to do it from the command-line. Linux users may use the graphical tool available in their distro, or "mkfs.vfat" at the command-line.

Once the SD card has been correctly formatted, open the ZIP file and copy everything over to the card.

Adding ROMs

The ZIP file does not include any Arcade ROMs due to copyright restrictions. Vectrex ROMs are supplied, and any added to the "vectrex" folder (or a folder inside it) should be added to the "Vectrex" menu when the Pi boots up.

Similarly, Arcade ROMs can be added in the "roms" folder. Inside here there are folders "37b16" and "0.106". For running the MAME emulator directly on the Pi, you need ROMs (in zip files) compatible with MAME version 37b16 in the "37b16" folder. If you use remote emulation on a PC with display via the Pi, you need ROMs (in zip files) compatible with MAME version 0.106 in the "0.106" folder.

Vector arcade ROMs that theoretically can be emulated are (the ROM ID is at the end of each line):

Atari Alpha One (prototype, 3 lives) mhavoc
Atari Alpha One (prototype, 5 lives) mhavoc
Atari Asteroids (rev 1) asteroid
Atari Asteroids (rev 2) asteroid
Atari Asteroids Deluxe (rev 1) astdelux
Atari Asteroids Deluxe (rev 2) astdelux
Atari Battle Zone (cocktail) bzone
Atari Battle Zone (set 1) bzone
Atari Battle Zone (set 2) bzone
Atari Black Widow bwidow
Atari Bradley Trainer bradley
Atari Gravitar (prototype) gravitar
Atari Gravitar (version 2) gravitar
Atari Gravitar (version 3) gravitar
Atari Lunar Battle (prototype, earlier) gravitar
Atari Lunar Battle (prototype, later) gravitar
Atari Lunar Lander (rev 1) llander
Atari Lunar Lander (rev 2) llander
Atari Major Havoc (prototype) mhavoc
Atari Major Havoc (rev 2) mhavoc
Atari Major Havoc (rev 3) mhavoc
Atari Quantum (prototype) quantum
Atari Quantum (rev 1) quantum
Atari Quantum (rev 2) quantum
Atari Red Baron redbaron
Atari Space Duel spacduel
Atari Star Wars (rev 1) starwars
Atari Star Wars (rev 2) starwars
Atari Tempest (rev 1) tempest
Atari Tempest (rev 2) tempest
Atari Tempest (rev 3) tempest
Atari Tempest (rev ?) tempest
Atari The Empire Strikes Back esb
Centuri Aztarac aztarac
Cinematronics Armor Attack (Rock-ola) armora
Cinematronics Armor Attack (prototype) armora
Cinematronics Armor Attack armora
Cinematronics Boxing Bugs boxingb
Cinematronics Cosmic Chasm (set 1) cchasm
Cinematronics Cosmic Chasm (set 2) cchasm
Cinematronics Rip Off ripoff
Cinematronics Solar Quest solarq
Cinematronics Space Wars spacewar
Cinematronics Star Castle (Mottoeis) starcas
Cinematronics Star Castle (older) starcas
Cinematronics Star Castle (prototype) starcas
Cinematronics Star Castle (version 3) starcas
Cinematronics Star Hawk starhawk
Cinematronics Sundance sundance
Cinematronics Tailgunner tailg
Cinematronics War of the Worlds (color) wotw
Cinematronics War of the Worlds wotw
Midway Omega Race omegrace
Other Asterock asteroid
Other Asteroids (bootleg on Lunar Lander hardware) asteroid
Other Delta Race omegrace
Other Demon demon
Other Major Havoc (Return to Vax) mhavoc
Other Meteorites asteroid
Other QB-3 (prototype) qb3
Other Space Fortress (Zaccaria) starcas
Other Stellar Castle (Elettronolo) starcas
Other Tempest Tubes tempest
Other Top Gunner topgunnr
Sega Eliminator (2 Players, cocktail) elim2
Sega Eliminator (2 Players, set 1) elim2
Sega Eliminator (2 Players, set 2) elim2
Sega Eliminator (4 Players) elim2
Sega Eliminator (4 Players, prototype) elim2
Sega Space Fury (revision A) spacfury
Sega Space Fury (revision C) spacfury
Sega Star Trek startrek
Sega Tac/Scan tacscan
Sega Zektor (revision B) zektor
Vectorbeam Barrier barrier
Vectorbeam Speed Freak speedfrk
Vectorbeam Warrior warrior

When ROMs are added in the "vectrex" or "roms" folders, the PiTrex software will identify them and, if they are compatible with the emulators, add them as options in the menu grouped by manufacturer. If the ROMs are incompatible, they will not appear. Note that this can delay start-up time, but only for the next start-up after ROMs have been added, removed, or changed, on the MicroSD card.

Variations of games are grouped and can be selected by moving the joystick left or right.

ROMs for the non-MAME arcade emulators, which are displayed as options in the "Linux" menu whether ROMs required by them are present or not, go directly into the "roms" folder. They can be zip files or, to minimise delays during start-up, extracted to folders with the same name as the expected zip file. Zip files here may also be used by MAME if version-specific ROMs are missing and these are compatible.

Adding PiTrex Games

Games and extra emulators may be distributed as individual files like game.tcz that can be added in the "tcz" folder on the MicroSD card. Some might come with a game.tcz.mnu file and/or a game.tcz.dep file that will also need to be copied to the "tcz" folder. These games should now appear as options on the "Linux" menu the next time PiTrexCore starts up.

Developers interested in making their own PiTrex games for PiTrexCore should read PiTrexCore_Internals and PiTrexCore_Extensions.

Using Sampled Audio

Some software, most notably MAME, doesn't support playing sounds via the Vectrex itself. A separate sound device can be started via the Linux section of the menu.

Note that in remote emulation mode the sound is played by the PC running the emulator, and not from the Pi itself. This is currently a better wireless approach for sound in MAME than using Bluetooth.

Bluetooth

Note: Bluetooth sound is currently very laggy and often cuts out. Once it's cut out a reboot is required to re-enable it. Games using ALSA-OSS (Zblast and Hyperoid) never seem to work with it at all. This is something that can hopefully be fixed later on.

To use a Bluetooth speaker a file must be created on the MicroSD card called "btdev_audio.txt", and this contains lines with the ID of each Bluetooth device that you might want to use (this ID may be described in the "pairing" section of your bluetooth speaker's manual, or printed on the speaker itself). Alternatively, if you can connect another device to the speaker, check the devices details to find the MAC address and use that instead or as well as the device ID.

Here is an example showing three bluetooth speaker IDs, and a MAC address at the end:

CP-OW-18-127
BTS-06
SB-02
93:39:04:05:91:A0

When the "Bluetooth Sound" option is selected from the "Linux" section in the menu, the Pi will scan for these devices and connect to the first one that it discovers (a connection sould should then be played by the speaker). During this time the Vectrex display will be blank. If no speakers are found after about a minute, it will time out and return to the menu.

If "startbluetooth" is added to the line in the cmdlinue.txt file on the MicroSD card, Bluetooth will be started during the boot process, which will cause it to take much longer before displaying the menu (Bluetooth pairing doesn't seem to work while displaying on the Vectrex screen).

USB

If you have connected a USB audio adapter to the Raspberry Pi Zero using an adapter cable, this can be activated by navigating to the "Bluetooth Sound" option in the "Linux" section in the menu, then moving right/left and selecting the "USB Sound" option that is then displayed.

WiFi

WiFi needs to be configured in a wpa_supplicant.txt file in the root directory of the MicroSD card, following the Raspberry Pi OS instructions from a PC, with the MicroSD card in a card reader. Thereafter WiFi is initialised when "Start WiFi" is selected from the Linux section of the menu. Note that the screen will be blank while a connection is being established.

If "startwifi" is added to the line in the cmdlinue.txt file on the MicroSD card, WiFi will be started during the boot process and run in the background to minimise any extra start-up delay. Note that this may be less reliable than starting from the menu because WiFi network discovery doesn't seem to work as well while displaying on the Vectrex screen.

Remote Emulation

To maximise performance on the Raspberry Pi Zero, an older version of the XMAME MAME emulator is used with it, and some emulated arcade games still run too slow anyway. For best performance, as well as an alternative to USB or Bluetooth audio for playing arcade game sound effects, a newer XMAME can be run on a PC while the display and crontrols are handled on the Vectrex.

Once the PC has booted to the live CD or USB drive written from the ISO image available from the download page, and connected via Ethernet or WiFi (Ethernet is recommended for best performance, and because WiFi settings aren't remembered after rebooting) to the same local network as was configured in wpa_supplicant.txt on the Pi's MicroSD card, select "XMAME Local/Remote" from the "Linux" section of the menu. If WiFi was not already started, it will be started now using the configuration in wpa_supplicant.txt as described above. The Pi will now find the PC on your network using mDNS and switch to using it for running the emulation of arcade games selected from the manufacturer-specific game lists. You now need the 0.106 MAME ROMs instead of the 37b16 ROMs for the emulation to work. Select "XMAME Local/Remote" again to switch back to running arcade emulations on the Pi itself.

The PC doesn't need to be very powerful. Minimum CPU specifications are x86 or x86_64 roughly 1.5GHz single-core, and at least 256MB of RAM. An old laptop might work well. PC Virtualisation or emulation (eg. VirtualBox, QEMU) could also work, but the emulated network interface must be able to get a unique IP address on your local network ("bridge mode") so that the Pi can connect to it.

Customising Menu Items

For any ROM or game, the directory where each file is located is checked for a matching .mnu file (so this may be in the form of: game.tcz.mnu, game.zip.mnu, game.bin.mnu). This is a text file containing one or more menu entry lines for the VMMenu menu sfotware. For MAME ROMs these files are automatically generated, and for tcz files there are some default entries in the "defalts" folder inside "tcz". If these files are added or customised, they will override the automatic generation of menu lines.

Customising X server configuration

Games that display via the Xvectrex display server can have controller button assignments and display settings customised by adding game.cfg files in the same folder as the corresponding game (.tcz) or ROM (.zip) file. These override the default XF86Config files used when starting X-based games and the MAME emulators. See the "Configuration" and "Drivers" section of the Xvectrex readme for an example and descriptions of the options available for the Vectrex X drivers.

As a starting point, these are the default files used for digital and analogue controlled games in MAME.

Besides the drivers that are used to make the Vectrex controller appear as a keyboard or mouse, a real USB keyboard or mouse can also be connected and configured for use via a .cfg file.

More information about how the X display server is used is in Xvectrex.

Support for Bluetooth joysticks and controllers is planned for the future.

Raspberry Pi Zero 2 W

The Raspberry Pi Zero 2 W will boot and start programs faster than the original Pi Zero, however there are some more bugs when using it, including that Bluetooth audio might not work at all. Overall an original Pi Zero is recommended at the moment, although better support for the Pi Zero 2 is being worked on.

Although it might introduce occasional glitches in the display, you can remove "nosmp" from the cmdline.txt file for increased performance of the MAME arcade emulator with the Pi Zero 2.