From a5580ed2f7fa6b8d30c12bfcf8f5a0c78da15a17 Mon Sep 17 00:00:00 2001 From: souvlakeeb Date: Thu, 9 Feb 2023 22:03:49 -0700 Subject: [PATCH 1/5] Discuss layout macro There is no mention or visualization of how to create a layout macro in `info.json` for split keyboards. @fauxpark helped me tremendously in Discord by creating and providing these visualizations to aid my understanding: https://cdn.discordapp.com/attachments/440868230475677698/1073409438712610907/image.png https://cdn.discordapp.com/attachments/440868230475677698/1073409562373259364/image.png I strongly feel these should be in the docs. I think it best to include a short discussion in the [split keyboard page](https://docs.qmk.fm/#/feature_split_keyboard), explaining that row pins are automatically doubled when setting `SPLIT_KEYBOARD = yes` and that QMK views the physical layouts according to those pictures. These are the pages I used to search for answers to the question: https://docs.qmk.fm/#/feature_split_keyboard https://docs.qmk.fm/#/porting_your_keyboard_to_qmk?id=layout-macros https://docs.qmk.fm/#/hardware_keyboard_guidelines?id=ltkeyboard_namehgt --- docs/feature_split_keyboard.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 616124004c71..704e108c283d 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -79,6 +79,17 @@ If you're using a custom transport (communication method), then you will also ne SPLIT_TRANSPORT = custom ``` +### Layout Macro +When setting `SPLIT_KEYBOARD = yes`, row pins are automatically doubled. +This is because QMK views a split keyboard as follows, with the numbers +representing row, column: + +IMG1 + +IMG2 + +Take care to define your layout in `info.json` accordingly. + ### Setting Handedness By default, the firmware does not know which side is which; it needs some help to determine that. There are several ways to do this, listed in order of precedence. From 331b862862b82a3d8cbbda5e62f516ef76d03ab9 Mon Sep 17 00:00:00 2001 From: souvlakeeb <109096368+souvlakeeb@users.noreply.github.com> Date: Fri, 10 Feb 2023 14:15:36 -0700 Subject: [PATCH 2/5] Add suggested change Co-authored-by: jack <0x6a73@protonmail.com> --- docs/feature_split_keyboard.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 704e108c283d..ff7114b43785 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -80,9 +80,7 @@ SPLIT_TRANSPORT = custom ``` ### Layout Macro -When setting `SPLIT_KEYBOARD = yes`, row pins are automatically doubled. -This is because QMK views a split keyboard as follows, with the numbers -representing row, column: +When configuring a split keyboard, note the matrix rows and pins are doubled, thus QMK views the layout as follows, where the numbers represent `row, col`: IMG1 From dd5b3c2b86767259d4f695d97a1f46978031e829 Mon Sep 17 00:00:00 2001 From: souvlakeeb <109096368+souvlakeeb@users.noreply.github.com> Date: Sat, 11 Feb 2023 21:23:09 -0700 Subject: [PATCH 3/5] Add suggested change Co-authored-by: Ryan --- docs/feature_split_keyboard.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index ff7114b43785..6909fad53356 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -80,13 +80,14 @@ SPLIT_TRANSPORT = custom ``` ### Layout Macro -When configuring a split keyboard, note the matrix rows and pins are doubled, thus QMK views the layout as follows, where the numbers represent `row, col`: -IMG1 +Configuring your layout in a split keyboard works slightly differently to a non-split keyboard. Take for example the following layout. The top left numbers refer to the matrix row and column, and the bottom right are the order of the keys in the layout: -IMG2 +![Physical layout](https://i.imgur.com/QeY6kMQ.png) -Take care to define your layout in `info.json` accordingly. +Since the matrix scanning procedure operates on entire rows, it first populates the left half's rows, then the right half's. Thus, the matrix as QMK views it has double the rows instead of double the columns: + +![Matrix](https://i.imgur.com/4wjJzBU.png) ### Setting Handedness From 98b34c33848782205f43c46596d5143af84c9845 Mon Sep 17 00:00:00 2001 From: souvlakeeb Date: Fri, 10 Feb 2023 14:12:54 -0700 Subject: [PATCH 4/5] Add see also --- docs/porting_your_keyboard_to_qmk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md index e6a3a72cda24..a3c6557d9933 100644 --- a/docs/porting_your_keyboard_to_qmk.md +++ b/docs/porting_your_keyboard_to_qmk.md @@ -150,6 +150,8 @@ In the above example, * It must conform to the [layout guidelines](hardware_keyboard_guidelines.md#ltkeyboard_namehgt) * `"matrix": [0, 0]` defines the electrical position +?> See also: [Split Keyboard Layout Macro](https://docs.qmk.fm/#/feature_split_keyboard?id=Layout Macro) and [Matrix to Physical Layout](https://docs.qmk.fm/#/understanding_qmk?id=matrix-to-physical-layout-map). + ## Additional Configuration There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config.md). The following sections cover the process for when an `info.json` option is unavailable. From 06452b3de7f63e64522b7dc575984e2b0e478153 Mon Sep 17 00:00:00 2001 From: souvlakeeb Date: Sat, 11 Feb 2023 21:37:43 -0700 Subject: [PATCH 5/5] Fix url --- docs/porting_your_keyboard_to_qmk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/porting_your_keyboard_to_qmk.md b/docs/porting_your_keyboard_to_qmk.md index a3c6557d9933..b0213a6d7005 100644 --- a/docs/porting_your_keyboard_to_qmk.md +++ b/docs/porting_your_keyboard_to_qmk.md @@ -150,7 +150,7 @@ In the above example, * It must conform to the [layout guidelines](hardware_keyboard_guidelines.md#ltkeyboard_namehgt) * `"matrix": [0, 0]` defines the electrical position -?> See also: [Split Keyboard Layout Macro](https://docs.qmk.fm/#/feature_split_keyboard?id=Layout Macro) and [Matrix to Physical Layout](https://docs.qmk.fm/#/understanding_qmk?id=matrix-to-physical-layout-map). +?> See also: [Split Keyboard Layout Macro](https://docs.qmk.fm/#/feature_split_keyboard?id=layout-macro) and [Matrix to Physical Layout](https://docs.qmk.fm/#/understanding_qmk?id=matrix-to-physical-layout-map). ## Additional Configuration