Well, ok, there actually is a Lego Game Boy and it has just been released today yesterday. What there actually oughta be is a real display for it, which this blog post is about.

If you just want to see it in action, check out the Youtube video. If you want to add a display to your own Lego Game Boy, read on for all the details on how to do this.

Please note that this article contains affiliate links, i.e. links that tell the target site that I sent you there and that earn me a share of their revenue in return, i.e. as an Amazon Associate I earn from qualifying purchases. In contrast to regular external links, such affiliate links are marked with a dollar sign instead of a box.

What and why?

Ok, I probably have to put a short disclaimer in front of this post. No, this is not as fancy and elaborate as many of my other posts. I literally just researched a screen of the right size, looked for a proper open source emulator and put everything together. The biggest contribution from my side might actually be a simple 3D printed adapter. But it worked out so nicely, I just couldn’t resist making a video about it.¹

What am I even talking about? Well, about Lego’s new Game Boy model (72046). They released it today, but when I saw its announcement a while ago I knew I had to pre-order it. I also already had a place in mind where I’d put the model on display as it would look really nice next to my Wooden Game Boy. But while I was patiently waiting for its release I realized that there is an important difference between my wooden Game Boy and the Lego Game Boy: The wooden one has a modern IPS backlit display, while the Lego Game Boy does not have an actual display at all.

Don’t get me wrong. Lego did not just put a void into the display area of their model. On the contrary: They created linticular displays that look very similar to the original Game Boy and which even simulate a moving image. These are fantastic and such a clever solution!

These lanticular displays are much closer to the original Game Boy than what my wooden Game Boy does and my modification to the Lego model will actually bring it farther away from the original. But the thing is that my wooden Game Boy will literally outshine the Lego one and I want to balance the looks on the shelf by adding a real display.

What you need

So, I researched ahead and found that the display of the Lego model is a 6 by 6 window², which my sons had handily available in their huge Lego stash. With that as a reference I did some research and ended up with a fitting display and a small microcontroller to run it. Here is the parts list, which is really short if you already have common maker tools at hand. In that case, adding a display to your Lego Game Boy can be done for about 25€.

What you need:

• Lego Game Boy (72046), 60€
• Seengreat 2inch LCD Display Module, 13€
• Waveshare rp2350-zero, 12€
• 3D printer -or- cardboard and a box cutter
• A soldering iron and its typical consumables (solder, wires, etc.)

Note, that I am not familiar with Seengreat and I have no idea if you can find the same display under different brand names. The important part is that it is a 320x240 pixels display with an ST7789V SPI controller. Of course the measures also need to be the same (careful when comparing: The distance between the screw threads is wrong in the amazon listing, but that does not matter for this project anyway).

As mentioned in the listing, I am quite sure that you do not need a 3D printer and can just cut some cardboard. If you have little experience with soldering stuff you might want to ask a friend, though, as I do not see a good way around this.

Assembly

Well, the Lego Game Boy comes with assembly instructions, so let’s assume you already have a fully assembled Lego Game Boy at hand :)

The display has eight pins that you need to connect to our microcontroller. If for some reason you want to connect it differently than I did, you really just need to make sure to connect VCC to the 3V3 pin and GND to GND. All other pins from the display just have to be connected to any GPIO pin on the rp2350. You just need to set up the correct pin mapping in the software later. However, if you want to do exactly what I did, here is the pin mapping I used:

• VCC - 3V3
• GND - GND
• DIN - GPIO 9
• SCK - GPIO 10
• CS - GPIO 11
• RST - GPIO 12
• D/C - GPIO 13
• BL - GPIO 14

As you can tell from the photos, this mapping allows mostly reusing the pin header that is already soldered onto the display. I directly soldered most of the pins to this header and hooked up the remaining ones with short pieces of wire.

At this point consider to do the software part in the next section first before putting the display into the Game Boy while you can still easily reach the microcontroller. However, it is also not too tricky while it is already in there and I like to keep hardware and software instructions separated, so…

The next thing you need is the simple adapter to hold the display in the center of the Lego window. If you have a 3D printer, simply grab the model from (thingiverse / printables / makerworld - check back in a few minutes) and print it. The display should fit neatly into the center with the flat cable at one side fitting into the gap. Then just put the entire assembly into the Game Boy’s window and you are done. If you do not have a 3D printer, get some thick black cardboard³ and a box cutter to recreate the same shape.

Finally, you just have to attach a USB cable and run it out from your Game Boy. Either do it like I am showing in the photo or remove some bricks if you prefer to run it differently. This may depend on how you want to show the model later and which sides or angles will be visible to the viewer.

Getting actual games to run on it

Now, here is the good news. This is not just a trick to run some videos on the display. We are going to run an actual emulator with original games on it! The bad news is that, obviously, I cannot just share ROMs of Nintendo’s games here, so you need to obtain a ROM file from your own games first (search the web).

The emulator that we will run on our rp2350 is “Pico-GB”. Originally, this was Peanut-GB by deltabeard, who already ported it as RP2040-GB, which was forked by YouMakeTech as Pico-GB with several improvements and which was then again forked by tobigun with even more improvements, most notably support for many more displays including ours.

Now, before you get confused by all these forks, just get the files from my fork, which has the configuration files already set to match our display and our needs. It also disables sets inputs to GPIO 0 (i.e. out of the way) and selects a grayscale color palette.

Just clone or download the entire repository (if you are unfamiliar with github, you can download a zip with the green button in the top right corner).

In theory, now you already have everything you need, but you have to get your ROM in there, so it will be compiled into the firmware ⁴. Unfortunately, you cannot just use the binary ROM file that you have, but instead it needs to be converted into a C header file. On Linux you can simply run xxd -i your-ROM.gb > game_bin.h, but on less abled operating systems you can use an online tool. Upload your ROM, press convert and save the file. Then place the file as game_bin.h in the src folder of the repository you just downloaded. Open the file with any text editor and make sure that the first line looks like this:

unsigned char GAME_DATA[] = {
  0x.., 0x.., 0x.., ....
  0x.., 0x.., 0x.., ....
  ...
}

You can ignore or remove any lines starting with // that the conversion tool added. The important part is that the line with GAME_DATA[] = comes directly before the big block of 0x..-entries.

Now it is time to compile and flash the code. This is a PlatformIO project, so you would open VSCode and load the project with PlatformIO. I would give step by step instructions on how to install VSCode and PlatformIO, but I am quite sure that things will be different for non-Linux readers, so please refer to the web if you are stuck as there should be plenty of tutorials for this. You basically only have to install VSCode from Microsoft and then use the Add-On-Store in VSCode to install PlatformIO as a plugin. You then have the alien head or insect head or whatever the icon of PlatformIO is at the left hand side of VSCode and can use that to open the folder that you downloaded from github (not src, but the one containing src). Press the tiny checkmark sign at the bottom to compile, plug in your rp2350 and press the arrow next to the checkmark to upload it to the rp2350. After a moment, your game should show up on the display⁵.

Results

Well, the result is a display fitting neatly into the Lego Game Boy and running the game you picked. Of course, at this point it does not have sound or any means to control the game, so you should pick a game that runs on its own in some demo mode. You might even want to look for ROM hacks that reduce the wait time for the demo mode or that do something entirely different.

However, if you want to create a fully functional Lego Game Boy, that should be possible, too. The emulator supports inputs via GPIO, it can generate sound and it should be easy to run the rp2350 on a battery. The tricky part will be getting it all into the Lego Game Boy and especially figuring out some kind of contact that works with the Lego Game Boy’s mechanical buttons. I think it can be done, but it would be total overkill for my purpose, so I am eager to hear from you when you managed it :)

The video above gives a good overview of the project. The blog entry below contains a few more technical details as well as links to source code and additional resources.

Please note that this article contains affiliate links, i.e. links that tell the target site that I sent you there and that earn me a share of their revenue in return, i.e. as an Amazon Associate I earn from qualifying purchases. In contrast to regular external links, such affiliate links are marked with a dollar sign instead of a box.

What is a Game Boy Photo Booth?

Loyal readers of my blog will certainly remember my bullet time video booth. It was a rig for my cousin’s wedding allowing guests to take short video clips of themselves with a bullet time effect as transition. In fact, building these video booths has become a bit of a tradition as I first created one for my own wedding, followed by a total of three for friends and cousins. Each time resulting in a wonderful memory of the wedding reception with clips from all the guest cut into one long video with upbeat music selected by the couple.

So, when another one of my cousins¹ got married, it was time for another one, video booth number five. Since reusing the bullet time rick was not an option due to space constrictions, it was a perfect chance to make a crossover between my camera stuff and my Game Boy stuff to create a Game Boy photo booth. After all, that cousin also loves the old video game systems.

Ok, so what is it? A photo booth or a video booth? Well, both.

When guests push the green button, they get some intructions and a countdown. At the end of the countdown a five second video clip is recorded using a proper modern mirrorless camera and a Game Boy camera simultaneously, resulting in a bunch of video clips for me to assemble later. That’s a video booth. But with this setup, it does not end here. It also takes three stills from the Game Boy Camera recording and offers the guests to print them through a Game Boy Printer as a souvenir for the guests themselves - like typical photo booths do at many wedding receptions².

Setup overview

The entire setup does not really do something unusual I haven’t done before, but it combines many different components.

At the heart sits a Raspberry Pi 4, which runs a Python script to control everything and to show a GUI to the guests. That GUI is actually a web-interface, based on Flask and displayed locally via Chromium. In theory, you could use this to show the status of the video booth remotely or display the newest video clips somewhere else at the wedding reception, but I only used it to show the GUI on a screen attached to the same Raspberry Pi for a simple reason: I find it much easier to create a full screen GUI with frame-precise playback³ of multiple videos via HTML5 and JavaScript than doing so with some specialized and OS-specific Python modules⁴.

The video box is controlled by two big push buttons. These are exactly the same push buttons I already used for the bullet time video booth. They run on two AA batteries each and have a Raspberry Pi Pico W inside that acts as a Bluetooth Low Energy keyboard, sending only a single button press to the Pi 4 whenever the push button is pressed. Its source code can be found here.

Then there is the main camera, the Game Boy Camera and the Game Boy Printer, which I will discuss in the next sections.

Controlling the main camera

In the context of this project, controlling the main camera, a Sony a6400, should be the boring part, but there are a few details to it that make this trickier than you might think.

In a perfect world, I would just hook up my modern camera to a USB port and be able to control it and to download recorded videos, so I can show the results to the guests. Unfortunately, that’s not possible with the a6400 (no video download in anything but mass storage mode).

In a less perfect, but still somewhat nice world, I would use the camera’s Wifi interface for this, but nope, also not possible on the a6400 (no video download via Wifi).

In a cumbersome but still livable world, I would grab the video directly from the camera through an HDMI grabber, but that is not possible on the a6400 with USB control (one camera stream is reserved for USB preview and hence unavailable for HDMI out).

The combination that actually worked well for me is (brace yourself!) controlling the camera via Bluetooth Low Energy and retrieving the recording through a Wifi SD card. In fact, this is what gave me the idea to create my Bluetooth remote control app for alpha cameras for which I already discussed the different control and retrieval options.

The downside is that I had to limit the resolution to 1080p instead of 4k due to the slow memory card, but compared to the Game Boy Cameras resolution that’s still plenty.

Capturing the Game Boy Camera

Believe it or not, but recording a video stream from the Game Boy Camera is much simpler. At least if you already have another one of my projects at hand: The GB Interceptor.

Quick explanation if you have not heard of it: It is a little adapter that goes between a Game Boy and a game cartridge (like the Game Boy Camera). It captures the communication between the two to reconstruct what the Game Boy is showing on the screen, all handled by an rp2040 microcontroller. In case of the Game Boy Camera, you can simply enter the shoot mode of the Game Boy Camera and the video will be available to the GB Interceptor.

The GB Interceptor simply acts as a regular USB webcam and since my original article on the GB Interceptor, I managed to implement MJPEG encoding which makes it compatible with pretty much any host device⁵, including computers and laptops with Linux, Windows and MacOS as well as Android tablets and iPads with iPadOS. If you are interested in learning how encoding MJPEG on an rp2040 works when it is already fully occupied following a Game Boy and rendering its graphics, I would recommend watching my talk at the 37c3 Chaos Communication Congress (yes, I am quite proud of that talk).

The point is that I only had to use a regular Game Boy, plug in the GB Interceptor, plug in the Game Boy Camera into the GB Interceptor and connect the GB Interceptor with a USB-C cable to the Raspberry Pi. Maybe the only unusual thing is that I used the break-out board of the GB Interceptor PCB to use a long ribbon cable between the Game Boy and the Game Boy Camera, allowing me to position it more freely.

Printing on the Game Boy Printer

And finally, the Game Boy Printer. This is the part for which I had to write the most code. Not because it was particularly difficult, but simply because I had not done it before.

When I am saying that it was not difficult, then this is the case not because I naturally speak Game Boy Printer, but because I could of course once again count on the Game Boy dev community to have long solved how this is to be done. As always, the gbdev.io Pandocs give all the necessary info in a compact overview, but there are also plenty more explanations for the Game Boy Printer communication to be found on the web.

Electrically, the communication is done through a Game Boy link cable, which is basically an SPI interface. In case of the printer it is even more rudimentary as data is never transmitted in both directions at the same time. So, I wrote some minimal Arduino code that receives data through a USB serial interface, writes it as SPI to the Game Boy Printer and returns the answer back to the USB serial.

The Arduino code runs on a 5V variant of the Pro Micro. You know how much I love the Pi Pico / rp2040, but in this case I had to yield to the old technology of the Game Boy Printer, which has a logic level of 5V. So, as the Printer would not accept the 3.3V commands from a Pi Pico, instead of fiddling with level shifters, I simply grabbed the first 5V uC from my collection that I could find - which was a Pro Micro.

