コンテンツにスキップ

LVGL SDKサンプル

SiFli-SDKのLVGLサンプルは、ディスプレイとUIを検証する出発点です。そのまま流用できる製品テンプレートではありません。まずバージョンの合うデモでパネルと入力の基本動作を確認します。その後、製品で特に検証が必要な機能のサンプルを選び、公式に記載されたボード設定で変更せずに実行してから、一度に1層ずつ製品向けへ置き換えてください。動作する基準構成として扱う前に、各READMEの検証状況と制約を確認します。

このガイドは、SiFli-SDK LVGLインデックスにある例を、設計・評価の目的別に整理しています。現在サポートされているボード、SDK構成、ソースパス、アセット、ビルドコマンド、バージョン固有の制限については、公式のソースページを参照してください。

このインデックスはサンプル一覧であり、ボード互換性の一覧ではありません。対応範囲はサンプルごとに異なり、ドキュメントURLにチップファミリー名が含まれていても、そのファミリーのボードがすべて対応しているとは限りません。各サンプルのREADMEにあるSupported Boardsを確認してください。汎用的なビルドコマンドやリポジトリーのビルドマトリクスへの登録だけでは、そのボードで実機動作が検証済みとは言えません。情報源によって範囲が異なる場合は区別して記載し、使用するSDKリビジョンとボードで確認してください。

適切なLVGL基準構成から始める

表: 目的別に選ぶSiFli-SDK LVGLサンプル
目的 ここから始める 確立できること 次に進むタイミング
標準的なLVGLアプリケーションを立ち上げる LVGL v8デモ、LVGL v8公式サンプル、LVGL v9デモ、またはLVGL v9公式サンプル 選択したLVGLバージョン、ボードのディスプレイドライバー、レンダリングループ、基本ウィジェット 実際のパネルで画面更新（flush）処理と入力デバイスが安定して動作したら
UIデザインワークフローを評価する gui_guider、SquareLine、またはEEZ Studioの例 生成されたUIコードをSDKプロジェクトにどう組み込むか 生成コードが問題なくビルドでき、LVGLのバージョンがプロジェクトと一致したら
焦点を絞ったUIの挙動を試作する Basechart、Baselabel、Follow、Imgarray、Imgbar、Mulroller、Multanim、Multlist、Multroller、Multslider、Sector、Select、またはTimeline 特定のインタラクション、ウィジェット、配置、あるいはアニメーションパターン 単体の表示要素から複数要素を組み合わせた製品画面へ進むとき
アセット、アニメーション、またはメディアを検証する eZipの動的読み込みv8 / v9、Lottie、ローカル動画再生、またはストリーミング再生 リッチなコンテンツを保存・デコード・描画・更新する処理経路 実機でリソース容量、メモリー配置、更新頻度、消費電力を測定し、製品の制約を満たすことを確認できたら
製品を想定した一連のUIを構築する 電子コンパス、ゲーム索引（マインスイーパーのREADME）、または時計UI v8 / v9 画面遷移、インタラクション、複数機能を含む表示負荷 製品固有のデータ、ライフサイクルの挙動、性能限界を使ってデモ内容を置き換えられる段階になったら

サンプルごとに対象ボードは異なります。v8 DemosのREADMEにはeh-lb563とSF32LB52x、SF32LB56x、SF32LB58xのLCDシリーズが記載されています。v8 Official Examplesにはsf32lb52-lchspi-ulpとこれら3つのLCDシリーズが記載されています。v9 DemoのREADMEが対応ボードとして挙げているのは3つのLCDシリーズです。後段の汎用的なビルド手順にはeh-lb563も登場しますが、明示的なSupported Development Boardsの一覧には含まれていません。v9 Official Examplesにはsf32lb52-lchspi-ulpと3つのLCDシリーズが記載されています。READMEの明示的な一覧を対象範囲とし、汎用ビルド例だけを根拠にボードを追加しないでください。

サンプルで確認できる範囲を先に整理する

LVGLサンプルを製品向けに変更する前に、サンプルで確認できる層と、製品側で別途対応が必要な層を整理してください。

