[Core] Add bidirectional and duplex matrix code #8160

elfmimi · 2020-02-13T12:58:26Z

Description

Two things.

1st) Now that we have more than one keyboards that utilize duplexing of matrix by deploying both COL2ROW and ROW2COL at the same time. Namely those keyboards are:

I suggest bringing the so to called COL2ROW2COL code into the core. I labeled it BOTHWAYS .
I've asked the author of those keyboards to test this code. and the result was perfect.

2nd) Using the fact that the technique above fully functions without ghost and with NKRO-bility, it can be proved that key-matrix with inconsistent diode direction can also be made to function, provided proper lines of code. It's worth noting the code for this is also compatible with both COL2ROW and ROW2COL at the same time. I labeled it EITHERWAY .

~~I suggest using EITHERWAY as a new default for when DIODE_DIRECTION is not defined.~~
This part is taken back.

This PR will not increase footprints of flash-rom or ram for any of the existing keyboards. It even reduces a few bytes for some split keyboards utilizing split_common.

I've also tested BOTHWAYS and EITHERWAY with my one-off experimental keyboard which has STM32F303, and it too worked great.

Minimum extent of documentation is included.
I'm planning to do extended and in-detail guide later on. after this is accepted.

Refer to Fixed: inconsistent MATRIX_COLS and MATRIX_COL_PINS in facew. #8115 for the first commit of the two. This is to stop Travis from complaining.

Types of Changes

Checklist

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
I have tested the changes and verified that they work and don't break anything (as well as I can manage).

elfmimi · 2020-02-13T15:06:13Z

Schematic drawing of Angel64 can be found here.
https://github.com/kakunpc/angel/blob/master/angel64/debug/README.md

Concerning documentation the part I want to change the most is this line.

So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro

https://docs.qmk.fm/#/hand_wire

Fullsize keyboard is possible with a single ProMicro.

quantum/config_common.h

quantum/matrix.c

elfmimi · 2020-02-28T20:01:06Z

Updated according to the requests. (except the symbol names)
Minimal extent of document is added.

skullydazed · 2020-03-01T17:28:24Z

This is pretty awesome, thank you for bringing it to core. I haven't reviewed the code in detail yet but I'm excited about what it will mean for custom keyboards.

I'm planning to do documentation later on. after this is accepted.

We'll be able to review the code and test it out, but we'll need documentation on how EITHERWAY and BOTHWAY work before we can merge this.

elfmimi · 2020-03-02T03:00:47Z

description updated.

elfmimi · 2020-03-02T11:03:39Z

cope with qmk cformat (clang-format).

elfmimi · 2020-03-02T11:23:53Z

For reference, here is an example how to apply BOTHWAYS to the-dog-keyboard.
elfmimi@d1b7505

The matrix of this keyboard can be found here. #7401 (comment)
https://user-images.githubusercontent.com/15257475/69113624-de717000-0ac6-11ea-8f0b-d603c023e05b.png

emilytrau · 2020-03-04T21:34:04Z

The matrix of this keyboard can be found here. #7401 (comment)
https://user-images.githubusercontent.com/15257475/69113624-de717000-0ac6-11ea-8f0b-d603c023e05b.png

Hi! Won't this matrix ghost after you press 3 keys? eg. SW1, SW57 and SW8 would cause SW7 to trigger.

elfmimi · 2020-03-08T17:04:18Z

That's a real good question. The answer is, It won't! Because Vf * 3 > Vih .
(for commodity diodes like 1N4148)
@angustrau

sowbug · 2020-04-10T01:22:21Z

The matrix of this keyboard can be found here. #7401 (comment)
https://user-images.githubusercontent.com/15257475/69113624-de717000-0ac6-11ea-8f0b-d603c023e05b.png

I might be missing something obvious. That link shows a standard matrix, not a duplex one. It has six rows and twenty columns, all the diodes go in the same direction, and every switch belongs to exactly one physical row and column. Did you mean to post a different image?

elfmimi · 2020-04-10T05:02:11Z

@sowbug Please take a look once again closely. In the left half of the matrix diodes are pointing upward (ROW2COL) and in the right half downward (COL2ROW) .

sowbug · 2020-04-10T05:15:58Z

Yes, I see now. I was looking at adjacent diodes expecting them to alternate direction. Thank you!

quantum/config_common.h

elfmimi · 2020-05-06T09:53:36Z

@hineybush's episode is a strikingly well suited example which showcase the enhancement this PR enables.
Though it surely is unwanted accident for him, I'm very proud that I could lend him a helping hand in this.

I heard some voices of anticipation hoping this PR get merged.
So I'm here to provide a quick recap.

At first there was no document, but I've already done decent documentation in the later commit.
Thus 'need doc' label does not apply anymore.