The Printer itself is somewhat limited. It can receive commands for line feed and accepts 8 pixel high rows of 2bit tile data in the same format that the Game Boy uses to print batches of eight pixel rows. Its horizontal resolution matches the Game Boy with 160 pixels while you can print endlessly to achieve any vertical resolution. However, it only has internal memory for a single Game Boy sized screen (144 pixels or 18 tile rows), so long images have to be split up into multiple commands. Transfer and printing takes a while although I am driving the Printer’s SPI interface at four times the data rate that could be achieved by the original Game Boy (32kbit/s instead of 8kbit/s).

I wrapped it all into a neat little Python module, which boils it down to a single command that takes an arbitrary image to be printed on the Game Boy Printer. Well, almost arbitrary: The height of the image must be a multiple of eight after it has been scaled to a width of 160 pixels.

You should be able to easily reuse my work by using my Arduino code on almost any 5V micro controller and using my Python module for the Game Boy Printer:

1
2
3
4
from GBPrinter import GBPrinter

with GBPrinter("/dev/ttyACM0", 115200) as gbp:
    gbp.printImageFromFile("testprint.png", 0.5)

The second parameter adjusts the “exposure” of the thermo paper, i.e. making the entire printout darker or brighter.

And a final important tip: You do not have to find some of the rare old stocks of original Game Boy Printer paper or expensive reproductions. Any thermal paper with the right width of 38mm and a not too big roll diameter should do fine.

Conclusion

In the end the guests had a lot of fun and especially my cousin who also appreciates old video games loved the Game Boy video/photo booth. Of course, the final video with the clips from all the guests primarily used the footage from the “good” camera. You would not want this memory of your wedding to be lost in 128x112 pixels⁶, but I could use the Game Boy Camera footage to spice up the video.

It might also be worth noting that once the setup was running, I did not have to look after it except for refilling the printer paper twice. I emphasize “once it was running”, because I was a bit careless with the quick solder job on the Pro Micro while setting it up, which means that I am now known as that nerd who brought a soldering iron to a wedding. Totally worth it.

Overview of source code and links

Usually, I provide one link to the source for a project, which contains everything, but in this case it is unlikely that you will reuse the entire project (after all, it is quite specific to all the components) and some parts have been reused from previous projects. So, here is an overview of all the bits and pieces already provided throughout the blog article:

• There is the Python code for the Raspberry Pi 4. Note, that this is based on the older code for the bullet time video booth, which might be worth checking out as well, because it might clear up a few oddities in the Game Boy Photo Booth code. For example, there is a rather unnecessary failure state recovery that only restarts the camera Bluetooth connection, which has the more complex task of actually restarting the entire USB bus for the old setup with 13 cameras hooked up to the system.
• I have placed the module for the Game Boy Printer in its own folder to make it easier to reuse it. This contains a copy of the GBPrinter module also present in the rPi 4 Python code along with a test script.
• The Arduino code for the Pro Micro comes as an Arduino project (just the “gblink” folder) along with a test script and a hookup guide.
• The BLE push buttons use exactly the same code as the old version for the bullet time video booth.

Check out this rather short Youtube video to see the tool in action or just look at the top of this post to try it out yourself.

Please note that this article contains affiliate links, i.e. links that tell the target site that I sent you there and that earn me a share of their revenue in return, i.e. as an Amazon Associate I earn from qualifying purchases. In contrast to regular external links, such affiliate links are marked with a dollar sign instead of a box.

I think that the tool is mostly self-explanatory, so here it is. You can find further info in an FAQ style below the tool. You can also open it on its own page.

General

Where is the source code?

On github

Are images being uploaded to your site?

No, the entire tool runs in your browser using JavaScript. In fact, you can download the tool and run it from your local drive without any internet connection (see next question).

How can I run this locally?

Go to github and download the entire project (if you are new to github: Green button labelled “Code” and then “Download ZIP”). If you downloaded it as a zip file, make sure to extract all files. Then simply open gbslideshow.html in your webbrowser (on most systems just a double click).

Usage

You can load your images into the tool by either dragging them onto the tool or by pressing the “Add image” button and selecting images from your machine. Each image appears as a group of three previews: The original file you uploaded (scaled down to the Game Boy’s resolution), a preview of the grayscale image for the original Game Boy or Game Boy Pocket (or similar) and a preview for the color image for the Game Boy Color or Game Boy Advance (acting as a Game Boy Color). You can move or remove images with the three buttons in the bottom left corner (arrows and cross).

You can adjust brightness and contrast to your liking and toggle dithering for the grayscale images. In most cases a dithered image looks better as the Game Boy only has four shades of gray (or green), but for logos and drawings an undithered image can look better if you adjust brightness and contrast.

Below each image group is a setting “Seconds before next image”. This determines the duration for which an image is shown. If set to zero it will not advance automatically, but only if you select the next/previous image by pressing a button on the Game Boy. On the Game Boy every image can be advanced by pressing the D-pad to the right or the A button and you can always go back to the previous image by pressing left or the B button.

When you are happy with your selection of images, you can simply press “Generate ROM” at the bottom and your ROM will be downloaded directly in your browser. (If you don’t know what to do with the ROM, read How do I get the ROM onto a real Game Boy? further below.)

Can I manually step through the images on the Game Boy?

You can always press the D-pad right or left to go the the next or previous image. The same works with the A and B button. If you don’t want the slideshow to advance on its own, set “Seconds before next image” to zero on all images.

What will be the ROM’s size?

In the current version each image takes up nearly 16kiB, such that it makes sense to store one image per memory bank. The first bank is used for the code and the image index, so for N images the tool will use 16kiB*(N+1). However, it will pad the file to create the common ROM sizes of 32kiB, 64kiB, 128kiB, 256kiB, 512kiB, 1MiB, 2MiB or 4MiB. The tool is currently limited to 254 images.

How do I get the ROM onto a real Game Boy?

You can directly use the ROM in an emulator or on modern devices that can handle ROM files directly (like the Analogue Pocket), but if you want to run it on original Game Boy hardware, you will need some kind of flash cartridge. It should work on any kind of flash cartridge as long as it is large enough for your ROM and properly handles common memory bank controllers (see below). I have tested the following:

• EZ Flash Junior
• insideGadgets’ 2MB Flash cart
• Simple 32kiB EEPROM chips directly connected to the Game Boy’s memory bus (aka using my WiFi cartridge without the ESP)
• An SD cart in an Analogue Pocket
• Various emulators

Which type of cartridge is supported? (MBC?)

Pretty much any flash cartridge should work as long as it is large enough for your generated ROM. If you upload more than one image, the cartridge needs to properly handle memory bank controllers (MBCs), but the ROM generated here should be compatible with all of the common Nintendo MBCs. The tool will declare in the ROM’s header that MBC-5 is required (unless you generate a 32kiB ROM, in which case it declares a ROM-only cartridge), but if your ROM fits the cartridge it should also run on an MBC-1 or MBC-3 cart (2MiB). If your flasher gives you a warning about the wrong MBC, you can simply ignore it. If declaring a specific MBC is really necessary for any cart, let me know and I will add an option for this.

Technology

How does it work?

The tool consists of a template ROM that I have written in assembly. This ROM is embedded into some JavaScript code which converts your images and then injects them into the template ROM. The template ROM uses two hardcoded addresses at which it expects a list of images. One for grayscale mode and one for color images. The image list consists of addresses (memory bank and memory address) and the display time for each image, so the JavaScript tool is simply responsible to write the images somewhere into the ROM (contained within a memory bank) and store the addresses there. In principle, different numbers of grayscale or color images could be supported, but that is not implemented in the JavaScript tool.

How are the images processed?

The JavaScript code simply scales the images onto a 160x144 canvas (native resolution of the original Game Boy and Game Boy Color). From there it directly processes the images following the limitations of each Game Boy, so the preview images are exactly what you get on your Game Boy (except maybe for the fact that colors on the Game Boy Color can look a bit different).

How are grayscale images stored?

The grayscale images are stored as 360 tiles and simply displayed by switching the tile data address halfway through the frame. Otherwise it is just the normal 2bit “color” palette of the original Game Boy, so you end up with a 160x144 image with four shades of gray. The tool offers dithering to mitigate this limitation (Sierra dithering to be exact).

How are color images stored?

The tile data works similar as for the grayscale images as there are 360 tiles with four colors per pixel. However, the four colors can refer to different color palettes on the Game Boy Color, so to use this, the tile data of the color images is not identical to the grayscale images.

The Game Boy Color only supports eight color palettes with four colors each. Also, not every pixel can just pick a random palette, but all pixels within an 8x8 tile are assigned to the same palette. Therefore, with a naive approach, the Game Boy Color could only display 32 colors at a time and in practice many of these colors would be duplicates because for example black is typically required in more than a single palette.

The trick for getting more colors is that one can edit the color palettes during hblank of each scanline. This technique has been demonstrated many times before and is commonly referred to as “hicolour”. Depending on the implementation for each line of pixels you can either replace four entire palettes or fewer random colors within any of the eight palettes. The problem with this is that the assignment of color palettes to each tile remains fixed or you would have to pay more bandwidth to also change these assignments. This leads to several possible strategies and rather unusual rules when converting images for the Game Boy Color.

In case of my tool, the assignment of color palettes is not updated each line, but optimized for each image and stored along with the tile data. On each line four entire palettes are replaced in an alternating pattern (palettes 0-3 on odd lines and palettes 4-7 on even lines).

To generate optimized images for this, the tool first uses k-means clustering to find which tiles should share the same palette indices. Then it proceeds to generate palettes line by line. Since each palette is used by some pixels of the previous or next line, palette generation takes into account all pixels in the two neighboring lines that are part of a tile which references the palette to be generated. This limitation is the most common source for artifacts as available colors can be too limited for strong contrasts along lines that run diagonally, forcing color changes within a tile and grouping of neighboring tiles.

Finally, tile data is written based on the already fixed palette assignments and generated palettes with the closest matching color available. So, in total the color image also has a resolution of 160x144 pixels and can theoretically hold up to 2320 colors with 5bit per RGB channel - but that claim about the number of colors leaves out a very important chunk of information on how the colors can be used.

By the way: Since the k-means analysis in the tools is based on random initialization, playing with the brightness/contrast sliders can lead to different results using the same settings. For some tricky images this can help to get lucky with a better result.

Could I get more than one image on a ROM-only cartrigde (32kiB)?

Since the grayscale images are smaller than the color images and since there is a bit of extra room in bank 0 after the code, a purely grayscale cartridge could hold multiple images without a memory bank controller and the template ROM supports images in random memory locations (as long as they do not go beyond bank boundaries). I just have not implemented this for the JavaScript code as I do not expect many people to be limited to 32kiB ROMs while having a strong use case for grayscale-only slideshows. Let me know if you need this nevertheless.

The video is mostly about my process of going through all the options to remotely trigger my camera and, yes, I took this as an excuse to create my first “Top 5” listicle. It is a good starting point if you want to know what problem this app solves and if it is for you. This article here will go into more detail of how the app works, how to control the camera via Python, what the app can do, what it cannot do and how to automate the app from other apps like Tasker.

Please note that this article contains affiliate links, i.e. links that tell the target site that I sent you there and that earn me a share of their revenue in return, i.e. as an Amazon Associate I earn from qualifying purchases. In contrast to regular external links, such affiliate links are marked with a dollar sign instead of a box.

Before we start, for those who just want the quick overview:

• α-Remote is free, ad-free and open-source
• It requires Android 12 or newer¹
• Source code on github
• Function is comparable to Sony’s physical Bluetooth remote control
• Available on Google Play and F-Droid

What the app is for

In 2014 I bought a Sony NEX-5T, my first camera with exchangable lens. Since then I have been locked into the Sony eco-system of cameras. Well “locked” might sound too negative. I have switched to an α6400 since then and while I am sticking to the cheaper and more portable world of the APS-C format, I have collected quite a few lenses and accessories, which makes switching to other brands expensive and complicated (actually, the formfactor of the a7C II looks like a nice compromise to keep using light APS-C lenses on trips and use fullframe glory at home - but that price is not for me).

At the beginning Sony was one of few manufacturers who were taking mirror-less cameras seriously and definitely a solid choice. Now others have caught up and it seems like the differences are more in the details, habits of use and brand identity. I do not have an eye for which brand has the best color science², best IBIS, best autofocus or whatever. If I had to start over I would not mind looking at the other brands, but at the same time I am happy with what I have and what Sony delivers.

Except for one thing.

Their bloody software.

The problem with Sony’s apps

The α6400 has barely seen any firmware updates, its menus are terrible and several functions exclude each other³, when I see no good reason why they should. But the worst of them all is its Wifi features. Even my old NEX-5T already had the option to transfer pictures via Wifi and remotly control the camera from my phone with a live view. Unfortunately, it sucked on the NEX-5T and it is still sucking on the α6400. It takes ages to connect to it (if connecting at all), the transfer speed is all over the place (usually slow with just enough short speed boosts to show what might have been possible) and the app feels like a patchwork of systems that barely holds together. It was bad when it was called “Play Memories”, it was bad when it was called “Imaging Edge” and frankly I cannot say if the new “Creators’ App” is any good, because for some reason my five year old α6400 is not even supported anymore - because of course it isn’t. Sony changes its Software ecosystem every few years and no need to support a camera that is still being produced.

But even if it was supported, I think that using WiFi as a remote control is not ideal. Yes, it has its benefits: The high bandwidth allows for a live preview and since it is based on a REST API, it is quite easy to control the camera through it like I did for my squirrel photo trap. But the big problem is that it takes a moment to set up and that it changes the networking setup of your phone. On older phones it would entirely replace whatever WiFi connection you have at the moment, but even on my Pixel 6, which can handle multiple WiFi connections at once, you can just tell how every app, including Imaging Edge itself, is confused by which network to use.

