Arabica3/7ビルドガイド

# build guide
この記事は自作キーボードキット Arabica3/7のビルドガイドです。
※現在遊舎工房で販売されているキットはすべてv1.3.1ですのでこのページを参考にして組み立ててください。
v1.2基板のビルドガイドは[こちら](https://github.com/CalciumNitride/Arabica37/blob/master/doc/v1.2buildguide.md)

## parts

![0_01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/17d408c5-700b-ccc0-6ea4-4c80d1934a20.png)

### キット内容物
※一部予備が含まれています
名称| 数量 | 備考 |
----|----:|:----:|
PCB             |　2 | リバーシブル
スイッチプレート  | 2|"
ボトムプレート   | 2|"
チルトプレート   | 2|"
Promicroカバー|2|"
ハイプロプレート | 2|
TRRSジャック     |2|
タクトスイッチ    |2|リセットスイッチ用
スペーサ M2 8mm   |20|
ネジ M2※       |40|
ダイオード       |44|スルーホール
Kailh PCBソケット|44|CheryMX用
ゴム足|10|

※現在のバージョンでは表側用の低頭ネジと裏側用の鍋ネジに分かれています

### 別途用意する必要のあるもの

名称| 数量 | 備考 |
----|----:|:----:|
キースイッチ|44|MX互換
キーキャップ  |44|キースイッチに合うもの
ProMicro|2|コンスルー使用可
スタビライザー|2|小指キー用 2U
microUSBケーブル|1|PCとの接続用
TRRSケーブル|1|左右の接続用



### オプション
名称| 数量 | 備考 |
----|----:|:----:|
SMDダイオード|44|1N4148W
SK6812mini|44|Backlight用
デジタルLEDテープ|2|Underglow用
配線材|6|Underglow用
OLEDモジュール|2|
4pinピンヘッダ|2|OLED用
4pinピンソケット|2|OLED用  


## 組み立て

PCBはリバーシブルです。どちらを左/右にしてもかまいません。
基本的に左右の実装は同じですが、Pro microの位置とSK6812miniの向きは間違えやすいので注意してください。

### 1.ダイオードを半田付けする

PCBの片面にダイオードを半田付けします(このあとの説明ではダイオードを実装する面を裏側とします)。
実装する場所は下図の赤い枠で囲われた部分です。四角い方のパッドがマイナスです。
※ダイオードには極性があります。黒い線が入っている方がマイナスなので向きを間違えないよう注意してください。
![1_diode01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/c3ec50f2-7adb-0a50-7c0c-7b8408ec54e8.png)

<details open>
    <summary><b>1-A.スルーホールのダイオード(キット付属)を使う場合</b></summary>

<div>

PCB上の穴に合わせて足を折り曲げます。

![1-A_diode01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/1f6fd478-eed3-b1f1-aba7-cd0a08d00a76.png)

ダイオードを穴に通します。黒い線が入っている側がPCB上の四角いパッドに来るようにします。

![1-A_diode02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/45728a1a-ec52-94de-d803-397a8874152e.png)

裏返して半田付けします。

![1-A_diode03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/33b81d95-77b9-1ba3-6244-fccadd93f3b8.png)

飛び出している足をニッパーで切ります。

![1-A_diode04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/0a9832ce-694f-311a-69ce-b00f02b1e3da.png)


</div></details>

<details><summary><b>1-B.SMDのダイオード(別売り)を使う場合</b></summary>
<div>
パッドの片側に予備はんだをします。

ダイオードを載せ半田付します。
向きに注意（ダイオードは印が付いている側、PCBはスルーホール用のパッドが四角い側がカソードです）
</div></details>

### 2.バックライトLEDを半田付けする(オプション)

バックライトに用いるSK6812miniは熱に弱く、実装難易度が高いため、温度調節可能な半田ごてとフラックスを使うことを推奨します。

<details><summary><b>フルカラーバックライトLEDを使用する場合</b></summary>

<div>

PCBの裏側から図の赤い枠で囲われた部分にSK6812miniを実装します。
PCB上の四角で囲われたパッド(図の赤く塗りつぶされたパッド)が+5Vです。
![2_backlightLED01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/6ff05321-9c02-f47b-9324-0ac9145a4338.png)
写真のように+5VのパッドにSK6812miniの一番大きいパッドが当たるように置き、パッドにフラックスを塗ります。
※+5Vのパッドは左右で位置が異なるので注意してください。
![2_backlightLED02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/81987c49-ba34-8726-0ba0-4d9e89453f78.png)

半田ごての温度を220℃～250℃に設定し、こて先に溶かしたはんだをパッド上になびるようにしてはんだを盛ります
![2_backlightLED03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/8219d098-e212-0d98-d1e6-4bce16ea78aa.png)


</div></details>


### 3.OLEDモジュール用ジャンパとピンヘッダ(オプション)

<details><summary><b>OLEDモジュールを使う場合</summary>

<div>

下図の赤い枠で囲われた部分にはんだを盛ってジャンパします。この作業は__表側のみ__行います。
![3_OLED01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/f2e71f55-dd14-784c-e4ca-47d5a2a2b85d.png)

![3_OLED02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/77244530-ccfe-c1ad-e6ec-5f893b49ec28.png)

次に、OLED用のピンヘッダを図の位置に実装します。表から差し込み、裏返して半田付けします。
![3_OLED03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/a5bb430b-daf3-0ed0-737b-4ec6f5a79c71.png)
![3_OLED04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/71ab3bbc-1d09-88a3-c77f-358e88e01aef.png)

</div></details>


### 4.タクトスイッチ、TRRSジャックを半田付けする

TRRSジャック、タクトスイッチをPCBの表側に実装します。
![4_TRRSandRS01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/e08570ac-3397-659d-fe97-c11487cad5a8.png)
![4_TRRSandRS02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/fa2b2737-c094-1d73-7b67-b0c733db3572.png)


### 5. ProMicroを実装する

ProMicroを図の位置の表側に実装します。PCB上の白い枠で囲われた列(図の赤く塗りつぶされた穴)にピンヘッダを差し込みます。
ピンヘッダは通常のものに加えてスプリングピンヘッダ(コンスルー)も利用できます。
![5_promicro01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/ae706e2f-f84c-76a3-a744-94c746b78772.png)

<details><summary><b>5-A.コンスルーを使う場合</b></summary>
<div>

コンスルーは上下があります。
![5-A_promicro01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/1d8e0b6d-305e-1f6e-5827-a66389f77e44.png)

コンスルーをPCBの先ほどの図の位置に差し込みます。下の写真のようにコンスルーの窓が同じ方向を向くように差し込むことが推奨されています。このとき、**コンスルーとPCBは半田付けしないでください**。
![5-A_promicro02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/e998ae2e-e9d2-f12a-b6d1-4b1d9a866c32.png)

差し込んだコンスルーの上にProMicroを平対面が上になるよう乗せ、コンスルーとProMicroを半田付けします。
![5-A_promicro03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/a7897c4d-8beb-3c39-9cb4-039cc44f54de.png)

</div></details>

<details><summary><b>5-B.コンスルーを使わない場合</b></summary>
<div>

ピンヘッダとPCBを半田付けし、さらにその上にProMicroを裏面(平たい方)を上にして半田付けします。

飛び出した足はニッパーで切り取ります。
</div></details>


### 6.PCBソケットを半田付けする

PCBソケットをPCBの裏側の図の位置に実装します。
![6_socket01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/02acc827-d113-825b-940f-1b315abb0d61.png)

まず、パッドにはんだを盛ります。
![6_socket02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/25ce7a57-a576-8faa-0ba9-3f13f3ca7982.png)

次に、ソケットを載せ、側面からこて先をあててはんだを溶かし取り付けます。このとき、ソケットが浮かないようにで押さえながら作業してください。

### 7. OLEDモジュールを実装する(オプション)

<details><summary><b>OLEDモジュールを使う場合</b></summary>
<div>

手順3で取り付けたピンソケットにOLEDモジュール用ピンヘッダを差し込みます。
![7_OLED01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/4c37fe12-407d-8ee7-f4c9-a0302fed99ae.png)

さらにその上にOLEDモジュール用をのせ、ピンヘッダとモジュールを半田付けします。OLEDモジュールが傾かないよう押さえながら半田付けしてください。
</div></details>

### 8.OLEDおよびバックライトLEDの動作確認(オプション)

<details><summary><b>OLEDモジュールの動作確認</b></summary>
<div>

[ファームウェア](#ファームウェア)の章を参考にArabica3/7のファームウェアを書き込みます。
正しく取り付けられていればOLEDモジュールが点灯し、左手側にはレイヤー状態と入力履歴が、右手側にはロゴが表示されます。
ソケットを取り付けた部分のパッドをショートさせたとき、OLEDの表示が変わってPCに文字が入力されれば動作確認は完了です。

</div></details>

<details><summary><b>バックライトLEDの動作確認</b></summary>

<div>

[ファームウェア](#ファームウェア) の章を参考にファームウェアの書き込み環境を用意し、以下のコマンドでLEDテスト用のファームウェアを書き込みます。

~~```$ make helix:led_test:avrdude```~~
現在は
```$ qmk flash -kb helix -km led_test```

正しく取り付けられていればLEDが赤、緑、青で点滅します。SK6812miniは数珠つなぎ状に信号を伝達していくので、動作しないものがあるとその後に接続されているLEDもすべて点灯しなくなります。
LEDが点灯しない原因は以下のいずれかです
 - 点灯していないLEDの半田付けにミスがある
 - 点灯していないLED自身が壊れている
 - 点灯していないLEDの前の番号のLEDのDOUTが基板と接続されていない 

LEDの接続順は下図の通りです。これを参考に半田付けの見直しを行ってください。

![8_LEDtest01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/50bd18ed-943a-1e41-814a-2710df43d872.png)



</div></details>


### 9. スタビライザーをはめ込む

2Uキー用のスタビライザーをPCBにはめ込みます。
![9_stabilizer01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/23a16f36-0149-97da-30de-f08b96f33118.png)
![9_stabilizer02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/6357d2b5-253b-5c64-d628-a5a9860cb45e.png)

　　　　　　　　　　　　　　　　　　　　　　　　　
### 10. ProMicroカバー用スペーサーを取り付ける

ProMicro付近の穴にスペーサーを後ろから5mmのネジで止めます。
![10_ProMicro_cover01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/75814a29-ad9a-0e6a-7de9-a6980a6ad3d4.png)
。


### 11. プレートにスイッチをはめ込む

スイッチプレートの4つの角にだけスイッチをはめ込みます。
![11_switchplate01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/5bb9dcfe-06a7-64d1-d625-80de6d05045b.png)

### 12. プレートとPCBを合わせる

スイッチの足がPCBソケットにささるようにスイッチプレートとPCBを合わせます。


### 13. スイッチをはめ込む

残りのスイッチをはめ込みます。
ソケットに差し込む際にスイッチの足が曲がっているとうまくささらず、折れてしまうことがあるので注意してください。
![13_switchplate01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/c53a6f42-a927-bf70-6c9e-5dbeae41f213.png)



### 14. Promicroカバーを取り付ける

手順10で取り付けたスペーサーにPromicroカバーを取り付けます。
![14_ProMicro_cover01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/01ff9e05-584b-4761-83f0-8835faee2058.png)


### 15. プレートを合わせる

ボトムプレートにスペーサーを取り付け、PCBと合わせたスイッチプレートをボトムプレートに乗せます。さらにハイプロプレートを重ねてねじどめします。ハイプロプレートの取り付けには長い方のねじをつかいます。
※ハイプロプレートは非常に壊れやすいので、保護紙を剥がしてからスイッチ穴の部分を切り離し、すぐに取り付けてください。

### 16. キーキャップを取り付ける

キーキャップをはめます。


### 17. ゴム足をつける

ボトムプレート底面に付属のゴム足を貼り付けます。
もしくは、ペデスタルプレート、チルトプレート利用することも出来ます(現在[データ配布](https://github.com/CalciumNitride/Arabica37/tree/master/plate_data)のみで販売は行っていません)。


## ファームウェア

### QMK firmwareの準備
<details><summary>__ファームウェアの本家mergeについて(2020/5/18追記)__</summary>
Arabica3/7のファームウェアが[QMK本家](https://github.com/qmk/qmk_firmware)にマージされました。別途キーボード用のファームウェアをダウンロードする必要はありません。下記の手順に従ってファームウェアを導入してください。
また、それに伴いファームウェアにいくつか変更を加えているため、古いファームウェアとはわずかに仕様が異なります。例えば、QMK本家の方針で`keymap.c`でキーコードを定義する際の`KC_`を省略するマクロは削除されています。`KC_`マクロを用いたファームウェアも[別途用意してあります](#追加キーマップ)。</details>

[こちら](https://docs.qmk.fm/#/newbs_getting_started)を参考にしてファームウェアを書き込むための環境を用意します。
~~WindowsではMSYS2、MacではhomebrewなどのLinuxコマンドラインを扱うツールが必要です。~~
従来のコマンドラインからの利用も可能ですが、新規に環境構築を行う場合は[QMK MSYS](https://msys.qmk.fm/)を使用する方法が簡単です。[リンク先の指示](https://msys.qmk.fm/guide.html)に従ってインストールと準備を行ってください

### ファームウェアを書き込む

PCにProMicroを接続したあと、

`$ cd qmk_fimware`
でQMK firmwareのフォルダを開きます。
別の場所にQMK firmwareを保存している場合は `$ cd (保存場所)` で開きます。
(既に開いている場合は不要です)

次に、
`$ qmk flash -kb arabica37/rev1 -km default`
でコンパイルと書き込みを行います。

`Waiting for USB serial port - reset your controller now (Ctrl+C to cancel).....`

という表示が出たら、キーボードのリセットボタンを押します。ProMicroの種類によっては二度押しもしくは長押しする必要があります。
(組み立て前に書き込みを行う場合は、ピンセット等を使いRSTピンをGNDに落とします)

以上でデフォルトファームウェアの書き込みが完了です。
同様にしてもう片手側にも書き込みます。二回目以降は左右を接続しマスター側に書き込みを行うだけでアップデートできます。

<details><summary><b>以前のバージョンのQMK_firmwareでのファームウェアセットアップと書き込みの方法</b></summary>

`$ git clone https://github.com/qmk/qmk_firmware.git`
でQMK Firmwareをダウンロードし、
`$ cd qmk_firmware`
`$ util/qmk_install.sh`
として準備完了です。


### ファームウェアを書き込む

PCにProMicroを接続したあと、

`$ cd qmk_fimware`
でQMK firmwareのフォルダを開きます。

次に、
`$ make arabica37/rev1:default:avrdude`
でビルド、書き込みを開始します。

`Detecting USB port, reset your controller now...`

という表示が出たら、キーボードのリセットボタンを押します。ProMicroの種類によっては二度押しもしくは長押しする必要があります。
(組み立て前に書き込みを行う場合は、ピンセット等を使いRSTピンをGNDに落とします)

`avrdude.exe done.  Thank you.`

と出たら書き込み完了です。同様にしてもう片手側にも書き込みます。二回目以降は左右を接続しマスター側にがわに書き込みを行うだけでアップデートできます。
</details>

### キーマップを変更する
#### ・追加キーマップ
標準では`Default`キーマップのみが用意されていますが、それとは別に、[こちら](https://github.com/CalciumNitride/Arabica37/tree/master/firmware/arabica37)にカスタマイズされたファームウェアとキーマップを用意しています。こちらのファームウェアは、QMK本家のものと異なり、キーマップを設定する際の`KC_`を省略出来るようになっています。

`rev1/rev1.h`を新しい物に置き換え、`lib`フォルダおよび`keypmaps`フォルダの中身を追加することで追加キーマップを使えるようになります。
フォルダ全体をそのまま置き換えたり、別名のフォルダを作っても構いません(別フォルダに保存する場合はコンパイル時に指定するキーボード名を対応する場所にしてください)。

現在は、標準的なキーボードと同様のQWERTY配列の`jp_qwerty`と、より効率的な入力を目指して作られたCOLEMAK配列の`jp_colemak`の二つが用意されています。

書き込みのときは
~~`$ make arabica37/rev1:(キーマップ名):avrdude`
で書き込むキーマップを選択します。~~
現在のバージョンのQMKでは
`qmk compile -kb arabica37/rev1:(キーマップ名):avrdude`
でコンパイル、
`qmk flash -kb arabica37/rev1:(キーマップ名):avrdude`
で書き込みを行います。

キーマップの名称は、`keymaps`フォルダ直下のキーマップフォルダの名前です。
![keymapsname.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/418533/3c2e726f-082b-a5f6-53d1-7efcd5aff685.png)

#### ・オリジナルのキーマップを設定する

`Default`キーマップもしくは追加キーマップを複製し、キーマップフォルダ内の`keymap.c`を編集することで、自由にキーマップを定義することが出来ます。
キーマップファイルの編集の詳細ついては、長くなるためここでは解説しません。別の記事を参考にしてみてください。

追加キーマップでは`LAYOUT_kc`を使っているため`KC_`を省略した形で記述できます。`KC_`で始まらないキーコードの再定義は`lib/keycode_exchanger.h`にまとめてありますが、`keymap.c`に直接書き連ねることも可能です。


#### ・OLEDモジュールのロゴを変更する

デフォルトでは、スレイブ側(右手側)のOLEDモジュールにはArabica3/7のロゴが表示されますがこの表示も自由に変更することが可能です。
OLEDモジュールの表示は`lib/glicdfont.c`で設定されています。
OLEDに表示したい画像ファイル(JPEGもしくはPNG)を用意したら、guri3氏の[Helix OLED Dot Maker](https://helix-oled-dot-maker.herokuapp.com)で変換する方法が簡単です。
変換したファイルを`lib`フォルダに入れ、`keymaps/(キーマップ名)/config.h`の`#define OLED_FONT_H`にパスを設定することでディスプレイを変更出来ます。