Beyond-KLE/journal/2026-10-29-square-matrix.md

二乗マトリクスの一般知識(ELC Editorの要検討の前提)

結論

• 二乗マトリクス: N本のピンがどれも駆動側にも受信側にもなる。キーは異なる2ピンの順序付きの組 (駆動, 受信) に1つ。 上限 N(N−1) キー。対角 (i, i) は使えない。考案は ikeji 氏(2019)。英語では Square / Round-robin / Charlieplex matrix。
• 実用されているのは改良二乗マトリクス(各ピンに追加ダイオード1つ)。素の二乗マトリクスは主要MCUでゴーストが出る。
• 通常・倍マトリクスは、二乗マトリクスの部分集合とみなせる(使うピンの組を row→col に限ったもの、その両向き)。
• 追加ダイオードはELCで持たない。マトリクス方式に依存し、位置が決定的なのでGeneratorで扱える(ユーザー判断)。
• QMKとZMKで row/col の向きが逆になる問題はGeneratorで扱う(ユーザー判断)。
• GND直結で対角を使う変形(N² キー)は標準対応しない。Directとの組み合わせで表せるかは、仕様が固まってから確認する(ユーザー判断)。

方式の比較(ikeji 2022)

方式	正常経路のダイオード数	ゴースト経路のダイオード数	成立条件
倍	1	3	Vf < Vth < 3Vf
二乗	1	2	Vf < Vth < 2Vf
改良二乗	2	4	2Vf < Vth < 4Vf

同じピン数Nでのキー数: 通常 N²/4、倍 N²/2、二乗 N(N−1)(N=18 で 81 / 162 / 306)。

ファームウェア

QMK

• 標準の二乗マトリクス対応はない。ただし標準機能の組み合わせで実現できる:
  • matrix_pins.rows と cols に同じピンを同じ順で並べる。
  • config.h に #define MATRIX_MASKED を置き、<keyboard>.c の matrix_mask で対角のビットを0にする。
• 対角のマスクは改良版かどうかに関係なく必須。Lowに駆動したrowピンを同じピンのcolとして読むので、常に押された扱いになる (gachiham: マスクしないとPCに認識されなくなった。STM32/RP2040)。
• matrix_mask は使わない位置も0にできる。対角はその一例。
• 実例 ewderna/cr0wn/cr0wn60(Dev/KBDs/qmk_firmware/keyboards/ewderna/cr0wn/cr0wn60): RP2040、9ピン(GP8 GP9 GP10 GP11 GP19 GP21 GP20 GP12 GP18)を rows/cols の両方に列挙、diode_direction: COL2ROW。 matrix_mask は row0〜6 で対角と未使用の位置を0にし、row7 は一部だけ1、row8 は全部0。
• 対応関係: row = Lowに駆動するピン、col = 読むピン。電流は col → row に流れる。

ZMK zmk,kscan-gpio-charlieplex

• 専用ドライバ。gpios にピンを並べるだけで、row/colの区別はない。
• interrupt-gpios なしで n本 → n(n−1)キー(ポーリング)。ありで (n−1)(n−2)キー(割り込み、省電力)。
  • 割り込みピンは gpios に含めない別のピン(ソース上、セルは gpios だけから作る)。
  • 待機中は全セルを出力1にし、割り込みピンのレベルを待つ。割り込みピンの配線はドキュメントに書かれていない。
  • 低電力改良二乗マトリクス(Cheena: 1ピンを復帰用にして (N−1)(N−2))と同じ構成と思われるが、回路は追えていない。
• キーの位置は matrix transform の RC(row, col) で書き、row = 駆動ピン、col = 受信ピン。対角は transform から除くよう明記されている。
• ドキュメントは GPIO_ACTIVE_HIGH を指定するよう求めている。この場合は入力プルダウン・High駆動で、電流は row → col に流れる。
  • QMK COL2ROW と逆向き。同じ基板では row/col が転置される。
  • ソース上は GPIO_ACTIVE_LOW ならプルアップ・Low駆動になり、QMKと同じ向きにできる。割り込みと併用できるかは未確認。
• 待ち時間の設定: CONFIG_ZMK_KSCAN_CHARLIEPLEX_WAIT_BEFORE_INPUTS / _WAIT_BETWEEN_OUTPUTS。

改良二乗マトリクスの追加ダイオードの位置

記事の図は読めなかった。以下は経路の段数から組み立てたもので、ユーザーの認識(各ピンに追加ダイオード)と合う。

• ピン i を、GPIOにつながる線 G_i と、ダイオード D_i(アノードが G_i 側)を挟んだ線 S_i に分ける。
• キー (駆動 a, 受信 b) は、S_b → G_a の向きのダイオードを付ける(QMK COL2ROW の場合)。
• 正常経路: G_b →D_b→ S_b →キー→ G_a で2段。
• ゴースト経路: G_c →D_c→ S_c →キー→ G_b →D_b→ S_b →キー→ G_a で4段。中継するピンでも D_b を通らされる。
• 回路図を格子に描くと D_i は対角 (i, i) の位置に来る。gachiham の「[0,0] はダイオードを入れているだけなのでスイッチとして使えない」と合う。

実測値(ikeji 2022)

MCU	Vth	Vf	2Vf	3Vf	4Vf
ATmega32u4	1.45〜1.56V	0.513V	1.034V	1.495V	1.963V
RP2040	1.26〜1.36V	0.474V	0.949V	1.418V	1.862V

• 素の二乗マトリクスは両MCUとも Vth > 2Vf で、ゴーストがLowと読まれる。改良版は両MCUとも成立する。
• ATmega32u4 では倍マトリクスの条件(Vth < 3Vf)が際どい。著者は測定条件(5V弱の電源、非選択線の電流)を疑っている。
• MCUとダイオードの相性は Vf と Vth の比で決まる。

出典

• ikeji 2019 キーボードの回路: https://blog.ikejima.org/make/keyboard/2019/12/14/keyboard-circuit.html (二乗マトリクスの初出。ゴーストはダイオード2つ分なので部品の組み合わせに注意、1キー2ダイオードが要るかも、と書いている)
• ikeji 2022 変則マトリクスキーボード設計: https://blog.ikejima.org/make/keyboard/2022/12/07/atypical-matrix-design.html
• gachiham QMK 0.19.2で改良二乗マトリクス: https://gachiham.hatenablog.com/entry/2022/12/17/000000 (9ピン72キーから63キー。rows/colsに同じピンを並べ、MATRIX_MASKEDを使う)
• Cheena でかいキーボード設計法: https://note.com/cheena/n/n846846c3efce(低電力改良二乗マトリクス)
• ZMK kscan: https://zmk.dev/docs/config/kscan
• ZMK ドライバ: https://raw.githubusercontent.com/zmkfirmware/zmk/main/app/module/drivers/kscan/kscan_gpio_charlieplex.c

捨てた記述

• 二乗マトリクスを e3w2q 氏の発案とした記憶は誤り。初出は ikeji 2019。