Linux Development Virutal Machine for 32blit SDK

October 23, 2021, at 04:21 AM by mgarcia in 2021, PC, Pics, GameDev, Blog (3 comments)

Title: Linux Development Virutal Machine for 32blit SDK Author: mgarcia Date: 2021-10-23 04:21 +0200 Tags: 2021, PC, Pics, GameDev, Blog Comments: Open

Image: Blog.2021-10-23-Linux-Development-Virutal-Machine-for-32blit-SDK

Click to view original image: 224kb


The VM is 32blit.7z, it is a 3.2 GB download and is 13.5 GB extracted.

It was created with Virtual Box 6.1, so you'll probably want to reinstall virtual box's guest tools. Auto log in as user dev
All passwords are: dev

It's MX-21_x64, set up with Eclipse CDT C/C++ 2021-09-R and builds for the following targets:

  1. Linux 64bit
  2. Windows 64bit (wine64 is also installed)
  3. Emscripten (chrome browser)
  4. Pimoroni 32blit
  5. Pimoroni PicoSystem
  6. Pimoroni VGA Board (aka Raspberry Pi Pico reference board, you can find it in chapter 3 of Hardware Design with RP2040 along with more general info about the VGA reference board.)

To install create a new Virtual Box application without the harddrive, then extract the 32blit.vbi into that folder and add the drive to the "virtual media manager" then add the drive to your VM application, configure it similarly to the images included and it should start fine. I recommend configuring the USB devices to auto connect to the VM guest, bidirectional copy and paste and a shared folder. How to use Eclipse and build the examples for each target is described at the end.

This is my personal VM, shared in the interest of helping the community. To my knowledge, there is nothing malicious or none GNU/free software.

Use at own risk, etc.

The challenge

ETA prime, did a review of the PicoSystem and threw down a challenge to play some community made games on his next video!


A New Handheld Powered By The Same Raspberry Pi Pico Chip!

PicoSystem's limitations makes it it's strength, by focusing on small 8bit or 16bit retro games, which also makes it ideal for game jams.

PicoSystem and VGA Board are very similar, so if you choose to get a VGA Board instead, I think that should be fine.

I see the VGABoard, as a console version, of a PicoSystem.

I'm not an expert, there's a lot of noob hacks here, but to encourage others, here are my notes on setting up.

32blit is very impressive how it can target so many platforms! Sorry I wont be mentioning Mac or chrome OS's, I'm not familiar at all with them.

I'm mostly in the 32blit discord (Chat) - But I can try and answer/help here to.

General noob tips

The 32blit documentation is pretty good, but I still got caught out here and there. Keep folders names simple, ie no spaces or none ASCI chars, including user name!

Make sure your .profile or .bash_profile etc can be run correctly in your window terminal before starting! Sometimes they have access issues, ie a quick fix can be:

chmod 777 $HOME/.bash_profile

If you want to build faster use:

make -j2

The number is the threads to run, the more the faster

I'm a git,cmake,arm noob, it's best to git clone each repo then to download them as zips, this is required by some, but best to do for all, IE:

git clone -b master

Each target has it's own build folder in the 32blit-sdk (or your game) folder

ie build.stm32 build.em etc.

Here is the directory structure, I've used:

> $HOME/	
>> 	emsdk
>> 	pico-sdk
>> 	32blit-tools
>> 	pico-extras
>> 	pico-sdk
>> 	gcc-arm-none-eabi-9-2020-q2-update (not required, and probably a me thing) 	
>>	.local/bin (auto generated - location of the 32blit tool)
>>	32blit-sdk (was 32blit-beta, latest branch for pico devices)
>>	32blit-sdk/
>>>>>   	build
>>>>> 		build.picosystem
>>>>> 		build.vgaboard
>>>>> 		build.win64
>>>>> 		build.em 
>>>>> 		build.stm32

My setup.

I thought I would use a new linux flavor, I went with MX (debian based) and picked XFCE (and unknowingly stable).

Here are the links:

–Xfce (our flagship desktop) MX-21_x64, with a standard 64 bit kernel and hardware support from Debian Stable. Suitable if your PC is a few years old.

Eclipse, my IDE of choose for over 20years now!

I installed this to a Virtual Box image, so it's self contained, the USB devices are automatically forward to the VM. To access the usb device from your account, enter:
sudo gpasswd -a yourusername vboxusers

log out and back in.


After install, run: sudo apt update

If VMWARE open-vm-tools should already be instaleld, don't use vmware's linux.iso. check vm tools is running: sudo /etc/init.d/open-vm-tools status

Test it by copying and pasting to and from VM, if not, installing the desktop might help: sudo apt-get install open-vm-tools-desktop reboot and test again.

Virtual Box, just insert VB tools cdrom and install.


sudo apt install git gcc g++ gdb gcc-arm-none-eabi cmake make python3 python3-pip python3-setuptools libsdl2-dev libsdl2-image-dev libsdl2-net-dev unzip

optional, handy to have installed:
sudo apt install p7zip-full p7zip-rar meld chromium-browser geany vbindiff audacity htmldoc lame imagemagick wine64 wine32

Old 2.8 gimp!

The OS app control keys are (see hardware-test app):

Dpad = arrow keys or WASD
A = Z key
B = X key
X = C key
Y = V key

Home = 1 key
Menu = 2 or ESC key

Joystick = Mouse within app screen
Joystick press = 3 key

Tilt controls, I don't know, gamepad right analog stick maybe?

32blit tool

I found this part a bit confusing.

In your $HOME folder (not 32blit root)

It also requires:


git clone

cd 32blit-tools

git clone

cp -a boilerplate-python/* .

Next, I had issues running pip3, not in the path (of sudo possibly), again, I brought forced scripts that used pip3, replacing it with: python3 -m pip


pip3 install 32blit


python3 -m pip install 32blit

or to update it, run:

python3 -m pip install --upgrade 32blit

That will build tool and install the tool into ~/.local/bin and add the path to your env file setting, ie .profile

Setup and build the linux native


Setup it, in user root (ie ~):

git clone

Building it is unnecessary, except to test the toolchain and see the demo's etc.

cd ~/32blit-sdk
mkdir build
cd build
cmake .. -D32BLIT_DIR=$HOME/32blit-sdk
make -j2

run and test the exe's

stm32 (32blit)

AKA 32blit: Follow:

Make sure to have a fat32 formated SD card handy!

cd ~/32blit-sdk
mkdir build.stm32
cd build.stm32
cmake .. -DCMAKE_TOOLCHAIN_FILE=$HOME/32blit-sdk/32blit.toolchain -D32BLIT_DIR=$HOME/32blit-sdk

make -j2

When linking the executables, you'll see a warning like this:

[ 97%] Building CXX object CMakeFiles/game.dir/assets.cpp.obj
[100%] Linking CXX executable game.elf
warning: cannot find entry symbol Reset_Handler; defaulting to 00000000900001a0

Building game.bin
   text	   data	    bss	    dec	    hex	filename
  21688	    904	   2280	  24872	   6128	/home/dev/eclipse-workspace/test/build.stm32/game.elf

There are 42 section headers, starting at offset 0x988a0:

The reason for this is because games don't have a reset handler (only the firmware does).

On my debian stable, or the MX repo the gcc-arm-none-eabi package (from 2018) couldn't build the stm32. I had to "brute force it"... and downloaded the tar.bz2 file and extracted it and manually fixed up the paths in .profile PATH="$HOME/gcc-arm-none-eabi-9-2020-q2-update/bin:$PATH"

gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 from

I had to specify -DPICO_TOOLCHAIN_PATH=$HOME/gcc-arm-none-eabi-9-2020-q2-update in stm32/pico cmake commands below.

TTY permissions

Before plugging in 32blit or a pico device, do this, give your user access to serial device! On linux, both devices uses: /dev/ttyACM0

sudo usermod -a -G tty username

update firmware.

Updated the firmware, if it's old.

cd ~/32blit-sdk/build.stm32

Put the 32blit in DFU mode (hold X/Y and press reset) , plug the USB cable in.

32blit flash firmware/firmware.bin


make firmware-update.flash

next install the launcher:

32blit install launcher/launcher.blit


make launcher.flash

If the 32blit is disconnected while flashing, it will kill the launcher, just reflash/install as above.

I recommend copying all .blit files (including the launcher.blit) to SD card first, and installing from there, using: 32blit install filename.blit /

Install all the other demos (see bottom of Makefile for more info):

make install DEMO-NAME.flash

You now should have a working and demo loaded 32blit!



git clone
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./

make sure paths are correctly executed when a new shell/terminal is open,it should automatically run source $HOME/emsdk/

cd ~/32blit-sdk
mkdir build.em
cd build.em

emcmake cmake .. -D32BLIT_DIR=$HOME/32blit-sdk 

************* hitting 16MB default limit *************

edit CMakeCache.txt

add -s TOTAL_MEMORY=67108864 to the LINKFLAGS

32MB = 33554432 
64MB = 67108864 

//Flags used by the linker during all build types.

It should automatically update the linker settings: CMakeFiles/game.dir/link.txt
If not, add it to the line after em++

Looking at the link.txt file above it also lets you change the shell-file which is normally at /home/dev/32blit-sdk/32blit-sdl/emscripten-shell.html, this HTML file sets the title

************* hitting 16MB default limit *************

make -j2 (or more, takes a long time!)

I like to create a script file that starts the server is helpful:

python3 -m http.server

Run in a terminal and CTRL C to stop it.

I don't know why, but firefox doesn't like it, chrome browser works fine.
The keyboard buttons (from hardware-test app):

Same as the native OS controls.


I don't have much experience with Android, the little I know is old school, but I got 32blit working with ant build, not gradle.

There are two archives here:

SDL2-32blit-Ouya-Android6-linux-development-envirnoment.7z 1.6G
This is all the Android tools and source to build the 32blit hardwaretest demo as signed, release apk, includes source NDK and SDK used to for example, extract the Android folder to the /home/dev folder in the Linux VM, put your game in the jni/game folder, modify the file and it should just work.

Source-Code-only-no-dev-env-ouya-android-PC.7z 36.9M
This is just the source folders to build the hardwaretest apk, it's include in the above files also, it includes:

  1. hardwareTest - added SDL2 embedded GameControllerDB support
  2. ouya-android - hardwareTest for Ouya, it's very hacky, I had to replace the button presses with keyboard keys, but it works.
  3. newer-android - hardwareTest for Android 6, it all works as expected and runs well.

windows exe


I use:
sudo apt-get install mingw-w64
Not the documented:
sudo apt install gcc-mingw-w64 g++-mingw-w64

after: sudo mkdir -p /opt/local/

make it accessible:
sudo chmod -R 777 /opt/local

cd  /opt/local 

and download and extract as per instructions.


in 32blit-sdk root
mkdir build.win64
cd build.win64

cmake .. -DCMAKE_TOOLCHAIN_FILE=$HOME/32blit-sdk/mingw.toolchain -D32BLIT_DIR=$HOME/32blit-sdk
make -j2

optionally install wine
sudo apt install wine64 
recommend installing wine32, also.

installs as: /usr/bin/wine64-stable or just wine.
test: /usr/bin/wine64-stable examples/geometry/geometry.exe

setting up PicoSystem / VGA BOARD



Both being based on the RP Pico, require the same source code, nothing is built in these folders.

Also read the PDF section 2.1. Get the SDK and examples

In your $HOME folder (not 32blit root)
git clone -b master
cd pico-sdk
git submodule update --init

cd ~

git clone -b master

cd into ~/32blit-sdk


PicoSystem Bleeding edge!

Note: below is based on old info, using the 32blit-sdk as normal. Docs are here:

Both devices are under heavy development currently!

The newer branches of 32blit-sdk has better performance and feature support ie USB support for VGA board, it's called 32blit-beta instead of 32blit-sdk. But the two can be used together by using the beta folder with pico devices, ie:

cd $HOME

git clone -b pico-all-the-boards --single-branch

This branch requires the latest tinyUSB

cd $HOME/pico-sdk/lib/

mv tinyusb tinyusb.orig

git clone

The new source code is referenced from the 32blit-sdk root builds, ie:

In 32blit-sdk root

mkdir build.picosystem

cd build.picosystem

I dev in linux and test (release build) on picosystem with:

cmake .. -DCMAKE_TOOLCHAIN_FILE=$HOME/32blit-sdk/pico.toolchain -D32BLIT_DIR=$HOME/32blit-sdk -DPICO_SDK_PATH=$HOME/pico-sdk -DPICO_EXTRAS_PATH=$HOME/pico-extras -DPICO_BOARD=pimoroni_picosystem -DCMAKE_BUILD_TYPE=Release

make -j2

The VGA board is similar as above, but with -DPICO_BOARD=vgaboard instead of -DPICO_BOARD=pimoroni_picosystem

repeat for vgaboard into new build folder, ie:

in 32blit-sdk root

mkdir build.vgaboard

cd build.vgaboard

mkdir build.vgaboard

cd build.vgaboard

cmake .. -D32BLIT_DIR=$HOME/32blit-sdk -DPICO_SDK_PATH=$HOME/pico-sdk -DPICO_EXTRAS_PATH=$HOME/pico-extras -DPICO_BOARD=vgaboard

make -j2

Pico, VGA & 32blit USB TTY printing

Make use TTY permissions is correct.

32blit can printf to the TTY terminal using:
blit::debugf("Play Sound \n");

Text is output via USB using the TTY, so install one, ie:
sudo apt-get install putty cu minicom screen

I found screen to work the easiest (no params)
display text output screen:
screen /dev/ttyACM0 115200

log file:
screen -L /dev/ttyACM0 115200

make; 32blit install game.blit ; screen -L /dev/ttyACM0 115200

In my experience, the logging can sometimes lock the 32blit and the terminal!

Alternatively, a simple cat of the tty device, also works fine:

cat /dev/ttyACM0

new project


cd into the folder you want to start a in project, ie:

cd $HOME/eclipse-workspace

git clone PROJECT_NAME


next you have to build it to set the executable, same process as above:

mkdir build

cd build

cmake .. -D32BLIT_DIR=$HOME/32blit-sdk -DCMAKE_BUILD_TYPE=Debug

make -j2

run it: ./game

You can create a new build folder for a release target, etc

I use a new release build directory, just run the same cmake command but with: -DCMAKE_BUILD_TYPE=Release

If you are targeting linux, I would suggest building with standard libraries statically linked... add the follow to the top (after project(32blit)) of 32blit-sdk/CMakeLists.txt:


       set(CMAKE_SHARED_LINKER_FLAGS "-static-libgcc -static-libstdc++ -static")

        MESSAGE(DEBUG "Linux os: ${outOS}")
        MESSAGE(DEBUG "Windows")       
        MESSAGE(DEBUG "No OS detected!")

How To Use Eclipse

I'm sure there's better ways to work with eclipse and cmake projects, but here's how I do it:

import the PROJECT_NAME folder as an existing code as makefile project. 

right click build->game -> run as -> local C++ app - double click C/C++ app.

click menu run -> run configuration, click 'build configuration' append build/ to  build director: ie ${workspace_loc/PROJECT_NAME:}/build/ click apply

Now if you change game.cpp it'll compile first before running.

Next, set the default header full paths for include SDL2/32blit-sdl/32blit.

right click main project -> properties -> C/C++ general -> Paths and symbols,  add to include directories individual, tick add to all config and languages:


Note: change dev to your username.

click apply.

right click main project, index -> rebuild 

CTRL left mouse click a 32blit classes/function and you should drill down into it, ect.

To debug, set a break point and click debug icon

To target other platforms, create a new build folder and use the same cmake parameters as above when building the 32blit-sdk examples.


mkdir build.em
cd build.em
emcmake cmake .. -D32BLIT_DIR=$HOME/32blit-sdk

python3 -m http.server

now, launch chrome browser, click game.html, close browser

ctrl -c to cancel server.

My 32blit Unboxing

Originally from: 2020 28th March - Warning, it's uses Text To Speech!

  32Blit, A modern day Net Yaroze, Retro hardware game development 

32Blit, A modern day Net Yaroze, Retro hardware game development

What to do next?

Using Eclipse (or your favorite IDE), import the 32blit examples, to look through the source code.

In Eclipse, the easy way is to create a new Project, by:
File -> New -> Project

Select "Makefile Project with Existing Code", next.

Click brows and select ~/32blit-sdk/examples

Next, pick Linux GCC and click finish.

Now, set the default header full paths for include SDL2/32blit-sdl/32blit as explained prior.

You'll have all the examples ready to read, however, you can't launch, compile or debug them.

32blit API Documentation

Although, there's not much documentation in 32blit API, it's included here, in a separate file.

But to recreate the doxygen doc's run:

sudo apt update && sudo apt install doxygen graphviz python3-setuptools

cd $HOME/32blit-sdk/32blit && doxygen doxygen.conf

Fix the scroll bars being too small

Change text size

MX Tweak - appearance (button bot right) - fonts tab - default font.

File browser shortcuts

Create shortcuts on the file browser, right click and send to -> side pane.

Launch exe's

zenity --question --text="What to do with the executable file '$1'?" \
       --ok-label=Run \

case $? in
    0)xfce4-terminal -e "$1"
    1)geany $1

[Desktop Entry]
Exec=bash -c '/home/dev/ %f'

Updating 32blit SDK

The VM image is pretty old now, and require new sources to be updated. Start with building the 32blit tool and the 32blit SDK for each target... it should just work!


In general, if you have any windows issue search it with Xfce.

If you have a file browser issue search it with thunar or MX linux.

I like having all my tools in the VM, so I install gimp etc.

3 comments on "Linux Development Virutal Machine for 32blit SDK"

  • Christopher Richards: 2022-11-19 20:27 +0100
    I appreciate it, that you're a pleasant guy who gave us all these. Thanks.
  • Christopher Richards: 2022-11-19 20:30 +0100
    If it is a book, could buy, globally from amazon as soon as we save up enough
  • mgarcia: 2022-12-06 01:21 +0100
    No problem, it's just my notes, that grew and grew :D

Comments are open.

Your name or alias (required):

Your plain text comment (required):

Your entered name and comment will be displayed above this form.
There is no reply notifications or editing of comments.

 Enter value: 8053  

RSS Feed @mgarcia_org Twitter Feeder my random Youtube videos
An IndieWeb Webring 🕸💍

Page last modified on January 13, 2023, at 02:08 PM and visited 1888 times.

Powered by PmWiki