Cqa02303v5rpi-01

HIDloom

HIDloomは、Linux SBCをprogrammable keyboard applianceとして動かすsoftware projectです。GPIO matrix / charlieplex scan、USB HID gadget、BLE HID keyboard/mouse、Vial、HTTP UI、LED/OLED表示、analog stick、runtime keymapをまとめて扱います。cqa02303v5は最初のdevice profileです。

まず見る

• 導入方式を選ぶ: INSTALL.md

• Raspberry Pi Zero 2 W keyboardを試す: Keyboard Package and M6 Image

• Raspberry Pi 4 touch panelを試す: Touch Panel Package

• 詳細ドキュメント目次: docs/README.md

• 画像ギャラリー: docs/gallery/README.md

• 回路図PDF: cqa02303v5 schematic

• PCB fabrication-layer PDF: cqa02303v5 fabrication layers

• 編集可能なhardware source: KiCad project

• メインターゲット: Raspberry Pi Zero 2 W

• 開発・貢献手順: CONTRIBUTING.md

• 公開sourceからの再現build: docs/ops/public-source-rebuild-runbook.md

• 公開文書とprivate運用資料の境界: docs/ops/public-documentation-boundary.md

• 実機失敗パターン: docs/ops/failure-patterns.md

• MCPサーバ: read-only診断 / guarded write companion

• Security: SECURITY.md

• Support: SUPPORT.md

• Community conduct: CODE_OF_CONDUCT.md

インストール方式を選ぶ

公開 Release では、同じ source revision から作成した3つの構成を選べます。

選択基準、Release asset、導入手順: INSTALL.md。Zero 2 W向けのpackageとM6は Keyboard Package and M6 Imageにまとめています。

Keyboard Layout

• Keyboard Layout Editor - CQA02303v5

システム概要

現在の構成は、Raspberry Pi Zero 2 W を USB HID 複合デバイス兼 BLE HID keyboard/mouse として動かし、Vial GUI / HTTP UI / 実キー入力を logicd-core-rs / logicd-companion / hidloom-outputd の runtime keymap と output control plane に集約します。

詳細: docs/architecture/system-overview.md

matrixd / httpd / i2cd / sendkey
        ↓
      logicd-core-rs + logicd-companion  ── keymap / layer / macro / output control
        ↓
      hidloom-outputd ── USB HID gadget / uinput
        └ logicd-companion ── BLE HID via btd
        ↓
PC / Linux input / log / Bluetooth host

主要 daemon:

出力先の内部名と表示名:

商標

「QRコード」は株式会社デンソーウェーブの登録商標です。

HIDloomのOLED Web UI QR機能、表示仕様、権利関係の説明は OLED Web UI QRを参照してください。

Repository Layout

root 直下は、導入入口と主要 daemon の位置を見失わないための薄い入口として残しています。

導入

fresh Raspberry Pi OS では、まず project build を行わない platform 準備だけを実行します。

sudo ./setup_fresh_rpi.sh --prepare-only

準備後の再起動が完了したら、x86_64 build host で作成した同じ version の hidloom-core と device profile package を同時に install し、profile を適用します。

sudo apt-get install -y \
  /tmp/hidloom-core_<version>_arm64.deb \
  /tmp/hidloom-profile-keyboard-ver1_<version>_arm64.deb
sudo hidloom-profile keyboard-ver1 --apply --backup --restart

引数一覧は ./setup_fresh_rpi.sh --help で確認できます。引数なしの checkout bootstrap は 実機 native build と package 管理外 unit install を行う legacy/recovery path です。

方式の選択: INSTALL.md

詳しい Raspberry Pi OS 導入手順: FRESH_INSTALL.md

実機への反映

現在の標準反映手順は Debian package です。実機側 checkout での git pull や native build は通常運用では使いません。

標準キーボード構成では、同じ version の core package と device profile package を 同時に install し、profile を明示適用します。

