diff --git a/docs/ja/hardware_avr.md b/docs/ja/hardware_avr.md new file mode 100644 index 000000000000..6eb86a378673 --- /dev/null +++ b/docs/ja/hardware_avr.md @@ -0,0 +1,189 @@ +# AVR マイコンを使ったキーボード + + + +このページでは QMK における AVR マイコンのサポートについて説明します。AVR マイコンには、Atmel 社製の atmega32u4、atmega32u2、at90usb1286 やその他のマイコンを含みます。AVR マイコンは、簡単に動かせるよう設計された8ビットの MCU です。キーボードでよく使用される AVR マイコンには USB 機能や大きなキーボードマトリックスのためのたくさんの GPIO を搭載しています。これらは、現在、キーボードで使われる最も一般的な MCU です。 + +まだ読んでない場合は、[キーボードガイドライン](ja/hardware_keyboard_guidelines.md) を読んで、キーボードを QMK にどのように適合させるかを把握する必要があります。 + +## AVR を使用したキーボードを QMK に追加する + +QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`util/new_keyboard.sh` スクリプトを実行します。 + +``` +$ ./util/new_keyboard.sh +Generating a new QMK keyboard directory + +Keyboard Name: mycoolkb +Keyboard Type [avr]: +Your Name [John Smith]: + +Copying base template files... done +Copying avr template files... done +Renaming keyboard files... done +Replacing %KEYBOARD% with mycoolkb... done +Replacing %YOUR_NAME% with John Smith... done + +Created a new keyboard called mycoolkb. + +To start working on things, cd into keyboards/mycoolkb, +or open the directory in your favourite text editor. +``` + +これにより、新しいキーボードをサポートするために必要なすべてのファイルが作成され、デフォルト値で設定が入力されます。あとはあなたのキーボード用にカスタマイズするだけです。 + +## `readme.md` + +このファイルではキーボードに関する説明を記述します。[キーボード Readme テンプレート](ja/documentation_templates.md#keyboard-readmemd-template)に従って `readme.md` を記入して下さい。`readme.md` の上部に画像を配置することをお勧めします。画像は [Imgur](http://imgur.com) のような外部サービスを利用してください。 + +## `.c` + +このファイルではキーボード上で実行される全てのカスタマイズされたロジックを記述します。多くのキーボードの場合、何も書く必要はありません。 +[機能のカスタマイズ](ja/custom_quantum_functions.md)で、カスタマイズされたロジックの記述方法を詳しく学ぶことが出来ます。 + +## `.h` + +このファイルでは、[レイアウト](ja/feature_layouts.md)を定義します。最低限、以下のような `#define LAYOUT` を記述する必要があります。 + +```c +#define LAYOUT( \ + k00, k01, k02, \ + k10, k11 \ +) { \ + { k00, k01, k02 }, \ + { k10, KC_NO, k11 }, \ +} +``` + +`LAYOUT` マクロの前半部ではキーの物理的な配置を定義します。後半部ではスイッチが接続されるマトリックスを定義します。これによってマトリックス配線の順とは異なるキーを物理的に配置できます。 + +それぞれの `k__` 変数はユニークでなければいけません。通常は `k` というフォーマットに従って記述されます。 + +物理マトリックス（後半部）では、`MATRIX_ROWS` に等しい行数が必要であり、各行には正確に `MATRIX_COLS` と等しい数の要素が含まれていなければいけません。物理キーが存在しない場合は、`KC_NO` を使用して空白を埋める事ができます。 + +## `config.h` + +`config.h` ファイルには、ハードウェアや機能の設定を記述します。このファイルで設定できるオプションは列挙しきれないほどたくさんあります。利用できるオプションの概要は[設定オプション](ja/config_options.md)を参照して下さい。 + +### ハードウェアの設定 + +`config.h` の先頭には USB に関する設定があります。これらはキーボードが OS からどのように見えるかを制御しています。変更する理由がない場合は、`VENDOR_ID` を `0xFEED` のままにしておく必要があります。`PRODUCT_ID` にはまだ使用されていない番号を選ばなければいけません。 + +`MANUFACTURER`、 `PRODUCT`、 `DESCRIPTION` をキーボードにあった設定に変更します。 + +```c +#define VENDOR_ID 0xFEED +#define PRODUCT_ID 0x6060 +#define DEVICE_VER 0x0001 +#define MANUFACTURER You +#define PRODUCT my_awesome_keyboard +#define DESCRIPTION A custom keyboard +``` + +?> Windows や macOS では、`MANUFACTURER` と `PRODUCT` が USBデバイスのリストに表示されます。Linux 上の `lsusb` では、代わりにデフォルトで [USB ID Repository](http://www.linux-usb.org/usb-ids.html) によって維持されているリストからこれらを取得します。`lsusb -v` を使用するとデバイスから示された値を表示します。また、接続したときのカーネルログにも表示されます。 + +### キーボードマトリックスの設定 + +`config.h` ファイルの次のセクションではキーボードのマトリックスを扱います。最初に設定するのはマトリックスのサイズです。これは通常、常にではありませんが、物理キー配置と同じ数の行・列になります。 + +```c +#define MATRIX_ROWS 2 +#define MATRIX_COLS 3 +``` + +マトリックスのサイズを定義したら、MCU のどのピンを行と列に接続するかを定義します。そのためにはピンの名前を指定するだけです。 + +```c +#define MATRIX_ROW_PINS { D0, D5 } +#define MATRIX_COL_PINS { F1, F0, B0 } +#define UNUSED_PINS +``` + + +`MATRIX_ROW_PINS` の要素の数は `MATRIX_ROWS` に定義した数と同じでなければいけません。同様に `MATRIX_COL_PINS` の要素の数も `MATRIX_COLS` と等しい必要があります。`UNUSED_PINS` は定義しなくても問題ありませんがどのピンが空いているのか記録しておきたい場合は定義できます。 + +最後にダイオードの方向を定義します。これには `COL2ROW` か `ROW2COL` を設定します。 + +```c +#define DIODE_DIRECTION COL2ROW +``` + +#### ダイレクトピンマトリックス + +各スイッチが、列と行のピンを共有する代わりに、それぞれ個別のピンとグランドに接続されているキーボードを定義するには、`DIRECT_PINS` を使用します。マッピング定義では、列と行の各スイッチのピンを左から右の順に定義します。`MATRIX_ROWS` と `MATRIX_COLS` 内のサイズに準拠する必要があり、空白を埋めるには `NO_PIN` を使用します。これによって `DIODE_DIRECTION`、`MATRIX_ROW_PINS`、`MATRIX_COL_PINS` の動作を上書きします。 + +```c +// #define MATRIX_ROW_PINS { D0, D5 } +// #define MATRIX_COL_PINS { F1, F0, B0 } +#define DIRECT_PINS { \ + { F1, E6, B0, B2, B3 }, \ + { F5, F0, B1, B7, D2 }, \ + { F6, F7, C7, D5, D3 }, \ + { B5, C6, B6, NO_PIN, NO_PIN } \ +} +#define UNUSED_PINS + +/* COL2ROW, ROW2COL */ +//#define DIODE_DIRECTION +``` + +### バックライトの設定 + +QMK では GPIO ピンでのバックライト制御をサポートしています。これらの設定を選択して MCU から制御できます。詳しくは[バックライト](ja/feature_backlight.md)を参照して下さい。 + +```c +#define BACKLIGHT_PIN B7 +#define BACKLIGHT_LEVELS 3 +#define BACKLIGHT_BREATHING +#define BREATHING_PERIOD 6 +``` + +### その他の設定オプション + +`config.h` で設定・調整できる機能はたくさんあります。詳しくは[設定オプション](ja/config_options.md)を参照して下さい。 + +## `rules.mk` + +`rules.mk` ファイルを使用して、ビルドするファイルや有効にする機能をQMKへ指示します。atmega32u4 を使っている場合、これらのオプションはデフォルトのままにしておくことが出来ます。他の MCU を使用している場合はいくつかのパラメータを調整する必要があります。 + +### MCU オプション + +このオプションではビルドする CPU をビルドシステムに指示します。これらの設定を変更する場合は非常に注意して下さい。キーボードを操作不能にしてしまう可能性があります。 + +```make +MCU = atmega32u4 +F_CPU = 16000000 +ARCH = AVR8 +F_USB = $(F_CPU) +OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT +``` + +### ブートローダー + +ブートローダーは MCU に保存されているプログラムをアップグレードするための特別なセクションです。キーボードのレスキューパーティションのようなものだと考えて下さい。 + +#### Teensy Bootloader の例 + +```make +BOOTLOADER = halfkay +``` + +#### Atmel DFU Loader の例 + +```make +BOOTLOADER = atmel-dfu +``` + +#### Pro Micro Bootloader の例 + +```make +BOOTLOADER = caterina +``` + +### ビルドオプション + +`rules.mk` にはオン・オフできるたくさんの機能があります。詳細なリストと説明は[設定オプション](ja/config_options.md#feature-options)を参照して下さい。 diff --git a/docs/ja/hardware_drivers.md b/docs/ja/hardware_drivers.md new file mode 100644 index 000000000000..cc85589e7b25 --- /dev/null +++ b/docs/ja/hardware_drivers.md @@ -0,0 +1,45 @@ +# QMK ハードウェアドライバー + + + +QMK はたくさんの異なるハードウェアで使われています。最も一般的な MCU とマトリックス構成をサポートしていますが、キーボードへ他のハードウェアを追加し制御するためのドライバーもいくつか用意されています。例えば、マウスやポインティングデバイス、分割キーボード用の IO エキスパンダ、Bluetooth モジュール、LCD、OLED、TFT 液晶などがあります。 + + + +# 使用できるドライバー + +## ProMicro (AVR のみ) + +ProMicro のピンを AVR の名前ではなく、Arduino の名前で指定できます。この部分はより詳しく文書化される必要があります。もしこれを使用したい場合にコードを読んでも分からない場合、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new)を通して助けることができるかもしれません。 + +## SSD1306 OLED ドライバー + +SSD1306 ベースの OLED ディスプレイのサポート。詳しくは[OLED ドライバ](ja/feature_oled_driver.md)を参照して下さい。 + +## uGFX + +QMK 内で uGFX を使用して、キャラクタ LCD やグラフィック LCD、LED アレイ、OLED ディスプレイ、TFT 液晶や他のディスプレイを制御できます。この部分はより詳しく文書化される必要があります。もしこれを使用したい場合にコードを読んでも分からない場合、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new)を通して助けることができるかもしれません。 + +## WS2812 + +WS2811/WS2812{a,b,c} LED のサポート。 詳しくは [RGB ライト](ja/feature_rgblight.md)を参照して下さい。 + +## IS31FL3731 + +最大2つの LED ドライバーのサポート。各ドライバーは、I2C を使って個別に LED を制御する2つのチャーリープレクスマトリックスを実装しています。最大144個の単色 LED か32個の RGB LED を使用できます。ドライバーの設定方法の詳細は[RGB マトリックス](ja/feature_rgb_matrix.md)を参照して下さい。 + +## IS31FL3733 + +拡張の余地がある最大1つの LED ドライバーのサポート。各ドライバーは192個の単色 LED か64個の RGB LED を制御できます。ドライバーの設定方法の詳細は [RGB マトリックス](ja/feature_rgb_matrix.md)を参照して下さい。 + +## 24xx シリーズ 外部 I2C EEPROM + +オンチップ EEPROM の代わりに使用する I2C ベースの外部 EEPROM のサポート。ドライバーの設定方法の詳細は [EEPROM ドライバー](ja/eeprom_driver.md)を参照して下さい。 diff --git a/docs/ja/hardware_keyboard_guidelines.md b/docs/ja/hardware_keyboard_guidelines.md new file mode 100644 index 000000000000..5a9de52ef42f --- /dev/null +++ b/docs/ja/hardware_keyboard_guidelines.md @@ -0,0 +1,155 @@ +# QMK キーボードガイドライン + + + +QMK は開始以来、コミュニティにおけるキーボードの作成や保守に貢献しているあなたのような人たちのおかげで飛躍的に成長しました。私たちが成長するにつれて、うまくやるためのいくつかのパターンを発見しました。他の人たちがあなたの苦労の恩恵を受けやすくするため、それにあわせてもらえるようお願いします。 + +## あなたのキーボード/プロジェクトの名前を決める + +キーボードの名前は全て小文字で、アルファベット、数字、アンダースコア(`_`)のみで構成されています。アンダースコア(`_`)で始めてはいけません。スラッシュ(`/`)はサブフォルダの区切り文字として使用されます。 + +`test`、`keyboard`、`all` はmakeコマンド用に予約されており、キーボードまたはサブフォルダ名として使用することは出来ません。 + +正しい例: + +* `412_64` +* `chimera_ortho` +* `clueboard/66/rev3` +* `planck` +* `v60_type_r` + +## サブフォルダ + +QMK では、まとめるためや同じキーボードのリビジョン間でコードを共有するためにサブフォルダを使用します。フォルダは最大4階層までネストできます。 + + qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4 + +サブフォルダ内に `rules.mk` ファイルが存在するとコンパイル可能なキーボードとして見なされます。QMK Configurator から使用できるようになり、`make all` でテストされます。同じメーカーのキーボードをまとめるためにフォルダを使用している場合は `rules.mk` ファイルを置いてはいけません。 + +例: + +Clueboard は、サブフォルダをまとめるためとキーボードのリビジョン管理の両方のために使用しています。 + +* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master) + * [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards) + * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← これはまとめるためのフォルダです。 `rules.mk` ファイルはありません。 + * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) ← これはコンパイルできるキーボードです。`rules.mk` が存在します。 + * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← これもコンパイルできるキーボードです。 デフォルトのリビジョンとして `DEFAULT_FOLDER` に `rev3` を指定しています。 + * [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) ← コンパイル可能: `make clueboard/66/rev1` + * [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) ← コンパイル可能: `make clueboard/66/rev2` + * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← コンパイル可能: `make clueboard/66/rev3` もしくは `make clueboard/66` + +## キーボードのフォルダ構成 + +キーボードは `qmk_firmware/keyboards/` 内にあり、前のセクションで説明したようにフォルダ名はキーボードの名前にする必要があります。このフォルダ内にはいくつかのファイルがあります。 + +* `readme.md` +* `info.json` +* `config.h` +* `rules.mk` +* `.c` +* `.h` + +### `readme.md` + +全てのプロジェクトにはどのようなキーボードなのか、誰が設計したか、どこで入手できるかを説明する `readme.md` ファイルが必要です。もしあれば、メーカーの Web サイトなどの詳しい情報へのリンクも含める必要があります。[キーボード readme テンプレート](ja/documentation_templates.md#keyboard-readmemd-template)を参考にして下さい。 + +### `info.json` + +このファイルは [QMK API](https://github.com/qmk/qmk_api) から使用されます。[QMK Configurator](https://config.qmk.fm/) が必要とするキーボードの情報が含まれています。ここでメタデータを設定することもできます。詳しくは [info.json 形式](ja/reference_info_json.md) を参照して下さい。 + +### `config.h` + +全てのプロジェクトには、マトリックスサイズ、製品名、USB VID/PID、説明、その他の設定などが含まれた `config.h` ファイルが必要です。一般に、このファイルを使用して常に機能するキーボードの重要な情報やデフォルトを設定します。 + +### `rules.mk` + +このファイルが存在するということは、フォルダがキーボードであり、`make` コマンドで使用できることを意味します。ここでキーボードのビルド環境を構築し、デフォルトの機能を設定します。 + +### `` + +ここではキーボードのカスタマイズされたコードを記述します。通常、初期化してキーボードのハードウェアを制御するコードを記述します。キーボードが LED やスピーカー、その他付属ハードウェアのないキーマトリックスのみで構成されている場合は空にできます。 + +通常、以下の関数がこのファイルで定義されます。 + +* `void matrix_init_kb(void)` +* `void matrix_scan_kb(void)` +* `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` +* `void led_set_kb(uint8_t usb_led)` + +### `` + +このファイルはキーボードのマトリックスを定義するために使用されます。配列をキーボードの物理的なスイッチマトリックスに変換する C マクロを最低限1つ定義する必要があります。複数のレイアウトでキーボードを構築出来る場合は、追加のマクロを定義しなければいけません。 + +レイアウトが1つしかない場合は、このマクロは `LAYOUT` とします。 + +複数のレイアウトを定義する場合、物理的に構成することが出来なくとも、マトリックス上で全てのスイッチ位置をサポートする `LAYOUT_all` という名前の基本となるレイアウトが必要です。これは `default` キーマップで使用すべきマクロです。次に、他のレイアウトマクロを使用する `default_` といった追加のキーマップを用意します。これによって、他の人が定義されたレイアウトを使いやすくなります。 + +レイアウトマクロの名前は全て小文字で、先頭の `LAYOUT` だけ大文字です。 + +例として、ANSI と ISO をサポートする 60% PCB がある場合、以下のようにレイアウトとキーマップを定義出来ます。 + +| レイアウト名 | キーマップ名 | 説明 | +|-------------|-------------|-------------| +| LAYOUT_all | default | ISO と ANSI のどちらもサポートしたレイアウト | +| LAYOUT_ansi | default_ansi | ANSI レイアウト | +| LAYOUT_iso | default_iso | ISO レイアウト | + +## 画像/ハードウェアのファイル + +リポジトリのサイズを小さく保つために、いくつかの例外を除いて、どの形式のバイナリファイルも受け入れないようになりました。外部の場所（など）でホストして、`readme.md` でリンクすることをおすすめします。 + +ハードウェアのファイル(プレートやケース、PCB など)は [qmk.fm リポジトリ](https://github.com/qmk/qmk.fm)に提供でき、[qmk.fm](http://qmk.fm) で利用可能になります。ダウンロード出来るファイルは `//`（名前は上記と同じ形式）に保存され、`http://qmk.fm//` で提供されます。ページは `/_pages//` から生成されて、同じ場所で提供されます（ .mdファイルはJekyllを通して .htmlファイル変換されます）。`lets_split` ファイルを参照して下さい。 + +## キーボードのデフォルト設定 + +QMK が提供する機能の量を考えれば、新しいユーザーが混乱するのは当たり前です。キーボードのデフォルトファームウェアをまとめるなら、有効にする機能とオプションをハードウェアのサポートに必要な最低限のセットにすることをおすすめします。特定の機能に関するおすすめは以下の通りです。 + +### ブートマジックとコマンド + +[ブートマジック](ja/feature_bootmagic.md) と[コマンド](ja/feature_command.md)は、ユーザーがキーボードを明白でない方法で制御出来るようにする2つの関連機能です。いずれかの機能を有効にする場合、この機能をどのように提供するかについて、よく考えることをおすすめします。この機能が必要なユーザーは、あなたのキーボードを最初のプログラムできるキーボードとして使用している初心者に影響を与えることなく、個人的なキーマップ内で有効に出来ることを覚えておきましょう。 + +新規ユーザーが遭遇する最も多い問題は、キーボードを接続している間に間違えてブートマジックをトリガーしてしまうことです。キーボードの下を持っているとき、知らない間に Alt とスペースバーを押して、これらのキーが交換されてしまったことに気づきます。デフォルトではこの機能を無効にすることをおすすめしますが、有効にする場合は、キーボードを接続している間に押し間違えないキーへ `BOOTMAGIC_KEY_SALT` を設定することを検討して下さい。 + +キーボードに2つの Shift キーがない場合は、`COMMAND_ENABLE = no` を指定していても `IS_COMMAND` が動作するデフォルトを設定しておくべきです。ユーザーがコマンドを有効化したときに使用するデフォルトが与えられます。 + +## カスタムキーボードプログラミング + +[機能のカスタマイズ](ja/custom_quantum_functions.md)にあるようにキーボードのカスタム関数を定義できます。ユーザーも同様にその動作をカスタマイズしたいかもしれないということと、ユーザーにそれを可能にすることを忘れないで下さい。 `process_record_kb()`のようなカスタム関数を提供している場合、関数がその関数の `_user()` 版を呼び出すことを確認して下さい。また、その関数の`_user()` 版の戻り値を確認して、user が `true` を返した場合のみカスタムコードを実行しなければいけません。 + +## 生産しない/手配線 プロジェクト + +プロトタイプや手配線によるものなど QMK を使用するどんなプロジェクトも受け入れますが、`/keyboards/` フォルダが乱雑になるのを防ぐために、`/keyboards/handwired/` を用意しています。いつかプロトタイプのプロジェクトが製品のプロジェクトになった時点でメインの `/keyboards/` フォルダへ移動します！ + +## エラーとしての警告 + +キーボードを開発するときは、全ての警告がエラーとして扱われることに注意して下さい。小さな警告が蓄積されて、将来大きなエラーを引き起こす可能性があります。(そして、警告を放っておくのは良くない習慣です) + +## 著作権表示 + +別のプロジェクトを元にしてキーボードの設定をするものの同じコードを使用しない場合は、ファイル上部にある著作権表示を次の形式に従って自分の名前を表示するよう、更新して下さい。 + + Copyright 2017 Your Name + + +他の人のコードを修正し、その変更が些細な部分のみであれば、著作権表示の名前をそのままにしておかないといけません。ファイルに対して重要な作業を行った場合、以下のようにあなたの名前を追加します。 + + Copyright 2017 Their Name Your Name + +年はファイルが作成された最初の年にします。後年にそのファイルに対して作業が行われた場合、次のように2つ目の年を追加して反映することが出来ます。 + + Copyright 2015-2017 Your Name + +## ライセンス + +QMK のコア部分は [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html) でライセンスされます。AVR マイコン用のバイナリを提供する場合は、[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) か、[GPLv3](https://www.gnu.org/licenses/gpl.html) のどちらかから選択出来ます。ARM マイコン用のバイナリを提供する場合は、 [ChibiOS](http://www.chibios.org) の GPLv3 ライセンスに準拠するため、[GPL Version 3](https://www.gnu.org/licenses/gpl.html) を選択しなければいけません。 + +[uGFX](https://ugfx.io) を使用している場合は、[uGFX License](https://ugfx.io/license.html) に準拠する必要があります。uGFX を利用したデバイスを販売するには個別に商用ライセンスを取得しなければいけません。 + +## 技術的な詳細 + +キーボードを QMK で動作させるための詳細は[ハードウェア](ja/hardware.md)を参照して下さい！