Setting up keybow software on a normal Raspbian OS

I’m still a bit of a noob when it comes to the Raspberry PI and since it took me a bit to figure out how to get the keybow software up and running on a normal Raspbian install I figured I’d share my method here :-) And perhaps collect some good pointers or suggestions from more experienced folks.

I wanted this setup so I can work on my keybow bindings over wifi instead of plugging the sdcard back and forth all the time. And in case I ever want the keybow to do something more fancy than just send keyboard events. And keep in mind this setup will take a lot longer to boot up than the minimal keybow OS image.

So here I’ll just quickly list how I did the following:

  1. autoconnect to wifi
  2. turn on ssh
  3. setup the Raspberry zero as a USB gadget
  4. install the keybow software and autorun it on boot

I downloaded and flashed ‘Raspbian Buster Lite’ from Raspberry Pi OS – Raspberry Pi

Once that is done you should see two partitions on the sdcard: rootfs and boot. We’ll add and edit files in both of these.

1: To autoconnect to your wifi add a file called ‘wpa_supplicant.conf’ in the boot partition and fill it with your settings. I used this template, ymmv.

country=US # Your 2-digit country code
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev

(I did notice that the raspberry wouldn’t connect to my 5ghz connection, there may be another setting for this or I’m doing something wrong)

2: To enable ssh just add an empty file called ‘SSH’ in the boot partition

3: In order for the Raspberry to act like a USB gadget we need to enable the proper modules. Inside the boot partition open the ‘config.txt’ file and add the line ‘dtoverlay=dwc2’ at the end. Then open ‘cmdline.txt’ and add the line ‘modules-load=dwc2,libcomposite’ just after where it says ‘rootwait’. Mine looks like this:

dwc_otg.lpm_enable=0 console=serial0,115200 console=tty1 root=PARTUUID=17869b7d-02 rootfstype=ext4 elevator=deadline rootwait modules-load=dwc2,libcomposite quiet init=/usr/lib/raspi-config/

In the rootfs partition open the /etc/modules file and add these lines at the end (I needed to be root on my machine to do this):


4: Download and unzip the keybow software (GitHub - pimoroni/keybow-firmware: Keybow Firmware for the Raspberry Pi Zero). What we need is in the sdcard folder. Copy over these folders+files: ‘layouts’, ‘patterns’, ‘snippets’, ‘default.png’, ‘keybow’, ‘keybow.lua’, ‘keys.lua’ to the root of the boot partition.

Finally open the /etc/rc.local file in the rootfs partition and add this line above the ‘exit 0’ line:

sudo /boot/keybow &

This will turn on the keybow software when the raspberry boots, so you may not want this on while you’re developing your own scripts for it.

That’s it! Put the sdcard into your keybow, plug it in and wait (for quite a while) for it to boot up, and you should be able to ssh into the machine over your wifi and edit the keybow scripts in the /boot/ folder as usual. Just remember to kill and restart the keybow software when you do.

I’m not entirely sure all of this is the best way to do things (especially point 3) so if you have any questions, suggestions or comments let me know!


Thank you so much for this amazing tutorial, it really helped me out.

In step 3, when adding the modules there is a typo and should be:


I want to add some more information about diffrences I toke that seemed to make this process easier.

After loading the raspbian onto a sd card, I loaded it onto a spare raspberry pi that I have and connected it to a screen and keyboard (I guess you could acheive the same with the raspberry pi zero in the keybow)
after booted into shell, I ran the command

sudo raspi-config

this allows you to setup ssh service, connect to wifi and a lot of other stuff. which, after completed, means you can then skip step 1 and 2 of this tutorial.

also another helpful tip, the boot partition can be found mounted into the /boot folder, this means you can accomplish the rest of this tutorial through ssh (directly on your keybow).

Thanks for the comments!

Typo is now fixed :)

Great tutorial! Think it would be possible to have the same setup on a ‘slim’ version of Raspbian that is then still loaded into RAM? Essentially KeyBowOS with wifi access and ability to add custom libraries that could be loaded on reboot.

Something like it must be possible, but I’m afraid it’s beyond my abilities. Perhaps it’s easier to start with finding/creating the most minimal Raspbian installation on your own (with wifi) and follow these instructions again? I’m honestly not sure how something like KeyBowOS is made.

aergia thanks for the great tutorial. could you check if the raspian OS keybow, properly set up can access to the bios of a pc?

the regular KeyBowOS cannot, and i’m wondering if this can be a workaround for it!

if i don’t want the Pi to run as a USB gadget can i just skip the Step 3?