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 [http://www.tinycorelinux.net/|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 [http://www.ombertech.com/cnk/pitrex/wiki/index.php?wiki=Entry-2023-06-08_02-46-43|release notes] and the [http://www.ombertech.com/cnk/pitrex/ftp/cnk/pitrexcore/ZIP_README.txt|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 [http://ridgecrop.co.uk/index.htm?guiformat.htm|FAT32format GUI] can be used. On Mac it [https://toolbox.iskysoft.com/mac-data-recovery/format-fat32-and-ntfs-drivers.html|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 [https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-networking-2|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 [http://www.ombertech.com/cnk/pitrex/ftp/github/xc/pitrex_README.txt|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 [http://www.ombertech.com/cnk/pitrex/ftp/github/xmame-0.37b16.1/XF86Config|digital] and [http://www.ombertech.com/cnk/pitrex/ftp/github/xmame-0.37b16.1/XF86Config_analogue|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.