Use Bluetooth instead

Because of this, I have been using a simple IR remote for a very long time, until recently I built a video booth for a friend’s wedding. He did not have the space for my massive bullet time video booth, so I wanted a minimal setup using only my α6400, a Raspberry Pi and a preview screen. So, the idea was that the guests would trigger a countdown and decide if they want to keep the result. This means that the Raspberry Pi controls video recording of the camera to capture a 5 second clip and eventually somehow shows the result of the recording to the guests and stores it depending on their decision. So, I need control of the video recording state, while showing a preview during recording and the ability to play back the recorded video clips. Which turned out to be very tricky:

The table shows all the combinations of remote control and retrieving recordings I know of - and all the reasons why no combination worked. I was close to once again build a setup with a primitive cable trigger or a custom IR sender⁴ when I accidentally found that my α6400 had another method of remote control that I did not know of: Bluetooth.

The advantage for the video booth was small, but important. No need for extra hardware as the Pi already has Bluetooth support, but more importantly the camera sends its recording state, so my software could react to it. With a simple cable remote or IR sender I could only toggle the recording state and hope that no signal is ever missed. Otherwise the camera would record only when it is not supposed to - until another signal is missed.

But the ease of using the Bluetooth control made me realize another thing: Simple triggering from a smartphone should be done via Bluetooth. You cannot get a preview stream via Bluetooth and you cannot download the picture, but that is not the point. I just want to be able to set up the camera for a family picture, take out my phone and trigger with the press of a button without having to wait - and without letting everyone else wait. And this is what we all know from Bluetooth. Take out your Bluetooth headset and they connect to your phone pretty much on the way from the case to your ears. They literally reach your ears in time for you to hear the connect-chime.

So, that’s what I created. An app that connects to your camera and shows remote control buttons in your phone’s notification area within seconds of turning it on:

Of course it also vanishes again as soon as you turn the camera off.

Controlling Sony cameras via Bluetooth

How do you control the camera via Bluetooth? Is there a documented API by Sony? Unfortunately not. While Sony has documented its WiFi API⁵, the Bluetooth API is not documented, but since it is based on Bluetooth Low Energy, it is not too hard to just look at which services and characteristics are exposed and see which characteristics can be subscribed to and what is sent by the camera. Figuring out commands to be sent to the camera can be trickier, but luckily, this work has already been done by Coral, Greg Leeds and Mark Kirschenbaum, who looked at the communication of their remote and documented what they found. Thanks a lot!

A few lines of Python

And with that info, it was quite easy to trigger the camera for my simple video booth. The tricky part about proper handling of Bluetooth Low Energy is that everything happens asynchronously and you have to implement queues, take care of service discovery, handle callbacks and be prepared for failures at any point because it is a wireless connection after all. In case of the camera you also need to handle scanning, filtering of advertisement packets and pairing.

Luckily, for a simple video booth, you know your camera and you know the one thing it is supposed to do. Even better, you are the only user, so you can take a lot of shortcuts.

So, I paired the camera with system tools, hard coded its Bluetooth address as well as the relevant characteristic’s UUID and just blindly wrote the byte sequences from Coral, Greg and Mark to the command characteristics using the Python module “bleak”, which allows me to just wait for the Bluetooth communication via asyncio. The result is just a few lines of Python code to trigger the camera. In fact, most lines simply define addresses or payload data with barely any additional logic:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import asyncio
from bleak import BleakClient, BleakGATTCharacteristic

bleAddress = "AA:BB:CC:DD:EE:FF" # Bluetooth address of the camera
bleCmdUUID = "0000ff01-0000-1000-8000-00805f9b34fb" # UUID for command characteristic

# Camera commands, see https://gregleeds.com/reverse-engineering-sony-camera-bluetooth/
blePayloadFocusDown = bytearray([0x01,0x07]) 
blePayloadFocusUp = bytearray([0x01,0x06])
blePayloadTriggerDown = bytearray([0x01,0x09]) 
blePayloadTriggerUp = bytearray([0x01,0x08])

async def demo():
    async with BleakClient(bleAddress) as client:
        #Press shutter button half and then full
        await client.write_gatt_char(bleCmdUUID, blePayloadFocusDown)
        await client.write_gatt_char(bleCmdUUID, blePayloadTriggerDown)

        #Short wait as we do not observe focus state. (You might want to observe focus and/or shutter state instead)
        await asyncio.sleep(0.2)

        #Release shutter button
        await client.write_gatt_char(bleCmdUUID, blePayloadTriggerUp)
        await client.write_gatt_char(bleCmdUUID, blePayloadFocusUp)

        #Disconnect, in most real applications you would stay connected
        await client.disconnect()

asyncio.run(demo())

A real application (and my video booth) should of course stay connected, automatically reconnect and maybe also subscribe to the status characteristic.

Companion apps and Android

Speaking of a real application, this became a bit more complicated when implementing these features as an Android app. Now the code runs without me anywhere nearby on devices that I have never personally seen in my life - and probably never will. So, I now have to handle scanning, pairing and any kind of error caused by software, hardware and wetware. I will not go into all the details of the implementation, which is entirely open on github and it suffices to know tha BLE on Android sucks.

However, there is one important consideration that I want you to be aware of, that is the concept of “companion apps” and “companion services”. If you look at Sony’s Imaging Edge app, you will find one Bluetooth feature for geotagging. If you enable it, the app will stay active all the time waiting for you camera and whenever it is turned on, Sony’s app will notify you (including an entirely pointless vibration), write the current location to the camera and after you turn off the camera, the app stays around in your notification area in case your camera reappears.

Beautiful. Not only do I spend 95% of my day with my camera being not even in the same room, most of the time when I use it I do not require an affirmative vibration from the phone in my pocket whenever I turn it on. The reason Sony does it like this, is that for old Android versions this was the only way to automatically connect to a device when it is turned on.

Luckily, Android 8 introduced an alternative in 2017. The so-called Companion Device Manager (CDM) is a system service that allows apps to associate themselves with a specific device (with the user’s permission), making paring and connecting much easier. But, more importantly, with Android 12 in 2021 it allowed apps to observe the device’s presence and to implement a Companion Device Service. What this means is that now the CDM keeps looking for the device and it launches the app’s service as soon as the device appears. If the device is turned off (or goes out of range) the CDM terminates the service again.

That’s why my app targets Android 12 or newer. It allows my app to stay entirely inactive when you are not using your camera. Unless you normally turn off Bluetooth entirely, your phone is keeping an ear open anyway and my app does not use any extra resources. My app will only be activated when your camera is nearby and turned on and the system kills it again as soon as the camera is gone.

What the app can do

Ok, great, so the app plays nice with my phone’s resources and is just there when it is needed. But what does it do?

It can do anything that Sony’s remote can do, which is emulating button presses on the camera. It can press the shutter, the recording button, Zoom in/out, Focus in/out, the C1 button and the “AF On” button (that is the hold button in the AF/MF or AEL lock select switch or whatever that thing is called).

You can pick any of these buttons, add a self-timer or toggle mode if you like, and put them in your notification area. There is also a dedicated remote control and I have added some automations around these button presses, like a tool for bulb exposure and a simple intervalometer.

Three kinds of shutter

Unfortunately, these are just blind button presses. The camera does neither report the state of a button nor what function you might have mapped to it. My app has no idea what the “AF On” button does in your setup - it just presses it. The camera does not even report if it is in MF or any AF mode, so labels or behavior cannot be adapted accordingly. The only thing it reports is whether an autofocus has been acquired, whether the shutter is open and whether a video recording is active.

This leads to some problems even for simple triggering: The buttons in the notification area can only be tapped, but they do not distinguish how long you press them (for reasons⁶). So, you cannot hold the trigger until the shutter clicks and the same is true for a self-timer. The app needs to figure out how long to press the shutter.

But how does it know when to release the shutter? Well, that is a problem and I have implemented a total of three kinds of shutter that are ideal for different camera settings:

• The simple shutter button. If you are using the full remote view of the app, you can simply press and hold the trigger to your liking, which is the same as pressing the shutter button on your camera (except that half-pressing it is a separate icon). So, if you do not need the notification area and no self-timer, that’s the most natural one. You can also use it with a defined hold duration if you are in a situation where the autofocus is fast enough. However, if you hold it too short and the focus does not lock in time, your camera will not take a picture.
• The “Trigger Once” function holds the shutter button until the camera reports that the shutter has been opened. This is good for most self-timer needs as it guarantees to trigger the camera as long as it is able to trigger at all. It just presses that button until there is a result. The only problem is that the report of the shutter status is slower than the faster burst modes. So if your camera is set to burst, this will take multiple photos. In my opinion, this is still fine for most self-timer situations (probably even desired if you have burst mode on), but it can be annoying.
• The “Trigger on focus” function reliably takes a single photo even in burst mode. It half-presses the shutter button and waits for the camera to report that the autofocus has acquired a lock. Then it fully presses the shutter very shortly. The problem with this mode is that it will fail entirely when you are focussing manually, because then there is no autofocus lock.

What the app cannot do

So, with all that in mind, what are the app’s limitations? Well, there is quite a list.

It lacks all the big features that cannot be done via Bluetooth: No preview image and no image transfer. It also lacks any kind of direct control over settings. It cannot set shutter time, ISO, whitebalance or anything like that, because it can only send button presses. It cannot send logical commands⁷.

This also applies to anything it actually can control: For example, there is no feedback from the focus in/out buttons and the amount it moves the focus depends on the lens being used. Therefore, there is no good way to implement focus bracketing. The app could in theory press the right buttons, but it cannot reliably move the focus to specific positions or even return to its original position.

So, you should think of this app as a handy small remote trigger. Like the physical remote controls (Bluetooth or IR) that you can buy from Sony. You just don’t have to carry it.

Intents

Well, there actually is one more interesting thing the app can do. In the settings view you can find an option to allow other apps to send commands via broadcasted intents. What is that? Intents are messages that apps can send to other apps. One app (or its part) might send a very specific intent to a specific different (part of an) app to trigger a function or transfer data. But an app can also listen for broadcasts that could come from any app and which may or may not be directed at a specific app. An example is your messaging app that tries to open an attached image when you tap on it. It will broadcast that it intends to open an image and any app that is able to open it may offer its service.

In case of my remote app, this will allow other apps to send an intent to trigger a command on the camera. This means that any other app may now be used as a remote trigger for your camera by going through my remote app. If you combine this with an app like Tasker, you can create any kind of automation and almost everything can become a remote for your camera. Tasker can use almost anything to start an automation and it can be configured to send a trigger intent to my app. Now anything can become a trigger. Your smartwatch, a smart motion detector, a text message to your phone - whatever you can think of. You can set Tasker to trigger your camera when your alarm clock rings on a rainy Tuesday if that’s what you want.

The setup for tasker and any similar app should not be too complicated. You need to send an intent to the package org.staacks.alpharemote with the action org.staacks.alpharemote.EXT_BUTTON.

You also need to set an “extra” with the name preset to a value that represents one of the buttons (or functions). These are:

• STOP
• SHUTTER_HALF
• SHUTTER
• TRIGGER_ONCE
• TRIGGER_ON_FOCUS
• RECORD
• AF_ON
• C1
• ZOOM_IN
• ZOOM_OUT
• FOCUS_FAR
• FOCUS_NEAR

(Note, that the app also accepts these in lower case.)

You can also set more “extras” to control optional additional parameters:

• toggle should be a boolean extra that controls if the button is just pressed or toggled on/off.
• selftimer should be a floating point extra that adds a self-timer in seconds.
• duration should be a floating point extra that sets how long the button should be pressed in seconds.
• step is a floating point extra in the range from 0.0 to 1.0 that determines the speed of jog controls like zoom or focus.
• down is a boolean extra that determines if a “down” event should be part of the command. This defaults to “true” meaning that pressing the button down is part of it, but if you set it to false (and leave up as it is) you can send a key release only.
• up is like down, just for the up event. It also defaults to true, so by default the intent would send a button press and release. But if you set up to false, you could send a button press without releasing it.

Note that Tasker does not specifically distinguish between different data types for its “extras”, but it seems to infer them from the value. For example, in order to send a “trigger once” with a self-timer of three seconds, you would set one “extra” to preset:trigger_once and another “extra” to selftimer:3.0 to get a string extra and floating point extra, respectively. (Not selftimer:3 without the decimal point.)

Go get it

Ok, that’s it. Keep in mind that this is more like a handy little remote trigger than a full-featured remote control.

If you like that and your camera supports Bluetooth remotes, get the app on Google Play or F-Droid:

Also keep in mind that I only have one camera and very few phones to test it with, so bear with me if you encounter issues and help me to fix them. Check the Readme on github for common problems and report issues on the issue tracker.

• I gave a talk at the 37th Chaos Communication Congress about how the GB Interceptor can reconstruct the Game Boy’s screen content by listening in on the memory bus. The recording is available at media.ccc.de.

• Because some asked for the music from my recent video about the wooden Game Boy (some as in a handful, I am not under the delusion that the world was waiting for my video soundtrack) I have uploaded it as a pure mp3 as well as making it available on common streaming services. You can find more details on there.oughta.be/music.

You can see the process in the video without much explanation. If you want to learn about the toolpaths, my reasoning behind a few things, lessons learned and what you should avoid if you try this yourself, read this blog post instead and check out my design files on GitHub.

Please note that this article contains affiliate links, i.e. links that tell the target site that I sent you there and that earn me a share of their revenue in return, i.e. as an Amazon Associate I earn from qualifying purchases. In contrast to regular external links, such affiliate links are marked with a dollar sign instead of a box.

