このリポジトリは Keyball シリーズ用ファームウェア（QMK+vialベース）です。
keyball公式を元に、RP2040系として個人的に作成したものです。
トラブル等は公式には問い合わせず、こちらのリポジトリのissueへお願いします。
機能としては、vial対応、スワイプ（マウスジェスチャ）、振動モーター対応、擬似フリック入力、OLEDでの挙動調整などを追加しています。
ドキュメントやソースコードに関しては生成AIを使用している箇所が多々あります。確認はしておりますが、誤りや不備がある場合は伝えていただけると幸いです。

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y git build-essential gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi
git clone --recurse-submodules https://github.com/toxaO/keyball.git
cd keyball
bash scripts/setup_and_build.sh  # 初回セットアップ（ビルドは行わない）
# user版は筐体別・レイアウト別に `user_dual` / `user_left` / `user_right` を指定してください
make -C vial-qmk SKIP_GIT=yes VIAL_ENABLE=yes keyball/keyball39:user_dual
# すべての user レイアウトをまとめてビルドする場合
bash scripts/build_user_maps.sh

scripts/setup_and_build.sh は make / arm-none-eabi-gcc の存在確認と、vial-qmk へのシンボリックリンク作成のみを行います（ビルドは行いません）。未導入のまま実行すると不足パッケージの警告が表示されます。

※ git clone --recurse-submodules を忘れた場合は、クローン後に git submodule update --init --recursive で補完してください。 ※ Docker でのセットアップを推奨しています。詳細は docs/docker_setup.md を参照してください。

• keyball … キーボード本体の実装
• keyball/lib … キーボード共有（KBレベル）のライブラリ
• keyball/lib_user … ユーザーレベルの実装
  • keyball/lib_user/user … 頒布用キーマップ（誰でも編集可）
  • keyball/lib_user/toxaO … toxaO 用の個人設定（サンプル）
• qmk_firmware … 公式 QMK へのリンク用ツリー
• vial-qmk … Vial 対応 QMK ツリー
• scripts … セットアップスクリプト群
• build … ビルド済み .uf2 の置き場
• docs/releases … バージョン別のリリースノート

• 頒布用キーマップは keyball/lib_user/user に配置されています。自身の設定を共有する場合はここを編集し、筐体/配列ごとに keyball/keyball{39,44,61}:user_{dual,left,right} を指定してビルドしてください。
• keyball/lib_user/toxaO は toxaO の常用設定です。挙動のサンプルとして参考にしてください。
• build/ 配下には頒布用の最新 .uf2 を随時更新して格納します。

• RP2040 へ載せ替えが必要です。ATmega32U4系promicro(普通のkeyballで使用しているボード)のままでは使用できません）
• 必要ボード: 下記いずれか
  • AliExpressの本品
  • RP2040 ProMicro 互換（4MBで可）

• I2C 接続の DRV2605L モジュール（例: Adafruit DRV2605L Haptic Driver）+ LRA/ERM モーターを左右に搭載すると振動フィードバックを利用できます。
• 動作確認パーツ
  • DRV2605Lモジュール)
  • LRAモーター
• 任意のケーブルでRP2040 側の SDA/SCL/3V/GND を DRV2605L に接続し、必要に応じて ENABLE ピンをプルアップしてください（私はプルアップせずに使用していますが問題ないようです）。
• OLED 設定の「SW_Hp conf」「Ly_Hp conf」「AML haptic」各ページから、スワイプ/レイヤー/AML 遷移時の振動モード番号や有効・無効をで調整できます。設定値は KBC_SAVE で EEPROM（kbpf）へ保存され、PC 再接続後も保持されます。

• 対応のボードのシルク（端子の記載）をよく確認の元、お手持ちのkeyballの仕様に合うようにコンスルーかピンヘッダを使用して取り付けてください。
• ※一度コンスルー（ピンヘッダ）をはんだ付けしてしまうと取り外すのが大変なので、取り付け向きに関してはよく確認してください。※
• 確認しているボードでは、リセットスイッチが下側（取り付けると隠れてしまう側）に来るように取り付けることになります。
• 取り付ける前に、RP2040へファームを書き込んでください。新品のrp2040ボードは、BOOTボタンを押しながらPCに接続するとストレージとして認識されるので、そこにファームウェアのファイル(.uf2ファイル)をコピーしてください。
• 一度ファームウェアを書き込み基板に取り付けた後は、keyballのリセットスイッチ（タクトスイッチ）を素早く2回押すことで、PCに書き込み可能モード（ストレージとしての認識）になります。
• またはキーコード(QK_BOOT)を使用しても良いです。
• 取り付ける向きは画像の面が上を向くようにしてください。（promicro互換ボードのリセットボタンが隠れます）
• 振動モーターを使用する場合は、写真を参考にピンとDRV2605Lとモーターをケーブルで接続してください。モーターの取り付け位置や固定度合いで振動の感じ方が変わります。ケースは各々のものがあると思いますので試行錯誤してください。左右それぞれに取り付け可能ですが、片側のみでも動作します。

