Peaky 8-bit Dev-log

How to Use Peaky 8-bit Repository / When you want customize key map

13 min

（日本語版は後ろにあります）

Peaky 8-bit (P8) uses ZMK for its firmware, and the repository is publicly available.

When you receive your P8, it comes pre-flashed with the firmware version that I (toya, the developer) consider the best starting point for new users, with the keymap and key assignments set to that version.

As you use P8, you’ll likely want to customize the keymap to suit your needs. Follow the steps below when you’re ready to do that.

Cheat Code

In the age of AI, you don’t even need a guide like this. Just hand the repository URL above to an AI (Claude, ChatGPT, etc.) and ask:

How do I change the keymap?

It’ll probably just tell you:

"Edit the CSV with your desired keymap, regenerate peaky8bit.keymap, and push!"

You can also ask the AI to generate the .keymap file for you — it can run Python/uv on its end. That might be the fastest way.

When I want to change the keymap myself, I just tell Claude:

"Swap the N and H keys!"
(Edit the CSV and regenerate peaky8bit.keymap)
(Actually run `gen_keymap.py`)

Then:

  1. Push the CSV and keymap that Claude generated to the repository
  2. Download the .uf2 (firmware) auto-built by Actions
  3. Flash it to the MCU (Xiao BLE)

That’s literally my workflow.

The Big Picture

  1. Edit docs/keymap_v04.csv
  2. Run gen_keymap.py to regenerate peaky8bit.keymap
  3. Commit and push both files together
  4. GitHub Actions automatically builds the new firmware
  5. Download the .uf2 and flash it

That’s it.

IMPORTANT

You never edit the .keymap file directly.

Before You Start

  • Fork the repository to your own GitHub account.

    • Actions run on your own fork.

  • Enable Actions

    • If you know how, do it in advance.
    • If not, Step 4 below walks you through it — skip this for now.

  • You’ll need a way to run Python: uv is the easiest.

    • Alternatives: Google Colab, etc.
    • Even easier: just ask an AI.

Step 1: Edit the CSV

Open docs/keymap_v04.csv. Each row corresponds to one chord code.

Repository structure and contents of docs/keymap_v04.csv, showing the hex, layer1, with_shift, and with_ctrl columns
Repository structure and contents of docs/keymap_v04.csv, showing the hex, layer1, with_shift, and with_ctrl columns
hex,layer1,with_shift,with_ctrl
0x11,write:a,write:A,keys:LCTRL+A
0x12,write:b,write:B,keys:LCTRL+B

To change a character, just find the row with that character and edit it. The hex column is the chord code ID — you can ignore it.

For example, to swap y and z:

- 0x2C,write:y,write:Y,keys:LCTRL+Y
- 0x2D,write:z,write:Z,keys:LCTRL+Z
+ 0x2C,write:z,write:Z,keys:LCTRL+Z
+ 0x2D,write:y,write:Y,keys:LCTRL+Y
Current positions of Z and Y. An example of swapping them.
Current positions of Z and Y. An example of swapping them.

The CSV has 4 columns, but the hex column is just the chord code ID — you can ignore it. You only need to edit the remaining 3 columns:

ColumnWhen it takes effect
layer1Normal input
with_shiftAfter arming Shift
with_ctrlAfter arming Ctrl
NOTE

“Arming” means pressing the modifier chord first (e.g. the “Ctrl +” chord), then pressing the character chord (e.g. the “A” chord) to produce Ctrl + A. The combo inputs shown below are the modifier arm chords.

Modifier Arm keymap
Modifier Arm keymap

Use a plain text editor to edit the CSV. Excel may silently reformat quotes and commas.

Step 2: Regenerate the Keymap

NOTE

I always ask Claude to do this for me.

uv run docs/gen_keymap.py docs/keymap_v04.csv > boards/shields/peaky8bit/peaky8bit.keymap

If your host PC uses a Japanese keyboard layout (JIS):

uv run docs/gen_keymap.py docs/keymap_v04.csv --layout jis > boards/shields/peaky8bit/peaky8bit.keymap

The same CSV works for both layouts. The script handles the keycode differences.

Step 3: Push Both Files

NOTE

I usually upload them manually through GitHub’s web interface.

git add docs/keymap_v04.csv boards/shields/peaky8bit/peaky8bit.keymap
git commit -m "swap y and z"
git push

You need both the CSV and the .keymap. The build reads peaky8bit.keymap, so if you forget to include it, nothing will change.

Step 4: Download and Flash

After pushing in Step 3, go to the Actions tab. You’ll likely see a yellow banner or a warning message.

Click the button that says:

I understand my workflows, go ahead and enable them

This enables the repository’s build scripts to run automatically on GitHub. (Specifically: every time you push to this repository, Actions will run and build the firmware.)