表: LVGLサンプルで確認できる範囲と製品側の課題
対象範囲 サンプルで確認できること 製品側で別途確認すること
ボードとパネル 既知のSDKボード構成とディスプレイ経路 実際に使うパネル、タッチコントローラー、電源投入シーケンス、ピン機能の割り当て、リセットタイミング、量産テスト手順
LVGL バージョンごとの初期化とサンプルUIの動作 製品の画面構成、イベント管理の責務分担、メモリー上限、画面更新方針
アセット サポートされているサンプルアセットパス アセットフォーマット、ストレージサイズ、ロード時間、キャッシュポリシー、ライセンス、失敗時の処理
レンダリング 動作する描画・flushループ 更新領域の管理方針、バッファー数、カラーフォーマット、DMA/キャッシュ処理、負荷下でのUI応答性
アプリケーション 画面上で確認できるデモの動作 センサー、Bluetooth、ストレージ、計時、低消費電力への遷移、復旧、ユーザーデータ

まず実際のディスプレイとパネルインターフェースを確認し、基本的な画面更新（flush）処理を検証してください。LVGLデモだけで最終的なグラフィックス構成の準備が整ったと判断せず、グラフィックス概要とディスプレイコントローラーも参照してください。

LVGLバージョンを意図的に選ぶ

公式のインデックスには、LVGL v8とLVGL v9の両方の例が含まれています。生成されたUIプロジェクト、基準となる例、SDK構成は同じLVGLメジャーバージョンに揃えてください。あるメジャーバージョンから生成された画面やカスタムウィジェットを、移植に必要な変更を確認せずに別のバージョンに持ち込まないでください。

最初のボード立ち上げでは、SDKのボード構成がすでに選択しているLVGLバージョンと一致するデモまたは公式例を使用してください。これにより、アプリケーション固有の作業に進む前に、パネル、バッファー、入力、スケジューリングの経路を確実に検証できます。

LVGL v8 SJPGサンプルを使う前にカードをバックアップする

v8 Official ExamplesプロジェクトでTFカードからSJPGを読み込むオプション経路は、マウントに失敗するとカードのルート領域に対してdfs_mkfs()を呼び出し、データを消去する可能性があります。この経路を有効にして実行する前にカードをバックアップし、使用するSDKリビジョンのコードを確認してください。この警告をすべてのLVGL v8/v9サンプルに一般化せず、各プロジェクトのマウント・フォーマット処理を個別に確認してください。

UIコード生成ツール: gui_guider、SquareLine、EEZ Studio

チームがビジュアルエディタを使って画面階層、スタイル、アセットを生成する必要がある場合は、UIデザインツールの例を使用してください。インデックスにはgui_guider、SquareLine、EEZ Studioの例が含まれています。

生成コードを製品へ取り込む前に、出力コードのバージョン、画面解像度、色深度、リソースのパス、コールバックの管理主体を確認してください。

gui_guiderとEEZ Studioの公式サンプルは、どちらもLVGL v8を指定しています。SquareLineでは生成コードが使うデフォルトテーマも有効にします。生成されたサブディレクトリをビルド対象に含め、任意のeZip変換も公式手順に従ってください。ファイルのコピーだけでは組み込みは完了しません。

生成コードはUIの構築を速めますが、ディスプレイドライバー、バッファー設計、入力ドライバー、電力管理の方針、統合テストの代わりにはなりません。再エクスポートで製品固有の変更を誤って上書きしないよう、生成ファイルと手作業で記述したアプリケーションロジックを分けて管理してください。

ウィジェットとインタラクションのパターン

LVGL v8の個別サンプルで、必要なUI動作を検証できます。ただし規模は一様ではありません。Multlistは単体ウィジェットの最小テストではなく、アプリケーションフレームワークを使った一式のデモです。

  • Basechartはデータ系列の描画、Baselabelはデータソースに連動するテキストの定期更新を扱います。
  • Followは重力方向に応じて動くアイコンメニュー、Selectは選択状態、Sectorは値に応じた画像の扇形表示を扱います。
  • Imgarrayは画像の字形を組み合わせた数値表示、Imgbarは前景画像を切り取った進捗表示です。
  • Mulrollerはコールバックで細かく調整できるローラー選択、Multrollerは文字列の選択肢を使う簡易ローラーです。
  • Multlistはリスト、ページ送り、画面遷移、リソースキャッシュ、ページのライフサイクルを扱います。Multsliderはスライダーのつまみに数値や短いラベルを表示します。
  • Multanimは画面遷移の効果を扱い、一部はGPU/VGLiteの対応に依存します。Timelineは共通の時間軸で複数のアニメーションを制御します。

個別ウィジェットのサンプルごとに対応ボードは異なります。たとえばMultanimとMultlistのSupported Boardsにはsf32lb52-lcd_n16r8とsf32lb52-lchspi-ulpが記載されていますが、後段の汎用ビルド手順ではより広い52x/56x/58xの対象が言及され、eh-lb563がビルド例として示されています。これらは同じ対応範囲を示すものではありません。該当READMEと現在のプロジェクト設定を確認し、インデックスやURLから他のウィジェットの互換性を推測しないでください。

製品で特定の操作部品の動作が懸念される場合は、対応するサンプルから検証してください。最初は変更範囲を絞り、元の部品を動かしてから製品のデータへ置き換えます。大きな画面に組み込む前に、再描画の処理量とメモリー使用量を測定してください。見た目が単純でも、複数の部品を組み合わせるとフレームバッファー、グラフィックスリソースの読み出し帯域、入力イベントの処理スケジュールに負荷がかかります。

アセット、アニメーション、メディアのワークロード

eZipの動的読み込み例は、LVGL v8とLVGL v9の両方で利用可能です。動的な圧縮アセットのロードを広く採用する前に、アプリケーションに一致するバージョンを使ってそれを検証してください。eZipの記事は、グラフィックスパイプラインにおけるアセット圧縮の役割を説明しています。

GIF/APNGアニメーション素材向けに、SiFliはMultimedia > AGIFに AGIF/APNG + LVGL v8と AGIF/APNG + LVGL v9の例も用意しています。各READMEにはeh-lb525が記載されています。一方、現行の GCCビルドマトリクスでは、両方のプロジェクトパスがdevkit_lcd_boardsに登録されています。マトリクスへの登録はビルド対象を示すものであり、そのグループ内の全ボードで実機動作が検証済みという意味ではありません。製品の基準例として使う前に、対象ボードとSDKリビジョンを確認してください。

動的eZipサンプルでは、ファイルパスによるアクセスとSRAM/PSRAMへの事前読み込みを比較できます。事前読み込みは追加メモリーを使いますが、繰り返しのファイル読み込みを減らせます。リソース形式をLVGL v8/v9に合わせてください。公式v9のパスには、v8と異なりA:/などのドライブ接頭辞が必要です。実際のストレージ構成とドライブ文字の設定を確認します。v9 READMEにはsf32lb52-lcd_n16r8、sf32lb52-lcd_a128r16、sf32lb52-lchspi-ulp、sf32lb52-core_e8r16、sf32lb56-lcd_a128r12n1、sf32lb56-lcd_n16r12n1、sf32lb58-lcd_n16r32n1_dsi、sf32lb58-lcd_a128r32n1_qspi、sf32lb58-lcd_n16r32n1_qspiが明記されています。この一覧はv9 READMEの対象であり、v8に転用したり、他のボードも対応していると推測したりしないでください。eZipのドキュメントでは、-winsize 2048の変換オプションが必要なのはSF32LB57のみです。

Lottie、ローカル動画再生、ストリーミング再生は、それぞれ異なる処理経路を検証するサンプルです。負荷の大小がこの順に決まるわけではありません。Lottie READMEは未検証と明記し、eh-lb563とSF32LB52x/SF32LB56xシリーズを挙げていますが、現行GCCビルドマトリクスではプロジェクトの登録がコメントアウトされています。このボード一覧を検証済みの対象とみなさないでください。ローカル動画READMEはeh-lb523とsf32lb52-lcd_n16r8を明示していますが、より広い対象を示す汎用ビルド手順も含みます。こちらもGCCビルドマトリクスではプロジェクトの登録がコメントアウトされているため、別の対象で使う場合はSDKの実際のチェックアウトを確認してください。サンプルはdisk/video_example.mp4のH.264動画を再生し、TFカードを正常にマウントできた場合はカードのルートにあるvideo_example.mp4を優先して読み込みます。ストリーミングREADMEが挙げるボードはsf32lb52-lchspi-ulpのみです。スマートフォンのBluetooth PANテザリングでネットワークに接続し、FFmpegを使います。BLEで動画を転送するサンプルではありません。

個々の表示だけでなく、システム全体の負荷として評価してください。Bluetooth、センサー、製品で使用するディスプレイインターフェースを動作させた状態で、リソースやストリームの保存容量、デコード時間、フレーム更新頻度、PSRAM/SRAM使用量、表示帯域、消費電流を測定します。実際の負荷は、コンテンツの複雑さ、解像度、デコーダー設定、バッファー構成によって変わります。