• このファームをmacで使用する場合、karabiner-elementsを使用して、right-controlをFnに変更することを強く推奨します。
• QMKではmacのキーボードに存在するFnキーに対応するキーコードがありません。そのためこのファームでは右コントロールキーをFnキーとして認識するようにkarabinerで変換することを前提として一部のキーを設定しています。詳細に関してはlib_user/user/keycode_user.hやlib_user/user/feature/macro_user.cを参照してください。（基本的なKC_系に関しては手を加えていないので、気にしなくて大丈夫です）
• vial上ではRALT(KC_F*)、ビルドできる方はキーマップにキーコードF1を割り当てると、macではRCTL(KC_F1)からkarabinerの変換を得てFn(KC_F1)として動作するようになります。その他のOSではF1はKC_F1として動作します。

• mac mouse fixも導入することを推奨します。
• スクロール動作が滑らかになり、MS_BTN4やMS_BTN5に機能を登録することでズームなどを実現できます。

• vialでRALT(KC_C)などを割り当てた場合、macではLGUI(KC_C)、その他ではLCTL(KC_C)として動作するようになっています。（典型的なキーコードのみの対応となっています）

• vial web appかvial デスクトップアプリをご利用ください

• SW系のキーを押しながら、上下左右にスワイプすることで、アプリ切替や音量調整などが可能。
• swipe_user.cの実装を変更することで、機能を追加できます。

• HAPTIC_DRIVER = drv2605l により、スワイプ／AML／レイヤー切り替え時に DRV2605L 経由で左右別の振動を再生できます。
• OLED の SW_Hp conf ページではスワイプの初回/2回目以降の振動モードや連続振動認識リセット時間（Idle）、テスト再生を操作できます。(初回は強く、連続で動作させる2回目以降は弱くするなどの使用を想定した機能です)
• Ly_Hp conf ページでは各レイヤーごとに左・右の振動の有効/無効とモード番号を設定可能です。
• AML haptic ページでは Auto Mouse Layer の遷移時(in/out)で振動するモードとon/offを設定できます。

• Flick_系のキーを押しながら、上下左右にスワイプまたはMULTI_{A, B, C}を押下することで、方向に応じた文字入力が可能。
• MULTI_Aは左、Bは右、Cの単体タップは上、Cのダブルタップは下に対応しています。

• どのスワイプキーを押しているかによって押した際の機能が変わります。
• multi_user.cの実装を変更することで、機能を追加できます。

• lib_user/user/user/oled_user.cで通常画面の表示内容を変更できます。

• SET_TOGキーを押すと、OLEDが設定モードに切り替わります。（再度押すと通常画面に戻ります。）
• 上下キーでカーソルの移動。左右キーでページ移動。Shift+左右キーで値の増減が可能です。
• 設定はKBC_SAVEキーで保存されます。KBC_RSTキーで初期化されます。OS毎に設定が保存されます。
• ご自分でビルドされる方は、lib/keyball/keyball.hで設定されているマクロをkeyball/.../keymap/user/config.hで上書きすることで初期値を変更できます。
• ページ構成は以下の通りです（RGBLIGHT/HAPTICが無効な場合は該当ページが省略されます）。

• Sp: (Mouse speed)ポインタの速度
• GaL: (Gain low speed)低速域のゲイン。低速域ではポインタの速度がここで指定した割合になります。
• Th1/Th2: (Threshold1/2)低速域のしきい値。Th1以下ではMoSpの(Glo)%、Th1～Th2では線形補間されたゲイン、Th2以上ではMoSpの速度になります。
• DZ: (DEAD ZONE)この値以下のボールの動作は無視されます。

• en: (enable) オートマウスレイヤーの有効/無効
• TO: (Time Out)設定の時間(ms)が経過するまでマウスレイヤーに留まります。500ms単位で増減。9500より大きく設定しようとすると、HOLDとして60秒間の設定となります。
• AMLはマウスキー以外のボタンを押すことで解除されます。（マウスキー：MS_BTN1やスワイプキー。util_user.cで追加設定できます。）
• TH: AUTO MOUSE LAYERの閾値。ポインタの移動量がこれを超えるとAMLが有効になります。
• TG_L: (Target Layer)AMLが有効になったときの切り替え先レイヤー番号。

• IN/OUT: Auto Mouse Layer の遷移/解除で振動させるかどうか。
• INf/OUTf: それぞれに割り当てる DRV2605L のエフェクト番号（1〜123程度）。

• Sp: (Scroll Speed)スクロールのステップ。1～7で設定可能。
• Dz: (DEAD ZONE)この値以下のボールの動作は無視されます。
• Iv: (Invert)スクロールの反転フラグ（OS別）。
• ScLy/LNo: 任意のレイヤーでスクロールモードを常時有効化するトグルとレイヤー番号。
• Md: (Mode) m:macモード、f:高精度モード、n:標準モード。macでは高精度モードを使用できません。
• H_Ga: (Horizontal Gain)スクロール最終ゲインの水平成分。垂直成分に対する割合(%)。左右方向のスクロールを遅くしたい場合に調整します。

• Mode: ver/ hor/ free。一方向へのスクロールを優先し、一定以上の量を超えた場合にフリースクロールになります。freeは常にフリースクロールです。
• Thr: (Threshold) ver/horモードでフリースクロールに切り替わる閾値。
• Rst: フリースクロールでいる時間。

• スクロール変換前後の生値（x/y/h/v）と内部加速度（ah/av）、テンション値(t)をリアルタイムで表示します。チューニング時の目視用です。

• Th: (Swipe Threshold) スワイプと判定する移動量の閾値
• Dz: (Dead Zone) この値以下のボールの動作は無視されます。
• Rt: (Reset Time) スワイプ動作のリセット時間(ms)。この時間内に閾値を超える動作がなければ、スワイプ動作用の移動量はリセットされます。
• Frz: (Freeze) スワイプ中にポインタを固定するかどうか。

• アクティブ状態（Ac）、現在のタグ（Md）、方向（Dir）、各方向の蓄積値（U/D/R/L）を確認できます。誤判定時のデバッグに利用してください。

• light on/off（offの時は以下の設定を変更できません）
• HUE (色相)。
• SAT (彩度)。
• VAL (明度)。
• Mode アニメーションモード。(一部モードではHUE, SAT, VALは変更できません)

• En: スワイプ時のハプティックを有効／無効。
• 1st: 1方向目のエフェクト番号。
• 2nd~: 連続スワイプ時に使用するエフェクト番号。
• Idle: 連続スワイプとして認識される時間。
• Test: カーソルを合わせて Shift+左右 でエフェクトをテスト再生。

• Ly: 設定対象のレイヤー番号。
• L/R: 左右の振動を個別に ON/OFF。
• Mode: それぞれのエフェクト番号。

• 現在の LED インデックスを表示し、該当 LED のみを青色で点灯させます。配線チェックや個別点灯確認に利用できます。 keyball_led_set_hsv_at() / keyball_led_set_hsv_range() を使用すると自動的に RPC 同期され、slave側のLEDも点灯させられます。

  #include "lib/keyball/keyball_led.h"
  
  void indicate_layer_change(void) {
      keyball_led_set_hsv_at(HSV_WHITE, 10);        // LED10 を白に
      keyball_led_set_hsv_range(HSV_RED, 20, 3);    // LED20～22 を赤に
  }

  これらの関数は内部で rgblight_sethsv_* を呼びつつ、分割構成では KEYBALL_LED_SYNC RPC により反対側へも同じ指示を送ります。より細かい制御を行いたい場合は keyball_led_monitor.c の実装を参考に独自の同期処理を追加してください。

• def: (Default Layer) デフォルトレイヤーとするレイヤー番号。default_layer_set と連動します。

• 直近に送出したキーコード・レイヤー・(row,col)・修飾キー状態を表示します。キースキャンの確認やデバッグに利用できます。

• APIや詳細仕様は keyball/lib/keyball/README.md を参照。

• シェルスクリプトによる導入（MSYS2/macOS/Ubuntu想定）
  • bash scripts/setup_and_build.sh
  • 依存確認→vial-qmk へのシンボリックリンク作成（ビルドは行いません）
• Vial 上でキーマップの編集が可能です（Vial対応ビルドを使用）。
• Docker でのセットアップを推奨しています。詳細は docs/docker_setup.md を参照してください。

• build/ ディレクトリにビルド済みファームが入っています（必要に応じて更新）。

• 公式ではなく、こちらへお願いします: https://x.com/toxa_craft
• issueでも可能。