# 二乗マトリクスの一般知識(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: ikeji「キーボードのマトリクス方式の分類」ikejiのblog、2019-12-14
    - 参照先: <https://blog.ikejima.org/make/keyboard/2019/12/14/keyboard-circuit.html>
    - 二乗マトリクスの初出。ゴーストはダイオード2つ分なので部品の組み合わせに注意、1キー2ダイオードが要るかも、と書いている。
- ikeji 2022: ikeji「変則マトリクスキーボード設計」ikejiのblog、2022-12-07
    - 参照先: <https://blog.ikejima.org/make/keyboard/2022/12/07/atypical-matrix-design.html>
- gachiham: gachiham「QMK 0.19.2で改良二乗マトリクスのキーボードファームウェアを作っていく話」gachiham's blog、2022-12-17
    - 参照先: <https://gachiham.hatenablog.com/entry/2022/12/17/000000>
    - 9ピン72キーから63キー。rows/colsに同じピンを並べ、MATRIX_MASKEDを使う。
- Cheena: Cheena「自作キーボード初心者のためのでかいキーボード設計法」note、2025-05-26(2025-09 追記あり)
    - 参照先: <https://note.com/cheena/n/n846846c3efce>
    - 低電力改良二乗マトリクス。
- ZMK kscan: 「Keyboard Scan Configuration」ZMK Firmware ドキュメント
    - 参照先: <https://zmk.dev/docs/config/kscan>
- ZMK ドライバ: zmkfirmware/zmk のソース `app/module/drivers/kscan/kscan_gpio_charlieplex.c`(main ブランチ)
    - 参照先: <https://raw.githubusercontent.com/zmkfirmware/zmk/main/app/module/drivers/kscan/kscan_gpio_charlieplex.c>

## 捨てた記述

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