Linux/Macのターミナルだけで自作キーボードのファームウェアを書き込む一例

ターミナルにコマンドを入力するだけで、他のツールはトラブルシューティングぐらいにしか使用しません。
以下の内容は基本的にLinux/Mac共用となっているので、コマンドなどはそのまま実行できます。
ただし、MacOSの場合は、brewコマンドが実行できるようになっている必要があります。

# 記事の内容
- Linuxにファームウェア書き込み環境を準備
- キーマップの作成、ファームウェアデータの作成
- ファームウェアデータの書き込み
- トラブルシューティング

# 事前準備
- キーボードの作成
  - ファームウェア書き込み後の動作確認のため、スイッチの半田付けまではやっておく必要がある。
- PCB名の判別
  - 購入時に判明している筈であるが、販売者が独自の名前を使っていたりする場合もある。
  - 製品ページにPCB名が明記されていない場合、販売者が案内しているファームウェア書き込み方法を参照すると、本来のPCB名が記載されている場合がある。

# ファームウェア書き込み環境の準備

### qmk-firmware をダウンロード。
- [Githubページ](https://github.com/qmk/qmk_firmware)から直接ダウンロードしてもＯＫ
- 今後も使用することになるので、ダウンロード場所は良く考えること。

```
$ git clone https://github.com/qmk/qmk_firmware
```

### 必要なツール類の自動インストール
- ダウンロードしたqmk-firmwareのディレクトリにあるシェルスクリプトを実行

```
$ ./qmk_firmware/util/qmk_install.sh
```

### キーマップのmakeテスト
- カレントディレクトリを`./qmk_firmware`に移してから、下記コマンドを実行してテスト。
- `./qmk_firmware/xd60_rev3_default.hex`が作成されればＯＫ

```
$ make xd60/rev3:default
※ PCB名/バージョン名:キーマップ名
```

- もしも`Some git sub-modules are out of date or modified, please consider running: make git-submodule`とエラーが出る場合、下記のコマンドを実行してから再度テストする。

```
$ make git-submodule
```

# ファームウェアデータの作成
### オリジナルのキーマップを作成・編集
- 下記コマンドを実行すると、編集用のキーマップファイルとディレクトリが作成される。
- 例文の場合だと、`./qmk_firmware/keyboards/xd60/keymaps`に`my_keymap`と言う名前のディレクトリと`keymap.c`が作成される。
- PCB名は目的とするPCBの名前に合わせて変更すること。

```
$ ./qmk_firmware/util/new_keymap.sh xd60 my_keymap
※シェルのパス PCB名 作成するキーマップ名
```

- 作成された`keymap.c`を編集し、自分の最強キーマップを作成する。
- 編集方法に関する記事は他の記事等を参照

### ファームウェアデータのmake
- デフォルトキーマップでのmakeテストと同様、下記コマンドでファームウェアデータを作成
- キーボードの中には`xd60/rev3`の様にサブディレクトリを指定する必要がある場合もあるので、`./qmk_firmware/keyboards`の中にあるPCB名のディレクトリの中を事前に確認しておく。

```
$ make xd60/rev3:my_keymap
```

# ファームウェアデータの書き込み
### キーボードをブートローダーモードで接続
- PCに接続してからPCB背面のリセットスイッチを押したり短絡させることでブートローダーモードで接続できる。
- ブートローダーモードで接続できたかどうかは、`lsusb`コマンドで確認する。
- 下記の例は`atmega32u4`チップを搭載したPCBの場合。他のチップの場合、`03eb:2ff4`の部分のID番号を[こちら](http://www.linux-usb.org/usb.ids)のページで参照し、コマンドで使用するチップ名を把握しておく。

```
$ lsusb
.
Bus 020 Device 002: ID 03eb:2ff4 Atmel Corporation ATm32U4DFU  Serial: 1.0.0
.
```

### PCBに書き込み済みのファームウェアデータを消去
- `./qmk_firmware`で実行

```
$ sudo dfu-programmer atmega32u4 erase
※MacOSの場合はsudo不要。以下同じ。
```

### PCBに作成したファームウェアデータを書き込み
- `./qmk_firmware`で実行

```
$ sudo dfu-programmer atmega32u4 flash xd60_rev3_my_keymap
```

### PCBをリセット
- 物理的にキーボードを付け外ししても同じ効果。`./qmk_firmware`で実行

```
$ sudo dfu-programmer
```

# トラブルシューティング
### 1. Chip already blank, to force erase use --force.

```
$ dfu-programmer atmega32u4 erase
Chip already blank, to force erase use --force.
```

- すでにチップのメモリーが消去されている場合のメッセージ。
- 強制的に消去する場合は`sudo dfu-programmer erase --force`を実行する。

### 2. Devic is write protected.

```
$ dfu-programmer atmega32u4 flash xd60_rev3_vimlike.hex
Checking memory from 0x0 to 0x587F...  Empty.
0%                            100%  Programming 0x5880 bytes...
[Device is write protected.
  X  ERROR
Memory write error, use debug for more info.
```

- チップのメモリが erase されていない場合に表示される。
- 書き込みするファームウェアデータの指定を誤った後に出る場合がある。この場合、メモリを erase しようとしても上述１のエラーにより正常に消去できなくなる。
- `sudo dfu-programmer atmega32u4 erase --force`を実行してから書き込みを試行する。

### 3. 入力されるキーがおかしい
- Linuxであれば`xev`、MacOSであれば`KeyCast`などを使用し、キースイッチを押した場合に入力されるキーコードを確認する。
- 特にデフォルトとは異なるレイアウトで組んだ場合によく陥る。
- 一度デフォルトのキーマップを書き込みし、デフォルトの`keymap.c`と入力されるキーコードを見比べて修正するのが簡単

# 記事作成の経緯
家にあったのがLinuxマシンとMacbookだったので。
使用ツール数の少ない汎用性の高いファームウェア書込み方法を模索して、最も簡単そうな方法がコレでした。