Introduction

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

//button 4
buttonStrings[3] = F("PlayPause");

to 

//button 4
buttonStrings[3] = 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
Up Arrow UpArrow
Down Arrow DownArrow
Right Arrow RightArrow
Left Arrow LeftArrow
Volume Up VolumeUp knobStrings[0] = F("VolumeUp");
Volume Down VolumeDown knobStrings[1] = F("VolumeDown");
Backspace Backspace
Space Space the space character
+ PlusSign buttonStrings[3] = F("Ctrl+PlusSign");
- MinusSign
Tab Tab buttonStrings[1] = F("Alt+Tab");
Return Return the enter key
Escape Escape
Insert Insert
Delete Delete
Page Up PageUp knobStrings[1] = F("PageUp");
Page Down PageDown knobStrings[0] = F("PageDown");
Home Home
End End
Caps Lock CapsLock
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[0] = F("LeftShift+2");
Left Ctrl or Ctrl LeftCtrl or Ctrl buttonStrings[2] = F("Ctrl+p");
Left Alt or Alt LeftAlt or Alt buttonStrings[4] = F("Alt+Tab");
Left Menu or Menu LeftMenu or Menu Windows Menu or Mac Command Key
Right Shift RightShift
Right Ctrl RightCtrl
Right Alt RightAlt
Right Menu RightMenu Windows Menu or Mac Command Key
F1-F12 F1, F2, F3, etc buttonStrings[0] = F("Ctrl+F11"); or buttonStrings[4] = 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
Num Lock KeyNumLock
F13-F24 F13, F14, F22, etc buttonStrings[2] = F("F17");
Media Rewind Rewind Rewinds the current song/media
Media Fast Forward FastForward buttonStrings[1] = 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: UpArrow+Release+Delay(500)+DownArrow This will press the up arrow and then press the down arrow 500 milliseconds later.

 

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. 

Availability