A wooden Game Boy

This project mostly began as a user request. When I got myself a CNC router a few months ago, one of the little exercises I did was a wooden Game Boy cartridge (see Youtube short clip or project files on GitHub). It was a mix of “let’s see if I can do that” and “sure the retro gamers on social media will love this”, but I did not expect how much they would love it and of course they asked for more. So, I did some testing, spent some time and several weeks later I find myself in the possession of a Game Boy with a beautiful walnut wood shell.

I mean, look at that thing. Isn’t it gorgeous? So, if you want to learn how exactly it was built, read on. If you just want to see some CNC timelapses and detail shots of the wooden Game Boy, you should probably watch the Youtube video instead.

Important notes

Before we go into details, there are some general things you should know to properly judge the results. At least if you plan to reproduce the Game Boy, you should read these carefully.

• I am a total noob. Yeah, I know that Game Boy does not look like the work of a noob and I would like to believe that I have proven that I can use a CNC router, but the noobness does not necessarily refer to the complexity of the project or my ability to wield some 3d software. This is more about best practices and hardware suggestions. I document what I did and which tools I used, but you should be aware that what I did mostly uses the first method I learned and the tools are the first tools of this kind that I own. They worked to create that Game Boy, but I lack the experience to tell if they are the best or even good methods/tools for this job.
• Related to this, I barely have any experience with wood. I have applied what I learned from some videos, but I have no idea how long that Game Boy will last. Wood tends to grow, shrink and bend over time, especially if exposed to changing humidity. This Game Boy could become something that I pass along to my grand children or it could crack open tomorrow. I literally have no experience to make any assumptions about this.
• The project is far from perfect and many design choices were made as it went along. At the end I knew some things better than at the beginning and some later toolpaths are designed to fix problems of the earlier one. The Game Boy you see here is my successful first attempt, but this also means that the design files have not been polished or tested a second time.
• I designed this Game Boy around aftermarket parts and especially for using an IPS mod. It should also fit original displays, but I have not tried that.
• In the end I closed the case with wood glue, because the original screws did not hold it together properly. So, there currently is no way to open it for maintenance. Read the notes of the drilling toolpaths for more info and thoughts on the problem.

Project files and software

Let’s start with the bad news for most of those who already have a CNC machine and just want to reproduce my work: I use the Blender CAM plugin. Yes, there is a CNC CAM plugin for Blender and it is free. Yes, it is quite versatile and powerful. Yes, using it is a pain in the ass even if you are used to Blender.

Still, I love it and the CAM alternatives that seem to allow me to do similar things are very expensive¹. So, I ended up using Blender CAM, which unfortunately means that many CNC users out there will cry before having to copy my models to their CAM to painstakingly recreate the toolpaths there.

Therefore, the project files are blend files on GitHub and I release everything under the Creative Commons Attribution 4.0 license. Do what ever you like with it, just make sure to mention me as the source. …and maybe keep in mind that Nintendo might want to have a word about trademarks if you try to sell these with their logo on it.

In addition to the blend files I have also uploaded the gcode files that I actually used. They are for grbl-based machines, but even if your CNC uses a grbl controller it is a bad idea to just feed them to your machine. You will have to adapt it to the equipment that you actually use and I only added them as reference to review and compare.

Speaking of equipment-specific things: The feeds and cutting depths set in the blend files are for the weak spindle on my machine. If your spindle is stronger, you can quite certainly go a lot faster. But also keep in mind that the speeds in the blend files do not have any meaning. My spindle is not digitally controlled and since it has little torque at lower speeds I pretty much used it at its maximum of 10,000 rpm. You will have to adapt this to your machine and your bits.

The hardware I used

Remember that I only got my CNC machine a few months ago, so do not expect comparative insights here. I will document what I use and try to explain a few things to people who have never used a CNC before. If you have a CNC and are just interested in the toolpaths, you can probably skip to the table with bits I used.

The CNC machine

If you have never looked at CNC machines before, this probably looks like a very fancy and professional setup. If you know about CNC machines, you probably recognize immediately that it isn’t. My machine is a Genmitsu PROVerXL 4030 V2, which is the toughest Genmitsu CNC router, but in the world of hobbyist CNC machines ranks somewhere in the middle. It is much more rigid than the small 3D printer like machines (that Genmitsu machines are often associated with), but much smaller and weaker than machines by more prestigious brands.

As a beginner I think that it is extremely capable for my needs, but its weak spot is its stock 400W spindle. Compared to stronger machines you will find that my toolpaths take much longer as I am doing significantly shallower cuts. Also the spindle is pretty much limited to its top speed of 10,000rpm as it seems to lack torque at lower settings. For the finer tools I would have wished for a higher speed and for some situations a reduced speed might have been beneficial as well. Luckily, this can be upgraded and I probably will do so in the future.

In the end, I mostly chose the 4030 V2 because of its rather small footprint. While others might consider this to be a disadvantage, it was the largest machine that I could fit into an enclosure onto my workbench. Since I do not have a proper wood workshop, the machine has to share a room with other hobbies in my basement, which means that I needed to address noise and dust, because CNC machines can deliver plenty of both.

I went for the OpenBuilds Enclosure Kit 510, added acoustic foam and paired it with the Genmitsuo dust shoe and a flexible hose. The vacuum hose then runs through a cyclonic separator and ends in a Makita vacuum. Add a workbench, an LED lamp inside the enclosure and a screen at the side (you might recognize this one from my bullet time rig) and that’s my setup.

Just a few warnings if you are thinking about picking up CNC as a hobby: Do not underestimate the noise and the amount of dust such a machine produces. The enclosure and dust extraction in my case ate up a huge part of my budget for a good reason. If you are in a dirty workshop far from other people you can ignore the enclosure, but please still think about your hearing and your lungs. I highly recommend to use a dust extraction system anyway and if you are doing this in a room that you spend a lot of time in or that you use for other things in general, a simple shop vacuum will not be enough. Fine saw dust will escape regular vacuums and you should really look into ones with a filter for dust class M.

Oh, and one more warning: I do not have a problem to leave my 3D printer unattended as long as I can check in once in a while through a webcam. The typical 3D printer accidents turn the machine into a PLA spaghetti factory, but it is still ok if you stop it 15 minutes later. The more dangerous typical fail state of a 3D printer is a cable fire especially on cheap printers like mine, but if you place your printer in an environment of low flammability there is plenty of time to recognize the problem before severe consequences.

This is different for a CNC machine! If things go south with a CNC machine, they go south fast! The typical CNC accident means driving a sharp piece of metal rotating at 10,000 rpm into something that was not supposed to receive that piece of metal. You can break a lot of stuff within seconds and that is the harmless case. Imagine running that 10,000 rpm metal stick into a dry piece of wood and leaving it there because of a failure or maybe because that wood got loose and now follows your machine. Remember those adventure movies where they make fire with a rotating stick? Do this with a 400W motor covered by saw dust and maybe with a dust extraction system sucking everything into the big container with even more sawdust.

The point is that you should not leave a running CNC machine, have a fire extinguisher nearby and make sure to have an easily accessible emergency stop that actually cuts power to your machine (in case of an enclose, put something like this on the outside). Here is a video to encourage you to take this serious.

The bits

Like in the previous section, I will be talking to people new to CNC routers here. Someone who already knows this stuff will probably just have a glimpse at the table below anyway.

While CNC machining often looks like you are just pushing a common drill bit to some wood, this is not what is happening at all (unless maybe you are actually drilling holes with your CNC). What looks like a drill bit usually is a milling bit (a so-called end mill). It is not designed to plunge vertically into the material (although in many cases it has to be able to do this, too), but to carve away material horizontally.

One interesting aspect of this is that the spiral of the bit might go in different directions. Some bits have a right-handed spiral like a drilling bit, but others can be left-handed or not even have a spiral form at all. The reason is that the actual milling is done at the side and just requires sharp edges while the spiral mostly helps to move the material away from the cutting edge. Right-handed drills are common as you want to push material upwards out of the drilling hole and for the same reason you will find many end mills with that shape. They pull material upwards and away from your work piece, therefore they are called “upcut” bits. The downside of this is that the upwards motion can fray the edges of your work piece, which is why I also often use the counterpart with a left-handed spiral, the “downcut” bit. There are also some other forms and compromises, but I only have those two variants and so for each task I have to pick a suitable diameter for my end mill (obviously you need small ones for details and large one to remove much material fast) and decide between upcut and downcut as a trade-off between a nice finish and efficient material removal especially in tight spots.

Another aspect is the shape of the tip of the bit. The most common one is the flat end mill, which is best suited to create a flat surface. However, if you want to create a curved 3D shape, this is not a good choice as it tends to create little steps that look similar to the layers of 3D printers. A ballnose bit with a circular tip can help as it can create a slope between one line to the next one.

A very important shape is the V-shape. On one hand, this is used to directly create angled edges (chamfers) in a single pass, but also they can be used to carve text or other designs. Imagine to just try and cut a small square. If you use a flat end mill with a 3mm diameter, you can quickly remove the material from the square, but the corners will always be rounded with a radius of 1.5mm. So, instead you use a smaller end mill, let’s say 1mm. Now it takes ages to remove the material² and still have round corners, now with a radius of 0.5mm (which might be ok for many use cases). That’s where the V-bit shines: If you do not care about how deep you cut, but just want to have a 2D shape at the surface, a V-shaped bit can simply use different depths to have different diameters at the surface. Need a tiny bit for a sharp corner? Only use the very tip of the bit. Need a large diameter to clear most of that example square? Go deep for a large radius. The result is a typical angled V-carving look that many (including me) find quite pleasing. Just search for V-carving on Youtube to find a bunch of very satisfying videos.

Unfortunately, that still is not all that needs to be considered when picking the right tool for each detail. You also need to consider the cutting length and the overall clearance of your bits. The cutting length is how deep the bit can go so that its sharp bits are still cutting away material instead of its dull bits just rubbing the wood and heating it up. That’s not much of an issue for me as my weak spindle usually limits the depth of my cuts anyway. The clearance is a much bigger issue because overlooking it usually causes some kind of damage. Whenever you cut into the material (or when you use clamps to hold your stock³) you need to have enough space for your machine and the rest of the bit. The machine itself mostly becomes a problem for deep pockets, but those small diameter end mills often still have a larger shaft. So, even if you observe the cutting length, you cannot cut at the side of a straight wall if you would run the shaft of your bit into it.

That should be enough of an overview. I am mostly writing down what I learned from others (mostly Youtube) over a few months, so I would recommend that, too, if you want to go deeper.

Now, finally, here is the list of bits I used in this project and the short name I use for them henceforth⁴.

Please keep in mind that I only got my first CNC router a few months ago, so these are mostly the first bits I ever used. I have no comparison to tell if they are good or bad, so take this as pure documentation and not as an endorsement.

The outside of the bottom shell (A)

Ok, it’s time to get serious. In the following I will go through all the toolpaths one by one and try to remember details that you should know about. For each one I will mention the bit I used, how long it took and the name of the gcode file I used (if available). As mentioned above it is unlikely that you can use the gcode file directly, but you should be able to view it in order to understand what the toolpath does.

The first step is to create the outside of the bottom half of the shell. For this you need a piece of wood with at least 160mm by 99.6mm and it should have a thickness of at least 23mm. Having a few more millimeters is highly recommended to allow for a few surfacing steps without becoming too thin.

A01

And surfacing is exactly what we start with. The current surface will be the one visible on the back of the Game Boy shell. So, it should look nice and needs to be surfaced down to a clean even plane. Keep in mind that the remaining thickness needs to be at least 23mm even after possibly surfacing the other side too. The exact thickness does not matter yet, so just aim for a nice finish on this side.

A02

This is my method of aligning the workpiece after flipping it. I drill small holes through to the backside that I can use to align it after turning it around. If you have a better way of doing this like a flip jig, a tool to measure distances along all three axes or even an additional axis, you can skip this toolpath.

I labeled this as a single path, but please notice that I have split it into two gcode files. The reason is that the working distance of my smallest bit is too short to go all the way through 23mm without hitting the wood with its wider 3mm shaft. So, there is a first step of drilling space for that shaft before creating the smaller and more precise holes on the backside.

If you use my solution, take note that zero is set to the corner of the Game Boy, so the hole in that corner will be drilled 5mm along negative x and y. So, when picking the start point to fit the 160mm by 99.6mm of the reference frame, keep in mind to offset zero by 5mm in both directions. This will be the zero for all subsequent steps, too.

Oh, and obviously, this step will drill through the entire workpiece and into your spoilboard.

A03

Next I do a profile cut that does not go all the way through. It will eventually meet with a profile cut from the other side (if aligned properly). At this point it also gives room for a few upcoming toolpaths that enter and leave the outer rim of the Game Boy shell.

A04

The curved sides on the back are created with a ballnose bit. However, I can still see distinct lines from the tool passes, so if you want to avoid that you need to set a higher overlap between passes or you need to do a better sanding⁵ job than me.

A05

This step carves the pockets for the cartridge slot and the battery compartment. Note, that it removes more material in the battery compartment than on the actual original Game Boy shell to make space for the upcoming toolpath using a 1.5mm downcut bit. My 1.5mm bit only has about 8mm of clearance before sloping into a 3mm shaft, so in order to create the finer details inside the battery compartment some room needs to be made. If you have a bit without such a limitation, you might want to optimize this towards the original.

A06

As mentioned before, this adds some details in the battery compartment. Important ones: These are the slits that will hold the battery contacts. My design is made for some after market contacts (see assembly section), but it has too much room and I needed to put something behind the contacts to hold them in place. If you know the exact contacts you want to use, this is something that could be optimized.

