How to make fantastic lighting styles for the Pimoroni Keybow 🌈

Feb 5, 2021 5 min read
How to make fantastic lighting styles for the Pimoroni Keybow 🌈

Got a #Keybow from @Pimoroni over the holidays? This guide will help you set up lighting styles to make it look the part on your desk.

As we start the new year, there is no better time to give your Keybow a fresh look. I have detailed the steps necessary to create exciting lighting styles that should keep your Keybow looking fresh for the year to come.

🤔 What is Keybow?

If you are not familiar with the Keybow, it is a small, customisable mechanical keyboard powered by a Raspberry Pi Zero WH. The Raspberry Pi runs on a stripped-down version of Raspian called Keybow OS and uses Lua scripts to create functions for each of the keys. Pimoroni sells two kits that allow you to build either a 3 or 12 key keyboard.

Typical configurations are for specific programs like Lightroom or OBS. My keybow has some macros for Destiny 2 and some snippets for development, but you can virtually configure it to do anything you want. Now that we know what it is let's see how we configure the lights.

💡 The lighting configuration

The Pimoroni website has a short section on how the lights work:

"There's a nifty way to light and animate the LEDs on Keybow. You can create a PNG file with a coloured gradient or pattern, and it will be animated across the LEDs from the top of the image to the bottom. The width of the PNG determines how it's displayed."

I found this description confusing and lacking some of the specifics for the key mapping or animations, but this is a perfect opportunity to help out.

Pimorono has created some genuinely brilliant products in their time. They also open-source many of their projects, allowing hobbyists to modify and alter them to their needs. So, rather than clicking the thumbs up button on the GitHub issue where better documentation is requested, let's help fix this issue and give back to the community.

There are example styles in the patterns folder on Github. If we start there, it might shed some light on setting them up.

✨ Animation configuration

This folder contains 11 PNG images, all of them 12 pixels wide. Each one of these 12 horizontal pixels represents a light for a specific key. Then, to create the animation, each row of pixels represents 16.667 milliseconds. Each row is precisely one pixel high, and the number of milliseconds it denotes is small enough to allow for animations that have exactly 60 frames per second. To help explain this, I have created the image below:

If we uploaded the 12x5 image above to the keybow, the animation would only last 83.5ms. I have added 12 more rows to each of the colours to fit 60 frames; this will allow us to see the animation. As all 12 keys are the same colour, we can use a shortcut to represent this with a 1-pixel wide image. What we end up with is a 1x60 image that will animate, as shown below:

This shows how the animation works, but how do the pixels map to the keys?

Note a black pixel is off, hence why the animation above goes from green to off.

⌨️ Pixel/Key Mapping

If we go back to a 12-pixel wide image, each pixel represents a key on the keybow. I have created this image below to help illustrate what keys map to which pixels.

12-pixel wide configuration

A little side note, from looking at the code, you can also supply a 4-pixel wide image where each 4x3 block represents the lighting configuration for that frame. This configuration is possibly a little hard to understand, so I have created another image to help show the config.

4-pixel wide configuration

The 4-pixel wide configuration is a bit tricky to create patterns. So I will stay with the 12-pixel format for now. Time to combine what we have learned about the animations and config, with some example lighting patterns!

👨‍🎨 Example lighting patterns

The default rainbow is an excellent lighting pattern to deconstruct to see how it works. The image, "rainbow.png", has the dimensions 1x400. With these dimensions, we can tell the pattern has a long animation due to the height of 400 pixels, and that it uses the 1-pixel wide shortcut to make all the keys the same colour. I have created the image below to show how it works:

If we step up the complexity and look at "animated-rainbow.png", this image has the dimensions 12x400. We can then tell that this pattern uses the 12-pixel configuration and is a long animation of 6.6 seconds. However, this configuration has the keys set to different colours, and animates like so:

I have noticed that this pattern doesn't match the standard rainbow effect that many fancy keyboards have where it looks like a wave of colour. For example, if you follow the red key, you can see it starting on the top row, then the bottom row, then the middle row. I have modified the rainbow pattern to reflect the fancy mechanical keyboards. The image below shows how I achieved this effect.

🏃 Next Steps

I am in the process of building a small app to help you configure your lights, so keep an eye out! But in the meantime, here are some patterns I have used recently:

Now that you know how to create fantastic lighting styles on your Keybow, you are free to be as creative as you want. Leave a comment below to show off what patterns you have made!

I have raised a PR to improve the documentation, and you can find all the lighting examples shown in this repo.

Happy hacking!🌈

Table of Contents
Great! Next, complete checkout for full access to Iain Smith.
Welcome back! You've successfully signed in.
You've successfully subscribed to Iain Smith.
Success! Your account is fully activated, you now have access to all content.
Success! Your billing info has been updated.
Your billing was not updated.