I beleave we've had more than enough time for people to swallow and consume the concept of this PR.
Just in case, there may be someone reading this who find oneself feeling kind of not fully understanding. It's okay. It is not because of lack of documentation. It is because of lack of knowledge in electronics. Just let it go. (possibly offensive language censored)
It really is as simple as "Doing COL2ROW and ROW2COL at the same time." , really.

What left was @fauxpark's statement about his fondness toward the wacky name of COL2ROW2COL.
I think that listing COL2ROW2COL next to COL2ROW and ROW2COL will make those two basic options look more complicated than it is. Especially for someone who is new to QMK. On the other hand, EITHERWAY and BOTHWAYS will definitely look as advanced options. Also you can speculate what they do from their names.
The bottom line is I'm not going to change those names.
I'll welcome usages of COL2ROW2COL as a nickname to BOTHWAYS.

This PR is ready to merge.

skullydazed

Just in case, there may be someone reading this who find oneself feeling kind of not fully understanding. It's okay. It is not because of lack of documentation. It is because of lack of knowledge in electronics. Just let it go.

Please be careful with statements like this. QMK is welcoming to people of all skills levels, and one of our primary missions is to educate. Making confrontational statements runs counter to our code of conduct.

The bottom line is I'm not going to change those names.

I understand your frustration with this process. We've learned through hard-won experience that names matter, and are nearly impossible to change. (See the various ways the word keymap is used in different context as just one example.) That's why we have these conversations, to find the names that are going to be the least confusing in the long run.

As things stand right now we feel that there is not enough distinction between the plain meaning of EITHERWAY and BOTHWAYS for those terms to be used. In particular, people with reading disabilities like dyslexia may have a hard time distinguishing between them. I've suggested names that do not suffer from this ambiguity.

skullydazed · 2020-03-02T18:03:49Z

docs/config_options.md

+  * COL2ROW , ROW2COL , EITHERWAY or BOTHWAYS - how your matrix is configured.
+  * COL2ROW means the black mark on your diode is facing to the rows or facing away from the cols. This is considered the preferred choice in QMK when you are planning a new design.
+  * ROW2COL means the opposide. The black mark on your diode is facing to the cols or facing away from the rows.
+  * EITHERWAY is useful as compensation when a matrix has diodes messed up with their directions. This works prorerly even when arbitrary number of diodes are soldered wrong way. That means this setting is compatible with COL2ROW matrix and ROW2COL matrix at the same time.
+  * BOTHWAYS is a new strategy to reduce number of pins required to drive a matrix. Compared to a conventional matrix twice the number of keys can be handled. This is considered an advanced topic and will be discussed separately.


We've been talking about this one internally and while we aren't in total agreement on the names we think these will work better.

Suggested change

* COL2ROW , ROW2COL , EITHERWAY or BOTHWAYS - how your matrix is configured.

* COL2ROW means the black mark on your diode is facing to the rows or facing away from the cols. This is considered the preferred choice in QMK when you are planning a new design.

* ROW2COL means the opposide. The black mark on your diode is facing to the cols or facing away from the rows.

* EITHERWAY is useful as compensation when a matrix has diodes messed up with their directions. This works prorerly even when arbitrary number of diodes are soldered wrong way. That means this setting is compatible with COL2ROW matrix and ROW2COL matrix at the same time.

* BOTHWAYS is a new strategy to reduce number of pins required to drive a matrix. Compared to a conventional matrix twice the number of keys can be handled. This is considered an advanced topic and will be discussed separately.

* `COL2ROW`, `ROW2COL`, `EITHER` or `DUPLEX_SCAN` - how your matrix is configured.

* `COL2ROW` means the black mark on your diode is facing to the rows or facing away from the cols. This is considered the preferred choice in QMK when you are planning a new design.

* `ROW2COL` means the opposite. The black mark on your diode is facing to the cols or facing away from the rows.

* `EITHER` is useful as compensation when a matrix has diodes messed up with their directions. This works properly even when arbitrary number of diodes are soldered wrong way. That means this setting is compatible with `COL2ROW` matrix and `ROW2COL` matrix at the same time.

* `DUPLEX_SCAN` is a new strategy to reduce number of pins required to drive a matrix. Compared to a conventional matrix twice the number of keys can be handled. See the section below on using `DUPLEX_SCAN`.

skullydazed · 2020-05-06T16:36:56Z

keyboards/facew/config.h

@@ -31,7 +31,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define MATRIX_COLS 11

 #define MATRIX_ROW_PINS { B0, B1, B2, B3, B4, B5, B6, B7 }