Oh, and this path also creates the decorative lines on the back of the Game Boy.

A07

The last step on this side drills some holes for the screws. These are not the holes the screws tap into, but the holes that the screws go through first. I have not tested the diameter much because I ended up gluing the shell, but they seemed ok.

The inside of the bottom shell (B)

Now it is time to flip the workpiece to do the inside of the bottom half. To do so, align it with your favorite method.

If you use my reference drills, align your workpiece such that you can jog 160mm along x and 99.6mm along y and always end up on one of the small 1mm holes as precisely as possible. Remember that you cannot fix the rotation of your workpiece if you use the tape and glue method (like I do), in which case I would recommend using a carpenter’s square to get the orientation right while gluing it and then use the holes to verify and to set zero.

Speaking of zero on my reference frame: Remember that the hole is at -5mm and -5mm, so align your bit above the correct hole and then move it by 5mm along x and y before setting zero. Keep that zero for the rest of the steps for the bottom half.

B01

Once again, it is time for surfacing. However, this time you are aiming for a final thickness of exactly 23mm. Of course, if you need to remove a lot of material, you can use a different method first, but at the end of this step you should have a perfectly flat workpiece with a thickness of 23mm. I designed the two sides to allow for a little uncertainty here, but I would say that you should hit 23mm to within about half a millimeter.

B02

This is the big workhorse step for this side. This removes most material to make room for the PCBs and it creates most of the relevant geometry inside. However, my gcode had a few problems here that you might want to improve on:

• I manually created layers for the pocketing that are far from optimal. By now I know better methods to do this, but at that time this was the best I could do in Blender CAM. The current toolpaths are inefficient and imprecise in a few places. You might want to recreate them with your preferred software (and especially if you have a beefier machine that can handle deeper cuts).
• A big mistake here is that one or two of the lower toolpaths accidentally cut away the lip and part of the rim of the shell near the power switch as well as the screw post near that switch. I compensated for that with a larger lip on the top half of the shell, but that is far from perfect. The reason for this error seems to be a boolean operator that did not work properly and failed to subtract that part of the rim from the pocketing area. Whatever the reason, you should carefully look at what would happen to the rim at the top of your Game Boy.
• Some parts were a bit imprecise. The screw posts for the metal shield of the Game Boy come to mind or the lower end of the link cable cutout. If you want to be precise, check out my photos and adjust things that are not perfect.

B03

First of all note that as far as I remember, the only reason for using an upcut bit here is that my 1.5mm upcut is a few millimeters longer than my 1.5mm downcut. If this is not a limitation for your tool, you should be fine with a downcut end mill, too, except maybe for some drilling for the screws.

This step adds some details to the power switch part, the battery contact cutouts for the main PCB and some small details like a little cutaway behind one of the screw posts to make space for the speaker cable. It also drills holes for the screws to tap in. In my experience the 1.5mm holes do not hold the thin original screws reliably. On the top half I will later drill 1mm holes, which unfortunately tended to break if a screw is tapped into a pole. So, some experimentation with alternative screws and drilling diameters might be in order here, especially if you plan to use a different kind of wood.

B04

And here is the final profile cut that should meet the profile cut you did on the other side. Note that I use the tape and glue method and did not have to consider any clamps. If you use something else you have to think about bridges if required.

This is where you find out if you have aligned your workpiece properly.

A little detail you should note here is that I did not figure out a reasonable way to create the hole for the AC adapter plug. I ended up manually creating it with a file after the bottom shell was complete.

The outside of the top shell (C)

Now it is time for the iconic front of the Game Boy. Please read steps C02 to C03 carefully and think about them. These are the common sign-maker’s method of doing a V-carve, painting everything and then cutting away the excessive paint. I have little experience here and this is the part of my wooden Game Boy that I am absolutely not happy with. My method (or choice of paint or choice of tools or whatever) lead to quite some smearing of the paint and letters that look soft and unfocused.

If making the entire wooden Game Boy was less time intensive, I would probably have another try with white epoxy instead of paint. I also notice that many hobby CNCists⁶ use a belt or disc sander for this instead of a surfacing bit, so maybe that’s part of the problem. If you recognize why this did not work out so nicely in my case, please let me know. Anyhow, below is what I did to get the Nintendo logo and labels onto my Game Boy and you might want to think about a different method.

You will also notice that I did not list a surfacing step. That’s because my method involves V-carving below zero and a later surfacing step anyway. Depending on what you want to do, you might want to surface first.

C01

Again, the reference for flipping. Again, skip if you prefer a different method. And again, if you use mine, remember to offset zero by 5mm along x and y.

But there is one important difference: If you use my method of painting you will have to remove the workpiece, paint it, replace it and realign it on the same side. That might not work with a flip jig if it cannot be fixed to your machine’s bed.

C02

Now, this engraves the Nintendo logo and button labels with a V-shaped bit. I actually ran that toolpath twice: Once starting from the surface (resulting in perfect letters at the surface) and then again starting 2mm below the surface. This is because I will later remove 2mm to return to the perfect letters and remove excessive paint. I did this in two steps because I was not sure if plunging a total of 4mm directly would be too much (now I think it wouldn’t). Also, 2mm might be a bit much, but I had made the observation in earlier tests that white paint enters the wood grain even with a clear coat primer, so I wanted to be safe.

Painting

A step that is not a toolpath. Paint your workpiece such that the logo and labels are properly colored. I used spray paint for this and first applied several layers of clear coat as a primer. After it had dried completely, I added several layers of white spray paint. The point of the primer is mostly to prevent white paint from entering the wood grain and showing up several millimeters deeper where it should not be visible. Make sure to seal up every part that could get sprayed with white paint - not only the actual letters.

Any suggestions on improving this method are welcome.

And of course, I had to remove my workpiece for this step. If you apply paint with a brush, you might be able to do this in place.

C03

Here I now removed the 2mm that I dove too deep during V-engraving. This removes all the paint outside the carved area, theoretically leaving me with perfect and precise letters. However, as mentioned above I am not entirely happy with the result and you might want to consider alternative methods.

C04

Next I did a profile cut and again not all the way through. This gives some room for some of the upcoming toolpaths at the edge. Also note that I will chamfer the outline of the Game Boy front, so there is no need for a downcut bit here.

C05

This is a simple shallow pocket for the screen bezel and a little drilling to create the hole for the power LED.

C06

The pocketing of the buttons, the actual screen and the speaker grill is done with a finer bit. In some cases because of thin lines and in some cases to achieve sharper corners. In some cases because it seemed like the buttons should be part of this package.

C07

The Game Boy features a slope at the speaker corner and some smooth indentations around the buttons. These are done with a ballnose bit.

C08

Finally, my favorite step of most CNC projects. Chamfering. So satisfying.

Unfortunately, there is a mistake in my toolpath. While just following the outline works perfectly for most parts of the Game Boy front, I underestimated the effect of the slope at the speaker corner. A 45° chamfer towards this slight incline resulted in a bit of overhand and a slightly weird look. I sanded⁵ most of the problem away, but you might want to consider skipping chamfering in this corner.

C09

The last step on the outside of the top half just adds the decorative fine lines to the front. This is quick and easy, but note that the only reason for using an upcut bit here is that I simply don’t own a 1mm downcut bit.

The inside of the top shell (D)

Once again it is time to flip your workpiece and align it. And once again remember to offset by 5mm if you use my method.

D01

If you use wood from the same board as the bottom half of the shell, you probably have to remove a lot of material here. You are aiming for a final thickness of 14.5mm. And this one needs to be very precise. On the bottom half a too thick shell might make it harder to get the battery contacts through to the battery compartment, but on the top half this impacts the top position of your buttons, how deep the screen is below the window and whether your speaker grill goes through (spoiler: mine didn’t).

D02

This is the massive pocketing job for the inside, covering most parts. Note that I took some liberty in optimizing the shape for a subtractive process. The original injection mold shape obviously tried to save material while we would like to save on carving away material. So in many parts I left a lot of wood in there, where the original Game Boy just has pockets of air. This should also make it more rigid.

D03

Adding details that could not be done with a 3mm bit in the previous step. Most notably some details around the buttons and the inside part of the speaker grill. Like on the original, the speaker grill is designed such that the lines on the outside just touch the ones on the inside to create openings. Unfortunately, this just did not work out on my build, but the sound can still be heard very well, so I am not attempting to tinker with it. However, you might want to keep an eye on the problem and maybe move paths closer together.

D04

Super short, super simple. The cutout for the headphone jack. I only used a ballnose because this is curved. If you want to save time, you could probably have just done it with a flat end mill in one of the previous steps.

D05

Finally, the profile cut that meets the one from the front. Hopefully you aligned everything perfectly.

D06

This drills 1mm holes into the poles for the screws to tap in. As mentioned in step B03, the 1mm holes also did not work perfectly. In my opinion they are better than the 1.5mm holes I used on the bottom half, but the longer poles near the display were split by the screws in this case. If you come up with a better solution, I would like to know.

Battery cover (E)

Wait, we are not done yet. You still need a battery cover. However, since I did not see how the latch of the original Game Boy could be created with a CNC and survive more than one battery changes, I made a very simple design that uses magnets to hold the cover in place.

So, this is a rather quick process and you only need a piece of wood with an even thickness of about 4mm to 5mm. The magnets should be 1mm thick discs with a diameter of 5mm and I could simply press them into the pockets.

E01

This step cuts references for flipping and adds the decorative lines on the outside of the battery cover. That’s it. Nothing more to see here and it is time to flip the wood piece to the other side.

E02

This of course could have been one gcode file, but I couldn’t be bothered for this little part at the end of all the work. In this step you will flatten the cover to the desired thickness while leaving a lip that prevents it from sliding out. Here you also create the pockets for the magnets and do the profile cut, which will go below your workpiece into your spoil board.

Assembly

That’s it, the hard part is done. You should sand⁵ any problematic or rough parts and apply wood finish. I use boiled Linseed oil, but there are many options⁷ out there and many people with more experience in selecting them.

After that, you should be able to simply disassemble a Game Boy and replace its shell with your new wooden one.

I actually only used the original mainboard of a broken Game Boy from ebay and aftermarket parts for everything else, so let me show you a few details.

First of all, the metal shield between mainboard and cartridge slot can simply be screwed into the wooden shell with the original screws (ok, those are also original parts). You just might need to file away some edges to fit the bent parts around the screw posts.

The same is true for the PCB and the attached boards. However, here I already had some problems of screws not holding well in the 1.5mm drills I did on the bottom half. The 1mm drills on the top half worked better, but posts tended to break there, so be careful here.

In the battery compartment you just have to insert the additional contacts. The outer contacts are already there from the PCB. Note, that in contrast to the photo above I had to put a thin piece of cardboard behind the contacts to press them against the batteries.

The white aftermarket plastic buttons fit perfectly, but there are some tricky aspects to the silicone pads between the buttons and the PCB. First of all, there are very thin poles that help aligning the silicone pads. They do not have to hold against any force, but still you should be careful to not break them as they really help putting everything together. Second, the silicone pad of the A and B button has a somewhat complex line around the buttons that looks roughly like a figure eight with an additional outline. I did not reproduce the slit for the additional outline, which prevents it from being flush on the wood by default. You either have to add a carving for the outline or cut the outline from the silicone pad like I did with my aftermarket pads.

For the display I decided against using an original screen⁸ and picked up a modern IPS mod kit instead. Note, that I made a few simplifications and optimizations to my design to fit this display. In particular, the contrast wheel has an additional lip on the original Game Boy and there are additional posts at the top of the display which I did not model. I think that an original display also fits, but you might look into this if you want to use a different screen.

I did not find a good way to add a small pole right next to the large pole in the bottom left corner of the display (viewed from the inside). Unfortunately, the plastic holder for the display that comes with the kit uses this pole as one of four poles that hold it in place. However, it still seems to be very stable when using only three of those poles. The PCB of the kit can simply be screwed into the shell with original screws and holds very well with the 1mm holes I drilled here. Only problem is that the poles below the display split in the process. So,… well… I am not sure what to make of this. The PCB is held very securely, but I am not sure if I will eventually find cracks in the case from the other screws over time.

Finally, all you need to do is to connect the two halves and glue the display cover into the screen bezel. There is just one major catch: For me the two halves were too tight and the screws could not properly hold them together. I am not sure if filing and sanding some parts for a better fit will help and if tapping the original screws into 1mm drill holes instead of the 1.5mm ones I have in the bottom half might be enough, but I only found a somewhat nasty solution: Gluing the case with wood glue.

While I still love the resulting Game Boy and while it feels very solid and reliable, it bugs me a little to have a slight gap on one side and a bit of glue residue. If I ever want to reach the parts inside, I probably have to crack the case open, but at least no original parts had to be glued and could simply be replaced in the original Game Boy. Still, it would be nicer if I could just open the shell in case I ever need to do maintenance inside.

Conclusion

When I started this project, I somewhat underestimated the amount of effort and time that had to go into it. But I also totally underestimated how stunning the result would be. At the moment it just sits on a sideboard in my office and I have to grin and pick it up each time I walk by it.

Initially, I planned to also machine the buttons out of a brighter type of wood. However, I did not find a good way to create a transparent display cover with matching wood applications and eventually settled for white aftermarket buttons and a matching display cover. Now that I see the result, I think that this was a good decision as it helps to define the shape and look.

Also, the Game Boy plays quite well. If I am looking for any playability problem, maybe the buttons trigger a little bit below their tactile response point and I am not entirely certain if this is to be expected. But this Game Boy will not be my daily gaming platform anyways. This is meant to be presented somewhere. At the moment I am thinking of making an acrylic stand for it and use my WiFi cartridge to use it as a status display in a prominent location.

