SayoDevice 設定ビューア

USB接続された SayoDevice プログラマブルキーボード（2x6V RGB）のキー設定を、HID経由で読み込んで表示するWindowsデスクトップアプリです。

設定内容を読み込んで表示するだけの読み込み専用ツールです。デバイスへの書き込みは一切行いません。

対象デバイス

項目	値
製品	SayoDevice 2x6V RGB
VID / PID	0x8089 / 0x000B
型番コード	0x0005（O2T_ES）

機能

• 2×6 のキートップ表示 — 実際のキートップのような立体感のあるレイアウトで12キーの設定内容を表示
• Fn0〜Fn4 レイヤー切り替え — 5セットのレイヤー設定を切り替えて表示可能
• 最前面固定 — チェックボックスで常に手前に固定（切替可）
• リフレッシュボタン — デバイスの現在設定を再読込
• 起動時自動読込 — アプリ起動と同時にFn0の設定を表示
• コンパクトサイズ — 固定ウィンドウサイズ（約236×487px）

必要環境

• Windows 10 / 11
• Python 3.8 以上
• tkinter（Python標準ライブラリ）
• hidapi.dll（同梱）

インストール

特別なインストール手順は不要です。このフォルダ内のファイル一式をそのまま配置して使用します。

ファイル構成

SayoDeviceConfigViewer/
├── sayo_viewer.py          # アプリ本体（GUI）
├── sayo_dump.py            # 設定読込ライブラリ（HID通信・プロトコル実装）
├── hidapi.dll              # HID通信用ネイティブライブラリ
├── create_shortcut.ps1     # デスクトップショートカット作成スクリプト
├── capture.ps1             # ウィンドウキャプチャ用スクリプト（動作確認用）
├── stop_app.ps1            # アプリ終了用スクリプト
├── sayo_config_dump.json   # 設定ダンプ（CUI版の読込結果）
└── README.md               # このファイル

使い方

アプリの起動

方法1：ショートカットから起動（推奨）

デスクトップの「SayoDevice Config Viewer」をダブルクリックします。

初回はショートカット作成スクリプトを実行してください：

powershell -ExecutionPolicy Bypass -File create_shortcut.ps1

方法2：コマンドから起動

python sayo_viewer.py

操作方法

1. アプリを起動すると、Fn0（メインレイヤー）の設定が自動的に読み込まれて表示されます
2. 上部の「Fn0 Fn1 Fn2 Fn3 Fn4」ラジオボタンで、レイヤーを切り替えて表示できます
3. デバイスの設定を変更したら「リフレッシュ」ボタンで最新設定を再読込します
4. 「最前面」チェックボックスで、ウィンドウを常に手前に固定できます

表示内容の見かた

各キートップには以下の情報が表示されます：

• 中央：キーに割り当てられた機能（人間可読）
• 下部：動作モード名

主な表示例

表示	意味
Ctrl+W	Ctrl+W の同時押し
Alt+↑	Alt + 上矢印
Ctrl+B→P	二段階操作（Ctrl+B を押した後、P を押す）
左クリック	マウス左クリック
(未割当)	設定なし

動作モード一覧

モード名	説明
キーボード	修飾キー＋キーコード
マルチキー	複数キーの同時押し
マウス	マウスボタン・移動・スクロール
コンシューマ	メディア制御（音量など）
二段階キーボード	2段階のキー入力（例：Ctrl+B → P）
ユーザースクリプト	カスタムスクリプト

コマンドラインツール

設定をJSONファイルにダンプするCUIツールも同梱しています：

python sayo_dump.py

実行すると sayo_config_dump.json にデバイス情報とキーマップ（Fn0）が保存されます。

技術情報

HID通信プロトコル

SayoDeviceはHID Feature Reportではなく、vendor-defined HIDインターフェース（usage_page=0xFF00）経由で設定の読み書きを行います。

パケット構造（64バイト固定）：

[id(2)] [cmd] [data_len] [data...] [check_sum]

• id：固定値 2
• cmd：コマンド番号
• check_sum：id から data までのバイト総和の下位8ビット

主なコマンド：

cmd	機能
0	デバイス情報取得（型番・ファームウェア・シリアル）
6	キー設定読み書き（Fn0のみ、旧プロトコル）
22	キー設定読み書き（全レイヤーFn0〜Fn4対応）
0xF0	スクリプト領域読み書き

本アプリは主に cmd=22 を使用し、全レイヤーのキーマップを一度に読み込んでいます。

プロトコル参照元

設定読込のプロトコル実装は、以下のオープンソースプロジェクトを参考にしています：

• fidian/sayo-keyboard-configuration — HIDプロトコル実装（C++/hidapi）
• Sayobot/sayo-device-web-hid — 公式WebHID実装
• libusb/hidapi — HID通信用ライブラリ

安全性

• 読み込み専用：デバイスへの書き込み（Save）コマンドは一切送信しません
• デバイス未接続時は警告メッセージを表示し、クラッシュしません
• HID通信の排他制御により、他の設定アプリと同時使用はできません（リフレッシュ時にエラーになります）

トラブルシューティング

アプリが起動しない

hidapi.dll が sayo_viewer.py と同じフォルダに配置されているか確認してください。

「デバイスから設定を読み込めませんでした」と表示される

• SayoDevice が USB で接続されているか確認してください
• 他の設定アプリ（公式WebHIDツールなど）が開いている場合は閉じてください（HIDの排他制御）
• USB ケーブルを抜き差ししてからリフレッシュしてください

表示が更新されない

「リフレッシュ」ボタンを押してデバイスから設定を再読込してください。

ライセンス

本アプリは個人利用を目的としています。同梱の hidapi.dll は hidapi （BSD-3-ClauseまたはGPL-3.0）の配布物です。