Introduction: Setup Waveshare Game Hat for Recalbox and Kodi

About: Arduino game consoles

The waveshare game hat is a good addition to your raspberry Pi 3B or 3B+ by turning it into Retro-gaming machine and a Kodi video station. Though the waveshare game hat comes with downloadable retro-pie images and drivers, there are not much instrctions on how to make the buttons work with Recalbox.

I like Recalbox better as it's got the nice skin and startup music, and also pre-loaded with Kodi.

Here are the setup steps to use waveshare game hat for recalbox. You watch this youtube video for a full demonstration of the steps:

A. Get all the parts.

B. Solder the parts together.

C. Install Recalbox software.

D. Configure Recalbox for GPIO buttons

Step 1: Get the Parts

Most of them available on amazon or aliexpress or from China and Hong Kong Taobao.

1. Raspberry Pi 3B+

2. 16G TF card.

3. Waveshare game hat for raspberry pi

Step 2: Set Up the Hardware.

1. Insert the raspberry pi 3B+ to the waveshare game hat

2. Connect the HDMI ports by the special U-shape HDMI connector.

3. Insert the rechargeable battery to the battery slot. Becareful of the polarity.

4. Secure the front and back cover with screws.

Step 3: Install Recalbox Software to Work in Default Set Up.

1. Download the Recalbox 2018 12 24 Xmas beta boot image for Respberry Pi 0.

2. The Recalbox boot image already comes with some freeware game roms. Download more Games Roms from the web.

Or you can download many of the pre-packaged recalbox image with many Game Roms. for RaspberryPi 3B/3B+ available on the internet.

3. Use Etcher or other Sdcard burner - to burn the Recalbox boot image to 16G TF card.

4. Insert 16G TF card to the TF card slot of the Raspberry Pi 0 W.

5. Connect an HDMI screen to the mini HDMI port of the Raspberry Pi 0W through a mini HDMI to HDMI convertor.

5. Connect a USB keyboard to the USB port of the Raspberry Pi trhough a microUSB to USB convertor.

7. Connect the Micro USB power cable to the 5V battery charger.

Switch on the slide switch to power it up.

8. Check that the recalbox splash screen appear and the startup music is played on the speaker. Otherwise, power it down and recheck all the connections.

9. The following keys on the keyboard is mapped to the joystick buttons for initial set up:

A=(to proceed), S=(to go back), ENTER/Return as START, Space as SELECT.

Arrow keys Up/Down/left/right are mapped to the D-PAD‘s up/down/left/right.

10. Press ENTER to get to system menu. Use arrow keys to go to the Network Settings, and press A.

11. Once in WIFI menu, use arrow keys and A keys to enable WIFI, input the SSID and password of your WIFI network. Make sure proper upper/lower case is used. Lastly select CLOSE and press A to enable WIFI.

12. Go back to the Network Settings screen, and record the IP address assigned to the Recalbox.

Step 4: Modify Recalbox Configurations for GPIO Controller Buttons

1. From your PC or Mac, SSH to the ip address of the recalbox.

ssh root@

Or you can try ssh root@recalbox.local

2. Login using the id of root and the default root password of “recalboxroot”

3. Type the following commands to set up the GPIO buttons and other parameters for the TFT LCD.

mount -o remount, rw /

cd ~

vi recalbox.conf

4. The new Recalbox 6.0 has been released in Mar 2019. For this new version, replace the "map=4" in the line highlighted below with "map=5".

For previous versions of Recalbox, you can follow the instructions exactly as below.

While in vi, use “/pattern” to search for the word. then press ENTER to jump there.

Press A key to turn into edit mode.

Type in required values (using arrow keys, backspace/delete keys where required).

Once editing of that line is finished, then press “ESC” key to go back to read-only mode.

Continue to search for the other parameters.

Once all done, press “ESC” to go back to read-only mode.

Press x:! To save and exit.



controllers.gpio.arg=map=4 gpio=5,6,13,19,21,4,26,12,23,20,16,18,-1







5. *** This step is only required for Recalbox versions earlier than 6.0 (those released before Mar 2019.

The boot up script file of the recalbox 2018 Xmas beta (/recalbox/scripts/ cannot take in the second parameter I put into the recalbox.conf file.

This bug has been fixed in Recalbox 6.0. But for any versions before that , we need to change the following lines to fix this issue so the custom GPIO button pin mapping can take effect.

mount -o remount, rw /

vi /recalbox/scripts/

While in Vi Search for the line with extra2=“$4” using the command /extra2=“ , then press ENTER and a to add a line after it.


Then Search for the line with map="$extra2” using the command /map=“

Then change it to

map="$extra2 $extra3”

6. After that, reboot the recall box to take effect of the changes by typing

shutdown –r now

7. After the recal box has boot up., use the keys on the keyboard to press ENTER to go to the main menu. Then select controller settings and press A. Select configure a controller and press A. press A a second time to confirm.

8. You will see a screen to ask you to press and hold one of your joystick keys. Press and hold the A button on your recalbox (not the keyboard) until you see the next screen. If this does not work, the button connections may have something wrong, pls check the connections again.

9. If all is good, you will be asked to press the button for each of the joystick keys laid out on the screen. First press the D-pad keys, up, down, left, right, etc. When you come to joystick-1, joystick-2, press Down button on the recalbox to skip these buttons as they are not provided on the GPIO controllers. When you come to L1/page up, press L1 button, L2/pagedown, press R1 button. For L2, R2, L3, R3, there are not provided by the GPIO controllers, skip these buttongs. Lastly,press Select button for the hotkey button .

10. Finally press the B button to accept the new buttons configured.

11. You will be back to the main menu. Test the up down left right and other buttons on the GPIO controllers.

12. If it‘s all good, you can proceed to test a game.

13. or press X button to launch Kodi to watch some video.

14. That‘s all the steps you need to set this up. Good luck with retro gaming.