-#define MATRIX_COL_PINS { A0, A1, A2, A3, A4, A5, A6, A7, C7, C6}
+#define MATRIX_COL_PINS { A0, A1, A2, A3, A4, A5, A6, A7, C7, C6, C5 }


Suggested change

#define MATRIX_COL_PINS { A0, A1, A2, A3, A4, A5, A6, A7, C7, C6, C5 }

#define MATRIX_COL_PINS { A0, A1, A2, A3, A4, A5, A6, A7, C7, C6}

This change is not relevant to this PR.

hineybush · 2020-05-13T00:28:03Z

That's a real good question. The answer is, It won't! Because Vf * 3 > Vih .
(for commodity diodes like 1N4148)
@angustrau

it actually does cause ghosting. I shipped a few of my "broken" hbcp PCBs out and a customer has had an issue with keys triggering while holding down three others (left shift, left ctrl and left arrow triggers right shift).

luckily I can fix this with the "fixed" PCBs with the correct diodes, once I get them in..

elfmimi · 2020-05-13T01:35:57Z

@hineybush Thank you for sharing your experience with us! I really appreciate it.
You are right. from AT90USB128s' datasheet

31.2 DC characteristics
Vih (min) = 0.6VCC

This will showcase a failure example. Ironically.
Too bad I couldn't help you, @hineybush .

Definitely, I will add a description on this matter.

stale · 2020-06-27T01:41:14Z

Thank you for your contribution!
This pull request has been automatically marked as stale because it has not had activity in the last 45 days. It will be closed in 30 days if no further activity occurs. Please feel free to give a status update now, or re-open when it's ready.
For maintainers: Please label with awaiting review, breaking_change, in progress, or on hold to prevent the issue from being re-flagged.

tzarc · 2021-10-30T23:47:26Z

Has conflicts, and unapplied suggestions.
Removed the on-hold label so stalebot can eventually close it.

stale · 2022-01-03T21:45:13Z

Thank you for your contribution!
This pull request has been automatically marked as stale because it has not had activity in the last 45 days. It will be closed in 30 days if no further activity occurs. Please feel free to give a status update now, or re-open when it's ready.
For maintainers: Please label with awaiting review, breaking_change, in progress, or on hold to prevent the issue from being re-flagged.

stale · 2022-04-17T09:33:37Z

Thank you for your contribution!
This pull request has been automatically closed because it has not had activity in the last 30 days. Please feel free to give a status update now, ping for review, or re-open when it's ready.

kbrock · 2022-11-07T20:19:10Z

This is very cool and the diffs are relatively minor.

Is there any chance for this code?
Does it make sense for someone to try and revive this PR to get it into the code base? Or has this ship sailed?

elfmimi · 2022-11-17T04:47:55Z

@kbrock I believe anyone can pick this up and continue working on it. because it is already openly released code under the same GPL license.

NoOne2246 · 2024-01-31T13:14:10Z

Hello,

Looking at the changes to the master branch since 2022 Feburary regarding the changes of matrix_read_rows_on_col
as well as the merging of matrix.c between split hands and the regular matrix, I did a rewrite in the following commit.

NoOne2246@883e34f

It might take a few weeks before I can get time to build a test keyboard for the code.
Just wondering if I should create a new pull request when ready or if it is best practice to merge this into elfmimi's code in this pull request.

The documentation that I plan to update:

https://docs.qmk.fm/#/reference_info_json?id=matrix
https://docs.qmk.fm/#/config_options?id=hardware-options
https://docs.qmk.fm/#/how_a_matrix_works (maybe, or include in following)
New page on keyboard building specific to Duplex Matrix Keyboard
- Controller and Diode choice
- Layout specific
- Software configuration

elfmimi · 2024-02-01T00:10:13Z

Hi! I'd say you should better create another pull request for your new revised construct.
As for the commit history, do it any way you feel comfortable. @NoOne2246

fauxpark requested changes Feb 13, 2020

View reviewed changes

quantum/config_common.h Outdated Show resolved Hide resolved

quantum/matrix.c Outdated Show resolved Hide resolved

quantum/matrix.c Outdated Show resolved Hide resolved

drashna added core enhancement needs doc labels Feb 13, 2020

elfmimi force-pushed the bidirectional-and-duplex-matrix branch from 802cb90 to a1d5b93 Compare February 28, 2020 18:28

elfmimi marked this pull request as ready for review February 28, 2020 18:34

elfmimi force-pushed the bidirectional-and-duplex-matrix branch from a1d5b93 to 73e66d7 Compare February 28, 2020 19:54

[Keyboard] Fixed inconsistent MATRIX_COLS and MATRIX_COL_PINS: facew

995ca32

elfmimi force-pushed the bidirectional-and-duplex-matrix branch from 73e66d7 to 78ffea9 Compare February 29, 2020 22:46

