Keyboardio Kaleidscopeのはじめかた

![DALL·E Jan 19 Sketch.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184128/fd06157b-60f5-95b2-7a3f-f2c018bb9613.png)

## まとめ

- Chrysalis → Kaleidoscope の順がおすすめ
- Kaleidoscope は Arduino IDE → CLI の順がおすすめ
- Chrysalis → Kaleidoscope に移行するときEEPROM を削除する 

## はじめに

[Keyboardio](https://shop.keyboard.io) は、とてもユニークなキーボードをつくっています。かれらが販売している [Atreus](https://shop.keyboard.io/products/keyboardio-atreus)は超コンパクトな44キーのキーボード。

わずか44キーながら、レイヤー切り替えによってフルサイズキーボードの機能を完全にカバーしています。とても小型のため、持ち運びも容易です。[rebuild.fm](https://rebuild.fm)の宮川さんや、[gofujita](https://gofujita.info/notes_atreus.html)先生なども利用されているそうです。

![e621c03fa31981a655060e363e02de16_original.jpeg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184128/e225926b-5d4a-1a7b-3ade-15caf6e6d019.jpeg)


キーマップのカスタマイズには、[Chrysalis](https://github.com/keyboardio/Chrysalis)または[Kalaidoscope](https://github.com/keyboardio/Kaleidoscope)が利用できます。しばらくChrysalisをつかっていましたが、Kaleidoscopeに切り替えました。

## 想定読者

- Atreus、Model 100などの、Keyboardioのキーボードのユーザ
- ErgoDox EZ、OLKB Planckなど、Kaleidoscope対応キーボードのユーザ
- Chrysalisのカスタマイズでは機能が足りなくなったユーザ

## まずはChrysalisがオススメ

Kaleidoscope をつかうまえに、まずは [Chrysalis](https://github.com/keyboardio/Chrysalis) でカスタマイズをするのがオススメです。

Chrysalis は Kaleidoscope をかんたんに使えるようにするためのアプリです。Kaleidoscope の全機能はカバーしていませんが、主要な機能はカバーしており、コードを書くことなく、マウスをぽちぽちしてキーマップをカスタマイズできます。

ほとんどのカスタマイズは Chrysalis で事足りる印象があります。わたしの場合も rev29 まではChrysalis で実施していました。

しかしながら、下記の機能はどうしても Chrysalis で実現できず、Kaleidoscope に切り替えることを決めました。

- 左Fnキーを、短押し→英数、長押し→レイヤー移動にしたい
- 左Fnキーを、短押し→かな、長押し→レイヤー移動にしたい
- aキーを、短押し→a、長押し→ctrlにしたい
- zキーを、短押し→z、長押し→shiftにしたい

前者ふたつは Chrysalis 未対応。後者ふたつは対応はしているのですが、微妙な設定が Chrysalis ではやり切れませんでした。


## Kaleidoscopeを使用するまで

[Kaleidoscopeの公式ページ](https://github.com/keyboardio/Kaleidoscope?tab=readme-ov-file) に解説があるとおり、[Arduino IDEを用いる方法](https://kaleidoscope.readthedocs.io/en/latest/quick_start.html)と、[git cloneしてセットアップする方法](https://github.com/keyboardio/Kaleidoscope?tab=readme-ov-file#use-git-to-check-out-a-copy-of-kaleidoscope)があります。

どちらを選ぶかは、経験に大きく左右されると思います。わたしはファームウェアをコンパイルしてインストールするのは初めてでした。

その立場からのオススメは、まずArduino IDEをドキュメントどおりにインストールし、最新版のデフォルトファームウェアのコンパイルとインストールまでは実施すること。

そして、概要がつかめたあとは、git cloneしてコマンドラインから操作するほうがシンプルで見通しが良いように感じました。


## ChrysailsからKaleidoscopeへの移行のハマりどころ

### Arduino IDEかコマンドラインか

上述のとおり、経験に左右されると思いますが、もし初めての場合は、まずはArduino IDE、次にgit cloneしてコマンドライン、をオススメします。

### EEPROM

まずはArduino IDE でファームウェアをコンパイルしてインストールしても、キーマップが変わりませんでした。この現象でいちばん悩みました。

結論は、Chrysalis のPreference > My Keyboard > Advanced Tools & Preferences > RESET EEPROM TO FACTORY DEFAULTS ボタンを押して、EEPROMを消去する。消去後に、ファームウェアをインストールすると、設定が反映されるようになります。

:::note
ChrysalisとKaleidoscopeの、EEPROMの取り合い

EEPROMとは、書き込み可能で、電源を切っても消えない記憶領域。Chrysailsは、ファームウェアはなるべくいじらず、EEPROM領域にキーマップを書き込むことでカスタマイズをおこないます。
Kaleidoscopeはキーボードにファームウェアを書き込みます。ファームウェアは、EEPROMが空いていれば使いますが、もし既に書き込まれている場合、遠慮してつかわない判断をします。
したがって、ChrysalisをつかったあとにKaleidoscopeでファームウェアをインストールすると、キーマップが変わっていないように見えてしまいます。
:::

:::note warn
EEPROM のリセットの前には、かならずキーマップのバックアップをお取りください。

Chrysalis は Backup & Restore > Export でファイルにバックアップし、Importでファイルから読み込んで復元できます。
:::


## Kaleidoscope の git clone

公式ページの [Use git to check out a copy of Kaleidoscope](https://github.com/keyboardio/Kaleidoscope?tab=readme-ov-file#use-git-to-check-out-a-copy-of-kaleidoscope) に書いてある通りですが、`~/git` にインストールするとして、

```shell
$ mkdir ${HOME}/git
$ cd ${HOME}/git

$ git clone https://github.com/keyboardio/Kaleidoscope

$ cd ${HOME}/git/Kaleidoscope
$ make setup
```

でインストール。

```shell
$ export KALEIDOSCOPE_DIR=${HOME}/git/Kaleidoscope

$ echo "export KALEIDOSCOPE_DIR=${HOME}/git/Kaleidoscope" >> ${HOME}/.bash_profile
```

などとして環境変数を設定します（上記はbashの場合）。


## Kaleidoscopeでの作業

キーボードは Atreus で、git clone先が`~/git`だと仮定します。作業は `~/git/Kaleidoscope/examples/Devices/Keyboardio/Atreus` でおこないます。

```shell
$ ls
Atreus.ino  Makefile    sketch.json sketch.yaml
```

の4つのファイルがあり、このうち `Atreus.ino` を編集します。

`$ make compile` でコンパイル。
`$ make flash` でコンパイルして Atreus にファームウェアをインストールします。

```shell
$ make flash
Using Kaleidoscope from /Users/user/git/Kaleidoscope
Building in quiet mode. For a lot more information, add 'VERBOSE=1' to the beginning of your call to /Applications/Xcode.app/Contents/Developer/usr/bin/make
最大28672バイトのフラッシュメモリのうち、スケッチが24520バイト（85%）を使っています。
最大2560バイトのRAMのうち、グローバル変数が983バイト（38%）を使っていて、ローカル変数で1577バイト使うことができます。

Used library                            Version Path
Used platform  Version Path
keyboardio:avr 1.6.11  /Users/user/git/Kaleidoscope/.arduino/user/hardware/keyboardio/avr

（中略）

To update your keyboard's firmware, hold down the key in the lower left corner of your Atreus.

When you're ready to proceed, press 'Enter'.
```

インストールする際には上記のようなメッセージが出ます。そこで、キーボードの左下のキーを押しながら `enter` を押下します。`enter` キーを押したあとも、左下キーはもうしばらく押しておきます。

:::note
左下キーを押下すると、キーボードがいわば「ファームウェア受入れモード」になります
:::

## 参考リンク

Chrysalis と Kaleidoscope の EEPROM 問題について：

- [From Chrysalis →Kaleidoscope - Help and Getting Started - Keyboardio community](https://community.keyboard.io/t/from-chrysalis-kaleidoscope/4620)
- [Stuck with old custom layout - #3 by boris - Help and Getting Started - Keyboardio community](https://community.keyboard.io/t/stuck-with-old-custom-layout/3504/3)
- [Atreus Firmware Puzzle - Programming - Keyboardio community](https://community.keyboard.io/t/atreus-firmware-puzzle/5084)

Keymap 作成にあたって：

- 基本手順：[Edit A Keymap · keyboardio/Kaleidoscope Wiki · GitHub](https://github.com/keyboardio/Kaleidoscope/wiki/Edit-A-Keymap) 
- キー名称：[Kaleidoscope/src/kaleidoscope/key_defs · GitHub](https://github.com/keyboardio/Kaleidoscope/tree/master/src/kaleidoscope/key_defs)
- inoファイル例1：[The Keyboardio Atreus | Felipe Vogel](https://fpsvogel.com/posts/2021/keyboardio-atreus)
- inoファイル例2：[dotatreus/fjolne_kbd/fjolne_kbd.ino · GitHub](https://github.com/fjolne/dotatreus/blob/master/fjolne_kbd/fjolne_kbd.ino)

下記、ご参考まで、わたしのinoファイル。

[Atreus.ino · GitHub](https://gist.github.com/hnsol/edaf16fe5d4d679d980561923e048cad)

## おわりに

Keyboardio の Atreus キーボードのカスタマイズに関する基本的なガイドラインをご紹介しました。Chrysalis と Kaleidoscope を利用することで、キーボードの体験を改善できます。

ファームウェアのコンパイルとインストールは初めての経験でした。なんだかすこし、禁断の領域に足を踏み入れたようなドキドキ感がありました。なんとはなく手を出してはいけない領域だとおもっていたようなのです。しかしこの領域は、キーボードカスタマイズにおいて重要そうです。

キーボードは、ユーザーがデジタル世界を操るための貴重な道具です。『ハリー・ポッター』シリーズでハリーの杖は、かれの特異な能力と運命を象徴し、かれの魔法の発現に不可欠なものでした。おなじように、カスタマイズされたキーボードは、単なる入力デバイス以上のものであり、わたしたちの能力や創造性を発揮するためのツールです。ハリーの杖がかれにとって特別であったように、よく手入れされたキーボードは、わたしたちにとって特別な存在なのかもしれません。

この記事が、そんなキーボード環境構築の一助となることを願っております。


### 環境

- Kaleidoscope v1.99.8
- Chrysalis 0.13.3
- Keyboardio Atreus
- macOS Sonoma 14.2.1（23C71）
- MacBook Pro (14-inch, 2021)