diff options
| -rw-r--r-- | docs/_langs.md | 1 | ||||
| -rw-r--r-- | docs/index.html | 2 | ||||
| -rw-r--r-- | docs/ja/newbs.md | 40 | ||||
| -rw-r--r-- | docs/ja/newbs_best_practices.md | 168 | ||||
| -rw-r--r-- | docs/ja/newbs_building_firmware.md | 98 | ||||
| -rw-r--r-- | docs/ja/newbs_building_firmware_configurator.md | 112 | ||||
| -rw-r--r-- | docs/ja/newbs_flashing.md | 399 | ||||
| -rw-r--r-- | docs/ja/newbs_getting_started.md | 121 | ||||
| -rw-r--r-- | docs/ja/newbs_learn_more_resources.md | 31 | ||||
| -rw-r--r-- | docs/ja/newbs_testing_debugging.md | 106 |
10 files changed, 1078 insertions, 0 deletions
diff --git a/docs/_langs.md b/docs/_langs.md index 7a7f127a97..b318687d04 100644 --- a/docs/_langs.md +++ b/docs/_langs.md @@ -5,3 +5,4 @@ - [:fr: Français](/fr-fr/) - [:he: עברית](/he-il/) - [:ru: Русский](/ru-ru/) + - [:ja: 日本語](/ja/) diff --git a/docs/index.html b/docs/index.html index 0cee19ecd6..d2ba99897c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -41,11 +41,13 @@ placeholder: { '/es/': 'Buscar', '/zh-cn/': '搜索', + '/ja/': '検索', '/': 'Search' }, noData: { '/es/': '¡Ningún resultado!', '/zh-cn/': '没有结果!', + '/ja/': '見つかりません!', '/': 'No results!' }, depth: 6 diff --git a/docs/ja/newbs.md b/docs/ja/newbs.md new file mode 100644 index 0000000000..ec6e278eec --- /dev/null +++ b/docs/ja/newbs.md @@ -0,0 +1,40 @@ +# QMK 初心者ガイド + +<!--- + original document: ed0575fc8:docs/newbs.md + $ git diff ed0575fc8 HEAD docs/newbs.md +--> + +QMK は、メカニカルキーボード用の強力なオープンソースファームウェアです。 +QMK を使用して、シンプルかつ強力な方法でキーボードをカスタマイズできます。 +完全な初心者からプログラマーに至るまで、あらゆるスキルレベルの人々が QMK を使用してキーボードをカスタマイズしています。 +このガイドは、あなたのスキルにかかわらず、同じことを行う手助けをします。 + +お使いのキーボードで QMK を実行できるかどうか不明ですか？ +もし作成したキーボードがメカニカルキーボードの場合、実行できる可能性が高いです。 +QMK は[多くの趣味のキーボード](http://qmk.fm/keyboards/)をサポートしているため、もし現在のキーボードで QMK を実行できない場合でも、ニーズに合ったキーボードを見つけるのに問題はないはずです。 + +## 概要 + +このガイドには7つの主要なセクションがあります。 + +* [はじめに](newbs_getting_started.md) +* [コマンドラインを使用して初めてのファームウェアを構築する](newbs_building_firmware.md) +* [オンライン GUI を使用して初めてのファームウェアを構築する](newbs_building_firmware_configurator.md) +* [ファームウェアを書きこむ](newbs_flashing.md) +* [テストとデバッグ](newbs_testing_debugging.md) +* [Git の最良の慣行](newbs_best_practices.md) +* [さらに学ぶための学習リソース](newbs_learn_more_resources.md) + +このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。 +その観点から選択と推奨を行います。 +これらの手順の多くには代替方法があり、これらの代替方法のほとんどをサポートしています。 +タスクを達成する方法について疑問がある場合は、[案内を求めることができます](getting_started_getting_help.md)。 + +## 追加のリソース(英語) + +* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 新規ユーザ視点から見た QMK ファームウェアの基本的な使用方法をカバーしたユーザ作成のブログ。 + +## 追加のリソース(日本語) + +_日本語のリソース情報を募集中です。_ diff --git a/docs/ja/newbs_best_practices.md b/docs/ja/newbs_best_practices.md new file mode 100644 index 0000000000..ebb7d0fabe --- /dev/null +++ b/docs/ja/newbs_best_practices.md @@ -0,0 +1,168 @@ +# Best Practices + +<!--- + original document: ed0575fc8:docs/newbs_best_practices.md + $ git diff ed0575fc8 HEAD docs/newbs_best_practices.md +--> + +## Or, "How I Learned to Stop Worrying and Love Git." + +This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. + +This document assumes a few things: + +1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. +2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). + + +## Your fork's master: Update Often, Commit Never + +It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. + +To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. + +### Updating your master branch + +To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +To verify that the repository has been added, run `git remote -v`, which should return the following: + +``` +$ git remote -v +origin https://github.com/<your_username>/qmk_firmware.git (fetch) +origin https://github.com/<your_username>/qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags — collectively referred to as "refs" — from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. + +To update your fork's master, run the following, hitting the Enter key after each line: + +``` +git checkout master +git fetch upstream +git pull upstream master +git push origin master +``` + +This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. + +### Making Changes + +To make changes, create a new branch by entering: + +``` +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. + +!> With `git push`, you can use `-u` in place of `--set-upstream` — `-u` is an alias for `--set-upstream`. + +You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. + +By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: + +``` +git checkout -b dev_branch master +``` + +Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: + +``` +git add path/to/updated_file +git commit -m "My commit message." +``` + +`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. + +!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. + +### Publishing Your Changes + +The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. + + +## Resolving Merge Conflicts + +Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. + +### Rebasing Your Changes + +A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. + +To start, run the following: + +``` +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: + +``` +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. + +Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: + +``` +git rebase upstream/master +``` + +This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. + +``` +$ git rebase upstream/master +First, rewinding head to replay your work on top of it... +Applying: Commit #1 +Using index info to reconstruct a base tree... +M conflicting_file_1.txt +Falling back to patching base and 3-way merge... +Auto-merging conflicting_file_1.txt +CONFLICT (content): Merge conflict in conflicting_file_1.txt +error: Failed to merge in the changes. +hint: Use 'git am --show-current-patch' to see the failed patch +Patch failed at 0001 Commit #1 + +Resolve all conflicts manually, mark them as resolved with +"git add/rm <conflicted_files>", then run "git rebase --continue". +You can instead skip this commit: run "git rebase --skip". +To abort and get back to the state before "git rebase", run "git rebase --abort". +``` + +This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: + +``` +<<<<<<< HEAD +<p>For help with any issues, email us at support@webhost.us.</p> +======= +<p>Need help? Email support@webhost.us.</p> +>>>>>>> Commit #1 +``` + +The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. + +Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. + +``` +<p>Need help? Email support@webhost.us.</p> +``` + +Now run: + +``` +git add conflicting_file_1.txt +git rebase --continue +``` + +Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. diff --git a/docs/ja/newbs_building_firmware.md b/docs/ja/newbs_building_firmware.md new file mode 100644 index 0000000000..32a7903fd4 --- /dev/null +++ b/docs/ja/newbs_building_firmware.md @@ -0,0 +1,98 @@ +# 初めてのファームウェアを構築する(コマンドライン版) + +<!--- + original document: ed0575fc8:docs/newbs_building_firmware.md + $ git diff ed0575fc8 HEAD docs/newbs_building_firmware.md +--> + +ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。 +ガイドのこのセクションでは、ファイルマネージャ、テキストエディタ、ターミナルウィンドウの3つのプログラム間を行き来します。 +キーボードファームウェアが完成して満足するまで、この3つすべてを開いたままにします。 + +ガイドの最初の部分を読んだ後でターミナルウィンドウを閉じて再度開いていた場合は、ターミナルが正しいディレクトリにあるように `cd qmk_firmware` を忘れないでください。 + +## キーマップフォルダに移動する + +あなたのキーボードの `keymaps`フォルダに移動することから始めます。 + +macOS または Windows を使用している場合は、キーマップフォルダを簡単に開くために使用できるコマンドがあります。 + +### macOS: + +``` open keyboards/<keyboard_folder>/keymaps ``` + +### Windows: + +``` start .\\keyboards\\<keyboard_folder>\\keymaps ``` + +## `default` キーマップのコピーを作成する + +`keymaps` フォルダを開いたら、`default`フォルダのコピーを作成します。 +フォルダには、あなたの GitHub でのユーザー名と同じ名前を付けることを強くお勧めしますが、小文字、数字、アンダースコアのみが含まれている限り、任意の名前を使用できます。 + +この手順を自動化するために、`new_keymap.sh`スクリプトを実行する方法もあります。 + +`qmk_firmware/util` ディレクトリに移動して、次を入力します。 + +``` +./new_keymap.sh <keyboard path> <username> +``` + +たとえば、John という名前のユーザーが 1up60hse の新しいキーマップを作成しようとするには、次のように入力します。 + +``` +./new_keymap.sh 1upkeyboards/1up60hse john +``` + +## あなたの好みのテキストエディタで `keymap.c` を開く + +`keymap.c`を開きます。 +このファイル内には、キーボードの動作を制御する構造があります。 +`keymap.c`の上部には、キーマップを読みやすくする `define` と `enum` があります。 +さらに下には、次のような行があります。 + + const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + +この行はレイヤーのリストの開始を表わしています。 +その下には、`LAYOUT` または `KEYMAP` のいずれかを含む行があり、これらの行はレイヤーの開始を表わしています。 +その行の下には、その特定のレイヤーを構成するキーのリストがあります。 + +!> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。 + +## 好みに合わせてレイアウトをカスタマイズ + +納得のいくまでこのステップを繰り返します。 +気になる点をひとつづつ変更して試すのもよし、全部作りなおすのもよし。 +あるレイヤー全体が必要ない場合はレイヤーを削除することもでき、必要があれば、合計 32 個までレイヤーを追加することもできます。 +ここで定義できる内容については、次のドキュメントを参照してください。 + +* [キーコード](keycodes.md) +* [機能](features.md) +* [FAQ](faq.md) + +?> キーマップがどのように機能するかを感じながら、各変更を小さくしてください。大きな変更は、発生する問題のデバッグを困難にします。 + +## ファームウェアをビルドする + +キーマップの変更が完了したら、ファームウェアをビルドする必要があります。これを行うには、ターミナルウィンドウに戻り、ビルドコマンドを実行します: + + make <my_keyboard>:<my_keymap> + +たとえば、キーマップの名前が "xyverz" で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します: + + make planck/rev5:xyverz + +これがコンパイルされる間、どのファイルがコンパイルされているかを知らせる多くの出力が画面に表示されます。 +次のような出力で終わるはずです。 + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex [OK] + * File size is fine - 18392/28672 +``` + +## ファームウェアを書きこむ + +[「ファームウェアを書きこむ」](newbs_flashing.md) に移動して、キーボードに新しいファームウェアを書き込む方法を学習します。 diff --git a/docs/ja/newbs_building_firmware_configurator.md b/docs/ja/newbs_building_firmware_configurator.md new file mode 100644 index 0000000000..0716e26ea9 --- /dev/null +++ b/docs/ja/newbs_building_firmware_configurator.md @@ -0,0 +1,112 @@ +# QMK Configurator + +<!--- + original document: ed0575fc8:docs/newbs_building_firmware_configurator.md + $ git diff ed0575fc8 HEAD docs/newbs_building_firmware_configurator.md +--> + +[QMK Configurator](https://config.qmk.fm) は、QMKファームウェアの hex ファイルを生成するオンライングラフィカルユーザーインターフェイスです。 + +?> **次の手順を順番に実行してください。** + +[Video Tutorial](https://youtu.be/tx54jkRC9ZY) を見てください。 + +QMK Configurator は Chrome/Firefox で最適に動作します。 + +!> **KLE や kbfirmware などの他のツールのファイルは、QMK Configurator と互換性がありません。それらをロードしたり、インポートしたりしないでください。QMK Configurator は異なるツールです。** + +## キーボードを選ぶ + +ドロップダウンボックスをクリックして、キーマップを作成するキーボードを選択します。 + +?> **キーボードに複数のバージョンがある場合は、正しいバージョンを選択してください。** + +大事なことなのでもう一度言います。 + +!> **正しいバージョンを選択してください!** + +キーボードが QMK を搭載していると宣伝されていてもリストにない場合は、開発者がまだ作業中か、私たちがまだマージするきっかけがなかった可能性があります。 +アクティブな [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) がない場合、[qmk_firmware](https://github.com/qmk/qmk_firmware/issues)で報告して、その特定のキーボードのサポートをリクエストします。 +製作者自身の github アカウントにある QMK 搭載キーボードもあります。 +それも再確認してください。 + +## キーボードのレイアウトを選択する + +作成したいと思うキーマップに最も近いレイアウトを選択します。一部のキーボードには、まだ十分なレイアウトまたは正しいレイアウトが定義されていません。これらは将来サポートされる予定です。 + +## キーマップの名前 + +お好みの名前をキーマップにつけます。 + +?> コンパイル時に問題が発生した場合は、もしかすると QMK ファームウェアリポジトリに既に同じ名前が存在しているのかもしれません、名前を変更してみてください。 + +## キーマップを作る + +キーコード入力は3つの方法で実行できます。 +1. ドラッグ・アンド・ドロップ +2. レイアウト上の空の場所をクリックして、希望するキーコードをクリックします +3. レイアウト上の空の場所をクリックして、キーボードの物理キーを押します + +マウスをキーの上に置くと、そのキーコードの機能の短い説明文が出ます。より詳細な説明については以下を見てください。 + +[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic) +[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes) + +キーマップをサポートするレイアウトが見つからない場合、例えばスペースバーが3分割されていたり、バックスペースが2分割されていたり、シフトが2分割されているような場合、それらを全て埋めてください。 + +### 例: + +3分割のスペースバー: 全てスペースバーで埋めます。 + +2分割のバックスペース: 両方ともバックスペースで埋めます。 + +2分割の右シフト: 両方とも右シフトで埋めます。 + +左シフトとISOサポート用に1つずつ: 両方とも左シフトで埋めます。 + +5分割だが4キーのみ: 以前やったことがある人を推測して確認するか尋ねてください。 + +## 後日のためにキーマップを保存する + +キーマップに満足するか、または後で作業したい場合は、`Export Keymap' ボタンを押します。上記で選択した名前に .json が追加されたキーマップが保存されます。 + +後日、`Import Keymap` ボタンを押すことで、この .json ファイルをロードできます。 + +!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .jsonファイルと同じ形式ではありません。これらのツールにこれを使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、キーボードが **爆発** する可能性があります。 + +## ファームウェアファイルを生成する + +緑色の `Compile` ボタンを押します。 + +コンパイルが完了すると、緑色の `Download Firmware` ボタンを押すことができます。 + +## キーボードに書き込む(フラッシュする) + +[ファームウェアを書きこむ](newbs_flashing.md) を参照してください。 + +## トラブルシューティング + +#### 私の .json ファイルが動きません + +.json ファイルが QMK Configurator で作ったものの場合、おめでとうございます。バグに遭遇しました。 [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。 + +そうでない場合は、... 他の .json ファイルを使用しないようにという、上に書いた注意書きを見逃してませんか？ + +#### レイアウトに余分なスペースがありますか？どうすればいいですか？ + +もしスペースバーが3つに分かれている場合は、全てスペースバーで埋めるのが最善の方法です。バックスペースやシフトについても同じことができます。 + +#### キーコードってなに？ + +以下を見てください。 + +[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic) +[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes) + +#### コンパイルできません + +キーマップの他のレイヤーを再確認して、ランダムなキーが存在しないことを確認してください。 + +## 問題とバグ + +私たちは利用者の依頼やバグレポートを常に受け入れています。[qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。 diff --git a/docs/ja/newbs_flashing.md b/docs/ja/newbs_flashing.md new file mode 100644 index 0000000000..54569e1225 --- /dev/null +++ b/docs/ja/newbs_flashing.md @@ -0,0 +1,399 @@ +# ファームウェアを書きこむ + +<!--- + original document: ed0575fc8:docs/newbs_flashing.md + $ git diff ed0575fc8 HEAD docs/newbs_flashing.md +--> + +カスタムファームウェアは出来たので、キーボードに書き込みたくなるでしょう/フラッシュしたくなるでしょう。 + +## QMK Toolbox を使ってキーボードに書き込む + +キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。 + +ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。 +Linuxを使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](newbs_flashing.md#コマンドラインでファームウェアを書き込む)で行なう必要があります。 + +### QMK Toolbox にファイルをロードする + +まず QMK Toolbox アプリケーションを起動します。 +Finder またはエクスプローラーでファームウェアのファイルを探します。 +ファイル名は `.hex` または `.bin` のどちらかの形式です。 +ビルド時に QMK は、キーボードに適した形式のものを `qmk_firmware` のトップフォルダにコピーしているはずです。 + +Windows か macOS を使用しているときは現在のファームウェアフォルダをエクスプローラーか Finder で簡単に開くためのコマンドがあります。 + +#### Windows + +``` +start . +``` + +#### macOS + +``` +open . +``` + +ファームウェアファイルは常に以下の命名形式に従っています。 + +``` +<keyboard_name>_<keymap_name>.{bin,hex} +``` + +例えば、`plank/rev5` の `default` キーマップのファイル名は以下のようになります。 + +``` +planck_rev5_default.hex +``` + +ファームウェアファイルを見つけたら、QMK Toolbox の "Local file" ボックスにドラッグするか、"Open" をクリックしてファームウェアファイルを指定します。 + +### キーボードを DFU (Bootloader) モードにする + +ファームウェアを書き込むには、キーボードを普段とは違う特別な状態、フラッシュモードにする必要があります。 +このモードでは、キーボードはキーボードとしての機能をはたしません。 +ファームウェアの書き込み中にキーボードのケーブルを抜いたり、書き込みプロセスを中断したりしないことが非常に重要です。 + +キーボードによって、この特別なモードに入る方法は異なります。 +キーボードが現在 QMK または TMK を実行しており、キーボードメーカーから具体的な指示が与えられていない場合は、次を順番に試してください。 + +* 両方のシフトキーを押しながら、`Pause` キーを押す +* 両方のシフトキーを押しながら、`B` キーを押す +* キーボードのケーブルを抜いて、スペースバーとBを同時に押しながら、キーボードを再び接続し、1秒待ってからキーを放す +* 基板(PCB)に付けられている物理的な `RESET` ボタンを押す +* PCB 上の `BOOT0` か `RESET` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする + +うまくいけば、QMK Toolboxに次のようなメッセージが表示されます。 + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### キーボードへの書き込み + +QMK Toolbox の `Flash` ボタンをクリックします。 +次のような出力が表示されます。 + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset + +*** DFU device disconnected +*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 +``` + +## コマンドラインでファームウェアを書き込む + +これは、以前のものと比較して非常に単純になりました。 +ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:flash + +たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。 + + make planck/rev5:xyverz:flash + +これにより、キーボードの構成が確認され、指定されたブートローダに基づいてキーボードへの書き込みが試行されます。 +これはあなたがキーボードが使用するブートローダを知る必要がないことを意味します。 +コマンドをただ実行して、コマンド自身に難しい処理を任せます。 + +ただし、これはキーボードごとに設定されているブートローダに依存します。 +もしこの情報が設定されていない場合、または使用しているキーボードのファームウェアの書き込みにサポートしていないターゲットが設定されている場合、次のエラーが表示されます。 + + WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. + +この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。 + +ブートローダは主に 5 種類のものが使われています。 +Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKBの AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。 + +より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](flashing.md) にあります。 + +使用しているブートローダがわかっているならば、ファームウェアをコンパイルするときに、実は `make` コマンドにブートローダを指定するテキストを追加して、書き込みプロセスを自動化できます。 + +### DFU + +DFU ブートローダの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:dfu + +たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。 + + make planck/rev5:xyverz:dfu + +コンパイルが終了すると、以下の出力になるはずです。 + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex + * File size is fine - 18574/28672 + ``` + +ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。 +デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。 + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +これを実行したら、コントローラーをリセットする必要があります。 +そして下のような出力が表示されます。 + +``` +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset +``` + +?> `dfu-programmer：no device present` など、これに関する問題がある場合は、[よくある質問](faq_build.md) を参照してください。 + +#### DFU コマンド + +ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:dfu` - これが通常のオプションで、DFUデバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFUデバイスが存在するかチェックしています。 +* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。 +* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROMファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_ +* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROMファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_ + + +### Caterina + +Arduino ボードとそれらのクローンの場合(たとえば SparkFun ProMicro)、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。 + + make <my_keyboard>:<my_keymap>:avrdude + +たとえば、キーマップの名前が xyverz で、rev2 Lets Split のキーマップを作成している場合、次のコマンドを使用します。 + + make lets_split/rev2:xyverz:avrdude + +ファームウェアのコンパイルが完了すると、以下のように出力されます。 + +``` +Linking: .build/lets_split_rev2_xyverz.elf [OK] +Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] +Checking file size of lets_split_rev2_xyverz.hex [OK] + * File size is fine - 27938/28672 +Detecting USB port, reset your controller now.............. +``` + +この時点で、キーボードをリセットすると、スクリプトがブートローダを検出し、キーボードに書き込みます。出力は次のようになります。 + +``` +Detected controller on USB port at /dev/ttyS15 + +Connecting to programmer: . +Found programmer: Id = "CATERIN"; type = S + Software Version = 1.0; No Hardware Version given. +Programmer supports auto addr increment. +Programmer supports buffered memory access with buffersize=128 bytes. + +Programmer supports the following devices: + Device code: 0x44 + +avrdude.exe: AVR device initialized and ready to accept instructions + +Reading | ################################################## | 100% 0.00s + +avrdude.exe: Device signature = 0x1e9587 (probably m32u4) +avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed + To disable this feature, specify the -D option. +avrdude.exe: erasing chip +avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: writing flash (27938 bytes): + +Writing | ################################################## | 100% 2.40s + +avrdude.exe: 27938 bytes of flash written +avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes +avrdude.exe: reading on-chip flash data: + +Reading | ################################################## | 100% 0.43s + +avrdude.exe: verifying ... +avrdude.exe: 27938 bytes of flash verified + +avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) + +avrdude.exe done. Thank you. +``` +うまくいかない時は、以下のようにする必要があるかもしれません。 + + sudo make <my_keyboard>:<my_keymap>:avrdude + + +#### Caterina コマンド + +ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。 + +* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。 +* `:avrdude-loop` - これは `:avrdude` と同じです。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへの書き込みに便利です。_Control+C を押して、手動でこの繰り返しを終了させる必要があります。_ |