Newsletter #0 - The PiTrex Card

Creating unique games for the PiTrex #pitrex #vectrex #retrogaming

Introduction

This is an introduction post (therefore called newsletter #0) that summarises what you can expect, and how you set up the Pitrex and give you some news on how to do that even easier. But now, let’s start!

What is the PiTrex?

The PiTrex cartridge connects a Raspberry Pi Zero with a Vectrex. It is a cartridge that allows running programs and games on the Raspberry Pi which can use the Vectrex as a vector monitor and use the Vectrex controller as the input device. But for what is that good? Well, first and foremost this combination allows you to write completely different calibers of games. As a developer, you can use the CPU power and memory of the Pi, while the Vectrex brings in its capabilities to display vector graphics. If you have ever written games for Vectrex, you will know that’s a game changer. Native programs on the Vectrex have always the challenge that you have just a few cycles per frame available for your own code. Most of the time is used for displaying graphics. Complex programs and games are not possible like that. The other challenge is the RAM you have available for your program. It’s 1024 Bytes! Yes BYTES, not kilo-bytes or megabytes or even giga-bytes as in today’s machines. In comparison to that, the Raspberry Pi Zero is a beast :

• 64-Bit ARM CPU (vs. 6809 8-Bit CPU)

• 512MB (vs. 1024 bytes)

• 1 GHz Cpu (vs. 1.5 MhZ)

• PLUS: Wireless Connectivity

For who is the PiTrex?

At the moment the PiTrex is a device intended for developers and can be used in two flavors:

• Like a game cartridge (bare-metal image)

• Raspberry PI OS mode (As a real Linux computer)

My newsletter is mainly about the second option because it provides a lot of possibilities. The disadvantage is that it’s not as easy to use out of the box. You need to have an idea of how a Raspberry Pi with its Linux-like OS works. But that I will change with some tools and enhancements I will introduce with the upcoming newsletter posts, so that end-users are also able to just plug & play and use the PiTrex as is.

Why did I start this Newsletter?

I think the Pitrex is an exceptional cartridge with huge potential. While the team behind (see section “Honors” below) does a great job on the base implementation it will need our entire community to build an ecosystem on it and some new games and content. Because I have already done a lot but (except Chess) never released something final to the community, I have started this newsletter with the intention to finish and release all step by step in 2023 and the upcoming years.

For Gamers

Setup & Usage

The installation is not super complicated but needs some know-how in Linux to set it up properly. This hurdle I have removed and gamers and content creators can use the PiTrex without any technical knowledge by using a web interface.

I created some pre-configured SD card images which you can order here for free if you are a paid subscriber. Everyone else with a free subscription receives the link to a free-to-order page at end of January.

If you want it, even more, easier than that, just order an SD card all pre-configured and ready to use here. This is available for everyone interested in it after January 10th.

Vexxon - The Game

Maybe you have subscribed here because you have already read about Vexxon or seen some short videos and info.
Vexxon is actually a Zaxxon alike game I work on and will finish as part of this newsletter. It’s a perfect game for the PiTrex and act’s also as a base to create more games on top of the engine. It will also be the base of a creation tool (non-coding tool) that will be announced in the second half of 2023.
But step by step. The plan is to write in the next post about the background, the design, and the prototype. The first level should be finally ready end of January to try out. It will be a free game, like all the games and content I create, but will also have some extras for paid subscribers. Stay tuned for more at the end of this week.

For Developers

If you are a developer or want to start with it you will always find some detailed information to do so. All are free and available at every subscription level.

See below the section on how to set up the PiTrex by yourself if you wanna start now.

Vexxon - The Game

I believe Vexxon will also be very interesting for (aspiring) developers. I will go into the source code, explain some techniques and also show the base architecture and best practices I use when programming for the Vectrex. So the next post is also for you!

You can’t wait? Then buy a Pitrex now or if you have already one, do the setup by following the steps below.

Requirements to use the PiTrex

To use the PiTrex you need:

• The PiTrex card itself (Order here)

• A Raspberry Pi Zero WH (Take the WH model to save time and even money)

• An SD card writer/reader

• An SD card of a minimum of 8GB (Take better a minimum of 32GB to also have enough space for ROMS etc.)

• And of course a Vectrex

If you have all that, you’re ready to go!

Install the SD Card

This installation guide is for macOS, Windows is coming soon

First, connect your SD card reader and insert the card. To continue you need to know the device number. This can be easily found out with the command:

diskutil list

It’s most of the time the last card in the list (in my case and in this example #3, so you would have to use/dev/disk3). If your SD card has a different number replace it in the script below. To use the piTrex later it’s also needed to connect it to your Wifi. This is also handled by the script. Just replace

• NETWORK-NAME with the name of your WiFi Network

• NETWORK-PASSWORD with the password you use for the WiFi network

$ curl -o pitrex8gb.zip http://classicscoder.com/downloads/pitrex8gb.zip
$ unzip pitrex8gb.zip
$ diskutil unmountDisk /dev/{disk number}
$ sudo dd bs=1m if=pitrex8gb.img of=/dev/disk{disk number}
$ touch /Volumes/boot/ssh
$ touch /Volumes/boot/wpa_supplicant.conf
$ echo 'country=US' >> /Volumes/boot/wpa_supplicant.conf
$ echo 'ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev' >> /Volumes/boot/wpa_supplicant.conf
$ echo 'update_config=1' >> /Volumes/boot/wpa_supplicant.conf
$ echo '' >> /Volumes/boot/wpa_supplicant.conf
$ echo 'network={' >> /Volumes/boot/wpa_supplicant.conf
$ echo '    ssid="{NETWORK-NAME}"'>> /Volumes/boot/wpa_supplicant.conf
$ echo '    psk="{NETWORK-PASSWORD}"' >>/Volumes/boot/wpa_supplicant.conf
$ echo '}' >> /Volumes/boot/wpa_supplicant.conf
$ echo 'Dont forget to set NETWORK-NAME and NETWORK-PASSWORD in/Volumes/boot/wpa_supplicant.conf'
$ echo 'After unmount sd card by using: diskutil eject /dev/{disk number}'

After the script is finished (this may take some minutes) you eject the SD card with the command

$ diskutil eject /dev/{disk number}

That was already the “hard” part, now to the fun part :)

Setup the PiTrex

In this article, I assume that you have already connected the RaspPi to the PiTrex card and plugged it into the Vectrex

After you start the Vectrex the screen will remain black and the RaspPi needs time to start up. When it stops blinking it should be ready and you can use the Terminal window now to connect to your RaspPi:

$ ssh pi@raspberrypi.local

If all was going well you should now see the RaspPi asking for the password. It’s initially pitrex. The SD card comes with all pre-installed but it’s most probably not the newest version. So it’s always safe to get the newest version from GitHub and build all.

$ sudo apt-get update
$ sudo apt-get install -y gcc-arm-none-eabi git-core libsdl2-dev libsdl2-2.0 libsdl2-mixer-2.0-0 libsdl2-mixer-dev alsa-oss locate
$ mkdir ~/src
$ cd ~/src
$ git clone https://github.com/gtoal/pitrex.git
$ cd ~/src/pitrex
$ sudo cp pitrex-config.sh /boot/
$ make clean all -f Makefile.raspbian

Note: You will see some errors regarding Tailgunner and Asteroids. For now, you can ignore them. We take care of this later.

When all is compiled, linked, and installed you have to use one last script by entering:

$ sudo /boot/pitrex-config.sh

You get asked at the end if you want to disable HDMI. Answer with YES and it’s all done. After the installation, it’s safe to shut down the RaspPi

$ sudo shutdown -h 0

and switch it off and on again to the Vectrex to restart it.

Now you’re ready to see the first game in action.

Log in again to Vectrex

$ ssh pi@raspberrypi.local

enter the password and start the first game with

$ sudo ~/src/pitrex/gyrocks/gyrocks

Outro

I hope you liked this first intro newsletter and stay tuned for the next one. Just let me know what you like and what you would change or improve.
It’s also quite new for me and there is a lot of work at the beginning until all is set up properly writing the newsletter and content at the same time also needs quite some effort :)

Thank you for subscribing!

Honors

This awesome project is founded, initiated, and mainly driven by 4 people that had the idea, realized the hardware, and created the libraries needed. It’s Kevin Koster, Malban, Graham Toal, and James Churchill.

KUDOS for creating this awesome project and making it even open-source and reachable for everyone interested. You guys rock!

What’s next?

After successfully installed and setup the PiTrex, the next post is about Vexxon - The Game and How to create your own games or programs for the PiTrex!
Until then, have fun!

Links

• If you don’t have one already, order a PiTrex now

• Order a preconfigured and ready-to-go SD card

• Read the official Project Wiki

• Read the official Official installation guide

• Take a look at the official GitHub repo