diff --git a/docs/ja/feature_backlight.md b/docs/ja/feature_backlight.md index 760c6444c2..9647f215d3 100644 --- a/docs/ja/feature_backlight.md +++ b/docs/ja/feature_backlight.md @@ -1,253 +1,224 @@ -# バックライト +# バックライト :id=backlighting 多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。 -QMK は *パルス幅変調*(*Pulse Width Modulation*) すなわち PWM として知られている技術で急速にオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。 +QMK は *パルス幅変調* (*Pulse Width Modulation*) すなわち PWM として知られている技術で、一定の比率で素早くオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。 MCU は、GPIO ピンにはそんなに電流を供給できません。MCU から直接バックライトに給電せずに、バックライトピンは LED への電力を切り替えるトランジスタあるいは MOSFET に接続されます。 -## 機能の設定 - ほとんどのキーボードではバックライトをサポートしている場合にデフォルトで有効になっていますが、もし機能しない場合は `rules.mk` が以下を含んでいることを確認してください: ```makefile BACKLIGHT_ENABLE = yes ``` -## キーコード +## キーコード :id=keycodes + 有効にすると、以下のキーコードを使ってバックライトレベルを変更することができます。 -| キー | 説明 | -|---------|------------------------------------------| +| キー | 説明 | +| --------- | ------------------------------------ | | `BL_TOGG` | バックライトをオンあるいはオフにする | -| `BL_STEP` | バックライトレベルを循環する | -| `BL_ON` | バックライトを最大輝度に設定する | -| `BL_OFF` | バックライトをオフにする | -| `BL_INC` | バックライトレベルを上げる | -| `BL_DEC` | バックライトレベルを下げる | -| `BL_BRTG` | バックライトの明滅動作を切り替える | +| `BL_STEP` | バックライトレベルを循環する | +| `BL_ON` | バックライトを最大輝度に設定する | +| `BL_OFF` | バックライトをオフにする | +| `BL_INC` | バックライトレベルを上げる | +| `BL_DEC` | バックライトレベルを下げる | +| `BL_BRTG` | バックライトの明滅動作を切り替える | -## バックライト関数群 +## 関数群 :id=functions -| 関数 | 説明 | -|----------|-----------------------------------------------------------| -| `backlight_toggle()` | バックライトをオンあるいはオフにする | -| `backlight_enable()` | バックライトをオンにする | -| `backlight_disable()` | バックライトをオフにする | -| `backlight_step()` | バックライトレベルを循環する | -| `backlight_increase()` | バックライトレベルを上げる | -| `backlight_decrease()` | バックライトレベルを下げる | -| `backlight_level(x)` | バックライトのレベルを特定のレベルに設定する | -| `get_backlight_level()` | 現在のバックライトレベルを返す | -| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す | +次の関数を使って、カスタムコードでバックライトを変更することができます: -### バックライトの明滅動作の関数群 +| 関数 | 説明 | +| ------------------------ | -------------------------------------------- | +| `backlight_toggle()` | バックライトをオンあるいはオフにする | +| `backlight_enable()` | バックライトをオンにする | +| `backlight_disable()` | バックライトをオフにする | +| `backlight_step()` | バックライトレベルを循環する | +| `backlight_increase()` | バックライトレベルを上げる | +| `backlight_decrease()` | バックライトレベルを下げる | +| `backlight_level(x)` | バックライトのレベルを特定のレベルに設定する | +| `get_backlight_level()` | 現在のバックライトレベルを返す | +| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す | -| 関数 | 説明 | -|----------|---------------------------------------------------| -| `breathing_toggle()` | バックライトの明滅動作をオンまたはオフにする | -| `breathing_enable()` | バックライトの明滅動作をオンにする | -| `breathing_disable()` | バックライトの明滅動作をオフにする | +バックライトの明滅が有効の場合(以下を参照)、以下の関数も利用できます: -## ドライバの設定 +| 関数 | 説明 | +|-----------------------|----------------------------------------------| +| `breathing_toggle()` | バックライトの明滅動作をオンまたはオフにする | +| `breathing_enable()` | バックライトの明滅動作をオンにする | +| `breathing_disable()` | バックライトの明滅動作をオフにする | + +## 設定 :id=configuration どのドライバを使うかを選択するには、以下を使って `rules.mk` を設定します: ```makefile -BACKLIGHT_DRIVER = software # 有効なドライバの値は 'pwm,software,no' です +BACKLIGHT_DRIVER = software ``` -各ドライバについてのヘルプは以下を見てください。 +有効なドライバの値は `pwm`, `software`, `custom`, `no` です。各ドライバについてのヘルプは以下を見てください。 -## 共通のドライバ設定 +バックライトを設定するには、`config.h` の中で以下の `#define` をします: -バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします: - -| 定義 | デフォルト | 説明 | -|---------------------|-------------|--------------------------------------------------------------------------------------| -| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) | +| 定義 | デフォルト | 説明 | +| --------------------- | ---------- | ------------------------------------------------------------------------------------------- | +| `BACKLIGHT_PIN` | *定義なし* | LED を制御するピン | +| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) | | `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) | -| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする | -| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） | -| `BACKLIGHT_ON_STATE` | `0` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` | +| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする | +| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） | +| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` | -### バックライトオン状態 +独自のキーボードを設計しているわけではない限り、通常は `BACKLIGHT_PIN` または `BACKLIGHT_ON_STATE` を変更する必要はありません。 -ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを*オン*にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。 +### バックライトオン状態 :id=backlight-on-state + +ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを *オン* にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。 ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。 -この機能は `BACKLIGHT_ON_STATE` 定義することでキーボードレベルで設定されます。 +この機能は `BACKLIGHT_ON_STATE` を定義することでキーボードレベルで設定されます。 -## AVR ドライバ +### AVR ドライバ :id=avr-driver + +`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです: -AVR ボードでは、デフォルトのドライバは現在のところ最善のシナリオを選択するために構成を探っています。ドライバはデフォルトで設定されますが、rules.mk 内の同等の設定は以下の通りです: ```makefile BACKLIGHT_DRIVER = pwm ``` -### 注意事項 +#### 注意事項 :id=avr-caveats -ハードウェア PWM は以下の表に従ってサポートされます: +AVR ボードでは、QMK はどのドライバを使うかを以下の表に従って自動的に決定します: | バックライトピン | AT90USB64/128 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P | -|-------------|-------------|-------------|-------------|---------|----------| -| `B1` | | | | | Timer 1 | -| `B2` | | | | | Timer 1 | -| `B5` | Timer 1 | Timer 1 | | | | -| `B6` | Timer 1 | Timer 1 | | | | -| `B7` | Timer 1 | Timer 1 | Timer 1 | | | -| `C4` | Timer 3 | | | | | -| `C5` | Timer 3 | | Timer 1 | | | -| `C6` | Timer 3 | Timer 3 | Timer 1 | | | -| `D4` | | | | Timer 1 | | -| `D5` | | | | Timer 1 | | +| ---------------- | ------------- | ------------- | ------------- | --------- | ----------- | +| `B1` | | | | | Timer 1 | +| `B2` | | | | | Timer 1 | +| `B5` | Timer 1 | Timer 1 | | | | +| `B6` | Timer 1 | Timer 1 | | | | +| `B7` | Timer 1 | Timer 1 | Timer 1 | | | +| `C4` | Timer 3 | | | | | +| `C5` | Timer 3 | | Timer 1 | | | +| `C6` | Timer 3 | Timer 3 | Timer 1 | | | +| `D4` | | | | Timer 1 | | +| `D5` | | | | Timer 1 | | -他の全てのピンはソフトウェア PWM を使います。[オーディオ](ja/feature_audio.md)機能が無効あるいは1つのタイマだけを使っている場合は、ハードウェアタイマによってバックライト PWM を引き起こすことができます: +他の全てのピンはタイマー支援ソフトウェア PWM を使います。 | オーディオピン | オーディオタイマ | ソフトウェア PWM タイマ | -|---------|-----------|------------------| -| `C4` | Timer 3 | Timer 1 | -| `C5` | Timer 3 | Timer 1 | -| `C6` | Timer 3 | Timer 1 | -| `B5` | Timer 1 | Timer 3 | -| `B6` | Timer 1 | Timer 3 | -| `B7` | Timer 1 | Timer 3 | +| -------------- | ---------------- | ----------------------- | +| `C4` | Timer 3 | Timer 1 | +| `C5` | Timer 3 | Timer 1 | +| `C6` | Timer 3 | Timer 1 | +| `B5` | Timer 1 | Timer 3 | +| `B6` | Timer 1 | Timer 3 | +| `B7` | Timer 1 | Timer 3 | -両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使いませんが、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれないかもしれないため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。 +両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使うことができず、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれない可能性があるため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。 -### AVR 設定 - -バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします: - -| 定義 | デフォルト | 説明 | -|---------------------|-------------|--------------------------------------------------------------------------------------------------------------| -| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです | -| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください | -| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) | -| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) | -| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする | -| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） | -| `BACKLIGHT_ON_STATE` | `1` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` | - -### バックライトオン状態 - -ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを*オン*にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。 -ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。 - -この機能は `BACKLIGHT_ON_STATE` 定義することでキーボードレベルで設定されます。 - -### 複数のバックライトピン - -ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。 -ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらすべてのピンは PWM デューティサイクル時に同時にオンおよびオフになります。 -この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock の代わりに LCTRL をマップしていて、Caps Lock がオンの時に Caps Lock LED をアクティブにする代わりにバックライトの一部にする必要がある場合に便利です。 - -複数のバックライトピンをアクティブにするには、`config.h` に次のようなものを追加する必要があります: - -```c -#define BACKLIGHT_LED_COUNT 2 -#undef BACKLIGHT_PIN -#define BACKLIGHT_PINS { F5, B2 } -``` - -### ハードウェア PWM 実装 +#### ハードウェア PWM 実装 :id=hardware-pwm-implementation バックライト用にサポートされているピンを使う場合、QMK は PWM 信号を出力するように設定されたハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。 -希望の輝度が計算され、`OCRxx` レジスタ内に格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。 +希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。 このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。`0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。 明滅動作の効果はカウンタがリセットされる(秒間あたりおよそ244回)たびに呼び出される `TIMER1_OVF_vect` の割り込みハンドラを登録することで可能になります。 -このハンドラ内で、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。 +このハンドラで、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。 -### タイマーにアシストされた PWM 実装 +#### タイマー支援 PWM 実装 :id=timer-assisted-implementation `BACKLIGHT_PIN` がハードウェアバックライトピンに設定されていない場合、QMK はソフトウェア割り込みを引き起こすように設定されているハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。 0 に再設定すると、CPU は LED をオンにする OVF (オーバーフロー)割り込みを発火し、デューティサイクルを開始します。 -希望の輝度が計算され、`OCRxx` レジスタ内に格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。 +希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。 このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。 `0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。 明滅の効果はハードウェア PWM 実装と同じです。 -## ARM ドライバ +### ARM ドライバ :id=arm-configuration + +まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです: -まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。ドライバはデフォルトで設定されますが、rules.mk 内の同等の設定は以下の通りです: ```makefile BACKLIGHT_DRIVER = pwm ``` -### 注意事項 +#### ChibiOS の設定 :id=arm-configuration -現在のところ、ハードウェア PWM のみがサポートされ、タイマーはアシストされず、自動設定は提供されません。 +以下の `#define` は ARM ベースのキーボードにのみ適用されます: -?> STMF072 のバックライトサポートのテストは制限されています。人によって違うかもしれません。不明な場合は、rules.mk で `BACKLIGHT_ENABLE = no` を設定します。 +| 定義 | デフォルト | 説明 | +| ----------------------- | ---------- | ----------------------- | +| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ | +| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル | +| `BACKLIGHT_PAL_MODE` | `2` | 使用するピン代替関数 | -### ARM 設定 +これらの値を決定するには、特定の MCU の ST データシートを参照してください。独自のキーボードを設計しているわけではない場合、通常はこれらを変更する必要はありません。 -バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします: +#### 注意事項 :id=arm-caveats -| 定義 | デフォルト | 説明 | -|------------------------|-------------|-------------------------------------------------------------------------------------------------------------| -| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです | -| `BACKLIGHT_PWM_DRIVER` | `PWMD4` | 使用する PWM ドライバ。ピンから PWM タイマへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです | -| `BACKLIGHT_PWM_CHANNEL` | `3` | 使用する PWM チャンネル。ピンから PWM チャンネルへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです | -| `BACKLIGHT_PAL_MODE` | `2` | 使用するピンの代替機能。ピンの AF マッピングについては ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです | +現在のところ、ハードウェア PWM のみがサポートされ、タイマー支援はなく、自動設定は提供されません。 -## Software PWM Driver :id=software-pwm-driver +?> STM32F072 のバックライトサポートのテストは制限されています。人によって違うかもしれません。不明な場合は、`rules.mk` で `BACKLIGHT_ENABLE = no` を設定します。 + +### ソフトウェア PWM ドライバ :id=software-pwm-driver + +このモードでは、他のキーボードのタスクを実行中に PWM は「エミュレート」されます。追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、`rules.mk` に以下を追加します: -他のキーボードのタスクを実行中に PWM をエミュレートすることにより、追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、rules.mk に以下を追加します: ```makefile BACKLIGHT_DRIVER = software ``` -### ソフトウェア PWM 設定 - -バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします: - -| 定義 | デフォルト | 説明 | -|-----------------|-------------|-------------------------------------------------------------------------------------------------------------| -| `BACKLIGHT_PIN` | `B7` | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです | -| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください | - -### 複数のバックライトピン +#### 複数のバックライトピン :id=multiple-backlight-pins ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。 -ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらすべてのピンは PWM デューティサイクル時に同時にオンおよびオフになります。 -この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock の代わりに LCTRL をマップしていて、Caps Lock がオンの時に Caps Lock LED をアクティブにする代わりにバックライトの一部にする必要がある場合に便利です。 +ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらのピンは PWM デューティサイクル時に同時にオンおよびオフになります。 -複数のバックライトピンをアクティブにするには、`config.h` に次のようなものを追加する必要があります: +この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock LED は通常バックライトとは別のピンに配線されるため、Caps Lock の代わりに Control をマップしていて、Caps Lock がオンの時に Caps Lock LED ではなくバックライトの一部をアクティブにする必要がある場合に便利です。 + +複数のバックライトピンをアクティブにするには、`config.h` に `BACKLIGHT_PIN` の代わりに次のようなものを追加します: ```c -#undef BACKLIGHT_PIN #define BACKLIGHT_PINS { F5, B2 } ``` -## カスタムドライバ +### カスタムドライバ :id=custom-driver -有効にするには、rules.mk に以下を追加します: +上記ドライバのいずれもキーボードに適用されていない場合(例えば、バックライトを制御するのに別の IC を使用している場合)、QMK が提供しているこの簡単な API を使ってカスタムバックライトドライバを実装することができます。有効にするには、`rules.mk` に以下を追加します: ```makefile BACKLIGHT_DRIVER = custom ``` -カスタムドライバ API を実装する場合、提供されるキーボードフックは以下の通りです: +それから次のフックのいずれかを実装します: ```c void backlight_init_ports(void) { // オプション - 起動時に実行されます - // - 通常、ここでピンを設定します + // 通常、ここでピンを設定します } void backlight_set(uint8_t level) { // オプション - レベルの変更時に実行されます - // - 通常、ここで新しい値に応答します + // 通常、ここで新しい値に応答します } void backlight_task(void) { // オプション - 定期的に実行されます - // - ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします + // これはメインキーボードループで呼び出されることに注意してください + // そのため、ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします } ``` + +## 回路図の例 + +この一般的な例では、バックライト LED は全て N チャンネル MOSFET に向かって並列に接続されています。そのゲートピンは、リンギングを回避するため 470Ωの抵抗を介してマイクロコントローラの GPIO ピンの1つに接続されています。 +プルダウン抵抗もゲートピンとグランドの間に配置されており、MCU によって駆動されていない場合にプルダウン抵抗を定義された状態に保ちます。 +これらの抵抗値は重要ではありません。詳細については、[this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) を参照してください。 + +![バックライトの回路例](https://i.imgur.com/BmAvoUC.png)