make core-deb-package
make keyboard-ver1-profile-deb
scp build/packages/hidloom-core_<version>_arm64.deb \
  build/packages/hidloom-profile-keyboard-ver1_<version>_arm64.deb \
  <user>@<keyboard-ip>:/tmp/
ssh <user>@<keyboard-ip> 'sudo apt-get install -y \
  /tmp/hidloom-core_<version>_arm64.deb \
  /tmp/hidloom-profile-keyboard-ver1_<version>_arm64.deb && \
  sudo hidloom-profile keyboard-ver1 --apply --backup --restart'

実際の package build / deploy / verify / rollback 手順は docs/ops/release-packaging-runbook.md を正とします。

Legacy / Recovery Deploy

checkout rsync、/opt release、pre-.deb layout は比較・復旧専用です。これらを使う場合も project binary は x86_64 build host で ARM64 cross-buildし、Raspberry Pi 実機では build しません。通常更新へ混在させず、先に dry-run と rollback path を確認します。

詳細は tools/package/README.md と release-packaging-runbook.md を参照してください。

動作確認

systemctl status hidloom-usb-gadget hidloom-hidd hidloom-uidd hidloom-outputd hidloom-logicd-core logicd-companion matrixd i2cd ledd httpd viald btd --no-pager
systemctl is-active logicd usbd || true  # legacy/rollback owner は通常 inactive
ls -l /dev/hidg0 /dev/hidg1
test ! -e /dev/hidg2 || ls -l /dev/hidg2
test ! -e /dev/hidg4 || ls -l /dev/hidg4
journalctl -u viald -u logicd-companion -u hidloom-logicd-core -u hidloom-outputd -u hidloom-uidd -u btd -u ledd -u hidloom-hidd -n 200 --no-pager
curl -k -u admin:$(hostname) https://127.0.0.1/api/status

USB gadget の割り当て:

現在含まれている主な機能

• GPIO matrix scan によるキー入力
• logicd-core-rs / logicd-companion による runtime keymap / layer / macro 処理
• USB HID keyboard / mouse / consumer control
• BLE HID over GATT keyboard/mouse backend
• Vial Raw HID bridge
• Vial GUI からの keymap 編集
• .vil keymap export / import
• VialRGB / LED direct control
• HTTP UI による keymap 編集・Lighting 操作・Key Tester
• OLED 表示 / alert 通知
• analog stick 入力
• sendkey.py による CLI キー入力
• getkeymap.sh / setkeycode.sh による runtime keymap 操作
• OutputRouter による gadget/uinput/bt/debug output backend モデル
• debug output による HID report ログ確認
• HTTP System panel からの Bluetooth Pair on/off
• LED video demo 再生の実験機能

詳細情報

よく使う補助コマンド

./sendkey.py tap 0x04
./getkeymap.sh --pretty
./setkeycode.sh 7,0 KC_ESC
./script/showlog.sh -s all -f

詳細:

• GETKEYMAP.md
• SETKEYCODE.md
• daemon/logicd/README.md
• daemon/http/README.md
• daemon/i2cd/README.md
• daemon/viald/README.md
• daemon/ledd/README.md
• daemon/usbd/README.md

ドキュメント運用

README は概要と入口に留め、長い手順・プロトコル詳細・設計メモは docs/ 配下へ分割します。方針は docs/policy/documentation-policy.md を参照してください。

ライセンス

HIDloom自身のsource codeはGPL-3.0-or-laterで提供します。 著作権は個々のcontributorに残り、包括的な権利譲渡は求めません。公開上の表記と contribution条件はAUTHORS.mdとCONTRIBUTING.mdを参照してください。 Buildroot、Linux kernel、BusyBox、Python/Rust dependencies、KiCad library、画像などの 第三者componentにはそれぞれのライセンスが適用されます。第三者componentの一覧と 再配布条件の確認状況はTHIRD_PARTY_NOTICES.mdに生成します。 公開exportはCycloneDX 1.7 SBOM.cdx.jsonと全export fileのSHA-256 manifestも生成します。