SuperKey多機能マクロキーボード¶
SuperKeyとは¶
SiFliSparks/SuperKey は、ディスプレイを備えた多機能マクロキーボードのSF32LB52ベースのリファレンス実装です。オープンソースのファームウェアはRT-ThreadとLVGL v9上で動作し、128 × 128のGC9107 LCD 3枚、RGB LED 3個、物理キー4個、ロータリーエンコーダー、SHT30温湿度センサーを制御します。また、複合USB HID/CDCデバイスとしてコンピューターに接続します。
SuperKeyは単なるショートカットキーパッドではありません。1つの動作するリファレンスに次の機能を統合しています。
- USB HIDによるキーボードおよびメディア制御の出力。
- USB CDCまたは1 Mbps UARTを介した、PCの性能、天気、設定、電源状態データの取得。
- 性能モニター、天気、時計、ユーティリティ、音楽、カスタムキー割り当てを表示する3画面UI。
- ホストデータの収集、機能設定、ファームウェア更新を行うコンパニオンアプリ SuperKeyHub。
- オープンな sf32-keyboard設計による再現可能なハードウェア。
SF32による実装の利点¶
SuperKeyはグラフィックス、複数ディスプレイ、複合USBデバイス、キーとエンコーダー、センサー、RGB効果、ファイルシステム、オプションのオーディオを必要とします。SF32LB52では、これらのリアルタイム処理をMCU上で実行できるため、コンパニオンアプリが起動していなくても、デバイスはUIを起動して基本的なHID動作を提供できます。PCのテレメトリーやインターネット上のデータなど、デスクトップOS側で扱うのが適切な処理はホストアプリに任せます。
この分担は、デスクトップコントローラー、ワークフローキーボード、ステータスパネル、小型HMIに適しています。一方で、明確な依存関係も生じます。高度なデータ表示にはコンパニオンアプリ、ドライバー、外部APIが必要です。ファームウェアとホストアプリのバージョン互換性を保つ必要があり、USB接続の喪失、ホストのスリープ、設定の破損についても個別に復旧試験を行う必要があります。
目標、対象範囲、開始条件¶
目標: バージョンを固定したSuperKeyを再現し、HID、CDC、3画面UI、入力、センサー、スリープからの復旧を検証します。そのうえで、ビルド、通信、回帰試験の証跡を製品レビューに引き継げる状態を保ちながら、動作を1種類だけ変更します。
オープンPCBが量産可能であることや、すべてのPCテレメトリー情報、天気サービス、シリアルブリッジ、USBホスト、OSバージョンに互換性があることを、このページは立証するものではありません。株価、天気、性能データは、SuperKeyHubのバージョン、サードパーティAPI、システム権限、ホストのハードウェアに依存する場合があります。
開始前に、次のものを用意してください。
- オープン設計を基に組み立てたSuperKeyハードウェア。GC9107 LCD 3枚、キー、エンコーダー、USBデータ接続を含みます。
- 主に文書化された手順を実施するためのWindows 10/11 PC。SuperKeyHubのリポジトリーはWindowsとmacOSをサポート対象としていますが、選択したOSで書き込み、CDC通信、復旧まで検証してください。
- ファームウェアに対応するバージョンのSuperKeyHub。
- SiFli-SDK環境、再帰的にチェックアウトしたSDKサブモジュール、動作確認済みの書き込み／復旧接続。
- 天気機能を使う場合は、有効なQWeather API Key、API Host、都市設定。
- USB認識、シリアルログ、キー動作、画面状態、スリープ復旧を記録するテスト記録。
| 項目 | 判明している基準 | 変更前に必要な証跡 |
|---|---|---|
| ハードウェア | オープンなsf32-keyboardハードウェアとsf32lb52-superkeyボードターゲット |
PCB／実装リビジョン、LCDと入力デバイス、電源、USB接続の記録 |
| ファームウェア | SuperKeyリポジトリー、SiFli-SDKサブモジュール、RT-Thread、LVGL v9、CherryUSB | ファームウェアとSDKのコミット、ビルドログ、イメージ、書き込みログ |
| コンパニオン | 互換性のあるファームウェアプロトコルを備えるSuperKeyHub | アプリのバージョン、OS、ポート、API設定、接続ログ |
| 基本動作 | HID、CDC、3画面、エンコーダー、キー、センサー、電源モード | コールドスタート、データ更新、入力、切断、スリープ復旧の記録 |
| 変更 | UI、キー、LED、データフィールドのいずれか1種類を一度に変更 | レビュー済み変更、ロールバック用イメージ、回帰試験一式の結果 |
ハードウェアとソフトウェアの仕様¶
ハードウェア仕様¶
| 部品 | 必要な仕様 | 役割 | 区分 | 入手先 | 互換性・置き換え時の注意 |
|---|---|---|---|---|---|
| SuperKeyオープンハードウェア一式 | プロジェクトに記載されたSF32LB52構成。128 × 128 GC9107 LCD 3枚、RGB LED 3個、物理キー4個、ロータリーエンコーダー、SHT30、USBを含む | マクロキーボードの制御、表示、入力、センシング、USB HID/CDC | 必須 | オープンなsf32-keyboard設計；SuperKeyリポジトリー |
設計ファイルは購入可能な実装済み基板の仕様ではない。PCBと実装リビジョンを記録する |
| ホストPCとUSBデータ接続 | 主な文書化済み手順はWindows 10/11。データ通信可能なUSB接続を用意 | SuperKeyHub、HID/CDCホスト、書き込み/復旧に使用 | 必須 | SuperKeyドキュメント | SuperKeyHubのリポジトリーはWindows/macOSをサポート対象としている。選択したOSでCDC、DFU、書き込み、復旧を検証する |
| QWeatherアカウント/API設定 | API Key、API Host、都市設定 | オプションの天気表示機能 | 任意 | QWeather | 認証情報をソース管理に含めない。サービスの利用条件と可用性を確認する |
ソフトウェア仕様¶
| パッケージまたはサービス | 必要なバージョンまたはリビジョン | 役割 | 区分 | 入手先 | 互換性・更新時の注意 |
|---|---|---|---|---|---|
| SuperKeyファームウェア | v1.4.2。使用したリポジトリーコミットを記録する | SF32ファームウェア、LVGL UI、USB、センサー、更新機能 | 必須 | v1.4.2リリース | ファームウェアのコミットを固定し、バージョン番号だけでホストとの互換性を判断しない |
| SuperKeyHub | ファームウェアv1.4.2との互換性を検証したリリースまたはコミット | ホストテレメトリー、設定、更新UI | ホスト機能を使う場合に必須 | リポジトリー | 参照した上流のリリース情報では固定の組み合わせを確認できない。テレメトリー、設定、DFUを試験し、組み合わせを記録する |
| SiFli-SDKサブモジュール、RT-Thread、LVGL、CherryUSB | 選択したファームウェアのチェックアウトに記録されたリビジョン | ファームウェアビルドとUSBスタック | ソースビルドに必須 | SuperKeyリポジトリー | 再帰的にクローンし、サブモジュールリビジョンを保持する。依存関係を個別に更新しない |
サポート対象の基準構成を選ぶ¶
上流のリリース一覧にはファームウェア v1.4.2 があり、固定した出発点として利用できます。参照資料からは対応するSuperKeyHubの版を特定できません。Hubのリリースまたはコミットを選び、v1.4.2と組み合わせてテレメトリー、設定、DFUを検証し、バージョン番号だけで互換性を推定せず、テスト済みの組み合わせを記録してください。
| 基準構成要素 | 推奨する開始点 | 重要な制約 |
|---|---|---|
| ファームウェア | SuperKey v1.4.2、またはチームで検証したコミット | ファームウェアとホストプロトコルのバージョンを一致させる必要があります |
| コンパニオン | v1.4.2との互換性を検証したSuperKeyHubのリリースまたはコミット | 参照資料では固定の組み合わせを確認できないため、選択したOSでCDCデータ、設定、DFUを検証する |
| ビルドターゲット | sf32lb52-superkey。ボードファイルはapp/boardsにあります |
汎用SF32LB52開発ボード用のターゲットではありません |
| 通信 | まず複合USB HID + CDCを検証し、使用する場合は1 Mbps UARTも別途検証 | 「USBとして認識された」だけでは、HIDとCDCの両インターフェースが機能する証跡にはなりません |
| 更新 | コンパニオンからのCDC DFUと、有線の書き込み／復旧経路を維持 | 中断、バージョン不一致、復旧を検証するまでは、フィールド更新手段とは見なせません |
SuperKeyの上流CIでは次のターゲットを使用しています。ローカルで実行する前にSiFli-SDK環境をインストールして有効にしてください。
git clone --recursive https://github.com/SiFliSparks/SuperKey.git
cd SuperKey/SiFli-SDK
./install.sh
. ./export.sh
cd ../app/project
scons --board=sf32lb52-superkey --board_search_path="../boards" -j8
WindowsではSiFli-SDK用のPowerShellインストールスクリプトと環境設定スクリプトを使用してください。並列ビルド数は変更できますが、ビルド記録にはボード名、ボード検索パス、サブモジュールのリビジョンを残してください。
プロジェクトの開発段階と判断ポイント¶
| 段階 | 判断する内容 | 必要な成果物 |
|---|---|---|
| 1. 未変更基準構成 | オープンハードウェア、ファームウェア、コンパニオンが記録どおりに連携するか | バージョンを固定した動作確認済みの動作記録 |
| 2. 通信と復旧 | USB、シリアル、スリープ、切断、設定の障害を診断・復旧できるか | 障害注入と復旧の記録 |
| 3. ソースからのビルド再現性 | クリーンなチェックアウトからチームが同じイメージを再ビルドできるか | ビルド環境、イメージ、書き込み、再現結果 |
| 4. 管理された変更 | 製品の動作を1つ変更しても基準構成を壊さないか | 範囲を限定した変更、ロールバック経路、回帰試験の証跡 |
| 5. 製品レビュー | カスタムPCB、筐体、パイロット生産の基盤として十分か | 担当者を割り当てたリスクと、続行／保留／中止の判断 |
システム構成と依存関係¶
flowchart LR
U["ユーザー\nキーとロータリーエンコーダー"] --> F["SF32LB52ファームウェア\nRT-Thread + LVGL v9"]
F --> D["GC9107 LCD 3台\nRGB LED、SHT30、オプションのオーディオ"]
F -->|"USB HID\nキーボードとメディアイベント"| P["Windows / macOSホスト"]
P -->|"USB CDCまたは1 Mbps UART\nテレメトリー、天気、設定、電源モード"| F
H["SuperKeyHub\n収集、設定、更新"] <--> P
H <--> A["天気APIとホストのテレメトリーソース"]
H -->|"CDC DFU"| F障害は、デバイスのハードウェア／ディスプレイ、HID入力、CDC／UARTデータチャネル、コンパニオン／システム権限、外部データサービスの5つの領域に分けて考えてください。天気パネルが空白でも、直ちにファームウェア障害とは限りません。APIキー、API Host、都市設定、データ送信に原因がある可能性があります。
段階1 — 未変更のリファレンス基準構成を確立する¶
目標: コードを変更する前に、リファレンス全体の経路が動作することを確認します。
- 上流の組み立て資料に従い、LCDケーブルの向き、スイッチ、エンコーダー、筐体、USBコネクターを確認し、PCBとファームウェアのリビジョンを記録します。
- ファームウェアに対応するSuperKeyHubをインストールします。デバイスの認識を確認してから、HIDとCDCを個別にテストします。
- 天気情報の認証情報、ポート、1 Mbpsのシリアル通信を設定します。コンパニオンなしの動作を記録してから接続し、データ送信を有効にします。
- 3画面の切り替え、キー割り当て、メディア制御、エンコーダー、SHT30データ、LED効果、テレメトリー更新1サイクルを確認します。
- コールドスタートして再試験します。UIの写真、コンパニオンログ、デバイスログ、バージョン照会の結果を保存します。
保存する証跡: ハードウェアリビジョン、ファームウェアタグ／コミット、SDKコミット、コンパニオンのバージョン、OS、ポートとAPIの設定、USB認識、ログ、画面、入力の記録。
ゲート1の終了条件: 2回のコールドスタートでHID入力、CDCデータ更新、3画面の操作が完了し、ログまたは観測可能な状態から各障害領域を区別できること。
段階2 — 障害と復旧の境界を検証する¶
目標: デスクトップ環境でよく起きる中断が、再書き込みを要するデモ機の状態につながらないことを確認します。
| テスト | 方法 | 合格を示す証跡 |
|---|---|---|
| コンパニオンなし | SuperKeyHubを終了してデバイスを再起動 | ローカルUIとHIDは動作し、コンパニオン依存の値は古い値または利用不可と分かる状態になる |
| CDC切断 | データ送信中にUSBを抜き差しするか、ポートを変更 | デバイスがハングせず、再接続後にバージョン照会とデータ送信が復旧する |
| ホストのスリープ | power_mode sleep/normalを有効にして、ホストのスリープ／復帰を1サイクル実行 |
LCD、LED、バックライト、センサーが意図どおり停止／再開し、その後のデータ更新も復旧する |
| バージョン不一致 | 管理された環境で互換性のないコンパニオン／ファームウェアの組み合わせを試す | 互換性のない更新を適用せず、動作を拒否するか診断可能なエラーを表示する |
| API障害 | 無効な天気設定を使うか、ネットワークを切断 | 天気機能の障害がHID、CDC、ローカルUI、復旧に影響しない |
| DFU中断 | 復旧可能な試験機で更新を中断 | 維持している有線書き込み経路で既知のイメージを復元できる |
ゲート2の終了条件: 該当する各障害について、文書化されていない手動修復を必要とせず、再現可能な検出・復旧結果が得られていること。
段階3 — 再現可能なソースの基準構成を整える¶
目標: 別のエンジニアがクリーンなチェックアウトから段階2を再ビルド、書き込み、再試験できるようにします。
- 再帰的にクローンし、SuperKeyとSiFli-SDKの両方のコミットを記録します。
sf32lb52-superkeyと../boardsの検索パスを指定してクリーンビルドします。- ビルドログ、メモリー／パーティション出力、書き込みスクリプト、生成イメージ、シリアルログを保存します。
- 2台目のPCまたはビルドディレクトリを削除した環境で再ビルドし、同じハードウェアに書き込んで主要な回帰試験を繰り返します。
ゲート3の終了条件: 未追跡ファイル、古い成果物、手動で差し替えたバイナリーに依存せず、段階2に合格するイメージを生成できること。
段階4 — 製品の変数を1つずつ変更する¶
目標: 合格済みのリファレンスを維持しながら、変更の影響範囲を検証します。
| 変更の種類 | 最初に試す変更 | 必要な回帰試験 |
|---|---|---|
| 製品識別とUI | アイコン、フォント、ページレイアウト、回転設定1つ | 3画面更新、回転、フォント、コールドスタート、メモリー使用量 |
| キー操作 | HID割り当てまたはキーの組み合わせを1つ | 押下／解放、複数キー、予期しない切断、設定の保持 |
| データ項目 | テレメトリーまたはセンサー値を1つ | プロトコル互換性、範囲チェック、更新タイムアウト、旧バージョンのコンパニオンでの動作 |
| LED効果 | 色またはアニメーションを1つ | 輝度の上限／下限、スリープ、キー操作フィードバック、長時間動作 |
| 更新 | バージョン方針または更新UI | イメージの出所、バージョン検証、中断、ロールバック、有線復旧 |
ゲート4の終了条件: 変更がレビューされ、元のイメージへ復旧でき、HID、CDC、ディスプレイ、入力、スリープ、復旧の各試験に合格すること。
段階5 — 製品化準備のレビュー¶
カスタムハードウェアやパイロット生産の前に、チームは次の質問に答える必要があります。
- 製品がSuperKeyHub、管理者権限、サードパーティの天気サービスに依存し続けるか。依存先の責任者は誰か。
- ファームウェア、コンパニオン、プロトコルのバージョンをどう管理し、互換性のない組み合わせをどう防ぐか。
- 対象PC、USBハブ、ケーブル、スリープポリシー、セキュリティソフトの組み合わせのうち、どれを試験したか。
- 3画面、USBデータ、LED、センサー、オプションのオーディオを同時に動作させたときのメモリー使用量、温度、消費電流はどうか。
- 電源断やストレージ破損後に、設定、キー割り当て、更新状態をどう復旧するか。
- オープンPCB、筐体、フォント、アイコン、音楽、サードパーティAPIのライセンスは予定する配布形態を許可しているか。
ゲート5の終了条件: 残る各リスクに担当者、証跡、対応方針が割り当てられ、「続行／保留／中止」の判断が記録されていること。
製品設計への引き継ぎ¶
SF32とメモリーの選定、USB HID/CDCディスクリプター、3画面とバックライトの接続、入力／センサーインターフェース、電源とスリープ方針、ファイルシステムと更新パーティション、コンパニオンプロトコル、量産テストポイント、検証済みの復旧経路を引き継いでください。続けて SF32LB52x、SF32LB52xハードウェア設計ガイド、SiFli-SDKのビルド、書き込み、モニター、量産設計を参照してください。
主な情報源¶
- SiFliSparks/SuperKeyファームウェアリポジトリー
- SuperKey v1.4.2リリース
- SiFliSparks/SuperKeyHubコンパニオンリポジトリー
- SuperKeyプロジェクトドキュメント
- オープンなsf32-keyboardハードウェア
- OpenSiFli/SiFli-SDK
最終更新: