This guide describes about how to build keyboard and flash firmware.
- Check parts
- USB port
- Diodes
- LED
- Resistors
- Crystal
- Capacitors
- Regulator
- Speaker
- DIP switch
- Reset switch
- MCU socket
- PH connector
- JTAG header and ISP header
- Rotary encoders
- Solder keyswitch for ESC key
- Test
- Solder rest of keyswitches
- Screws and spacers
- Firmware and bootloader
- Build bootloader
- Flash bootloader
- Modify fuse-bit
- Build firmware
- Flash firmware
- Create custom keymap
パーツをPlanck Through Hole Kit自作キット - ⌁DHTN⌁で入手した場合は、以下のように分類されています。
- 基板2枚
- 袋A(銀) - マイクロコントローラー(MCU)
- 袋B(赤) - ネジ、スペーサー、クッションゴム
- 袋C(赤) - ロータリーエンコーダー
- 袋D(赤) - ソケット、ヘッダピン、コネクタ、スイッチ類
- 袋E(赤) - ダイオード
- 袋F(赤) - 抵抗、コンデンサ、クリスタル、LED、レギュレーター
自分で各パーツを調達した場合には以降を適宜読み替えてください。
それぞれの分類に含まれる個別のパーツは以下のとおりです。
| パーツ名 | 数量 |
|---|---|
| トッププレート用基板(黒) | 1 |
| ボトムプレート用基板(マットブラック) | 1 |
※マットブラックのボトムプレートは製造工程で多少の擦り傷がついている場合があります
| パーツ名 | 基板上の対応位置 | 数量 |
|---|---|---|
| ATmega32A | MICROCONTROLLER | 1 |
| パーツ名 | 数量 |
|---|---|
| M2黒ナベネジ 4mm | 20 |
| M2ステンレススペーサー 5mm | 10 |
| クッションゴム | 4 |
| パーツ名 | 基板上の対応位置 | 数量 |
|---|---|---|
| ロータリーエンコーダー | ENCODERS | 2 |
| パーツ名 | 基板上の対応位置 | 数量 |
|---|---|---|
| MCUソケット 40ピン | MICROCONTROLLER | 1 |
| DIPスイッチ | DIP SWITCH | 1 |
| 圧電スピーカー | SPEAKER | 1 |
| USBコネクタ | USB PORT | 1 |
| PHコネクタ | ALT USB PORT | 1 |
| ピンヘッダ 2×5 | JTAG HEADER | 1 |
| ピンヘッダ 2×3 | ISP HEADER | 1 |
| タクトスイッチ | RESET | 1 |
| パーツ名 | 基板上の対応位置 | 数量 |
|---|---|---|
| ダイオード | D1〜D48 | 50 (予備2個含む) |
| パーツ名 | 基板上の対応位置 | 数量 | 備考 |
|---|---|---|---|
| カーボン抵抗 68Ω | R1, R2, R4, R5 | 4 | 青灰黒金 |
| カーボン抵抗 1.5Ω | R3 | 1 | 茶緑赤金 |
| レギュレーター | POWER REGULATOR | 1 | |
| セラミックコンデンサ 20pF | C1, C2 | 2 | |
| 積層セラミックコンデンサ 22pF | C1, C2 | 2 | 20pFのものとどちらかを選んで使う |
| 積層セラミックコンデンサ 0.1uF | C3 | 1 | |
| 積層セラミックコンデンサ 4.7uF | C4 | 1 | |
| クリスタル(水晶発振子) | Y1 | 1 | |
| 赤色LED | PWR | 1 | |
| 緑色LED | ACT | 1 |
C1およびC2に使うコンデンサには以下の2種類を封入してあります。
- 静電容量20pFのセラミックコンデンサ 2個
- 容量はPlanck THK作者のJack Humbert氏の設計および基板上の表示通り
- ただしノーブランド品なので静電容量以外の詳細は不明
- 静電容量22pFの積層セラミックコンデンサ 2個
- 容量は20pFよりも大きいが、ATmega32Aのデータシートでは12〜22pFがクリスタル用推奨コンデンサ容量として挙げられているため問題ないと考えられる
- 村田製作所のものなのでスペックおよび品質は信頼できる
手元でそれぞれを使用したものを製作しましたが動作に違いはありませんでしたので、C1およびC2には上記を踏まえたうえでどちらかのコンデンサを使ってください。
Let's soldering parts on a PCB.
Solder the USB connector on USB PORT silk.
Since solder land for USB connector is so small and closes each other, be careful not to short (PCB version 0.1 improved this).
Solder 48 diodes from D1 to D48.
Diodes has polarity, place diode's black line on up side.
Planck THK doesn't have case which covers soldered parts, so solder carefully and beautifully.
Solder red LED on PWR, green LED on ACT.
LED has polarity, insert short lead into - (minus) hole.
まず、4本ある68Ω抵抗(青灰黒金)をR1、R2、R4、R5の箇所にはんだ付けします。
以下の写真のように、抵抗の脚は本体を出てすぐに曲げるくらいでないとうまく刺さらないので注意。
次に、1本だけの1.5kΩ抵抗(茶緑赤金)をR3の箇所にはんだ付けします。
クリスタル(水晶発振子)を Y1 の箇所にはんだ付けします。
前述のように20pFのセラミックコンデンサまたは22pFの積層セラミックコンデンサのいずれか2本を、クリスタル両側の C1 および C2 の箇所にはんだ付けします。
以下は22pFの積層セラミックコンデンサを実装した場合。
次に0.1uFの積層セラミックコンデンサを C3 の箇所に、4.7uFの積層セラミックコンデンサを C4 の箇所にそれぞれはんだ付けします。脚の幅が広い(5mm)ほうが4.7uF、狭い(2.54mm)ほうが0.1uFのもになります。
4.7uFのコンデンサはあらかじめラジオペンチなどで脚を伸ばしてから、以下の写真のように幅を狭めておくとスルーホールに通しやすくなります。脚がホールに通りさえすれば、あとはカットしてしまうので多少不格好でも大丈夫です。
C3 と C4 への実装が完了すると以下のようになります。
レギュレーターを POWER REGULATOR の箇所にはんだ付けします。
この際、スルーホールに差し込む前にラジオペンチなどで以下のように脚を直角に曲げておきます。
圧電スピーカーを SPEAKER の箇所にはんだ付けします。
極性はありませんが、スピーカーに「OK」の刻印があるのでこれを基板の向きと揃えるとよさそうです。
DIPスイッチを DIP SWITCH の箇所に、写真のように左側に1〜4の数字がくるようにはんだ付けします。この基板で最もランドが小さいので注意してください。
タクトスイッチを RESET の箇所にはんだ付けします。強く押し込むと基板と隙間なくはまります。
MCUソケットを MICROCONTROLLER の箇所にはんだ付けします。向きがありますので、以下の写真のように切り欠きが右側にくるようにして差し込みます。
以下は差し込んだ状態。
PHコネクタを ALT USB PORT の箇所にはんだ付けします。
※動作に必須ではないので、取り付けを省略することもできます。
2×5ピンのピンヘッダを JTAG HEADER の箇所に、2×3ピンのピンヘッダを ISP HEADER の箇所にそれぞれはんだ付けします。
※動作に必須ではないので、取り付けを省略することもできます。
ロータリーエンコーダー2個を ENCODER 1 および ENCODER 2 の箇所にはんだ付けします。はんだ付けの際に斜めになりやすいのでマスキングテープなどで固定するとよいです。
※動作に必須ではないので、取り付けを省略することもできます。
動作確認に最低限必要な「ESCキー用のキースイッチ」のみをはんだ付けします。
Planckのデフォルトのキーマップでは「一番左の列の上から2個目のキー」がESCキーとなるため、この部分スイッチのみをまずはんだ付けします。以下の写真では CTRL キーが付いてる箇所です。
スイッチを1つはんだ付けしたら、動作確認を行います。
MCU(ATmega32A)をMCUソケットに差し込みます。向きがありますので、MCUの切り欠きがソケットと同じく右側にくるようにします。
DIPスイッチの1番のみをONの状態に切り替えてから(ファームウェアの起動成功時やキー押下時に音が鳴るようになるので確認に便利)、Planck THKをUSB mini-BケーブルでPCやMacと接続します。
正常に動作している場合はPWRの赤色LEDが点灯し、コンピューター側からは以下のように HIDBoot という名前のUSBデバイスとして認識されます(＝ブートローダーが起動した状態)。
HIDBoot デバイスとして認識されている状態でESCキー(に相当するスイッチ)を押下すると、ACTの緑色LEDが点灯してスピーカーからPlanckの起動音が1回鳴ります。
ここでファームウェアの起動が成功すると、(前述のDIPスイッチ1番がONになっている場合はもう一度音が鳴ったうえで) Planck というUSBデバイスとして認識され、キーボードとして使用できる状態となります。
現時点ではこのブートローダーからファームウェアへの切り替え動作が安定せず、起動音が鳴った後に Planck として認識されないことがあります。そのような場合は以下の手順を何度か繰り返すと、4の状態になります。
- リセットスイッチを押してブートローダーを起動する
- ESCキーを押下してファームウェアを起動する
- 起動音が鳴る
- (DIPスイッチ1番がONの場合は)さらに音が鳴り、
Planckが認識される
この過程を実際に行っているところを動画にしてありますので、動作確認の参考にしてください。
この時点ではPlanckキーボードの default キーマップが適用されているので、キーアサインなどについては keyboards/planck/keymaps/default を参考にしてください。また、左側のロータリーエンコーダーにはマウスホイールによるスクロールがアサイン済みとなっています。
2018-12-06 追記 上記の「ブートローダーからファームウェアへの切り替え動作が安定せず」の件は、ファームウェアのオーディオ機能を無効化することで安定して動作するようです。詳細については後述の「ファームウェアの起動を安定させる」の項目を参考にしてください。
動作が確認できたら残りのキースイッチをはんだ付けしていきます。
まず、ボトムプレートとなる基板の上に10個のスペーサーをネジで固定し、次にその上にトッププレートとなる基板を載せ、基板の表から10個のスペーサーに対してネジで固定します。
構造としては以下のようにスペーサーを上下の基板で挟む形になります。
[↓ネジ]
[トッププレート]
[スペーサー]
[ボトムプレート]
[↑ネジ]
最後にクッションゴム4個をボトムプレートの四隅に貼り付ければハードウェアの実装は完了です。🎉
この項目の内容は 2018-11-11 時点での
の内容を元にしています。
Planck THKはブートローダーとして bootloadHID (V-USB Projects
Bootload HID) を利用しています。bootloadHIDの実装は planck_thk ブランチの keyboards/planck/thk/bootloader 以下に用意されています。
電源投入時およびリセット時は常にブートローダーが起動して、ファームウェアの書き込み待機状態となります。書き込み待機状態でESCキーが押下されるとQMK Firmwareに制御が移り、Planckキーボードとしての動作が開始します。
キーマップのカスタマイズやDIPスイッチ、ロータリーエンコーダーの挙動を変更する際は、通常のQMK Firmware対応キーボードのカスタマイズと同様の手順で作業・ビルドを行います。
一方、ビルドしたファームウェアをブートローダー経由で書き込むためには、コンピューター側にもbootloadHIDの書き込みコマンドをインストールしてそれを利用する必要があります。
QMK FirmwareのPlanck THK対応ブランチは2018-11-11時点でまだ master へマージされていないため、以下のようにして qmk/qmk_firmware リポジトリの planck_thk ブランチをチェックアウトしておきます。
$ git clone https://github.com/qmk/qmk_firmware.git
$ cd qmk_firmware
$ git checkout -b planck_thk origin/planck_thk
$ ls keyboards/planck/thk
README.md bootloader config.h matrix.c rules.mk thk.c thk.h usbconfig.hQMK FirmwareにおいてPlanck THKは planck キーボード内の1つのバリエーションとして定義されており(Planck rev6などの各リビジョンと同等)、
- ファームウェア:
keyboards/planck/thk以下 - キーマップ:
keyboards/planck/keymaps以下
という構成になっています。つまり、キーマップは planck キーボード全体と同じものを共有しています。
したがって、例えばPlanckのデフォルトキーマップを使ったファームウェアをビルドする方法は以下のようにQMKの標準的な方法と同様になります。
$ make planck/thk:default
QMK Firmware 0.6.161
Making planck/thk with keymap default
avr-gcc (GCC) 7.3.0
Copyright (C) 2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Size before:
text data bss dec hex filename
0 26088 0 26088 65e8 .build/planck_thk_default.hex
Compiling: tmk_core/common/command.c [OK]
Linking: .build/planck_thk_default.elf [OK]
Creating load file for flashing: .build/planck_thk_default.hex [OK]
Copying planck_thk_default.hex to qmk_firmware folder [OK]
Checking file size of planck_thk_default.hex [OK]
* The firmware size is fine - 26088/28672 (2584 bytes free)ここで生成された planck_thk_default.hex がファームウェアとなり、これを bootloadHID を利用して書き込むことになります。
前述のようにファームウェアの書き込みには、コンピューター側にも bootloadHID コマンドをインストールする必要があります。
macOSでHomebrewが利用できる場合のインストール手順は以下のようになります。
$ brew cask install crosspack-avr
$ brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
$ pip install pyusbインストールに成功すると以下のように bootloadHID コマンドが実行できるようになります。
$ bootloadHID
usage: bootloadHID [-r] [<intel-hexfile>]Windowsの場合は HIDBootFlash - V-USB が利用できるかもしれません。
ファームウェアを書き込むには、Planck THKのブートローダーが起動している状態(コンピューターから HIDBoot デバイスが見えている状態)で以下のコマンドを実行します。
$ bootloadHID -r planck_thk_default.hex
Warning: could not detach kernel HID driver: Function not implemented
Warning: could not detach kernel HID driver: Function not implemented
Warning: could not detach kernel HID driver: Function not implemented
Page size = 128 (0x80)
Device size = 32768 (0x8000); 30720 bytes remaining
Uploading 26112 (0x6600) bytes starting at 0 (0x0)
0x06580 ... 0x06600-r オプションが指定されているため、書き込み完了後に自動でファームウェアに制御が移り、コンピューターからは Planck USBデバイスとして認識されます。
ただし前述のようにファームウェアの起動に失敗するケースがあるため、そのような場合にはリセットおよびESCキー押下の手順を踏みます。
ファームウェアのコードを一部変更して、
- 起動音(の一部)を無効にする
- オーディオ機能を無効にする
のいずれかを行うと、ブートローダーからファームウェアへの切り替えに失敗することは無くなり動作が安定するようです。
起動音(の一部)を無効にする場合:
diff --git a/keyboards/planck/keymaps/default/config.h b/keyboards/planck/keymaps/default/config.h
index 6fa31cc8a..919532316 100644
--- a/keyboards/planck/keymaps/default/config.h
+++ b/keyboards/planck/keymaps/default/config.h
@@ -1,8 +1,8 @@
#pragma once
#ifdef AUDIO_ENABLE
- #define STARTUP_SONG SONG(PLANCK_SOUND)
- // #define STARTUP_SONG SONG(NO_SOUND)
+ // #define STARTUP_SONG SONG(PLANCK_SOUND)
+ #define STARTUP_SONG SONG(NO_SOUND)
#define DEFAULT_LAYER_SONGS { SONG(QWERTY_SOUND), \
SONG(COLEMAK_SOUND), \オーディオ機能を無効にする場合:
diff --git a/keyboards/planck/thk/rules.mk b/keyboards/planck/thk/rules.mk
index bba4ea707..090764482 100644
--- a/keyboards/planck/thk/rules.mk
+++ b/keyboards/planck/thk/rules.mk
@@ -38,7 +38,7 @@ CONSOLE_ENABLE = no
COMMAND_ENABLE = yes
KEY_LOCK_ENABLE = no
NKRO_ENABLE = no # Nkey Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
-AUDIO_ENABLE = yes
+AUDIO_ENABLE = no
# Do not enable SLEEP_LED_ENABLE. it uses the same timer as BACKLIGHT_ENABLE
SLEEP_LED_ENABLE = no # Breathing sleep LED during USB suspend動作させている様子はこちらのツイートにあります。
以上を踏まえて、キーマップをカスタマイズする際は次のような手順となります。
keyboards/planck/keymaps/defaultを自分用に複製する- 複製したキーマップ関連ファイルをカスタマイズする
make planck/thk:キーマップ名でファームウェアをビルドするbootloadHID -r planck_thk_キーマップ名.hexでファームウェアを書き込む
ここでは、ブートローダーが書き込まれていないATmega32AをPlanck THKのMCUとして利用可能にするための手順について解説します。
planck_thk ブランチの keyboards/planck/thk/bootloader には Makefile が不足しているため、まずこれを用意します。
Jack Humbert氏が用意してくれたものが BootloaderHID Makefile for Planck THK にあるので、これを keyboards/planck/thk/bootloader/Makefile として保存し、make コマンドでビルドします。
注意: この Makefile ではヒューズビットの変更を行うためのターゲットも定義されていますが、指定されているビット値が正しくないため make コマンドによるヒューズビットの変更は利用しないでください(上位バイト0x90、下位バイト0xcfとなるのが正しいがこれが逆になっている)。これを実行してしまうと以降の手順でブートローダーを書き込むことはできなくなり、復旧には別な手順が必要となります。
make コマンドを実行すると以下のようにビルドが行われます。
$ cd keyboards/planck/thk/bootloader
$ make
avr-gcc -Wall -Os -fno-move-loop-invariants -fno-tree-scev-cprop -fno-inline-small-functions -Iusbdrv -I. -mmcu=atmega32a -DF_CPU=16000000 -DDEBUG_LEVEL=0 -x assembler-with-cpp -c usbdrv/usbdrvasm.S -o usbdrv/usbdrvasm.o
avr-gcc -Wall -Os -fno-move-loop-invariants -fno-tree-scev-cprop -fno-inline-small-functions -Iusbdrv -I. -mmcu=atmega32a -DF_CPU=16000000 -DDEBUG_LEVEL=0 -c usbdrv/oddebug.c -o usbdrv/oddebug.o
avr-gcc -Wall -Os -fno-move-loop-invariants -fno-tree-scev-cprop -fno-inline-small-functions -Iusbdrv -I. -mmcu=atmega32a -DF_CPU=16000000 -DDEBUG_LEVEL=0 -c main.c -o main.o
main.c: In function 'main':
<built-in>: warning: function declared 'noreturn' has a 'return' statement
In file included from usbdrv/usbdrv.c:10:0,
from main.c:22:
main.c: At top level:
usbdrv/usbdrv.h:223:24: warning: 'usbFunctionDescriptor' used but never defined
USB_PUBLIC usbMsgLen_t usbFunctionDescriptor(struct usbRequest *rq);
^~~~~~~~~~~~~~~~~~~~~
usbdrv/usbdrv.h:230:17: warning: 'usbSetInterrupt' declared 'static' but never defined [-Wunused-function]
USB_PUBLIC void usbSetInterrupt(uchar *data, uchar len);
^~~~~~~~~~~~~~~
avr-gcc -Wall -Os -fno-move-loop-invariants -fno-tree-scev-cprop -fno-inline-small-functions -Iusbdrv -I. -mmcu=atmega32a -DF_CPU=16000000 -DDEBUG_LEVEL=0 -o main.bin usbdrv/usbdrvasm.o usbdrv/oddebug.o main.o -Wl,--relax,--gc-sections -Wl,--section-start=.text=7000
rm -f main.hex main.eep.hex
avr-objcopy -j .text -j .data -O ihex main.bin main.hex
avr-size main.hex
text data bss dec hex filename
0 1708 0 1708 6ac main.hex生成された main.hex がブートローダーとなります。これをそのまま書き込んだだけではキーボードとしては動作しないため、起動後にファームウェアを別途 bootloadHID でUSBで書き込む必要があります。
ブートローダーとデフォルトのファームウェアをセットで書き込む場合は、ISP Flashing Guide - QMK Firmware の Advanced/Production Techniques を参考に、
- ブートローダーをテキストエディタで開く
- 最終行の
:00000001FFを削除する - ファームウェアをテキストエディタで開く
- ファームウェアの内容をすべてブートローダーの内容の後にコピー＆ペーストする
- ファイルを
<keyboard>_<keymap>_production.hexのような名前で保存する
という手順で書き込み用のファイルを用意します(順序はブートローダーが先でないと動作しません)。
1の手順で用意した *.hex をISP(In-System Programming)用の回路で書き込みます。
書き込み回路を自前で作成するかArduino ISP用のシールドなどを利用して、ATmega32Aに対するISPが行える状態にしたうえで、avrdude で以下のように書き込みます。
$ avrdude -P /dev/tty.デバイス名 \
-b 19200 \
-c avrisp \
-p atmega32 \
-U flash:w:書き込むファイル.hex
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.02s
avrdude: Device signature = 0x1e9502 (probably m32)
avrdude: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "planck_thk_default_production.hex"
avrdude: input file planck_thk_default_production.hex auto detected as Intel Hex
avrdude: writing flash (30380 bytes):
Writing | ################################################## | 100% 28.41s
avrdude: 30380 bytes of flash written
avrdude: verifying flash memory against planck_thk_default_production.hex:
avrdude: load data flash data from input file planck_thk_default_production.hex:
avrdude: input file planck_thk_default_production.hex auto detected as Intel Hex
avrdude: input file planck_thk_default_production.hex contains 30380 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 15.88s
avrdude: verifying ...
avrdude: 30380 bytes of flash verified
avrdude: safemode: Fuses OK (E:FF, H:90, L:CF)
avrdude done. Thank you.ATmega32AをPlanck THKのMCUとして利用するには、AVRチップに特有のヒューズビットを変更する必要があります。指定すべき値は planck_thk ブランチの README.md にて以下のように言及されています。
Fuses I used are -U lfuse:w:0xcf:m -U hfuse:w:0x90:m, and I hit the ESC to bootup normally (just a work-around right now).
したがってヒューズビットは以下の値になるよう変更します。
- 上位バイト:
0x90 - 下位バイト:
0xcf
$ avrdude -P /dev/tty.デバイス名 \
-b 19200 \
-c avrisp \
-p atmega32 \
-U hfuse:w:0x90:m \
-U lfuse:w:0xcf:mヒューズビットの値を間違えて変更してしまうと、それ以降ISPが行えない状態となってしまうことがあるので注意してください。ヒューズビットの詳細についてはATmega32Aのデータシート内の「29.2 ヒューズビット」を参考にしてください。