Merge branch 'master' into develop

docs/feature_led_matrix.md

@@ -10,9 +10,11 @@ If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_r
 
 There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
 
- LED_MATRIX_ENABLE = yes
- LED_MATRIX_DRIVER = IS31FL3731
-
+```make
+LED_MATRIX_ENABLE = yes
+LED_MATRIX_DRIVER = IS31FL3731
+```
+
 You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:
 
 | Variable | Description | Default |
@@ -28,33 +30,38 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>
 
 Here is an example using 2 drivers.
 
- // This is a 7-bit address, that gets left-shifted and bit 0
- // set to 0 for write, 1 for read (as per I2C protocol)
- // The address will vary depending on your wiring:
- // 0b1110100 AD <-> GND
- // 0b1110111 AD <-> VCC
- // 0b1110101 AD <-> SCL
- // 0b1110110 AD <-> SDA
- #define LED_DRIVER_ADDR_1 0b1110100
- #define LED_DRIVER_ADDR_2 0b1110110
-
- #define LED_DRIVER_COUNT 2
- #define LED_DRIVER_1_LED_COUNT 25
- #define LED_DRIVER_2_LED_COUNT 24
- #define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
+```c
+// This is a 7-bit address, that gets left-shifted and bit 0
+// set to 0 for write, 1 for read (as per I2C protocol)
+// The address will vary depending on your wiring:
+// 0b1110100 AD <-> GND
+// 0b1110111 AD <-> VCC
+// 0b1110101 AD <-> SCL
+// 0b1110110 AD <-> SDA
+#define LED_DRIVER_ADDR_1 0b1110100
+#define LED_DRIVER_ADDR_2 0b1110110
+
+#define LED_DRIVER_COUNT 2
+#define LED_DRIVER_1_LED_COUNT 25
+#define LED_DRIVER_2_LED_COUNT 24
+#define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
+```
 
 Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
 
 Define these arrays listing all the LEDs in your `<keyboard>.c`:
 
- const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
- /* Refer to IS31 manual for these locations
-  * driver
-  * | LED address
-  * | | */
-  {0, C3_3},
-  ....
- }
+```c
+ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
+ /* Refer to IS31 manual for these locations
+ * driver
+ * | LED address
+ * | | */
+ { 0, C1_1 },
+ { 0, C1_15 },
+ // ...
+ }
+```
 
 Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
 
@@ -66,26 +73,28 @@ All LED matrix keycodes are currently shared with the [backlight system](feature
 
 Currently no LED matrix effects have been created.
 
-## Custom layer effects
+## Custom Layer Effects
 
 Custom layer effects can be done by defining this in your `<keyboard>.c`:
 
- void led_matrix_indicators_kb(void) {
-  led_matrix_set_index_value(index, value);
- }
+```c
+void led_matrix_indicators_kb(void) {
+ led_matrix_set_index_value(index, value);
+}
+```
 
 A similar function works in the keymap as `led_matrix_indicators_user`.
 
-## Suspended state
+## Suspended State
 
 To use the suspend feature, add this to your `<keyboard>.c`:
 
- void suspend_power_down_kb(void)
- {
-  led_matrix_set_suspend_state(true);
- }
+```c
+void suspend_power_down_kb(void) {
+ led_matrix_set_suspend_state(true);
+}
 
- void suspend_wakeup_init_kb(void)
- {
-  led_matrix_set_suspend_state(false);
- }
+void suspend_wakeup_init_kb(void) {
+ led_matrix_set_suspend_state(false);
+}
+```

docs/ja/adc_driver.md

@@ -0,0 +1,155 @@
+# ADC ドライバ
+
+<!---
+ original document: 0.10.52:docs/adc_driver.md
+ git diff 0.10.52 HEAD -- docs/adc_driver.md | cat
+-->
+
+QMK は対応している MCU のアナログ・デジタルコンバータ（ADC) を使用し、特定のピンの電圧を計測することができます。この機能はデジタル出力の[ロータリーエンコーダ](ja/feature_encoders.md)などではなく、アナログ計測が必要な可変抵抗器を使用したボリュームコントロールや Bluetooth キーボードのバッテリー残量表示などの実装に役立ちます。
+
+このドライバは現在 AVR と一部の ARM デバイスをサポートしています。返される値は 0V と VCC (通常 AVR の場合は 5V または 3.3V、ARM の場合は 3.3V)の間でマッピングされた 10ビットの整数 (0-1023) ですが、ARM の場合、もしもより精度が必要であれば `#define` を使うと操作をより柔軟に制御できます。
+
+## 使い方
+
+このドライバを使うには、`rules.mk` に以下を追加します:
+
+```make
+SRC += analog.c
+```
+
+そして、コードの先頭に以下の include を置きます:
+
+```c
+#include "analog.h"
+```
+
+## チャンネル
+
+### AVR
+
+|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
+|-------|-------------|-------------|---------|-----------|
+|0 |`F0` |`F0` |`A0` |`C0` |
+|1 |`F1` |`F1` |`A1` |`C1` |
+|2 |`F2` | |`A2` |`C2` |
+|3 |`F3` | |`A3` |`C3` |
+|4 |`F4` |`F4` |`A4` |`C4` |
+|5 |`F5` |`F5` |`A5` |`C5` |
+|6 |`F6` |`F6` |`A6` |* |
+|7 |`F7` |`F7` |`A7` |* |
+|8 | |`D4` | | |
+|9 | |`D6` | | |
+|10 | |`D7` | | |
+|11 | |`B4` | | |
+|12 | |`B5` | | |
+|13 | |`B6` | | |
+
+<sup>\* ATmega328/P には余分な2つの ADC チャンネルがありますが、DIP ピンアウトには存在せず、GPIO ピンとは共有されません。これらに直接アクセスするために、`adc_read()` を使えます。
+
+### ARM
+
+これらのピンの一部は同じチャンネルを使って ADC 上でダブルアップされることに注意してください。これは、これらのピンがどちらかの ADC に使われる可能性があるからです。
+
+また、F0 と F3 は異なるナンバリングスキーマを使うことに注意してください。F0 には1つの ADC があり、チャンネルは0から始まるインデックスですが、F3 には4つの ADC があり、チャンネルは1から始まるインデックスです。これは、F0 が ADC の `ADCv1` 実装を使用するのに対し、F3 が `ADCv3` 実装を使用するためです。
+
+|ADC|Channel|STM32F0xx|STM32F3xx|
+|---|-------|---------|---------|
+|1 |0 |`A0` | |
+|1 |1 |`A1` |`A0` |
+|1 |2 |`A2` |`A1` |
+|1 |3 |`A3` |`A2` |
+|1 |4 |`A4` |`A3` |
+|1 |5 |`A5` |`F4` |
+|1 |6 |`A6` |`C0` |
+|1 |7 |`A7` |`C1` |
+|1 |8 |`B0` |`C2` |
+|1 |9 |`B1` |`C3` |
+|1 |10 |`C0` |`F2` |
+|1 |11 |`C1` | |
+|1 |12 |`C2` | |
+|1 |13 |`C3` | |
+|1 |14 |`C4` | |
+|1 |15 |`C5` | |
+|1 |16 | | |
+|2 |1 | |`A4` |
+|2 |2 | |`A5` |
+|2 |3 | |`A6` |
+|2 |4 | |`A7` |
+|2 |5 | |`C4` |
+|2 |6 | |`C0` |
+|2 |7 | |`C1` |
+|2 |8 | |`C2` |
+|2 |9 | |`C3` |
+|2 |10 | |`F2` |
+|2 |11 | |`C5` |
+|2 |12 | |`B2` |
+|2 |13 | | |
+|2 |14 | | |
+|2 |15 | | |
+|2 |16 | | |
+|3 |1 | |`B1` |
+|3 |2 | |`E9` |
+|3 |3 | |`E13` |
+|3 |4 | | |
+|3 |5 | | |
+|3 |6 | |`E8` |
+|3 |7 | |`D10` |
+|3 |8 | |`D11` |
+|3 |9 | |`D12` |
+|3 |10 | |`D13` |
+|3 |11 | |`D14` |
+|3 |12 | |`B0` |
+|3 |13 | |`E7` |
+|3 |14 | |`E10` |
+|3 |15 | |`E11` |
+|3 |16 | |`E12` |
+|4 |1 | |`E14` |
+|4 |2 | |`B12` |
+|4 |3 | |`B13` |
+|4 |4 | |`B14` |
+|4 |5 | |`B15` |
+|4 |6 | |`E8` |
+|4 |7 | |`D10` |
+|4 |8 | |`D11` |
+|4 |9 | |`D12` |
+|4 |10 | |`D13` |
+|4 |11 | |`D14` |
+|4 |12 | |`D8` |
+|4 |13 | |`D9` |
+|4 |14 | | |
+|4 |15 | | |
+|4 |16 | | |
+
+## 関数
+
+### AVR
+
+|関数 |説明 |
+|----------------------------|------------------------------------------------------------------------------------------------------------------------------------|
+|`analogReference(mode)` |アナログの電圧リファレンスソースを設定する。`ADC_REF_EXTERNAL`、`ADC_REF_POWER`、`ADC_REF_INTERNAL` のいずれかでなければなりません。|
+|`analogReadPin(pin)` |指定されたピンから値を読み取ります。例えば、ATmega32U4 の ADC6 の場合 `F6`。 |
+|`pinToMux(pin)` |指定されたピンを mux 値に変換します。サポートされていないピンが指定された場合、"0V (GND)" の mux 値を返します。 |
+|`adc_read(mux)` |指定された mux に従って ADC から値を読み取ります。詳細は、MCU のデータシートを見てください。 |
+
+### ARM
+
+|関数 |説明 |
+|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`analogReadPin(pin)` |指定されたピンから値を読み取ります。STM32F0 では チャンネル 0 の `A0`、STM32F3 ではチャンネル 1 の ADC1。ピンを複数の ADC に使える場合は、この関数のために番号の小さい ADC が選択されることに注意してください。例えば、`C0` は、ADC2 にも使える場合、ADC1 のチャンネル 6 になります。 |
+|`analogReadPinAdc(pin, adc)`|指定されたピンと ADC から値を読み取ります。例えば、`C0, 1` は、ADC1 ではなく ADC2 のチャンネル 6 から読み取ります。この関数では、ADC はインデックス 0 から始まることに注意してください。 |
+|`pinToMux(pin)` |指定されたピンをチャンネルと ADC の組み合わせに変換します。サポートされていないピンが指定された場合、"0V (GND)" の mux 値を返します。 |
+|`adc_read(mux)` |指定されたピンと ADC の組み合わせに応じて ADC から値を読み取ります。詳細は、MCU のデータシートを見てください。 |
+
+## 設定
+
+## ARM
+
+ADC の ARM 実装には、独自のキーボードとキーマップでオーバーライドして動作方法を変更できる幾つかの追加オプションがあります。利用可能なオプションの詳細については、特定のマイクロコントローラについて ChibiOS の対応する `hal_adc_lld.h` を調べてください。
+
+|`#define` |型 |既定値 |説明 |
+|---------------------|------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |`true` の場合、この実装は循環バッファを使います。 |
+|`ADC_NUM_CHANNELS` |`int` |`1` |ADC 動作の一部としてスキャンされるチャンネル数を設定します。現在の実装は `1` のみをサポートします。 |
+|`ADC_BUFFER_DEPTH` |`int` |`2` |各結果の深さを設定します。デフォルトでは12ビットの結果しか取得できないため、これを2バイトに設定して1つの値を含めることができます。8ビット以下の結果を選択した場合は、これを 1 に設定できます。 |
+|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |ADC のサンプリングレートを設定します。デフォルトでは、最も速い設定に設定されています。 |
+|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|結果の分解能。デフォルトでは12ビットを選択しますが、12、10、8、6ビットを選択できます。 |