elfmimi requested a review from fauxpark February 29, 2020 22:48

drashna requested a review from a team March 1, 2020 01:16

[Core] Add bidirectional and duplex matrix code

b2aae55

elfmimi force-pushed the bidirectional-and-duplex-matrix branch from 78ffea9 to b2aae55 Compare March 2, 2020 11:03

fauxpark added the feature label Mar 3, 2020

sowbug mentioned this pull request Mar 17, 2020

Add duplex matrix option sowbug/keycad#28

Open

nooges reviewed Apr 13, 2020

View reviewed changes

quantum/config_common.h Show resolved Hide resolved

hineybush mentioned this pull request Apr 14, 2020

[Keyboard] add dual-direction diode capability for hbcp #8795

Merged

13 tasks

skullydazed requested changes May 6, 2020

View reviewed changes

stale bot added the awaiting changes label Jun 27, 2020

tzarc added the on hold label Jul 16, 2020

stale bot removed the awaiting changes label Jul 16, 2020

elfmimi mentioned this pull request Mar 7, 2021

Consistency check of MATRIX size against the number of defined pins #12151

Closed

14 tasks

tzarc requested review from skullydazed and nooges October 30, 2021 23:45

tzarc changed the base branch from master to develop October 30, 2021 23:46

tzarc removed the on hold label Oct 30, 2021

tzarc added the stale Issues or pull requests that have become inactive without resolution. label Nov 5, 2021

stale bot added the awaiting changes label Jan 3, 2022

stale bot closed this Apr 17, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Core] Add bidirectional and duplex matrix code #8160

[Core] Add bidirectional and duplex matrix code #8160

elfmimi commented Feb 13, 2020 •

edited

Loading

elfmimi commented Feb 13, 2020

elfmimi commented Feb 28, 2020

skullydazed commented Mar 1, 2020

elfmimi commented Mar 2, 2020

elfmimi commented Mar 2, 2020

elfmimi commented Mar 2, 2020 •

edited

Loading

emilytrau commented Mar 4, 2020

elfmimi commented Mar 8, 2020

sowbug commented Apr 10, 2020

elfmimi commented Apr 10, 2020

sowbug commented Apr 10, 2020

elfmimi commented May 6, 2020 •

edited

Loading

skullydazed left a comment

skullydazed Mar 2, 2020

skullydazed May 6, 2020

hineybush commented May 13, 2020

elfmimi commented May 13, 2020

stale bot commented Jun 27, 2020

tzarc commented Oct 30, 2021

stale bot commented Jan 3, 2022

stale bot commented Apr 17, 2022

kbrock commented Nov 7, 2022

elfmimi commented Nov 17, 2022 •

edited

Loading

NoOne2246 commented Jan 31, 2024

elfmimi commented Feb 1, 2024

	#define MATRIX_COL_PINS { A0, A1, A2, A3, A4, A5, A6, A7, C7, C6, C5 }
	#define MATRIX_COL_PINS { A0, A1, A2, A3, A4, A5, A6, A7, C7, C6}

[Core] Add bidirectional and duplex matrix code #8160

[Core] Add bidirectional and duplex matrix code #8160

Conversation

elfmimi commented Feb 13, 2020 • edited Loading

Description

Types of Changes

Checklist

elfmimi commented Feb 13, 2020

elfmimi commented Feb 28, 2020

skullydazed commented Mar 1, 2020

elfmimi commented Mar 2, 2020

elfmimi commented Mar 2, 2020

elfmimi commented Mar 2, 2020 • edited Loading

emilytrau commented Mar 4, 2020

elfmimi commented Mar 8, 2020

sowbug commented Apr 10, 2020

elfmimi commented Apr 10, 2020

sowbug commented Apr 10, 2020

elfmimi commented May 6, 2020 • edited Loading

skullydazed left a comment

Choose a reason for hiding this comment

skullydazed Mar 2, 2020

Choose a reason for hiding this comment

skullydazed May 6, 2020

Choose a reason for hiding this comment

hineybush commented May 13, 2020

elfmimi commented May 13, 2020

stale bot commented Jun 27, 2020

tzarc commented Oct 30, 2021

stale bot commented Jan 3, 2022

stale bot commented Apr 17, 2022

kbrock commented Nov 7, 2022

elfmimi commented Nov 17, 2022 • edited Loading

NoOne2246 commented Jan 31, 2024

elfmimi commented Feb 1, 2024

elfmimi commented Feb 13, 2020 •

edited

Loading

elfmimi commented Mar 2, 2020 •

edited

Loading

elfmimi commented May 6, 2020 •

edited

Loading

elfmimi commented Nov 17, 2022 •

edited

Loading