NESPi Software Install Guide

If you're following this project you might have seen the guide videos I've made about it.

So far we've printed and assembled the case, installed the electronics and the next step is to install the software.

This post will serve as a companion to the software install video and will contain links and screenshots to help you do everything at your own pace.

If you're like me and Raspberry Pi is your introduction to using Linux, then you might find it a bit daunting, it's quite different to what you're used to on Windows or MacOS.

I use Windows, and this guide will show the setup using a Windows machine.

Before we start you'll need to make sure you have:
  • Raspberry Pi 3B
  • Micro SD card
  • SD card reader
  • USB keyboard
  • Ethernet cable
  • Micro USB Power supply and cable
  • HDMI cable and Monitor/TV
  • Computer and Internet connection
  • Electronics Kit (optional)
You can start the install without the kit, but I'll be referring to it's functions throughout the rest of the guide.

To make things easy we'll use the RetroPie image that's been specially built for Raspberry Pi by the guys at the RetroPie project.

They have a great installation guide that's really useful as a reference.

First we need to download the image for Raspberry Pi 2/3:
Next we'll extract the the .img files from the .gz file we just downloaded, ready to write to our micro SD card.

To write the .img file to our SD card we can use Win32 Disk Imager on Windows or as RetroPie suggests, Apple Pi Baker on MacOS.

Once the image had finished writing we can insert the SD card into our Raspberry Pi and start our first boot.

We need to connect our USB keyboard and Ethernet cable to our Raspberry Pi, and if you have your electronics kit installed then plug your micro USB power cable into the top port.

Booting Up...

Hold down the reset button until the LED flashes white. It will then turn blue and the front LED will start to fade up and down.

The Raspberry Pi will now be powered on and will start to boot.

If you don't have your kit installed yet then plugging-in your micro USB power cable will start the boot straight away.

Your Raspberry Pi will reboot a couple of times and you'll see some text scrolling but after a short while you'll be presented with this screen:

You should have your keyboard plugged in and when you hold any key down it will detect it and show you the controller configuring page.

Go through this process pressing the keys on you keyboard to map to the controller inputs, it doesn't really matter for now what keys you choose, you can set up your controllers later.

Setting up your keyboard now will let you navigate EmulationStation for the purposes of setting everything up.

You should now have this screen on your Raspberry Pi:

You'll notice it's empty bar the settings page, this is because we haven't transferred any games yet.

We do want to go into this page briefly in order to change a couple of RetroArch settings.

First we want to go into 'settings' and 'configuration' and make sure that 'save on exit' is on.

Then go down to 'network' and change 'network commands' to on.

This will enable our reset button to reset our emulator like it does on the original console.

We can now exit this menu and our settings will be saved and we can start to install the rest of the software.

Installing additional software...

To transfer the files and install software we're gonna go back to our computer and download WinSCP and PuTTY.

We can get both programs from the WinSCP page here:
These programs allow us to connect to the Raspberry Pi so we can transfer files and also install software on the Pi itself.

You'll notice, if you've got your electronics kit installed, that the front indicator is still fading in and out and the LED is lit up blue.

This is because it doesn't know that the Raspberry Pi has booted up yet, we need to install my NESPi program to enable the communication.

To do this we need to install a few bits and pieces on the Pi. We can either type directly in the shell or connect to over SSH using the PuTTY software we just downloaded.

Using PuTTY is easier because we can copy and paste the commands instead of typing them out manually.

Make sure your Raspberry Pi is on and connected to the same network as your computer.
(I recommend using an ethernet connection during this set-up but you can use WiFi.)

Start up PuTTY and in the 'Host Name' box type 'retropie', make sure SSH is selected and then click open.
(if typing the hostname doesn't work, input the ip address of your Pi found from the RetroPie menu)

You'll now get a prompt, login as 'pi' and password is 'raspberry'

Using this program we can input commands to be run on the Raspberry Pi.

Copy the lines below one-at-a-time and paste them into the PuTTY terminal by right-clicking inside the window.

First we need to install some Python dependencies that we use in our NFC reading program.

sudo apt-get update
sudo apt-get install python-dev python-pip python-gpiozero
sudo pip install psutil pyserial

After pasting a line hit enter and 'y' if prompted, to download and install each module.

Next we need to change the default settings for the serial port.

sudo raspi-config

This opens the Raspbian configuration tool.

We need to scroll down to 'Advanced Options' then 'Serial' and select 'No', then 'Finish' to exit.
Use your arrow keys to navigate this page and Enter key to select.

Now we need to edit the boot config to enable the serial port for us to use in our program.

sudo nano /boot/config.txt

This command opens up the config file in a text editor(nano). We need to change the very last line.

Scroll down using your arrow keys and change 'enable_uart=0' to 'enable_uart=1'.

Hit 'Ctrl+X' then 'y' and finally 'Enter' to save and exit.

Now we're ready to install the NESPi software.

Paste these lines at the prompt to first, download the latest version of the program, then copy part of it to the correct directory.

git clone
sudo cp /home/pi/NESPi/ /opt/retropie/configs/all/

Now the program is in place we need to tell the system to start it on every boot.

We do this by scheduling a job in cron.

sudo crontab -e

Hit '2' to open the cron table in nano. Scroll down to the bottom, just below the lowest '#' and paste:

@reboot python /home/pi/NESPi/ &
Again, hit 'Ctrl+X' then 'Y' and 'Enter' to save and exit.

All the software's installed and we're ready to reboot. Before we do, we can transfer some games first. (keep the PuTTY window open for later)

Transferring games...

There are a few ways to transfer your game files to the Raspberry Pi. I like to use WinSCP.

It's quite straight-forward to use, log in with the following details:
  • Host name: retropie
  • Port number: 22
  • User name: pi
  • Password: raspberry
Now we have two windows. On the left, our computer, the right is the Raspberry Pi.

Navigate to your rom folder on your computer, make sure all your roms are unzipped(not essential, but helps with compatibility)

On the Raspberry Pi roms need to be placed in the correct folder in: /home/pi/RetroPie/roms

For example I'm putting my NES games in: /home/pi/RetroPie/roms/nes

Find the rom folder you need on the Raspberry Pi window, highlight you roms on the left, then click 'Upload' to transfer them.

Once we've transferred all our games, we can go back to our PuTTY window and type:

sudo reboot

This restarts the Pi and when it boots back up we should be ready to play with some cartridges.

Programming the Carts...

There are two ways to easily program your mini-cartridges.

Using your phone or using the system itself.

Phone method:

For this we need a modern Android device that supports NFC.

As of October 2016, iPhone does not support reading/writing NFC tags although the 6/6s and iPhone 7 do have NFC capable hardware.

With your NFC-capable Android phone you need to download this app (I use the Pro edition, but the free version does everything we need)

We need to create two text records:

  • the first contains the console name eg: nes, snes, gba etc.
  • the second contains the rom filename eg: 'The Legend of Zelda.nes'

Hit write, and then put your tag next to your phone's NFC antenna, usually on the back somewhere and it will write your tag almost instantly.

Now you can insert your cart into your mini NES to try it out, make sure the filename is correct and your roms are in the right folder.

Cart slot method:

In the newest version of my program it's possible to write your cartridges using the system itself.

To do this you need to first transfer some games to your system as above, then pick a game you want to write to the cart from your list and start the game by pressing 'A' on your controller.

Exit the game back to the menu by pressing 'Select+Start' and with the cartridge slot empty press in the 'power' button (so the power button is in the 'on' position)

Then insert a cartridge (it can be blank, or one that you want to overwrite)

Now when you press the 'power' button again, ie. turn the power off (so the button goes from the 'on' to 'off' position) the game that you last played will be written to the cartridge in the slot.

The LED will flash orange then green to show that the cart has been erased and written to, it should then turn green to show that the cartridge is good and ready to play.


The LED shows us the status of the system. It gives us information about the cartridge slot.

In normal operation the LED will be orange, this tells us that there is no cartridge in the slot.

When you insert a cartridge with an compatible NFC tag, the LED will turn 'Aqua Blue'

If your tag is blank, then it will stay 'Aqua' however if there is data written to it then it will change colour after about a second. (if not, try removing the cart and blowing on it before re-inserting ;)

The system checks the rom filename and if it's correct then the LED will turn 'Green' and you can start the game by pressing the 'power' button.

If there's a problem with the cartridge, most likely the filename is incorrect/the game you're trying to play is not found in the relative folder, then the LED will turn 'Red'.

If this happens, check you've got the rom in the correct folder and the name on the tag is correct, including the extension ie. Castlevania.nes

Writing your carts with the system itself as described above should mitigate these errors although you have to be aware of the 'power' button's position when you have a cart inserted as you can overwrite a game (although it's very quick to re-write it.)