Oh, and if you have been wondering about the wooden Pokemon cartridges: Those are based on the cartridge I published earlier with several improvements to the toolpaths (man, I learned so much from the Game Boy project) and the Pokemon logo added. These versions are also in the GitHub repository for the wooden Game Boy, but I did not add more documentation for it. If you got to this point, I am sure you can figure it out… :)

Since this is a very visual project, you should really watch the video. This blog post contains the same info with more details, but those details are probably only relevant if you really want to recreate this project, which is not an easy thing to do.

What is a bullet time video booth?

The story of this project actually begins in 2017 when I created a video booth for my own wedding. At many wedding receptions you can find photo booths, which are simple camera setups with a remote trigger to allow guests to create some memories of the special day. Usually this involves silly props like hats, wigs and giant glasses and it is as much about creating photos as a memory as it is about the fun of being creative while doing so. …and for my wedding I mixed it up a bit by putting my Sony NEX-5T on a tripod and allowing guests to take short 5 second clips¹ instead of static photos. Later I cut all the clips into one long video with upbeat music and we still enjoy watching this memory today.

My family enjoyed it so much, that one of my cousins used the same setup a few years later at her wedding and when another cousin planned his wedding for this year, he also asked for a video booth. But this time I wanted to try something new by adding a bullet time effect.

In case you never heard of it: The bullet time effect has been around for a while, but became really famous when it was popularized with the movie “The Matrix” from 1999. It really became a signature style for these movies and has been copied and reused so many times that it pretty much became a movie cliché. But while it can easily be recreated in purely rendered form like animated movies or video games, it is still quite involved and costly to achieve with real cameras: You set up an array of photo cameras, trigger them all simultaneously² and play back the individual photos as frames of a video. The result is that the scene seems to be frozen in time while the camera moves around freely.

And here you see the problem for hobbyists. If you are not rendering the entire scene but need to take photos of real people, this can quickly become expensive. Bullet time-time costs one camera per frame. For someone shooting with the typical “European” 25 fps³ that’s 25 cameras per second. And that of course also explains why my bullet time video booth only uses this effect for the transitions instead of recording several seconds of bullet time footage. I simply wanted to keep the costs for this project in a reasonable range by only using twelve cameras.

This means that I only have a bit less than half a second of bullet time footage per guest. But as you could see in the little example clip above (and more in the Youtube video) the effect is still nice and appears longer. To achieve this I used two tricks:

• I trigger the cameras at the beginning and the end of each video recording and they are arranged in an arch towards the wall behind the guests. By mirroring every second guest clip and playing the bullet time photos in different order I can combine the two twelve photo sequences from the end of the previous guest clip and the beginning of the next guest clip to make it look like the camera spins through the wall to the next clip. An additional blurred frame at the location where the camera would be inside the wall and a non-equidistant placement of the cameras for an accelerating motion towards the wall help to sell the effect. This adds up to 25 frames and therefore one second of bullet time footage.
• I created the final video of all guests (and the example above) in DaVinci Resolve and used its Optical Flow Estimation to generate artifical additional frames. This allows to smoothly slow down the bullet time effect further and also gradually slow down the video recording after leaving a bullet time transition and before entering the next bullet time transition.

So, I was able to pull this of with twelve cameras plus the one for the video recording. But this setup requires more than just the cameras…

Setup

In this section I will go through the important components of the bullet time video booth. Keep in mind that pretty much everything was selected to keep the costs as low as possible. Unfortunately, this also means that some components were a bad decision in hind sight and some components are simply more expensive or better equipment which I happened to already have. So, if you want to build something similar, be prepared to pick your own components and adapt the software to your needs.

Bullet time camera array

Let’s start by looking at the part that obviously is the most expensive because that purchase comes with a factor of twelve: The cameras used for the bullet time effect.

When I said that the bullet time effect is still expensive, I have to admit that it has become much cheaper since 1999. Cameras have become so readily available and good today that a comparison to 1999 equipment would be ridiculous. Still, I set myself a limit of 50€ per camera, which means that the twelve cameras alone would cost 600€, which I find quite heavy for a fun gimmick to a video booth⁴. And now think about what cameras you can get for 50€… There are some possibilities like webcams, used smartphones, used action cams, etc. But used ones for 50€ will have poor image quality and their small sensors are not ideal for this effect as they require more light for short shutter speeds or you will get a lot of motion blur. Raspberry Pi cams are also an interesting alternative in the maker world, but the cheap ones have very poor image quality and the better ones cost 50€ alone without a lens - and you need a few actual Raspberry Pis which are even more expensive.

Instead, I looked for old used DSLRs. They have large (albeit old⁵) sensors, they support means to remotely trigger the shutter, they have plenty of resolution, their settings can be controlled precisely and nobody except me is interested in them anymore. The trick is that we are using the photo mode of these old DSLRs to create a video, which means that we are comparing old photo specs with modern video specs. So, I looked for the oldest mainstream beginner DSLR that has a decent resolution and picked the Canon EOS 400D⁶ from 2006.

That camera is now almost 17 years old, which means that craigslist⁷ is full of those cameras. There are so many people trying to sell their old camera with almost nobody being interested in such outdated technology⁸ that I could simply work through the offers starting with the oldest listings. I offered my 50 bucks for the 400D and its mediocre kit lens, reminded the seller that nobody has even looked at the listing in six months, and either he accepted or I contacted the next one in the list.

But is it good enough? Well, that’s where we can now compare the photo specs to the video specs. The old 400D from 2006 has a photo resolution (it cannot even shoot video) of 3888x2592 pixels, which is more than our modern 4k (or actually UltraHD) video with 3840x2160.

Video camera

But since the Canons cannot record video⁹ I need one more camera as the main camera that shoots the video. Initially, when I selected the 400Ds, I aimed for 4k video and planned to use my trusted Sony a6400 for this. Unfortunately, it turned out to be rather difficult to trigger the video recording precisely and transfer the resulting video file. Both can be done via USB, but one requires the camera to be in control mode and the other one requires it to be in mass storage mode. Video files apparently cannot be transferred in PTP mode, which seems to be an oversight by Sony.

I either needed to use a Wifi SD card like I did in my old original video booth or record externally with an HDMI grabber. Since transferring 4k videos with a Wifi card (or maybe even recording to that old Wifi SD card) seemed like a bad idea, I dropped the 4k goal and went with one of my cheap 1080p HDMI grabbers instead. And since I did not need to tie up my good camera in this project if I only record 1080p footage through a mediocre HDMI grabber, I used my Sony a5000 instead. Some of you might remember it from an older post, because it requires a hack to get a clean HDMI signal.

So, we are down to FullHD, but as a plus using an old cheap camera gives me some valuable peace of mind when leaving the bullet time rig unattended at the wedding venue.

Quarter circle stand

At that point I thought that I had bought the most expensive part of my bullet time rig - until I faced the question of how to mount the cameras. Whichever solution comes to your mind right now: Remember to multiply its cost by twelve and think again.

Using twelve individual super-cheap tripods is impractical as someone will easily hit one of the tripod feet and misalign a camera from the other ones. So, I was sure that I need a common stand to which I mount all cameras. I first thought of traverse material as found on stage, but that is super expensive. The next idea was to build something myself out of plywood when I stumbled upon a B-stock e-drum rack. Specifically, it was a rack for the Alesis Strike Pro SE. On its own this is not ideal because its components are not enough to form a proper quarter circle and the horizontal bars are not mounted at the same heights. But I got that B-stock rack and a new one for a total of 93€ and combined them in a different arrangement. This even left a few spare parts that I could use to mount a screen to the setup.

Unfortunately, that was not the end of the problem, because I still needed to mount the cameras to the rack. That’s where I went for a solution that was too cheap. I got cheap clamps from aliexpress (which were fine) and attached them to the cameras with simple threaded rods and cheap threaded plates. My thought was that twelve cheap ballhead mounts are quite expensive in total and that instead I could rotate the clamp around the rack bar and adjust the second axis by tightening the threaded plates. Unfortunately, I ended up just tightening the clamps to the cameras until the threaded plates cracked, which worked ok that one time, but if I want to use the setup again, I need to replace all plates - and probably buy twelve of those cheap ballhead mounts after all.

Power supplies

Another bad solution that I cannot recommend is the power supplies. You obviously don’t want to rely on batteries, so a set of dummy batteries from aliexpress had to be purchased (again, factor twelve - you see how this adds up?). For some reason I thought that getting ones that plug into USB ports instead of AC outlets would be a good idea, although both need to convert the voltage to the camera’s 7.4V. The tempting idea was that I could just plug all cameras into two 8-port multi chargers.

That was until I did my first tests and the cameras reset instead of taking a picture. At least when I triggered all twelve cameras simultaneously. Because in that case the chargers could not keep up with the sudden surge current and were unable to provide the proper voltage for the cameras. I think the problem here is that these old DSLRs need next to no power in standby as they do not show a live view. But when triggered, they have to move the mirror as well as the shutter while suddenly reading and processing the sensor - and they were designed with a Li-Ion battery in mind and not a cheap USB-based converter. The chargers on the other hand expect a more or less constant high current draw from a device that actually buffers sudden power demands with its own battery.

Regardless of the cause of the problem I tried many chargers and most of them struggled with the triggering cameras. In the end the multi-charger was the most reliable one if only two cameras were connected, so I ended up buying six of these multi-chargers, which of course was way more expensive and inefficient than using dummy batteries with individual AC power supplies in the first place.

USB connections

And while we are talking about USB problems, the data transfer was not any easier. I connected the twelve cameras through two active USB hubs. I think this is close to the limit of what you want to manage as a large web of USB cables. Larger projects should instead use a few Raspberry Pis and connect via ethernet, but twelve cameras plus a Rapberry Pi Pico (see next section) plus the HDMI grabber (on its own USB bus) should be managable, right?

Well, it worked on a Raspberry Pi 3 which I first used as the brain of the bullet time rig. I had some electrical issues like the entire USB bus resetting when I turn on the fluorescent lights in my basement, but in principle I could control and read-out all cameras reliably. But since the Pi 3 was too slow to generate a preview in under a minute I replaced it with an old Dell XPS 12. And suddenly I could not use all USB devices at the same time.

After some research I learned that the Intel xHCI USB3 host controller in that device has a limit of 96 endpoints and that USB3 uses (at least) three endpoints per device. That’s still plenty? Well, don’t forget that each USB hub and all internal USB devices like the laptop’s Wifi module, Bluetooth module, webcam, sensor hub and internal USB hubs count towards that limit. In the end, after blacklisting some devices (no BIOS option to disable the webcam) I still had one device more than the controller could handle.

The solution? Connecting the USB3 hubs through a cheap USB2 cable. Seriously. That forced the devices into USB2 mode, reduced the number of endpoints and solved the problem.

Camera trigger

Ok, so at that point we have all cameras mounted, they have power and they can be controlled via USB. That’s it, right? Not necessarily. You can trigger the cameras via USB and that’s what I tried first. But I found that this was not reliable and precise enough and that some cameras would trigger with a minor delay. Not much, barely noticable from the sound of the camera shutters, but if you play back the photos as a bullet time clip, you would notice that some photos were taken at slightly different moments in time - at least if there is fast motion in front of the camera.

So, instead I used the trigger inputs of the Canon cameras. These are fairly simple: It is a smaller TRS audio jack with a common ground and two contacts that control the autofocus and the shutter. These two contacts are pulled up to 3.3V by the camera and if you connect them to ground they signal the camera to focus or to trigger, respectively.

If you want to build a proper solution, you would now design a little circuit for each camera that decouples this electrically via optocouplers which in turn you control through some simple transistors and a GPIO pin of the microcontroller of your choice. If you are lazy, you simply connect all trigger inputs in parallel directly to the GPIO pin, set it to open drain mode to avoid it fighting with the camera’s logic level and let it drive all twelve pins to ground through a common connection.

I chose the lazy solution.

The advantage of this is that you can use cheap audio splitters and a bunch of cheap audio cables to connect all twelve cameras. Everything, including the GPIO connection, is just connected in parallel.

The disadvantage is electrical issues as all camera logic levels are connected through their pullups and all grounds are connected through the trigger cables as well as the USB spaghetti and dummy batteries with their voltage converters and USB chargers. You can tell that this is not how these triggers are meant to be used when you notice that all cameras trigger randomly if one of the cameras is turned off. This is an electrical nightmare and probably also part of the reason that the USB bus resets when I turn on the lights. I cannot really recommend doing this. …but it works.

Oh, the code for the Pi Pico of course is as simple as it can get, but if it helps you can get it from my github repository.

Bluetooth push buttons

A part that I am actually somewhat proud of are the big push buttons. Not because they are such an intricate design, but because they are mostly a spontaneous solution that worked perfectly. I left them for the end of the project thinking that I just need to add cables and connect them to one of the many GPIO pins of the Pi Pico that also controls the shutters. But when I got to that point I was uncertain on where the buttons would be placed at the wedding reception.

So, I spontaneously decided to make them wireless. And since I am not a fan of keeping a stock of Li-Ion batteries¹⁰ and also wanted to be able to have spare batteries available if necessary, I wanted to use good old AA batteries. So, I checked my stock of microcontrollers, ruled out the ESP32s which are a bad mix with AA batteries¹¹ and found the Raspberry Pi Pico Ws that I bought with another electronics order and had not used yet.

These are cheap, can easily run on two AA batteries and have a Bluetooth module on board (like the ESP). They are also small and easily fit into the buttons together with the batteries. Only problem: Their Bluetooth module has only been implemented recently and it is still a bit tricky to get this set up. Also, Bluetooth is currently only available in the C SDK. But once I figured it out I had two big push buttons, running on AA batteries all night long. They connect to any device that supports Bluetooth Low Energy as a normal HID interface, i.e. they act as a normal Bluetooth keyboard that only has a single button.