The Actions tab showing a recent Action run (in this case, "Add files via upload").
The Actions tab showing a recent Action run (in this case, "Add files via upload").
  1. Open the Actions tab in your forked repository
  2. Wait for the build to finish (a few minutes), then download the artifact
  • Click the Action run, scroll to the bottom, and find the download button in the “Artifacts” section
In the Actions tab of your repository, click on the most recent Action run, scroll to the bottom, and you'll find an "Artifacts" section with a download button.
In the Actions tab of your repository, click on the most recent Action run, scroll to the bottom, and you'll find an "Artifacts" section with a download button.

Next Step: Connect via USB and Flash the MCU (Xiao BLE)

After this, you’ll flash the .uf2 file to the Peaky 8-bit hardware using a USB Type-C cable. Details will be covered in a separate article. Here’s the general idea:

  • Double-tap the XIAO’s RST button quickly to enter bootloader mode
  • Drag and drop the .uf2 file onto the drive that appears

If Something Goes Wrong

Just revert and push again.

git revert HEAD
git push

Or grab a known-good .uf2 from Releases and flash that instead.

Want to Do More?

The CSV supports much more than just swapping characters — symbols, function keys, Bluetooth profile switching, multi-character snippets, and more. The format is documented in comments inside the script itself, so the quickest way is to feed docs/gen_keymap.py to an AI and ask: “What can I put in this CSV?”

Bonus

On the topic of “just ask an AI” — you can even ask it to build a typing practice app from the GitHub repository, and it’ll probably just work.

I had Claude build this typing practice app by:

  1. Handing it the GitHub repo and saying “build a typing app for this quirky keyboard”
  2. It was done in a single prompt.
  3. Bilingual support and minor tweaks took about 2 more prompts.

日本語版

Peaky 8-bit（P8）はZMKを利用してファームウェアを作成しており、そのリポジトリを公開しています。

P8の入手時には、開発者（私、toya）が「今のところ、これが一番、初めて使う人にベスト」と考えたファームウェアのバージョンがMCU（Xiao BLE）に書き込まれており、キーマップ・キーアサインもそのバージョンになっています。

P8を利用していると、ご自身の都合に合わせてキーマップをカスタマイズしたくなってくると思います。 その際には下記の手順を参考にしてください。

チート情報

AIが普及した昨今では、このような手順書の記事がなくとも、上述のリポジトリのURLをAI（ClaudeやChatGPTなど）に渡して

キーマップの変更の仕方を教えて！

と尋ねれば、あっさり

「CSVを希望するキーマップに書き換えてpeaky8bit.keymapを生成してPushするだけだよ！」

と教えてくれると思います。

また、.keymapの生成も、AIに頼めばAI側でpython/uvを実行して生成してくれると思います。 それが一番早いかもしれません。

私もキーマップを変更したくなったときは、Claudeに

「NキーとHキーを入れ替えて！」
（CSVを書き換えて、peaky8bit.keymapを生成して）
（`gen_keymap.py`を実際に実行して）

とお願いして、

  1. Claudeが作ってくれたCSVとkeymapをリポジトリにPushし、
  2. Actionsで自動生成されたuf2（ファームウェア）をDLして、
  3. MCU（Xiao BLE）に書き込んでいるだけ、

という感じで使っています。

ということで、大まかな流れの説明

  1. docs/keymap_v04.csv を書き換える
  2. gen_keymap.py を実行して peaky8bit.keymap を作り直す
  3. 2つのファイルを一緒に commit して push
  4. GitHub Actions が自動で新しいファームウェアをビルド
  5. .uf2 をダウンロードして書き込む

これだけです。

IMPORTANT

.keymap ファイルを直接編集することはありません。

始める前に

  • リポジトリを自分のアカウントに Fork してください。

    • Actions は自分の Fork 上で動きます

  • Actionsを有効化する

    • わかる人は事前に対応してください。
    • 不明な人はこの後の「ステップ４」で解説があります、今は飛ばしてOK。

  • Python を動かす手段：uv が一番ラクです。

    • その他手段：Google Colabなど
    • もっと簡単：AIに頼む。

ステップ1：CSVを編集する

docs/keymap_v04.csv を開きます。 1行が1つのコードに対応しています。

リポジトリ構成とdocs/keymap_v04.csvの中身。hex列とlayer1、with_shift、with_ctrl列がある
リポジトリ構成とdocs/keymap_v04.csvの中身。hex列とlayer1、with_shift、with_ctrl列がある
hex,layer1,with_shift,with_ctrl
0x11,write:a,write:A,keys:LCTRL+A
0x12,write:b,write:B,keys:LCTRL+B

文字を変えたいときは、その文字が書かれている行を探して書き換えるだけです。 hex 列はコードのIDなので、気にしなくて構いません。