Other Functions

Power on:

To power the system on, press and hold the 'reset' button until the LED flashes.
The LED will light blue while the system boots-up and the front indicator will fade in and out.

Manual shutdown:

To shutdown the system, press and hold the 'reset' button until the LED flashes.
The LED will turn red during the shutdown and will turn off when it's safe to unplug the system.

Shutdown detect:

If you trigger a shutdown or reboot of the system from within RetroPie, then the LED will turn purple and the indicator will begin fading in and out.
After 30 seconds, if the system doesn't detect a signal from the Raspberry Pi then the power will be turned off.


  1. About halfway down the page, for the line cp /home/pi/NESPi/ /opt/retropie/configs/all/, I needed to add sudo before it to get past a permission denied error.

    1. hmmm... interesting, I didn't need elevated privileges there, I suppose it doesn't hurt to sudo though, I'll change the line.

    2. I wonder if that would be maybe because I didn't start fresh but instead already had RetroPie set up. Not sure.

  2. Also, the written guide doesn't have the Retroarch settings changes that the video guide does.

    1. gah, knew I forgot something, i'll add that too, thanks

  3. Thanks Mike for this great guide. Unfortunately, when I boot, the LED just stays pink or stays pink for a ~20 seconds then flashes aqua and turns off. The Pi system itself gets no power at all when I plug into additional micro USB installed. When I plug into the original, the machine boots just like normal. Additionally, the pins for the fan power aren't powered either. I've triple checked the installed parts to make sure it's setup correctly. Hmm...

    1. Additionally, the light near the power/reset buttons never turns on at all.

    2. Hi Derrick, This problem could be caused by your power supply, the system can be sensitive to input voltage drops.

      You can operate the system from the bottom USB power port. The Pi will boot the first time you plug it in, but if you turn on the NFC reader with a long press of the reset button, everything will operate as it does in the video.

      The only difference is; when you wake the system up from a shutdown, you will have to press the power button after holding down reset.

    3. Thanks Mike! I swapped in a different power supply, and now it's working as expected. I was using a 5V from CanaKit that's specifically for the Raspberry PI. Swapped it with a 10W 5.1V iPad power supply, and now its all good. Thank you for the help!

    4. Well, it boots and everything seems to work. But the gameplay for SNES games is extremely sluggish and I get the rainbow box in the corner. But, this got me on the right track.

  4. Mike..could you link me to the fan that you use? I have a few, but they don't fit as perfectly as yours does.


    1. Try this one:

  5. Hello Mike, I wanted to ask if the raspberry pi2 should be fine. And if in the future you are going to sell copies of minicard and NES. I do not own a 3D printer and it would be good to buy it from you. thank you so much

    1. Yes, although for the older Raspberry Pi Model B boards you'll have to edit line 23 of the script to read:
      "ser = serial.Serial("/dev/ttyAMA0", 9600, timeout=None)"

  6. Hello Mike, I've been following your project from the beginning and i can see all the hard work you put into this project (bravo,zulu). I'm at the point where all i need is a schematic of the nfc reader/arduino board. I got all the parts at the very beginning so i just want to solder everything on a board and pinouts are very important. thank you for your time.

  7. I know mike is not responding, but if anyone could answer me it'd be great. I have no experience with arduinos, but I'm planning on building one of this (obviously whithout the electronics kit, sience mike isn't selling more of those) and I'd like to know if, aside from the things that are showed in this tutroial, it's necessary to do something to the arduino to configure it. Thank you very much to anyone who can answer.

  8. I'm on retroarch version 1.9.7 as of writing this. Following this guide, when I got to the point to enable "network commands", it was missing from my list of options. Doing a Google search, I found that I had "user interface" in settings and switch "show advanced settings" to on in order to get "network commands" to appear. I hope this helps anyone that comes across this.