Only bad news is that the licenses for the Bluetooth example that I used have not yet been adapted by the Raspberry Pi foundation. By that I mean that my code is based on hid_keyboard_demo.c of the Blue Kitchen Bluetooth stack, which is currently only referenced by the Raspberry Pi Foundation’s pico-examples repository. While some rumors speak of an upcoming maker-friendly license, the demo is currently only available under the Blue Kitchen license, which explicitly prohibits any redistribution for commercial purposes. Since I receive ad revenues for my projects (i.e. Youtube) I cannot claim that there is no commercial purpose and hence I am not allowed to share my code at this point.

If the code is eventually released under a more permissive license, please let me know and I will happily share the changes I made.

Until then, it is not too tricky to adapt hid_keyboard_demo.c. Connect the push button such that a GPIO pin is connected to ground by the button, enable the internal pullup of that GPIO pin and modify the demo such that a keypress is sent when the GPIO pin goes low.

Update from October 2024: The license is still pretty much the same, but I do not think that anyone would still consider my code to be commercial after this time. So, you can now find it on github.

Lights

Last but not least, you cannot neglect the lights. On one hand you want your shutter speed to be short enough to avoid motion blur from jumping guests. On the other hand you also do not want to use any auto-mode of the cameras. You want to avoid auto-focus, auto-exposure and auto-whitebalance, because the cameras would get different results and the pictures from each camera would be slightly different, which in turn would lead to flickering when playing them back in sequence.

So, you have to manually focus all lenses to a fixed spot and you either have to set the exposure and autobalance via USB for all cameras and automatically adapt it to changing light of the environment as the sun sets - or you bring controlled lights that dominate the other lights, so you can work with a fixed exposure and whitebalance through the entire day and night.

I already had a selection of video lights from the Aputure Amaran series and brought a 200d (200W COB LED light with a light dome attached), a 60d (60W COB LED light with an umbrella), an HR672C (larger LED panel) and two F7s (small LED panels). That won’t impress a professional videographer, but it’s a decent collection for a hobbyist and still I could notice some color shifts when the sun hit the windows of the room during sunset.

Oh, and don’t forget to think about the impact on the actual wedding reception. In this case I was lucky as I could set up the video booth in a separate room that was not used at that time and everyone became curious because of the bright white light that came from the door to the other room. But if you are in the same room as the dance floor, people will not be happy if you kill the mood by bringing your own personal sun without shielding it somehow. Just sayin’.

Software

Well, that was the difficult part. In contrast to some other projects, figuring out the cheap solution and getting all the hardware was indeed more time consuming than implementing the software. Besides the two minimal firmwares for the Raspberry Pi Picos (the camera trigger and the push buttons) the software only consists of a bit of Python code, which you can grab from my github repository.

As mentioned above, the brain of the bullet time video booth is an old Dell XPS 12. This is definitely not an ideal device here as it is an older convertible laptop without particularly impressive processing power. In fact, this might be one of the worst laptops I ever owned since I never really used it in tablet mode and it had a lot of shortcomings when you think of it as an expensive laptop¹². But it was not in use and had significantly more processing power than the Raspberry Pi 3 that I tried to use first.

The thing is that this device shows the interface to the guests, which is either a simple countdown or an idle loop of previously recorded bullet time clips from other guests. But it also has to retrieve the photos from the cameras, record the stream from the HDMI grabber and convert the photos and that stream into video clips for a preview and that idle loop. On the Pi 3 it took more than a minute to create a 720p preview while the guests waited to see what they just recorded. On the XPS 12 it takes 20 seconds, which could still be improved with a newer device, but which is bearable for the guests.

The conversion to video clips is not a simple concatenation in ffmpeg. In order for the bullet time effect to look good, the cameras have to be aligned perfectly, which is nearly impossible with the cheap mount solution that I picked. Also, you have to expect that the alignment will not remain perfect throughout the entire wedding reception as guests might accidentially bump into cameras¹³. So, instead of trying to achieve a perfect alignment, I made sure that the focal length of the bullet time cameras is a bit shorter (i.e. wider viewing angle), so that I can align and crop the resulting images later. This is the same as image stabilization for a video with the benefit that a misaligned frame does not come with additional motion blur. So, I used ffmpeg’s image stabilization for the clips that were generated on-site (preview and idle loop).

The filters in ffmpeg also came in handy to create what I call a “Pseudo in-wall frame”. That additional blurred frame at the location where the camera would be inside the wall, which I mentioned earlier. This is simply the photo from the camera closest to the wall, shifted slightly so that the wall is in the center of the image. A strong directional blur then masks the fact that the perspective is still far from the wall and only leaves a wall-colored smear that sells the idea of the motion blur that you might see if you could actually move through the wall.

The entire thing is implemented in Python and uses gphoto2 to communicate with the cameras via USB and an ffmpeg-wrapper module to generate the preview clips as well as the higher quality 1080p clips that are shown while the booth is not being used. The interface however is implemented in Flask and shown in Chromium. The reason for this is that the video players in webbrowser are among the best players in terms of performance and frame-precise playback. Since the clips are shown randomly during the idle loop they have to alternate between the mirrored and regular version and in order to sell the impression of the camera moving through the wall, the next clip has to start playback precisely on the last frame of the previous clip. This can be achieved with two HTML5 videos that alternate their playback state, so that one can preload the next clip while the other one is visible and playing. With one of the players being mirrored with a simple CSS transformation and without any noticable performance cost, the alternating flipping comes naturally in this system.

Post-processing

Now, there is one last step missing to get the bullet time clips from the preview above. The ffmpeg version only generated a rather generic image stabilization by trying to stabilize the entire image, which includes countering the apparent rotating motion of the camera. Instead we want to stabilize the central point around which the camera moves. This is something I had to do manually in post using DaVinci Resolve. I used a simple tracker and a bullet time clip in which a person stood quite precisely in the place that should be the pivot point for the camera rotation. I tracked some features on the person and stabilized them while also zooming into the footage slightly to avoid black corners around the repositioned images.

There is no reason to do this tracking for every clip, as the solution of the reconstructed camera motion can simply be applied to all other bullet time shots as long as the cameras have not been moved. So, I only had to do this three times for the entire footage from the reception when a guest bumped into a camera and changed its alignment. In the end there were some cameras that were so misaligned that black borders were no longer avoidable and I masked this with a blurry scaled copy of the orignal image behind the stabilized one.

Another important processing step in DaVinci Resolve is adding additional frames. The one second bullet time transition generated with ffmpeg on-site already looked quite nice, but with optical flow estimation it is possible for many clips to add almost perfect additional artificial frames. So, I set up a slowed down version with Resolve’s Time Warp feature, which does not work for every scene and sometimes creates obvious artifacts, but which helped to really bring out the bullet time effect for scenes on which it worked nicely.

In the end my cousin’s guests recorded more than 100 clips, which I had to edit into a longer video. Luckily, DaVinci Resolve can be automated with Python, so I set it up to automatically generate stabilized versions of all recordings with different amounts of additional artifical frames. This means that I had a collection with different variants of each clip, so I could pick which version looked best and also which had the right duration to match different music tracks. So, of course, not every clip ended with a bullet time transition as slow as shown in the demo above. In the end, nobody would want to sit through a video with a hundred of those, but it helped to showcase some really cool transitions with airborne kids, flowing hair and flying items¹⁴.

Conclusion

At this point I have to say that the final video worked out even nicer than I had hoped for. In fact, the part that bugs me most in the end is that this ugly wood panel wall in the background really downgrades the final look, but that could not be helped. If there is a next time (as in another occasion, not as in that same cousin marrying again) I should prepare a backdrop. Before the actual wedding I was really worried that I would spend a lot of time debugging and fixing things instead of celebrating with my family, because there were so many things that failed during tests. In the end there are 13 cameras in a rather naive electrical setup and if any one of them got stuck or had any other type of problem, the shots would be ruined. I had to deal with loose memory card covers that turned off a camera, a lose contact in one of the dummy batteries, some cameras dropping out due to a bad USB cables and of course all the troubles I had until I had enough power supplies to get a somewhat stable voltage when the cameras are triggered.

I got really lucky that none of this happened on that particular day. I had included a simple recovery code that detects unresponsive cameras and tries to reconnect the USB hub with all the cameras while warning the guests to wait a minute or call me if the issue persists. According to the recordings and what I heard from the guests this happened once, but I did not have to personally tend to it even once.

Still the point is that you should not try to set this up for your own wedding. Someone with some spare time and the appropriate knowledge should be ready to spontaneously fix things, which usually does not apply to the bride or groom. If you want this for your wedding, ask a nerd friend to look after it and if you want to build this for a friend, make sure that you have time to fix things on site.

But if it works, this is a fantastic alternative to the traditional photo booth. You can be sure that guests have never seen something like this before (well, unless my Youtube video becomes more succesful than I would expect), they will have a lot of fun posing in front of the camera array and playing with the bullet time effect (especially later in the evening) and the happy couple really enjoys watching the result and sahring it with their guests after the wedding.

And sorry if this pops up in your RSS feed several months later. I simply forgot to add a blog entry for this and backdated it.

The video above should give you a good overview of what it does, how it works and what its limitations are. This article here goes more into the technical details of how it works. If you are interested in how to order and build your own GB Interceptor, check out github and the order and build video.

Why do we need this?

The best way to explain why¹ I developed and built the GB Interceptor is to explain which problem I tried to solve with it. A few months ago a Tetris enthusiast got in touch with me about this problem: An online Tetris tournament during which the contestants stream their gameplay.

Today, there is nothing unusual about streaming footage from a Game Boy. Emulators can easily do it and modern Game Boy variants like the Analogue Pocket offer HDMI output that could be captured. There also are some mods to add HDMI out to original Game Boy hardware, so getting a video stream from a Game Boy is a challenge that has long been solved.

The unusual detail about doing it for a Tetris tournament is that the players have to rely on their muscle memory which they trained on their personal Game Boys. Switching them for an unfamiliar modern device or an emulator will significantly impede their ability to play competitively. Also, you can imagine that a tournament that asks each contestant to first mod the hell out of their beloved Game Boys just to stream a video would not be well received.

So, we need a way to get a video from unmodified Game Boys also without modifying the game that is being played. Ideally in a form that can be used by anyone without complicated software or additional hardware like an HDMI grabber.

Basic concept of how it works

Well, in the end, the only connector with game data that is accessible on a Game Boy without a mod is the cartridge slot². After all, the entire game data has to go through there. So, the idea is to create an adapter that connects the cartridge to the Game Boy directly and only adds the capability to intercept a copy of the transferred data.

However, this means that we cannot randomly access data of interest and we cannot see the data in RAM that the Game Boy’s CPU put together from the raw instructions from the cartridge. Especially, we cannot see the Video RAM, which would have been very nice as it would contain everything³ required to draw the image on screen. Instead, we need to create our own copy of VRAM.

To do so, I had to write an emulator to which I feed the data from the cartridge memory bus. For this I use an rp2040 (the Raspberry Pi Pico’s microcontroller) and split its cores to the two main processing parts of the Game Boy. One core emulates the CPU to recreate a copy of VRAM and the other core emulates the Game Boy’s graphics unit, the PPU⁴.

The CPU emulation actually is the trickiest part here, because it has to keep up with the memory bus that is pushing out events at a rate of about 1 MHz. If the PPU emulation falls behind, it would cause a short glitch like a flicker, but if the CPU emulation falls behind, it will eventually miss an event on the memory bus. Not only would the simulated copy of the RAM possibly get out of synch forever, but the emulator would not even be able to interpret the following instructions. An event on the bus is not always the next instruction, because the Game Boy’s CPU may take several cycles to execute some instructions while others are completed within a single cycle. So, the emulator has to keep track of how many cycles have to be ignored after a specific instruction before an event should be considered to be an instruction again. If we miss only one of them it becomes nearly impossible to get this right again.

This together with the overhead of emulating an 8-bit CPU on a 32-bit CPU made it necessary to overclock the rp2040 from its default 125 MHz⁵ to 225 MHz. The rp2040 can usually handle this without any problems, but still I would love to see if someone can improve the efficiency of my code to dial this back a bit.

Since the PPU emulation is not that critical and actually periodically gets some free time during the Game Boy’s vblank period when no image is being drawn, it also handles USB communication.

The hardware

The actual hardware to implement this is pretty much a Raspberry Pi Pico with some bus transceivers to connect its GPIO ports to the cartridge bus. From the 32 pins of this bus, two are used for +5V and ground, one is used for analog audio⁶ and one is used to control the reset state of the Game Boy. The other 28 pins are connected to the rp2040, which therefore gets access to 16 address pins, 8 data pins and the four bus control pins clock, read, write and chip select. Since these use 5V logic I use the same bus transceivers that already served me well in the WiFi Game Boy cartridge to convert the signals to 3.3V for the rp2040.

This leaves two GPIOs unused. One observes the voltage on the +5V line to check if the Game Boy is turned on or not and the other one controls a status LED and reads a mode button.

The rest of the cartridge is based on the minimal hardware design example for the rp2040 by the Raspberry Pi Foundation. This includes an oscillator, flash memory, a voltage converter and a USB port, which I replaced by a Type C variant.

That’s pretty much it. A Raspberry Pi Pico in Game Boy cartridge format hooked up to the Game Boy’s memory bus. The schematics and PCB designs can of course be found in the project’s github repository.

Implementation

What really let’s the GB Interceptor do what it does is its software, which can of course also be found on github. In the following I will write about some of its details.

USB video class

