clee/qmk-macos.md Secret

## qmk-macos.md

      
    Raw
  

              qmk-macos.md
            
          
    installing QMK on your Pearl from macOS

introduction

This guide is going to assume that you know how to use the Terminal app on your Mac. If you don't know how to use the command-line, you may want to try a free online course.
prerequisites

Open a Terminal window. Commands to enter into the Terminal will be formatted like this:
echo "hello, world"

command-line tools

First, we install the Xcode Command-Line Tools, which we'll need for the next step...
In the Terminal window, run:
xcode-select --install

homebrew

Next, install homebrew ("the missing package manager for macOS"), which we'll need to install a bunch of other things.
In the Terminal window, run:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

install everything we need to build qmk

Building QMK requires more than just a C compiler; we're going to need a cross-compiler for AVRs along with the latest version of git.
In the terminal window, run:
brew tap osx-cross/avr && brew install git avr-gcc

bootloadHID

Once a firmware image is built, you need a program called bootloadHID to actually flash the firmware onto the Pearl's controller.
To install bootloadHID, run this command in the Terminal:
brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb

building qmk

get the code

Before we can start customizing a QMK firmware, we need a copy of the code locally. QMK is developed in git on GitHub.
In the Terminal window, run:
git clone git://github.com/qmk/qmk_firmware

Once the code is downloaded, you should move into the new directory:
cd qmk_firmware

going with the default

If you want to use the default Pearl keymap, building the firmware is as easy as:
make pearl

make is the command that compiles QMK from source code into firmware images. It must be run from inside the qmk_firmware directory to work. pearl tells make the name of the keyboard to build the firmware for, and when no keymap is specified, all of the available keymaps for that keyboard are built.
Now you can flash it to your Pearl by following these steps.

In the Terminal, type make pearl:default:program and hit Enter
Unplug your keyboard from the computer and hold down the 'Esc' key (or whatever key you installed in the top left corner of the board).
While holding the 'Esc' key, plug the USB cable back in. (See note below about USB)
If you soldered the indicator LEDs in the lower-right corner of your Pearl, all three should be blinking at a steady medium pace. This means the Pearl has entered bootloader mode, so it can be programmed with a new firmware image.
You can let go of the 'Esc' key now and watch as the Pearl is reprogrammed.
QMK should now be running on your Pearl.

A note about USB: You may have better luck reprogramming the Pearl's firmware if you plug the cable into a USB port that is directly attached to your motherboard. Some USB hubs don't provide enough power, or they don't transfer the data with the correct timing, or other various issues; if your firmware doesn't program correctly because of a communication error, try unplugging as many USB devices as possible and plug the Pearl directly into the motherboard without any hubs or extensions and try again. (Unplug, hold Esc, replug, rerun make pearl:default:program.)
going custom

The default layout probably won't work for you, because the Pearl is so flexible that it can be built many ways and it's unlikely that you chose to build yours with the exact same keys as the default layout. So you'll want to go custom.
I recommend the following approach:
cp -a keyboards/pearl/keymaps/default keyboards/pearl/keymaps/custom-name

open keyboards/pearl/keymaps/custom-name/

This will open up a Finder window with a file called keymap.c. You can open that in any text editor you like. Some popular macOS programming editors are SublimeText, Atom, and Visual Studio Code.
You can, of course, use another name for your keymap instead of custom-name. For example, my custom keymap is the same as my username, clee. If you change the name on your system, just make sure to substitute it in the following commands.
The default keymap has two layers, but you can add more if you follow the formatting. Some notes about the Pearl specifically:

The first row can have two different configurations (a 2U backspace or 2x 1U keys in the same spot)

If you use the 2U backspace, the very last keycode on the line is what will be sent when you press the key
Otherwise, the key codes are 1:1 with the buttons across the whole first row


The second and third rows only have a single supported configuration, and the key codes map 1:1 with the buttons on those rows
The bottom row supports quite a few different key positions; you should be able to figure out the order of the keys by noting that the left spacebar, 6.25U/7U spacebar, and right spacebar all have separate positions on the board.

If you're making your own custom keymap with QMK, you'll want to keep the QMK documentation handy.
Some particularly useful pages in the QMK documentation are:

QMK Basic Keycodes
QMK Advanced Keycodes

With advanced keycodes, for example, you could make a key send Ctrl when held, but Esc when tapped, with something like this:
CTL_T(KC_ESC)

QMK allows all kinds of incredibly advanced behavior. There's too much to cover in this guide, but here are a few pointers for faster typists. You can try adding a couple of lines to your keyboards/pearl/config.h, right before the final #endif line:
#define PERMISSIVE_HOLD
#define TAPPING_TERM 125

PERMISSIVE_HOLD is better documented in the QMK docs, and TAPPING_TERM is the number of milliseconds after which a tap turns into a hold. The QMK default is 200ms.
flashing your sweet new custom firmware

Programming a custom keymap is very similar to programming the default; you just have to set the keymap, like so:
make pearl:custom-name

make pearl:custom-name:program

And follow the same steps as before - unplug USB cable, hold Esc, replug USB, and watch it program.