短いデモが滑らかに動いても、長時間のアニメーションを安定して実行できるとは限りません。製品で使うコンテンツの長さと、実際のパネル更新方針で検証してください。

フォントと実行時の言語切り替え

FreeTypeサンプルでは、ファイルシステムからTrueTypeフォントを読み込み、実行時にフォントやサイズを切り替えます。READMEではsf32lb52-lchspi-ulpでの動作が確認されています。他のボードではFS_REGIONパーティションと、使用するフォントに十分なシステムヒープが必要です。このサンプルによって他のボードまで検証済みになるわけではありません。読み込み失敗時の内蔵フォントへの切り替え、ヒープ容量の確認、変更時の旧フォントの解放も扱います。製品で使う言語とサイズで、文字の収録範囲とヒープ使用量を確認してください。大きなCJKフォントは必要な文字に絞り込みます。このサンプルはTrueTypeアウトラインを必要とし、CFFアウトラインのOpenTypeフォントには対応しません。ウィジェットやスタイルが参照しているフォントは解放できず、フォントの変更はLVGLスレッドで行う必要があります。同梱フォントを変更したら、ファイルシステムイメージfs_root.binを再生成して書き込んでください。アプリケーションだけを書き換えても、そのファイルは更新されません。

多言語サンプルの LVGL v8版と LVGL v9版は、内蔵言語、外部言語パックのインストール、実行時の切り替え、インストールディレクトリの再走査、share_prefsによる選択言語の保存を扱います。v8 READMEにはsf32lb52-lchspi-ulpが記載されています。v9についてはv9 READMEの対象一覧を別途確認し、v8のボード範囲を推測で引き継がないでください。JSONまたはXLSXから、ファームウェアに組み込む言語リソースや外部配布用のバイナリパックを生成します。翻訳キーを全言語で揃え、必要な文字をフォントが収録していることを確認してください。切り替え、再起動後の設定保持、リソース欠落時の動作、ファイルシステムの更新手順を検証します。機能名が同じでも、各バージョンのドキュメントに記載されたパスや設定が同一とは限りません。

コンパス、ゲーム、時計インターフェース

電子コンパスと時計UIのサンプルでは、表示処理とアプリケーションの動作を合わせて確認できます。画面構成、入力・アニメーションのタイミング、表示負荷が増えた場合の影響を調べる際に利用してください。ゲーム索引にはマインスイーパーのサンプルがあります。READMEに記載されているのはeh-lb563とSF32LB52x/56xで、58xは含まれていません。58xで使う場合は、現在のSDKソースで対応状況を確認してください。

ドキュメントに記載されたコンパスの基準構成は、sf32lb52-lchspi-ulpでMMC56x3の3軸磁力計をI2C接続して使用します。製品ではドライバー、配線、校正条件を確認してください。画面に方位角が表示されるだけでは、測定精度は保証できません。

ゲームや時計UIのサンプルは画面遷移を検討する出発点になります。ただし、データの管理主体、低消費電力時の動作、画面のウェイクアップ方針、通知、障害復旧は製品側で定義する必要があります。

v8の時計UI READMEにはSF32LB52x、SF32LB56x、SF32LB58xのLCDシリーズとsf32lb52-lchspi-ulpが記載され、v9 READMEには3つのLCDシリーズが記載されています。どちらも520-hdkは非対応で、SF32LB55xでは3D回転デモを使用できないとしています。フォント追加時はリソースパーティションの容量を確認してください。v8ではフォント領域の容量超過が起こり得ます。

検証記録を残しながら製品へ組み込む

表: LVGLサンプルを製品へ組み込む際の確認事項
ステップ 残す検証記録 重要な理由
元のサンプルをビルドする SDKのリビジョン、ボード名、構成、ビルドログ 動作確認済みの基準構成を保持する
ハードウェアで実行する 写真/動画、シリアルログ、パネルとタッチの挙動 実際のディスプレイと入力の経路を確認する
1つの製品要素を追加する 変更履歴と、フレームレートおよび画面更新に関する測定結果 変更による不具合の原因を特定しやすくする
製品負荷をかける Bluetooth、センサー、ストレージ、低消費電力への遷移を伴うUIの応答性 単体デモでは見えない組み込み時の制約を見つける
最終的な制約を記録する バッファー使用量、メモリー配置、フレームレート、電力、既知の故障挙動 サンプルを保守可能な技術資料にする

最終更新: