DIY Custom RP2040 Macropad With OLED and Encoder (QMK Firmware)

Apna Dost is a custom RP2040-powered macropad built to streamline everyday workflows with programmable keys, a rotary encoder, OLED feedback, and a fully open-source design.

Meet 'Apna Dost'—a custom 4-input macro pad engineered to turbocharge your daily desktop productivity, media control, and multitasking.

Powered by a Waveshare RP2040-Zero running custom QMK firmware, it packs mechanical switches, a 128x32 OLED, and a clicky rotary encoder into a clean layout.

1. Dynamic OLED Display: Automatically renders custom 512-byte raw bitmaps for instant profile and layer feedback.
2. Dual-Purpose Encoder: Handles smooth system volume adjustments by default, but shifts into a micro-step color wheel controller when needed.
3. Engineered for Long Grinds: Built for 10+ hours of daily use, the onboard RGB is hardware-capped at 65% brightness to eliminate heat and component stress while delivering rich, smooth color transitions.

These were the components used in this project:

1. Waveshare RP2040-Zero
2. OLED 128×32
3. Mechanical Switches (otmeu blue switch)
4. Rotary Encoder (EC11)
5. Keycaps
6. Encoder cap
7. Diodes (1N4148)
8. PCB / Perfboard
9. Type-c USB Cable

Hardware Architecture:

To build 'Apna Dost', I first mapped out the circuit schematic. While I assembled and hand-wired this version cleanly on a standard prototype perfboard, I have also fully designed a custom printed circuit board layout. I am sharing both the schematic and the open-source Gerber files if you want to order a professionally printed board!

Open source files and downloads:

All design files are open-sourced. Download them from the links below:

Gerber Files (Ready for Manufacturing) Download Gerber ZIP

1.The keyboard Matrix (2X2)

We have mapped our 4 physical inputs (3 keys + 1 encoder click) into a simple matrix using the following pins:

1. Rows: GP10, GP11
2. Columns: GP12, GP13

Each mechanical switch has a 1N4148 diode soldered to its pin to ensure clean signal isolation and to prevent from ghosting.

2. OLED Display Connection (I2C Bus)

The 128x32 SSD1306 OLED requires stable I2C communication. We are using the hardware I2C1 bus on the RP2040, which provides excellent stability for rendering raw bitmaps without performance drops:

1. SDA (Data): Connected to GP6
2. SCL (Clock): Connected to GP7
3. VCC & GND: Connected to the board’s 5V/3.3V and Ground pins respectively.

3.Rotary Encoder Settings

The EC11 rotary encoder handles our precise rotary inputs and is connected natively to:

1. Encoder Pin A: GP14
2. Encoder Pin B: GP15

4.RGB LED (LED Expandability)

1. My Setup (Internal + External Chain): Instead of leaving the internal LED uselessly hidden inside the case, I did a custom hardware hack. I traced the output line of the onboard smart LED on GP16 and carefully soldered an external addressable LED to it in series (Daisy-chain). This gives me both the onboard status light and an extra external glow off the exact same data pin!
2. What you can do: If you don't want to perform this advanced soldering hack on the tiny onboard components, you can simply use GP16 for the single internal LED, or route a fresh wire to GP27 to run a completely separate external addressable LED strip. If you copy my dual-LED setup, just make sure to set your firmware count to RGBLIGHT_LED_COUNT 2.

Now that our hardware circuit is ready, it's time to configure the brain of our macropad using QMK Firmware. Inside your QMK directory (qmk_firmware/keyboards/), create a new folder named "apna_dost" (Change this to match your setup).

Inside this folder, we need to define our hardware features and layout mapping using two main configuration files.

1. Enabling Features (rules.mk)

Create a file named rules.mk. This file tells QMK exactly which hardware drivers to load.

2. Defining the Layout Matrix (keyboard.json)

Next, create a file named keyboard.json. This file maps our physical 2x2 matrix keys, encoder pins, and hardware details so QMK can translate pin state changes into actual keystrokes

With the firmware initialized, we now need to write the actual logic that controls our dual-purpose encoder, locks our RGB brightness to safeguard the hardware

1. Configuration and Safety Limits (config.h)

Create a file named config.h in your project folder. In this file, we safely cap the brightness of our chained LEDs to 65% (165 out of 255) so that the RP2040's internal regulator stays perfectly cool. We also change the default Hue Step from 10 to 2 to unlock a massive variety of smooth color transitions.

2. The Master Layout and Macros (keymap.c)

Next, create a file named keymap.c. This script maps our macro actions (like opening YouTube via Windows Run command) and contains the intelligent encoder logic. By default, the encoder fine-tunes the system volume, but when you press the encoder to mute the PC, it seamlessly shifts into a precise color wheel adjuster!

Use this hex code to run some quick logo tests.

With our configuration files (rules.mk, keyboard.json, config.h, and keymap.c) fully written and saved inside the qmk_firmware/keyboards/apna_dost/ directory, it is time to build the binary and flash it onto our microcontroller.

1. Setting Up the Compiler Environment

Open your QMK MSYS terminal (on Windows) or your native Terminal (on Linux/macOS) and run the setup command to ensure your environment is fully up to date:

Bash

2. Compiling the Project

To compile your custom source code into a flashable firmware file, execute the following command:

Bash

1. QMK will now parse your matrix pins, build the dynamic OLED drivers, apply the 65% hardware brightness cap, and pack everything into a high-performance binary file.
2. Once successful, it will generate a file named apna_dost_default.uf2 inside your main QMK directory.

3. Flashing the RP2040-Zero MCU

1. Unplug your macropad from your PC.
2. Press and hold the physical BOOT button on the Waveshare RP2040-Zero controller.
3. While holding the BOOT button, plug the USB Type-C cable back into your PC, then release the button.
4. Your computer will instantly recognize the controller as a standard removable flash drive named RPI-RP2.
5. Simply drag and drop (or copy-paste) the compiled apna_dost_default.uf2 file directly into that drive.

The drive will automatically disconnect and reboot in a fraction of a second. Your custom mechanical macro pad is now fully operational!

Now that the firmware is flashed, your macropad is fully alive! In this final step, we will verify all functions and check the desktop integration.

What to Test:

1. Core Key Functions

1. Key 1 — Toggle between open applications (Alt + Tab)
2. Key 2 — Opens YouTube
3. Key 3 — Launches the Windows Snipping Tool instantly
4. Key 4 — Your custom function (whatever you assigned)

2. Rotary Encoder

1. Rotate clockwise → Volume Up
2. Rotate counter-clockwise → Volume Down
3. Press the encoder switch → Mute / Unmute

3. RGB LED (Dual LED Hack)

1. Tap the encoder button to mute your system audio. Now, rotate the encoder again; instead of changing volume, it will cycles seamlessly through incredibly fine color gradients at a perfectly safe, comfortable 65% brightness level.
2. 
   

The complete project (Gerber files, schematic, firmware, source code, and keymap) is fully open-source.

📂 GitHub Repository:

https://github.com/NP-Vishwakarma/apna_dost

Feel free to modify the keymap, add new layers, improve OLED animations, or redesign the PCB for your own needs.

If you face any issues or have questions regarding the matrix layout, soldering, or QMK configuration, drop a comment below. I'll be happy to help!

If you build your own version, I'd love to see it in the comments.

Made with ❤️ for productivity and learning.

Happy Building! ✌️