Introduction: Batocera Waveshare Gamehat Set Up

About: Arduino game consoles

Full video demonstration of the setup

Batocera is an alternative retro game emulator to RetroPie and Recalbox that can be run on different hardware, PCs, Macs and other types of portable hardware including RaspberryPi.

it also comes with KODI embedded for you to view videos/youtube/media.

The Waveshare game hat is a good addition to turn your raspberry pi into a retro game console.

It comes with

3.5inch IPS screen, 480×320 resolution on HDMI port with an adoptor that fits with Raspberry Pi3 (not 4)
60 frame experience, smoothly display, no more frame loss

Compatible with Raspberry Pi A+/B+/2B/3B/3B+ (Raspberry Pi Zero/Zero W/Zero WH requires another HDMI cable)

Integrates battery charge circuitry, powered from one 18650 lithium battery (NOT included)

plays anywhere anytime

Battery capacity indicator

Onboard speaker and earphone jack, listen to the familiar BGM from the old days

This instruction has been tested with Batoceria 5.25 (batocera-5.25-rpi3-20200309.img.gz) If WIFI has not yet been set up for your Batoceria, connect it to a LAN cable first instead of using WIFI.

Waveshare game hat currently only works with Raspberry Pi3B/B+. Unless you connect a convertor cable, the HDMU port on the game hat cannot fit with the micro HDMI port on the Pi 4. Waveshare mentioned that they are considering an adaptor to bridge the gap, but not available yet at this point in time.

Step 1:

Get all the parts

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

1. Raspberry Pi 3B+

2. TF card of at least 4GB (recommend 16G or 32G to store game rom).

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: Set Up the Software

Make the TF Card

Browse to

Select your raspberry pi and click it to download

Use a Micro TF card of 4GB or above.

I recommend 16GB or 32GB to store more game ROMs.

Insert the TF card to your computer.

Browse to to download and install the Etcher application.

Start Ether to burn the Batocera image to the TF Card

Connect a LAN cable to the raspberryPi

Insert the micro TF Card

Power up the Raspberry Pi

From your computer start a terminal (Mac) or putty (windows)

ssh root@batocera.local (password for the first time login is linux)

(Note: If there is no response, you may want to first "ping batocera.local" to see if there is any response. Otherwise, try to check your router to find out the ip address. (e.g. Then type "ssh roo@" )

Type "nano batocera.conf" to edit the configuration

Use Control+W Key command to search for "gpio" Once found, remove the # and change the following lines


controllers.gpio.args="map=4 gpio=5,6,13,19,21,4,26,12,23,20,16,18,4"

press Control+X to save the file. type

Note that the HOT key is being assigned to the same pin 4 as the SELECT key. So, select key will also function as the HOT key.

Type "reboot" to reboot the respberry Pi.

Once rebooted, the buttons on waveshare gamehat should work right away.

You will not need to start the systems menu to configure the controllers.

But in case you need, press "START" button to see if you can see the system menu, then select "Controllers Settings".

Then select to configure the controller.

You should see "1 gamecontroller detected"

Then go ahead to configure your game controller by pressing the right buttons.

SELECT button will be configured as the hot key.

If the above does not work, then you might have some typo error in the configuration file.

Repeat the configuration steps and check again.

You can also check the log file to see whether mk_arcade has been loaded properly by typing this command.

cat /userdata/system/logs/batocera.log | grep mk_arcade

You should see something like this in the log when the mk_arcade driver has been loaded successfully for waveshare game hat

loading module mk_arcade_joystick_rpi args = map=4 gpio=5,6,13,19,21,4,26,12,23,20,16,18,4

After boot up, press Start button to go to system menu and click Network to set up WIFI.

You can then enjoy all the games.

or go to system menu to start KODI to watch the multimedia.