Pikatea Macropad deej Programming Guide
This guide will walk you through the process of programming your macropad to be used with deej. deej is an open-source program that let's you control individual application volume levels with your macropad. As a general overview, we will be using the Arduino environment and modifying it so that the key-mappings are what you like.
Note: This guide is considered rudimentary. If you run into issues, please ask in the discord in the #deej-firmware-dev.
Setting up the Arduino Environment
Download and install the latest Arduino IDE for your specific platform. In this guide I will be using Version 1.8.15 but the latest version should work and should be used unless issues arise.
Download the sketch file (.ino) from the github page here.
Open the Arduino IDE
Open the sketch file that was downloaded by going to File -> Open and finding the file.
Go to the Library Manager by going to Tools -> Manage Libraries. We will need to install the appropriate libraries (listed below) for the sketch to compile. The libraries can be found by searching for the name in the search bar in the Library Manger. Below are the libraries needed
- Hid-Project (by Nicohood)
- Bounce2 (by Thomas O Fredricks)
- Encoder (by Paul Stoffregen)
Verify the correct libraries are installed by clicking Verify in the top left. The console should say "Done Compiling" if successful.
Go to Tools -> Board and select Arduino Leonardo
If your macropad is already connected to the computer, disconnect it. Go to Tools -> Port and note down the ports already listed. (There is a good chance this is greyed out in which case you don't have to remember anything)
Plug your macropad into the computer and go to Tools -> Port again. The new port is the one that should be selected. If only one port is available, that should be the macropad.
After the correct board and port is selected, click Upload. If successful, the console should say Done Uploading. The device will disconnect and reconnect while uploading.
Modifying the Firmware
Now that you are able to compile and upload the firmware to your device, it's time to modify it so that when you press any of the buttons, the action you want occurs.
In the code, scroll down to the section that says
----------------- START HERE -------------------
The configuration for each button (or knob) is defined in the quotation marks on each line and is labeled with a comment. To edit button 4, for example, change the text
buttonStrings = F("PlayPause");
buttonStrings = F("Home");
doing this will change button 4 from playing and pausing music to pressing the Home key.
Configuration can include a combination of keys that will be pressed all at once. Using the table below, specify each action with a '+' symbol in between them.
Note 1: There is a small delay between each action (5 milliseconds). Sometimes various programs don't like the small delay between keypress and an extra delay should be added. For example Ctrl+Delay(40)+Alt
Note 2: A single UPPERCASE letter is not the same as a single lowercase letter. Menu+T will actually press menu and shift and t. Menu+t will press only menu and t.
|Key||Defined in Config||Notes|
|Volume Up||VolumeUp||knobStrings = F("VolumeUp");|
|Volume Down||VolumeDown||knobStrings = F("VolumeDown");|
|Space||Space||the space character|
|+||PlusSign||buttonStrings = F("Ctrl+PlusSign");|
|Tab||Tab||buttonStrings = F("Alt+Tab");|
|Return||Return||the enter key|
|Page Up||PageUp||knobStrings = F("PageUp");|
|Page Down||PageDown||knobStrings = F("PageDown");|
|Play/Pause||PlayPause||Plays or pauses the current music/media|
|Next||Next||Plays the next song/media|
|Previous||Previous||Play the previous song/media|
|Mute||Mute||Sets the volume to zero|
|Left Shift or Shift||LeftShift or Shift||buttonStrings = F("LeftShift+2");|
|Left Ctrl or Ctrl||LeftCtrl or Ctrl||buttonStrings = F("Ctrl+p");|
|Left Alt or Alt||LeftAlt or Alt||buttonStrings = F("Alt+Tab");|
|Left Menu or Menu||LeftMenu or Menu||Windows Menu or Mac Command Key|
|Right Menu||RightMenu||Windows Menu or Mac Command Key|
|F1-F12||F1, F2, F3, etc||buttonStrings = F("Ctrl+F11"); or buttonStrings = F("Alt+RightShift+F5");|
|Left Mouse Click||MouseLeft|
|Right Mouse Click||MouseRight|
|Middle Mouse Click||MouseMiddle|
|Scroll Up||ScrollUp||scrolls the mouse wheel at a slower speed|
|Scroll Down||ScrollDown||scrolls the mouse wheel at a slower speed|
|Scroll Up Fast||ScrollUpFast||scrolls the mouse wheel 3x faster|
|Scroll Down Fast||ScrollDownFast||scrolls the mouse wheel 3x faster|
|Scroll Right||ScrollRight||Scrolls up while holding the shift key|
|Scroll Left||ScrollLeft||Scrolls down while holding the shift key|
|Any other character||a, b, c, d, -, &, #, etc||presses the character|
|Type a word or sentence||This is a sentence for example||types 'This is a sentence for example' (NOTE: the configuration file and the Pikatea macropad has a maximum memory size. We would highly recommend not trying to type out entire paragraphs of text)|
|Delay in milliseconds||Delay(x)||Delay(500) delays the program by half a second|
|Number Pad 0-9||Keypad1, Keypad2, etc|
|Number Pad Dot||KeypadDot|
|Number Pad Enter||KeypadEnter|
|Number Pad Add/Plus||KeypadAdd|
|Number Pad Subtract/Minus||KeypadMinus|
|Number Pad Multiply/Star||KeypadMultiply|
|Number Pad Divide||KeypadDivide|
|F13-F24||F13, F14, F22, etc||buttonStrings = F("F17");|
|Media Rewind||Rewind||Rewinds the current song/media|
|Media Fast Forward||FastForward||buttonStrings = F("FastForward");|
|Media Stop||Stop||Stops the current media|
|Release/action chaining||Release||Used to release the current keys. This is useful for chaining multiple actions for a single keypress. Example:
After editing the buttons so that they perform the actions you need, upload the firmware to the device by clicking Upload. The firmware will be compiled and then upload.
Refer to the deej github here on configuring deej. You'll use the same port as you've been using to upload the firmware.
Note 2: Ideally we'd like to move this documentation to the github page and clean up the code but we don't have to time to focus on doing that at the moment. If you'd like to help with that, we will be giving away goodies like oreo knobs, relegable keycaps and 69% keyboards to those that contribute. We have not thought about the exact way to go about this but ultimately we want to reward those that help us out.