たとえば y と z を入れ替えるなら：

- 0x2C,write:y,write:Y,keys:LCTRL+Y
- 0x2D,write:z,write:Z,keys:LCTRL+Z
+ 0x2C,write:z,write:Z,keys:LCTRL+Z
+ 0x2D,write:y,write:Y,keys:LCTRL+Y
現行のZとYの位置。これを入れ替える、というたとえ話。
現行のZとYの位置。これを入れ替える、というたとえ話。

CSVには4列ありますが、hex 列はコードのIDなので気にしなくてOK。 書き換えるのは残りの3列です。

列いつ効くか
layer1通常の入力
with_shiftShift を arm した後
with_ctrlCtrl を arm した後
NOTE

「armする」＝「Ctrl + A」などしたいときに「Ctrl +」のキーマップを先に押す（その後Aのアサインを押下）、という動作のことです 下図のコンボ入力が該当します

Modifier Armのキーマップ
Modifier Armのキーマップ

編集は テキストエディタ を強く推奨します。 Excel で開くとクォートやカンマを勝手に整形されることがあります。

ステップ2：生成し直す

NOTE

私はいつもClaudeに頼んでいます。

uv run docs/gen_keymap.py docs/keymap_v04.csv > boards/shields/peaky8bit/peaky8bit.keymap

PC側が日本語配列（JIS）の場合：

uv run docs/gen_keymap.py docs/keymap_v04.csv --layout jis > boards/shields/peaky8bit/peaky8bit.keymap

CSV はどちらでも同じものを使います。 キーコードの違いはスクリプト側で吸収されます。

ステップ3：2つのファイルを push

NOTE

私はいつもブラウザ版のGitHubのリポジトリに手動でアップロードしています。

git add docs/keymap_v04.csv boards/shields/peaky8bit/peaky8bit.keymap
git commit -m "swap y and z"
git push

CSVと.keymapの両方が「必要」です。 ビルドが読むのは peaky8bit.keymap の方なので、これを入れ忘れると何も変わりません。

ステップ4：ダウンロードして書き込む

ここで、前述の「ステップ3」を実行し、Actionsタブに移動すると、黄色いバナーが出ているか、警告コメントのようなものが出ると思います。

I understand my workflows, go ahead and enable them

と書かれたボタンを押してください。 すると、自動でリポジトリ内のスクリプトが、GitHub上で実行されるようになります。 （具体的には：このリポジトリにPushが走ると、都度Actionsが実行され、以下の挙動が走ります）

Actionsのタブと、直近の実行したてのAction（この場合は"Add files via upload"が当該。）
Actionsのタブと、直近の実行したてのAction（この場合は"Add files via upload"が当該。）
  1. Fork した自分のリポジトリの Actions タブを開く
  2. ビルド完了を待って（数分）、成果物をダウンロード
  • 実行したActionをクリック ⇒ 一番下に行く ⇒ “Artifacts”内にDLボタンがある
手元のリポジトリのActionsにて、直近の実行したばかりのActionをクリック⇒一番下に行くと、"Artifacts"というセクションがありDLできるボタンがある。
手元のリポジトリのActionsにて、直近の実行したばかりのActionをクリック⇒一番下に行くと、"Artifacts"というセクションがありDLできるボタンがある。

次のステップ：MCU（Xiao BLE）にUSB接続して書き込む

このあと、USB Type-Cを利用してPeaky 8-bit本体に入手した.uf2を書き込みます。 こちらは次の記事にて詳細を説明します。 大方の流れとしてはこんな感じになります。

  • XIAO の RST を素早く2回タップしてブートローダーモードに入る
  • 出てきたドライブに .uf2 をドラッグ&ドロップ

うまくいかないとき

戻して push し直せば大丈夫です。

git revert HEAD
git push

または Releases から動いていた .uf2 を取ってきて書き戻してください。

もっと凝ったことをしたい人へ

CSV では文字の入れ替え以外にも、記号・ファンクションキー・Bluetoothプロファイル切り替え・複数文字のスニペットなど、いろいろ書けます。 書式はスクリプト自体にコメントとして書いてあるので、docs/gen_keymap.py を AI に読ませて「このCSVには何が書ける？」と聞くのが手っ取り早いです。

おまけ

「AIにお願いする」という点で、例えば「タイピングアプリを作って」というのもGitHubリポジトリをAIに渡せば簡単にできてしまうと思います。 私もこちらのタイピング練習用アプリを、

  1. GitHubリポジトリを伝えて「このちょっと変わったキーボード用のタイピングアプリを作って欲しい」と頼む
  2. シングルプロンプトでできてしまった。
  3. ２言語対応や細かい部分の微修正を依頼するのに2プロンプトほど追加

という感じでClaudeに作ってもらえました。

👍/ Like

user-guide