If you want to either test the program before committing to physically purchasing the hardware required to run the program or if you want to alter the source code and develope the program yourself but do not have access to the hardware at the time you can use one of the device emulation methods detailed below. Device emulation lets you create a virtual instance of the display and see it's output without an actual display. A Windows 10 or Linux computer will be required, Mac OS should also work, however I have not been able to test this to confirm.


: Important

A strong level of computer skills are assumed with the following guide, the guide will not cover all required steps, step by step but instead provide only a general idea of the work needed.

Types of Emulation

There are three types of emulation available, pygame, gifanim and capture. To run anyone of these emulators you should send a tag of '--Display' to the program followed by the emulator type. The default is 'ssd1322' which is a real physical display.


pygame emulator only currently works on Linux based systems, or using Windows Sub-Systems for Linux, if you already own a raspberry pi of any kind running a non lite/ graphical version of raspbain this is my recommend approach. pygame will launch a new application window, which will emulate that of a real display. Simply close the application to stop running the program.


gifanim will work on both Linux and Windows, when running it will produce a gif of the screen output, the gif can then be viewed back to see the output of the display. The length of the gif is dependent upon the value of '--max-frames', which states how many frames the gif should last for. Therefore once the gif is of the max length the program will close and save the gif for you to review.


capture will work on both Linux and Windows, when running it will save every frame of the display as an image file to your device, this will keep running continuously until you stop the program from running with 'Ctrl+C'. The outputted frames can then be made into a video using additional editing software of your choice.

Emulation on Linux

Emulation on Linux should be straight forward, for most distros simply follow the instructions on the project website. pygame emulation however requires a graphical version of Linux and has only been tested of raspbian buster.

Emulation on Windows (10)

Emulation on Windows is much harder, many of the libraries used by the program require parts of Linux. Windows 10 however now supports Windows Subsystems for Linux. Using WSL you can run the program and it's emulation. A full guide on how to download and install WSL is already provided by Microsoft here:

I would recommend downloading the Debain version of Linux as this is the one closet to what a Raspberry Pi uses.

Once you have WSL installed, download the git hub repo to your local Windows machine, navigate to the project in file explorer, hold down shift and right click, then click "Open Linux Shell Here". This will launch a Linux command window, from here follow all the instructions on the project website about installing all the required program libraries. Once you have all the libraries installed you can run the program passing the '--Display' command to run an emulator. At time of writhing pygame emulation does not work on Windows. The output of the emulation, either a gif or a collection of image files depending upon your option will be saved into the same location as where you launched the console window from (the project folder.)

To run PyGame on Windows you will need to set-up GUI apps in WSL, my recommended way of doing this can be found here: