doc: update documentation, add faq about row2col

Signed-off-by: Haobo Gu <[email protected]>
HaoboGu · Dec 25, 2024 · fb24075 · fb24075
1 parent ece91dd
commit fb24075
Show file tree

Hide file tree

Showing 17 changed files with 40 additions and 28 deletions.
diff --git a/docs/src/faq.md b/docs/src/faq.md
@@ -1,5 +1,26 @@
 # FAQ
 
+### My matrix is row2col, the matrix doesn't work
+
+RMK enables `col2row` as the default feature. To use the row2col matrix, you have to change your `Cargo.toml`, adds `default-features = false` to RMK crate, disabling the `col2row` feature.
+
+```toml
+# Cargo.toml
+rmk = { version = "0.5", default-features = false, features = ["nrf52840_ble", "async_matrix"] }
+```
+
+If you're using the cloud compilation, you have to update your `keyboard.toml`, add `row2col = true` under the `[matrix]` section or `[split.central.matrix]` section:
+
+```toml
+# keyboard.toml
+[matrix]
+row2col = true
+
+# Or
+[split.central.matrix]
+row2col = true
+```
+
 ### Where is my built firmware?
 
 By default, the built firmware is at `target/<TARGET>/<MODE>` folder, where `<TARGET>` is your microcontroller's [target](./user_guide/2_setup_environment.md/#3-install-your-target) and `<MODE>` is `debug` or `release`, depending on your build mode.

diff --git a/docs/src/keyboard_configuration.md b/docs/src/keyboard_configuration.md
@@ -62,7 +62,7 @@ Here is an example toml of `[matrix]` section for stm32:
 # Input and output pins are mandatory
 input_pins = ["PD4", "PD5", "PD6", "PD3"]
 output_pins = ["PD7", "PD8", "PD9"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 ```
 
@@ -316,7 +316,7 @@ matrix_type = "normal"
 # Input and output pins
 input_pins = ["PIN_6", "PIN_7", "PIN_8", "PIN_9"]
 output_pins = ["PIN_19", "PIN_20", "PIN_21"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 
 # Direct Pin Matrix is a Matrix of buttons connected directly to pins. It conflicts with the above.
 matrix_type = "direct_pin"

diff --git a/docs/src/user_guide/2-1_cloud_compilation.md b/docs/src/user_guide/2-1_cloud_compilation.md
@@ -2,6 +2,8 @@
 
 RMK provides a [project-template](https://github.com/HaoboGu/rmk-project-template) that you can use to create your firmware easily. The following is a step-by-step tutorial for compiling RMK firmware using Github Actions.
 
+Note: There are some limitations currently for cloud compilation. For example, you cannot edit cargo features in the generated project. If you have any problems when compiling RMK using cloud, please [open an issue](https://github.com/HaoboGu/rmk/issues/new)!
+
 ## Steps
 
 1. To get started, open [project-template](https://github.com/HaoboGu/rmk-project-template), click `Use this template` button and choose `Create a new repository`:
@@ -28,4 +30,4 @@ RMK provides a [project-template](https://github.com/HaoboGu/rmk-project-templat
 
    ![artifacts](../images/artifacts.png)
 
-5. Now you get your RMK firmware! RMK provides `hex` and `uf2` firmware that you can use. The final step is to flash the firmware to your microcontroller. You can follow [instructions here](4_compile_and_flash.md#flash-the-firmware) if you don't know how to flash the firmware to your keyboard.
+5. Now you get your RMK firmware! RMK provides `hex` and `uf2` firmware that you can use. The final step is to flash the firmware to your microcontroller. Follow the instructions in [Flash the firmware](3_flash_firmware.md) section.
diff --git a/examples/use_config/esp32c3_ble/keyboard.toml b/examples/use_config/esp32c3_ble/keyboard.toml
@@ -12,7 +12,7 @@ usb_enable = false
 input_pins = ["gpio6", "gpio7", "gpio20", "gpio21"]
 output_pins = ["gpio3", "gpio4", "gpio5"]
 
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/esp32c6_ble/keyboard.toml b/examples/use_config/esp32c6_ble/keyboard.toml
@@ -12,7 +12,7 @@ usb_enable = false
 input_pins = ["gpio6", "gpio7", "gpio20", "gpio21"]
 output_pins = ["gpio3", "gpio4", "gpio5"]
 
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/esp32s3_ble/keyboard.toml b/examples/use_config/esp32s3_ble/keyboard.toml
@@ -11,7 +11,7 @@ usb_enable = false
 # Input and output pins are mandatory
 input_pins = ["gpio6", "gpio7", "gpio20", "gpio21"]
 output_pins = ["gpio3", "gpio4", "gpio5"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/nrf52832_ble/keyboard.toml b/examples/use_config/nrf52832_ble/keyboard.toml
@@ -11,7 +11,7 @@ usb_enable = false
 # Input and output pins are mandatory
 input_pins = ["P0_03", "P0_04", "P0_28", "P0_29"]
 output_pins = ["P0_11", "P0_27", "P0_07"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/nrf52840_ble/keyboard.toml b/examples/use_config/nrf52840_ble/keyboard.toml
@@ -10,7 +10,7 @@ chip = "nrf52840"
 # Input and output pins are mandatory
 input_pins = ["P1_00", "P1_01", "P1_02", "P1_07"]
 output_pins = ["P1_05", "P1_06", "P1_03"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/nrf52840_ble_split/keyboard.toml b/examples/use_config/nrf52840_ble_split/keyboard.toml
@@ -7,8 +7,6 @@ manufacturer = "haobo"
 chip = "nrf52840"
 
 [layout]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
-# row2col = true
 rows = 4
 cols = 3
 layers = 2
@@ -47,6 +45,8 @@ ble_addr = [0x18, 0xe2, 0x21, 0x80, 0xc0, 0xc7]
 
 [split.central.matrix]
 matrix_type = "normal"
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
+# row2col = true
 input_pins = ["P0_12", "P0_13"]
 output_pins = ["P0_14", "P0_15"]
 

diff --git a/examples/use_config/nrf52840_ble_split_direct_pin/keyboard.toml b/examples/use_config/nrf52840_ble_split_direct_pin/keyboard.toml
@@ -7,8 +7,6 @@ manufacturer = "haobo"
 chip = "nrf52840"
 
 [layout]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
-# row2col = true
 rows = 4
 cols = 3
 layers = 2

diff --git a/examples/use_config/nrf52840_usb/keyboard.toml b/examples/use_config/nrf52840_usb/keyboard.toml
@@ -10,7 +10,7 @@ chip = "nrf52840"
 # Input and output pins are mandatory
 input_pins = ["P1_00", "P1_01", "P1_02", "P1_03"]
 output_pins = ["P1_05", "P1_06", "P1_07"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/rp2040/keyboard.toml b/examples/use_config/rp2040/keyboard.toml
@@ -10,7 +10,7 @@ chip = "rp2040"
 # Input and output pins are mandatory
 input_pins = ["PIN_6", "PIN_7", "PIN_8", "PIN_9"]
 output_pins = ["PIN_19", "PIN_20", "PIN_21"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/rp2040_direct_pin/keyboard.toml b/examples/use_config/rp2040_direct_pin/keyboard.toml
@@ -6,10 +6,6 @@ product_id = 0x4643
 manufacturer = "haobo"
 chip = "rp2040"
 
-# [matrix]
-# input_pins = ["PIN_0", "PIN_1", "PIN_2", "PIN_3", "PIN_4", "PIN_5", "PIN_6", "PIN_7", "PIN_8", "PIN_9", "PIN_10", "PIN_11"]
-# output_pins = ["PIN_19", "PIN_20", "PIN_21"]
-
 [matrix]
 matrix_type = "direct_pin"
 direct_pin_low_active = true

diff --git a/examples/use_config/rp2040_split/keyboard.toml b/examples/use_config/rp2040_split/keyboard.toml
@@ -6,13 +6,6 @@ product_id = 0x4643
 manufacturer = "haobo"
 chip = "rp2040"
 
-# [matrix]
-# Input and output pins are mandatory
-# input_pins = ["PIN_6", "PIN_7", "PIN_8", "PIN_9"]
-# output_pins = ["PIN_19", "PIN_20", "PIN_21"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
-# row2col = true
-
 [layout]
 rows = 4
 cols = 3
@@ -48,6 +41,8 @@ serial = [
 ]
 [split.central.matrix]
 matrix_type = "normal"
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
+# row2col = true
 input_pins = ["PIN_9", "PIN_11"]
 output_pins = ["PIN_10", "PIN_12"]
 

diff --git a/examples/use_config/stm32f1/keyboard.toml b/examples/use_config/stm32f1/keyboard.toml
@@ -10,7 +10,7 @@ chip = "stm32f103c8"
 # Input and output pins are mandatory
 input_pins = ["PD4", "PD5", "PD6", "PD3"]
 output_pins = ["PD7", "PD8", "PD9"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/stm32f4/keyboard.toml b/examples/use_config/stm32f4/keyboard.toml
@@ -10,7 +10,7 @@ chip = "stm32f411ce"
 # Input and output pins are mandatory
 input_pins = ["PD4", "PD8", "PD6", "PD7"]
 output_pins = ["PD5", "PD9", "PD10"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]

diff --git a/examples/use_config/stm32h7/keyboard.toml b/examples/use_config/stm32h7/keyboard.toml
@@ -10,7 +10,7 @@ chip = "stm32h7b0vb"
 # Input and output pins are mandatory
 input_pins = ["PD9", "PD8", "PB13", "PB12"]
 output_pins = ["PE13", "PE14", "PE15"]
-# WARNING: Currently row2col/col2row is set in RMK's feature gate, configs here do nothing actually
+# WARNING: Currently row2col/col2row is set in RMK's feature gate, row2col config here is valid ONLY when you're using cloud compilation
 # row2col = true
 
 [layout]