ErgoDox EZのキーマップを変更する

[ErgoDox EZ](https://ergodox-ez.com)を購入したらやっぱりキーマップを弄りたくなると思います（？）ので、キーマップの変更方法を簡単に書いておきます。

結構リポジトリ構成が変わることがあるので、間違いなどあれば編集リクエストいただけますと助かります:pray:

環境
----

以下環境を前提としています。

- Mac OSX
- Homebew

Teensyをインストールする
----

作成したキーマップをキーボードのマイコンに転送するためにTeensyが必要になります。

### GUI版を使う

- http://www.pjrc.com/teensy/loader_mac.html

**Teensy Loader Disk Image**からダウンロード＆インストールしてください。
インストールといっても、dmgファイルをマウントしてアプリケーションフォルダに移動するだけです。

### CLI版を使う

コマンドラインで完結させたい場合は[teensy_loader_cli](https://www.pjrc.com/teensy/loader_cli.html)を入れると良いです。homebrewで以下のようにインストールしてください。

```bash
$ brew install teensy_loader_cli
```

キーマップファイルを作成する
----

キーマップファイルの作成方法は２つあります。

1. massdropの[configurator](https://keyboard-configurator.massdrop.com/ext/ergodox)で作成＆ダウンロードする
2. ソースからビルドする

### 方法1. massdropのconfiguratorを使用する

1の場合、最低限のキーマップは作成できますが、LEDの設定や特殊なキーの挙動までは設定することができません。
ErgoDoxシリーズ共通の最低限の設定だけで十分という場合はこちらの方法でも問題ないです。

### 方法2. ソースからビルドする

**ErgoDox EZのデフォルトキーマップはこのconfiguratorでは再現できない**ため、元の設定を維持したまま一部変更を加えたい場合は2のソースからビルドする必要があります。

ここではソースからビルドする方法を記載しますが、massdropのconfiguratorからダウンロードした場合はビルド作業はとばしてその後の「キーマップを適用する」に進んでください。

ソースからビルドする
----

### avr-libcをインストールする

ビルドにはAVRライブラリが必要になるので、Homebrewでインストールしておきます。
時間がかかるのでキーマップファイルを弄る前に実行しておくのが良いです。

```bash
$ brew tap osx-cross/avr
$ brew install avr-libc
```

### リポジトリをgit cloneする

ソースが含まれたリポジトリをクローンしてきます。

```bash
$ git clone https://github.com/jackhumbert/qmk_firmware.git
```

### キーマップファイルをビルドする

詳しくは以下を参考にしてください

- https://github.com/jackhumbert/qmk_firmware/tree/master/keyboards/ergodox

このリポジトリにはErgoDox EZ以外のソースも含まれています。
ErgoDox EZ用のソースは以下にあります。

- keyboards/ergodox/keymaps/default/keymap.c

```bash
$ cd keyboards/ergodox/keymaps/default/
$ vim keymap.c
```

指定するキーのパターンは既存のキーマップや、下記を参考に設定してください

- [Quick aliases to common actions](https://github.com/jackhumbert/qmk_firmware#quick-aliases-to-common-actions)
- [ErgoDoxのキーマップをいじる時に見るシートチートシート - Qiita](/ReSTARTR/items/970354940f49c67fb9fd)

例えば、Aキー左側のBackspaceをCtrlにしたい場合は以下のように変更します。

```diff
--- a/keyboards/ergodox/keymaps/default/keymap.c
+++ b/keyboards/ergodox/keymaps/default/keymap.c
@@ -34,7 +34,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
        // left hand
        KC_EQL,         KC_1,         KC_2,   KC_3,   KC_4,   KC_5,   KC_LEFT,
        KC_DELT,        KC_Q,         KC_W,   KC_E,   KC_R,   KC_T,   TG(SYMB),
-        KC_BSPC,        KC_A,         KC_S,   KC_D,   KC_F,   KC_G,
+        KC_LCTRL,        KC_A,         KC_S,   KC_D,   KC_F,   KC_G,
        KC_LSFT,        CTL_T(KC_Z),  KC_X,   KC_C,   KC_V,   KC_B,   ALL_T(KC_NO),
        LT(SYMB,KC_GRV),KC_QUOT,      LALT(KC_LSFT),  KC_LEFT,KC_RGHT,
                                              ALT_T(KC_APP),  KC_LGUI,

```

こんな感じで編集した後、ビルドを実行します。
`keymap=default`の指定は`keyboards/ergodox/keymaps/${keymap}`のディレクトリ名と対応しているので、ディレクトリがdefault以外の場合はこの値も変える必要があります。

```bash
$ cd keyboards/ergodox/
$ make clean && make keymap=default
# リポジトリ下の`.build`にhexファイルが生成されます
$ ls ../../.build/ergodox_ez_default.hex
../../.build/ergodox_ez_default.hex
```

makeのオプション指定はいくつか指定可能なパターンがあり、qmk_firmwareリポジトリ直下にて

```bash
make keyboard=ergodox subproject=ez keymap=default
```
もしくは

```bash
make ergodox-ez-default
```

という指定でビルドすることもできます。

ビルドが完了したらqmk_firmwareリポジトリ下に`.build/ergodox_ez_default.hex`というファイル名で出力されます。
※ファイル名の命名規則は`${keyboard}_${subproject}_${keymap.hex}`となっています。

キーマップファイルをロードする
----

### GUI版を使う場合

![teensy](https://qiita-image-store.s3.amazonaws.com/0/8647/42e45592-899d-f507-6530-795d8c0d8c23.png)

TeensyアプリのFile>Openから、作成したhexファイルを開きます。
（ファイルアイコンからでも開けます）

下記のように**Auto**を有効にしておくと、Teensyキーを押したら自動的に転送＋リブートが実行されます。
![スクリーンショット 2016-04-17 15.19.05.png](https://qiita-image-store.s3.amazonaws.com/0/8647/ce833207-de4d-6a89-f1e3-e2ee2ef98408.png)

### CLI版を使う場合

以下を実行すればHEXを読み込んでリブート待ちの状態になります。

```bash
$ make teensy
```

他makeタスク同様、keymap指定の場合は下記のように指定します。

```
$ make teensy keymap=default
```

実行すればこのように待ち状態になります。

```
   :
   :
Teensy Loader, Command Line, Version 2.0
Read "./.build/ergodox_ez_default.hex": 18230 bytes, 56.5% usage
Waiting for Teensy device...
 (hint: press the reset button)
```

ですので、キーマップのビルドとリブート待ちまでの処理を一括で行いたいのであれば、コマンドでつなげてしまうことが可能です。CLIに慣れている方であればこちらの方法が良いかと思います。

```bash
$ make && make teensy
```

### キーマップを適用する(キーボードをリセットする)

RESETキーコードが送信できれば良いのですが、ErgoDox EZのデフォルトキーマップには設定されていないため、
右手キーボード上部のLED横にある小さな穴からアクセスしないといけません。
(_L2とか適当なキーに`RESET`をアサインしておくと物理的なアクセスが不要になります_)

僕はギター弦の6弦の切れ端が運良く手元にあったのでそれを利用しましたが、それなりに長さがないとアクセスできないので注意です。ボールペンの先とかでは長さがたりません。1cm程度の長さが必要ですので、クリップ等を利用しても良いかと思います。


リブートが完了すると、LEDが光ります。
(以下はUSB接続時の映像ですが、リブート時も同様のLEDパターンで光ります)

<blockquote class="twitter-tweet" data-lang="ja"><p lang="ja" dir="ltr"><a href="https://twitter.com/hashtag/ErgoDox?src=hash">#ErgoDox</a> EZは、usbケーブルを繋ぐと三色のLEDが光ります。あと、選択してるレイヤーによって色が変わるしかけ。 さらにファームをカスタムすれば色々できそう。 <a href="https://t.co/MXOKSkWtaa">pic.twitter.com/MXOKSkWtaa</a></p>&mdash; Masaki Yoshida (@ReSTARTR) <a href="https://twitter.com/ReSTARTR/status/717731988384288768">2016年4月6日</a></blockquote> <script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

あとは、実際にキーボードを使ってみて設定が反映されているか確認できれば完了です。

参考までに
----

僕が今使用しているキーマップを以下で公開していますので、こちらも参考にしていただければ幸いです。

- [qmk_firmware/keymap.c at ergodox_ez/ReSTARTR · ReSTARTR/qmk_firmware](https://github.com/ReSTARTR/qmk_firmware/blob/ergodox_ez/ReSTARTR/keyboard/ergodox_ez/keymaps/default/keymap.c)

まだErgoDox EZを持っていない方はこちら
---

- [ErgoDox EZが届いた · I Will Survive](http://blog.restartr.com/2016/03/31/got-my-ergodox-ez/)
- [ErgoDoxを購入して人生がバラ色になった - YAMAGUCHI::weblog](http://ymotongpoo.hatenablog.com/entry/2016/03/25/203734)
- [流行りにのってErgoDox EZを買ってしまった - タオルケット体操](http://hachibeechan.hateblo.jp/entry/first-impression-of-ergodox-ez)
- [ErgoDox というキーボードを買った - yosida95](https://yosida95.com/2016/04/22/bought-ergodox.html)