[HOW-TO] Use Harware buttons on Raspberry Pi Zero with GPIO-KEY

Hi, if you need harware control to use OSMC on the go with Raspberry Pi Zero then this should be useful.

Note: This should work with all Raspberry with the lastest kernel since this overlay is there for all version.

First, the electronic part. If you are able to solder, you can do like me and recycle boards from old radio or this can be done on a little breadboard as well. Use what you have.

For the switches normally open tact switch (wich are very common) are all we need.

Some are two legs other four but they do the same thing.

You can either make these buttons active high (when you press the switch it connects 3.3V to gpio)


active low (when you press the switch it connects ground to gpio) .

I decided to go with active high so here is the schematic for 8 switches:

3.3 volts is from raspberry gpio ( pin 1 or pin 17) I added a 1k resistor as current limiting.

GPIO pins are the one I had free on my board (I have a DAC connected to I2C that uses some pins)

You need one GPIO pin for each switch so I used 8 pins + 1 for the 3.3V

I suggest you use Only GPIO pins for this so the other options will remain available (SPI, I2C, etc)

Here is a good pinout image from the DAC site, the GPIO-only pins are in green.

You should use a mulimeter to check your connections before using your pcb or breadboard (it’s not dangerous for the gpios since the source is the gpio 3.3v but checking the harware is working as expected is always a good idea)

What I did is that I connected the 3.3v line but not the GPIO yet, I connected a volmeter to the output of the switch and checked if I had 3.3v when pressed, then repeated for all the switches)

When the hardware is ok you can wire it to the GPIOs. The hardest part is done.

Now, you just have to set an overlay line for each switch in your config.txt

You can do this by ssh but the easiest way is to plug your sd card directly to another computer, the config.txt will be there.

I use notepad++ to edit the file.

I did not know how to set it at first but the Overlay Readme is pretty clear. Here is the description of gpio-key overlay

Name: gpio-key

Info: This is a generic overlay for activating GPIO keypresses using
the gpio-keys library and this dtoverlay. Multiple keys can be
set up using multiple calls to the overlay for configuring
additional buttons or joysticks.

Load: dtoverlay=gpio-key,param=val


gpio GPIO pin to trigger on (default 3)

active_low When this is 1 (active low), a falling edge generates a key down event and a
rising edge generates a key up event. When this is 0 (active high), this is reversed. The default is 1 (active low)

gpio_pull Desired pull-up/down state (off, down, up) Default is “up”. Note that the default pin
(GPIO3) has an external pullup

label Set a label for the key

keycode Set the key code for the button

We got all we need,

First you call the overlay dtoverlay=gpio-key

Next specify the gpio pin you are using for that button gpio=23

If like me you use active high button, set the parameter active_low=0 otherwise you don’t have to set it since the default is active low. (active_low=1)

Same goes for the pull state, if you use active high button set pull_state=down (to ensure that the gpio input is not floating and is really zero when no button is pressed) otherwise you don’t have to use this parameter since the default is pull up (if you use active low button)

Nest you set a label for the key label=enter

Note: a long label seems to product unexpected results, at first I used playpause and it was too long, I replaced it by playII and the button was now working.

The last parameter is the linux event code. you can find these codes here

And kodi keyboard function here


Here are my overlay lines









One line per button and all parameters are separated by commas (I added a space between each dtoverlay line so it’s more readable here but in my config.txt there are no spaces between each lines)

With the enter, back, up, down keys you can navigate in osmc to your video.

Once you are playing it, enter activate a menu where you can turn on subtitles, adjust video zoom, etc) you can view how much time is left on your movie.

To remove the progress bar and this menu, press the back button.

play/pause and stop do what their labels say

right and left to skip a little bit backward or forward

up and down to skip more at a time

Hello, I’m having difficulty reproducing what is said in the post, I wanted to know if you could help me, it’s something important for me but unfortunately I don’t have enough capacity to do it.

That user hasn’t logged into this site in years. I’m not sure how much luck your going to have with the OP.

How far did you get with reproducing it? I just read through the instructions and it all seemed pretty clearly explained and detailed. If you could explain where you got stuck or what exactly it is that your not understanding then perhaps we could get you past your hump.

1 Like

My understanding is too limited to even reproduce this. I’m not sure but I believe my gpio-keys.dtb file is working fine, however, The button-overlay has an error that I cannot identify, but it originates from a lack of knowledge on my part, where I tried to replicate other files I found on the internet with poor execution. Having help from AIs, as it was the only “being” I could turn to in an unpretentious way.

That guide as I read it says that you only need to connect switches to GPIO pins and then add lines to config.txt specifying their behavior. With OSMC we now recommend that users modify /boot/config-user.txt instead so it doesn’t run the risk of getting overwritten during an update. The links are for reference, and the lines after “Here are my overlay lines” are what the OP added to their config.txt file.

I don’t use Raspberry.Pi, it’s another brand called Orange.Pi, in it I found the file corresponding to config.txt and added the lines of code “gpio=29,2”, which according to research would be like this. But it still doesn’t work, after that I tried assigning the buttons to a shortcut in LVC to test and they don’t work.

This is a support site for OSMC which you apparently are not running. We do not provide support for other operating systems here.