The GB Interceptor streams the resulting image using the USB video class implementation of TinyUSB, so in theory no drivers are needed and it should just show up as a webcam. Well, in theory. Unfortunately, this only works as expected on Linux, where I can directly use the GB Interceptor in VLC, OBS, Zoom or ffmpeg. On Windows and Android many apps seem to have trouble with the format of the video stream. On Windows, for example, VLC (despite working on Linux) complains that no suitable format could be found while OBS works perfectly fine without any settings or drivers required. On Windows this is good news because you can use OBS as a virtual webcam to forward the GB Interceptor stream to any software that is picky about the format. A list of tested host software can be found on github.

Unfortunately, at the time of this writing I was not able to get any video on MacOS and I am not yet sure why. For some reason it does not even trigger TinyUSB to enable the video stream, so I am not entirely convinced that it is the format. Keeping in mind that I have not yet done many tests on MacOS and that the video class implementation in TinyUSB is very recent and experimental, I hope that I can fix this in the future. Even if I could not get the video class to work here, it should be possible to pump the images through UART on the USB bus and use a simple Python script to convert it to a video stream on the system. You can check the current state of this issue on github.

So, what is that unusual format? Well, obviously, this starts with the Game Boy’s resolution of 160x144 pixels, which I can imagine might surprise some software expecting a modern 1080p stream. But it gets a bit more complicated when we look at the limitations that arise from the rp2040’s Full Speed USB port and its implications for the isochronous transfer implemented by TinyUSB. This combination means that the maximum buffer size for this endpoint is 1023 bytes and since isochronous transfer happens every 1 ms, we get 1,023,000 bytes per second.

If we just look at the raw image from the Game Boy, this is more than enough. The Game Boy has a “color depth” of 2 bit, so one image frame is 5760 byte. With roughly 60 frames per second we only require 345,600 bytes, which is why I see a custom UART protocol as an interesting alternative on MacOS if all else fails.

However, we do not want to need a driver or additional software. We want something that just works and unfortunately there is no 2bit color format that is widely accepted. Instead, there are plenty of compressed formats for which we do not have enough computation power left⁷ and some uncompressed color formats that are considered to be widely supported, most of which use 16bit per pixels. Instead we use a supposedly also widely supported slightly more efficient format: NV12 with 12 bit per pixel. The 12 bit are comprised of 8 bit per pixel for luma (grayscale brightness) and 16 bit shared by four pixels (hence 4 more bit per pixel) for the color information.

The good news is that the color data of the entire frame is stored at the end, so we can set it to gray or green once and can ignore it. In fact, we can treat the data before as a simple 160x144 pixel buffer with 8bit grayscale data, which is more or less ideal for our purpose.

The bad news, of course, is that it still takes up 6 times as much data as the original 2bit image would have needed. With our 1,023,000 bytes per second we are now limited to 29fps.

So, overall we have a 29fps NV12 stream at a resolution of 160x144. Not exactly what all those video conference tools expect.

By the way, although the GB Interceptor therefore only pushes out 29fps, it still works internally with 60fps and blends these frames to emulate the latency of the old LCDs. It just pushes out the latest blended frame whenever the USB bus calls for it.

Programmable IOs

Now after I explained how to get the result out from the GB Interceptor, let’s talk about the other end: How to get the communication on the cartridge bus to the rp2040.

Remember how much I struggled with my WiFi Game Boy cartridge when I tried to listen to a single event with an ESP8266? Interrupts were too slow⁸ and keeping the CPU in a tight loop observing the clock line was not an option. Well, the rp2040 has a trick up its sleeve: Programmable IOs. These are simple state machines that can directly access the GPIO pins as well as a FIFO buffer to/from the CPU. And these PIOs simply laugh at this task.

All we need to do is wait for the clock line to become low and then simultaneously read the remaining 27 GPIO pins that are connected to the Game Boy’s memory bus and write the result to the FIFO. For this we only need a single PIO and that executes only four instructions:

1
2
3
4
    wait 1 pin 28 ;Wait for CLK to go high
    wait 0 pin 28 ;Wait for falling flank of CLK
    mov isr pins  ;Read all GPIO pins to the input shift register
    push          ;Push the ISR to the FIFO

From there, the CPU can just pick up one of these events packed into a single 32 bit integer from the FIFO whenever it is convenient.

The emulator part

Now it is time to talk about what these events look like. Or rather, how we need to deal with them. At this point I expect that you have a basic idea of how the Game Boy works. For those who are not familiar with Game Boy development I always recommend Michael Steil’s “Ultimate Game Boy Talk”.

As explained above, the basic idea is that one core of the rp2040 interprets the incoming bus events such that it follows the same instructions as the Game Boy’s CPU. That is, it emulates the Game Boy CPU in order to recreate an exact copy of VRAM (and OAM). The second core then acts as the PPU and renders an image from our VRAM copy. This is mostly just the implementation of a basic Game Boy emulator, but there are some differences that I would like to talk (or write) about.

Conditional jumps and IO

First of all, there are several things that become much simpler in this scenario. Think about the program counter and conditional jumps. We do not have to implement those. The real Game Boy fetches the next instruction anyways. It does not matter if it is the next instruction by incrementing the PC or if it jumps to an entirely different address. The real Game Boy will fetch the next instruction and we do not have to care about where the instruction came from.

This solves one of the seemingly biggest issues: We cannot see any of the hardware I/O registers. In particular, we do not see the input from the game pad! How should we ever emulate a game if we cannot see the player’s input? Well, almost every code in existence will compare the gamepad input to check which button was pressed and make a conditional jump to code that is triggered by the button. Our emulator will simply follow these same instructions and does not have to care whether it was triggered by a button press.

You could say that the GB Interceptor is an emulator on rails.⁹

This only becomes a problem if the data from the I/O registers eventually ends up in VRAM. Imagine that the value of the gamepad is added to a base address to calculate the tile index to an image that shows the current state of the D-Pad. The CPU would get the instruction to fetch the gamepad register value, add a number to it and our emulator would not know the correct result of that operation. This result is then written to VRAM and we have no idea what is in that location.

However, these should only amount for small visual differences. I do not know of any example where this is done with the gamepad I/O, but I have an example for the DIV register. In Tetris it is used as a source for random numbers and most of the time it branches the code through conditional jumps to pick different blocks that come next or to generate the initial pile of garbage blocks in game mode B. We do not see that random number, but when it triggers the code to logically pick the upcoming block, we will still get the same block as we get to execute the same code. This also goes for the decision whether a block of the garbage pile in mode B is empty or filled, so we also get the same layout for the garbage stack. But those garbage blocks also have a randomized visual style and that is not based on branching code, but just a random number added to a base tile index.

The result is that we see the same garbage stack layout on the GB Interceptor, but the individual blocks have a different look. This is harmless and you would only ever notice if you compare the image to the Game Boys screen.

We only get into real trouble when an entire stream of prepared data is written to VRAM from one of the I/O registers. The only example that I know of (and that I can think of) is the link cable. Here, we can look at the same example of the mode B garbage stack, but in two player mode of Tetris. The problem is that both players should have the same garbage stack. So, the Game Boy that starts the game first will generate that stack and send it to the second one via link cable. The second one writes the data directly to VRAM without any checks or conditional jumps and we cannot see anything.

Therefore, in two player Tetris, the GB Interceptor works fine if it is in the Game Boy that starts the game first (except for the different visual style of individual blocks), but it produces unusable output if it is in the second Game Boy.

Clocks, the DIV register and the halt instruction

Speaking of the DIV register, this is actually an I/O register that we might be able to emulate. Since we get the exact clock from the Game Boy we can count an emulated register in synch with the real one without any danger to diverge. There are only two problems:

1. The initial value is unknown - at least to me. When the code from the cartridge is executed, the state of the DIV register depends on the Game Boy model and in some cases it also depends on the user interaction during the boot sequence of that model. For example, if you change the color mode of the Game Boy Color during the boot sequence, the DIV register will have a different value at the beginning. I am not sure if the Interceptor sees enough action on the bus during the boot sequence to compensate for that, but I also would not rule this out entirely.
2. We lose the reference clock when the Game Boy enters the halt state, which for most games happens at least once per frame. Here, the clock of the rp2040 has to take over precisely, which should be possible if we had a little bit more computational headroom. (i.e. if someone can optimize my code)

The thing is that we actually measure how many rp2040 clock cycles occur for each Game Boy clock cycle during the boot sequence before the actual game starts. Here we can observe thousands of cycles and should be able to get a very precise substitute clock from our rp2040. Unfortunately, for performance reasons, I only use an integer ratio of both clocks, which typically is in the order of 225 rp2040 clocks per Game Boy clock. This means that just the rounding error will lead to an error of roughtly one cycle per 100 cycles during a halt state, which happens regularly.

So, maybe we can do a fractional clock count, but for now as it only affects the div register which I cannot properly initialize anyway, this is not implemented.

Synching CPU and PPU

While we are on the subject of synchronizing our emulator to the real Game Boy… We of course also need to synchronize our PPU to the one of the real Game Boy. Otherwise any effect that requires changes in the VRAM midframe would lead to glitches and at least we would see some tearing effects as data is updated in VRAM randomly.

The problem is, that no trace of the PPU can be found on the memory bus. We have to deduce the state of the PPU by the behavior of the game, which has to synch to the PPU as well - at least to know when it may write to VRAM. The big problem here is that games can use many different ways to do so.

The most common method, is the vsync interrupt. Most games simply let the Game Boy trigger an interrupt when vsync is reached and we can see when the code of this interrupt is being executed, so we can simply adjust the timing of our own emulated PPU to enter vsync at that same moment.

Unfortunately, there are many other options to do this. Another common one for games that need to squeeze out a bit more access to VRAM (for example implemented in Donkey Kong Land) is to read the LY register in a tight loop and to periodically compare it to a specific line number. A conditional jump jumps back to the LY readout until the correct line is reached and the code simply goes beyond the conditional jump. Luckily, the developer can save a few cycles by jumping while it is not reached, so many games do it this way, which allows for a simple and naive detection of these tight loops in the Interceptor.

However, there will be games out there with a different approach (like my Wifi cartridge) and the output of the GB Interceptor will look glitchy until a detection for these other methods has been implemented.

Detecting interrupts

Oh, and while interrupts are a blessing to synch the PPU, these are not exactly easy to detect in the first place. We need to keep track of every single instruction and how many cycle the Game Boy needs for each instruction to be sure which event on the memory bus would be the next instruction. The Game Boy jumping to a different point in the execution and taking a few extra cycles to do so is not exactly helpful here.

Have a look at the first vsync interrupt of “The Legend of Zelda - Link’s Awakening”¹⁰ on the original Game Boy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  Address Data Instruction
   01a2    fb    EI 
   01a3    c3    JP a16    
   01a4    bd    
   01a5    03    
   81a5    71    
   03bd    3e    IRQ    
   82bd    01    
   82bd    01    
   dffe    81    
   dffd    a5 
   0040    c3    JP a16    
   0041    25    
   0042    05    
   8042    24    

When ignoring interrupts, we would falsely interpret 0x3e in line 7 as an opcode. The only way to be more or less sure that we are seeing an interrupt is by implementing the GB Interceptor such that it reads ahead¹¹ a few cycles to recognize an interrupt before the current event is misinterpreted as an instruction when in truth it is just garbage on the memory bus while the CPU takes a moment to enter the interrupt.

Luckily, the Game Boy jumps to few fixed addresses during an interrupt, so we look out for those. But since these addresses could theoretically also be called from regular code, we mix in a few more indicators, specifically the behavior of the stack pointer. During an interrupt call, the current PC is pushed onto the stack, so the SP register is decremented twice and the Game Boy writes to the two decremented addresses. Usually these do not point to an address belonging to the cartridge, but these addresses are still visible on the memory bus, so this adds to our confidence to detect an interrupt.

The only trouble with this is that the Game Boy is not really required to do this consistently and to show the SP address on the memory bus as no game cartridge cares about these operations. Therefore, it is not surprising that we can see a few differences here between different devices. Here is only the interrupt call for the original Game Boy (DMG), the Game Boy Color and the Analogue Pocket:

1
2
3
4
5
6
7
8
      DMG                 GBC                Pocket
  Address Data        Address Data        Address Data
   03bd    3e          03bd    3e          03bd    3e
   82bd    01          83be    00          dfff    00
   82bd    01          dfff    00          dffe    01
   dffe    81          dffe    80          dffd    9b
   dffd    a5          dffd    00          0040    c3
   0040    c3          0040    c3          0040    c3    <   Next instruction

If we look at this closely, we find some slight differences: The DMG also shows the SP address before decrementing it, the GBC only shows the two decremented addresses it actually writes to and the Pocket does this one cycle earlier. Taking all these cases into account, of course makes our interrupt detection less reliable and at the moment it does not work properly with the variant of the Pocket.

Schematics and build instructions

I think these are the most interesting parts of the implementation. Kudos to you, if you have read up to this point - you are a true 8bit geek!

If you want to see even more details, you now have to dive into the code on github where you can also find the hardware design files and material for cases. I hope that there will be some community contributions to both, the code and hardware design, so if a few months have passed since the publication of this article, this is also something that will mostly take place on github.

If you want to build your own GB Interceptor, you should also watch the order and build video.

I hope you enjoyed this project!

Acknowledgements

This project would not exist without the work by many people who researched, tested and prodded the Game Boy before me and (most importantly and why I am writing these articles myself) documented their work. Here are some of my most important resources:

• gbdev.io and especially its Pan Docs was my prime source for everything about how the Game Boy works.
• Many hardware details and some intricate specifics can be found on Joonas Javanainen’s webpage.
• While there are many site with opcode tables for the Game Boy, I found the one by Megan Sullivan to be the most convenient one, which is why I had it open pretty much all the time.

I have never done this before and am quite curious on how it will turn out and how many will attend. See you on Friday!