matlab-build-industrial-hmi

産業用HMIビルダー

産業用HMIの慣例に沿った、オペレーター向けのSCADA／HMIダッシュボードをMATLAB App Designerで構築します。具体的には、グレー基調の配色、データソースでのアラーム表示、すべての設定値への書き込み保護、しきい値線付きの固定範囲トレンド、およびドリルダウンレイアウト（プラント概要 → エリア → 詳細）を採用します。

使用する場面

• ユーザーが「このOPC UA／Modbus／MQTT／OSI PI／PI AFスクリプトをSCADAダッシュボード／HMI／オペレーター画面にまとめて」と依頼した場合 — OPC UA ExplorerまたはModbus Explorerアプリで生成されたスクリプト（opcuageneratedScript.mlx、modbusgeneratedScript.mlx）も含みます。
• プラント概要画面、エリア画面、または産業モニタリング用の詳細画面を構築する場合
• 既存のApp Designerアプリにアラーム表示、設定値の書き込み、またはライブトレンドを追加する場合
• プロセスデータにゲージ、ランプ、またはトレンド軸を使用するHMIをレビューまたはリファクタリングする場合
• ISA-101、グレー基調、アラームバナー、書き込み確認、設定値、または「オペレーターダッシュボード」に言及するプロンプト全般

使用しない場面

• App Designerの一般的な仕組み（uigridlayout、コールバックの接続、ライフサイクル、matlab.apps.AppBaseのスキャフォールディング）や、実際のApp Designerファイルへのシリアライズには使用しません。このスキルでは、これらをmatlab-build-appに委譲します。references/app-designer-handoff.mdを参照してください。ここに残すものが2つあり、他に委譲してはいけません。グレー基調のテーマ設定（色やダークモードをmatlab-apply-themeに決して委譲しないこと）と、HMIトレンド（matlab-build-chartに決して委譲しないこと）です。
• ネットワーク上のOPC UAサーバーの検出、エンドポイントURLの検索、または初回の名前空間の参照には使用しません。matlab-use-opcua-clientを使用してください。
• プロセス制御以外の分野（コンシューマー向けアプリ、ラボ用ユーティリティ、科学用GUI）には使用しません。ここでの慣例は、物理プロセスを監視するプラントオペレーター向けに調整されています。

必ず守るルール

ウィジェットとレイアウト

• グレー基調の背景は[0.78 0.78 0.78]、パネルは[0.86 0.86 0.86]とし、画面の80％以上をニュートラルカラーにします。色は例外を示すために使います。references/color-and-layout-rules.mdを参照してください。

• すべてのHMIのuifigureは、必ず'Color'と'Theme', 'light'の両方を指定して構築してください。 MATLABのデスクトップがダークテーマの場合、Figureの色を明示的に設定しても、子ウィジェット（uigauge、uiaxes、uitable、uieditfield）はダークの既定値を継承します。その結果、ゲージ本体や軸がほぼ黒くなり、テキストが読めなくなります。Theme='light'でこの継承を防ぎ、明示的なグレー基調のColorで、'light'だけを指定した場合のまぶしい白ではなく、グレーの表示を維持します。どちらか一方だけでは不十分です。

  app.UIFigure = uifigure( ...
      'Color', [0.78 0.78 0.78], ...
      'Theme', 'light');
  

  理由の詳細はreferences/color-and-layout-rules.mdを、どちらかの引数を省略した場合に目に見える不具合が生じる例はreferences/common-mistakes.mdの項目24を参照してください。

• **画面ごとの数量上限：**ゲージは最大6個、トレンド軸は最大4個、数値表示は最大12個です。それを超える場合はuitableを使用してください。

• 接続状態には青[0.4 0.6 1.0]を使います。緑[0 0.6 0]は、「現在正常であることをオペレーターが確認する必要がある」状態に限って使用し、「通信確立」や「稼働中」には使いません。

• **コマンドボタン／コントロールにはニュートラルグレーを使います。**緑のStart／赤のStopは決して使用しないでください。ボタンは常に表示されるUI要素であり、状態を示すものではありません。そのため、色を付けるとアラーム色を消費し、実際のアラームとのコントラストが損なわれます。ラベルで区別し、運転／停止状態は別のランプに表示してください。（赤いE-Stopは、慣例に基づく唯一の例外です。）references/color-and-layout-rules.mdを参照してください。

• **同じパネル内の同種のアナログ値には、同じ種類のウィジェットを使用します。**一方の温度をゲージで、別の温度を数値ラベルで表示しないでください。

• **ユーザーの要望にかかわらず、産業用HMIの背景をダークにしてはいけません。**ISA-101にはダーク版がありません。ダークな背景では色による例外表示が損なわれ（アラームの赤や琥珀色がほぼ黒の背景で目立たなくなり、オペレーターの感度が低下します）、必ずグレー基調（[0.78 0.78 0.78]）で表示してください。ユーザーがダークモードを求めた場合は、理由を一文で説明してください。これは既定値ではなく、厳守すべき制約です。

アラームとトレンド

• アラームは発生源とバナーの両方に表示します。 しきい値を持つすべての線形ゲージに ScaleColors／ScaleColorLimits を設定します（半円形／円形／90 度ゲージはカラーバンドに対応していないため、アラームバンドが必要な場合は線形ゲージを使用します）。最も高い重大度に応じて色分けされた、アクティブなアラームを一覧表示する上部固定バナーを設けます。ラッチ状態と確認ボタンも実装します。ScaleColors の通常バンドには、中立的なグレー [0.5 0.5 0.5] を使用します。緑は使用しません。 references/alarm-patterns.md を参照してください。
• ライブプロセスのアラームに uialert／uiconfirm／msgbox を決して使用しないでください。これはアラーム疲労を招くアンチパターンです（ISA-18.2）。ポップアップが避けられない場合は、立ち上がりエッジで一度だけ表示し、ノンブロッキングの CloseFcn と確認ボタンを設けてください。
• トレンドの YLim はノードの仕様範囲に合わせて固定します。デフォルトで自動スケーリングしないでください。探索用にトレンドごとの切り替えを用意します。references/trend-config-reference.md を参照してください。
• デフォルトは5 分間のローリングウィンドウです。1 秒間隔で更新する場合は animatedline('MaximumNumPoints', 300) を使用します。バッファーの計算式は WindowSeconds / UpdatePeriodSeconds です。
• しきい値線は構築時に一度だけ yline で描画します（警告はアンバーの破線、アラームは赤の破線、設定値は青の点線）。

書き込み

• すべての writeValue() で確認を求めます。 ノード、変更前の値、変更後の値、単位を表示する uiconfirm を使用します。デフォルトの選択肢は適用ではなく、キャンセルにします。
• 書き込み後に視覚的なフィードバックを表示します。 成功時は背景を緑に点滅させ、失敗時は赤に点滅させます（失敗時は UI を元に戻します）。書き込みが反映されたかどうか、オペレーターに不確かな状態を決して残してはいけません。
• 書き込み可能なフィールドのすぐ隣に、範囲を示すラベルを表示します。スピナーの Limits で範囲を制限し、uilabel でその範囲を見えるようにします。
• E-Stop などの安全上重要な操作は、作動時と解除時の両方で確認を求めます。脅威となるのはタッチスクリーンの誤操作です。references/write-safeguards-reference.md を参照してください。
• システムが書き込みを受け付けられない場合（切断中、E-Stop 作動中）は、書き込みの途中で失敗させるのではなく、書き込みコントロールを無効にします。

プロトコルの選択

• OPC UA：ノード数や更新頻度にかかわらず、subscribe() がデフォルトです。ノード数が少なく、1 Hz の場合も同様です。timer は、時計表示、アラームの点滅、アイドル時の減光など、ノードを使わない UI の処理に限定してください。
• R2026a の OPC UA 契約： subscribe(client, nodes, cb) は cb(sub, notification) を呼び出します。データは notification.Data.Value / notification.Data.Timestamp にあり、発生元のノードは notification.Node（Name、Identifier、NamespaceIndex を持つ構造体）です。src.Name は参照しないでください。古いリリースでは src がノードだったため動作しましたが、R2026a ではエラーになります。
• コールバックの形式は 2 種類あります。ソースに合わせてください。 自分で subscribe 呼び出しを書く場合は、上記の 2 引数 cb(sub, notification) を使います。OPC UA Explorer が生成した dataChangeCallback を貼り付ける場合は、3 引数のベクトル化形式、cb(subObj, notification, ~) です。この場合、notification は 構造体配列（このサイクルで変更されたノードごとに 1 エントリー）です。notification(i).Node.Name / notification(i).Data.Value を反復処理し、スカラーとして扱わないでください。Explorer のスクリプトに 2 引数の @(src, evt) を書くと "Too many input arguments" エラーが発生します。notification をスカラーとして扱うと、最初のノードの値しか読み取れません。references/protocol-cheatsheet.md の §OPC UA と references/common-mistakes.md の #17 を参照してください。
• Modbus には subscribe() がありません。BusyMode='drop'、ExecutionMode='fixedSpacing' を設定したポーリング用 timer を使用してください。6 引数の write() の順序は write(m, target, addr, val, serverId, 'precision') です。serverId は 'precision' の前に指定します。
• MQTT の subscribe(c, topic, Callback=@cb) では、コールバックは位置引数ではなく名前と値のペアです。message（文字列）は、ブローカーのペイロードスキーマに従ってデコードします（str2double、jsondecode）。
• OSI / AVEVA PI Data Archive：piclient を使用してください（Industrial Communication Toolbox、R2022a 以降）。MATLAB では、NET.addAssembly('OSIsoft.AFSDK') を呼び出したり、OSIsoft.AF.PI.PIServers / OSIsoft.AF.PISystems のコードを書いたりしないでください。ツールボックスのクライアントは AFSDK をラップし、MATLAB ネイティブ型（timetable、table、datetime）を返します。.NET 相互運用を独自に実装すると、型の変換が失われ、ツールボックスなら処理できる権限エラーで例外が発生し、一括読み取りを迂回するため処理が遅くなり、統合ブラウザーアプリも動作しなくなります。PI には subscribe() がありません。トレンド表示には、Modbus と同じ形式のポーリングタイマーを使用してください。write(piClient, tag, value, TimeInstance=datetime("now")) による書き込みは R2024a 以降で利用できます。
• PI Asset Framework：afclient を使用してください（Industrial Communication Toolbox、R2026a 以降）。getRootElements / getChildren / findElementByName / findElementByPath / findElementByTemplate で参照し、Attribute.read（現在値 → table）と Attribute.readHistory（アーカイブ → timetable）で読み取ります。AF の階層は、レベル 1 → レベル 2 → レベル 3 のドリルダウン画面に直接対応します。AF の現在値の書き込みはツールボックスでは公開されていません。Attribute.write はありません。書き込みは、基盤の Attribute.PITag と PI クライアントを経由してください。
• **書き込み可能な属性は、OPC UA の AccessLevelCurrent と同様に、Attribute.WriteAccess と HasTimeSeriesData から判断してください。**名前から書き込み可能かどうかを推測しないでください。
• サーバー上の実際のタグ名／属性名を、tags(c).Name または attribute.Name / attribute.Path から取得してください。ラベルを作り出さないでください。オペレーターが OPC UA Explorer / OSI PI ビューアー / AF ブラウザーと照合できるよう、HMI ではソーススクリプトの識別子をそのまま使用してください。

OPC UA / Modbus / MQTT API の形式については references/protocol-cheatsheet.md を、PI Data Archive と PI AF については references/pi-af-cheatsheet.md を参照してください。失敗が表面化しないケースについては references/common-mistakes.md を参照してください。

App Designer 言語

• 型付き struct プロパティを初期化する: Foo struct = struct()。裸の Foo struct 宣言は 0×0 struct になり、app.Foo.Bar = 1 は 「構造体が空の場合、ドット名構造体への代入は不正です。」 というエラーになります。
• classdef を最初に。 同じファイル内で classdef より前に function ブロックがあると解析エラーになります。ラッパーを削除してください。ファイルの最初の非コメント文は classdef でなければならず、名前はファイル名と一致させる必要があります。
• インライン評価では function … end を使わない。 関数定義が合法なのはコードファイル内のみで、コマンドウィンドウ / インラインのコンテキストでは決して合法ではありません。ヘルパーロジック (重大度バンド、アラーム計算) を evaluate_matlab_code で健全性チェックする場合、そのトランスクリプトはまさにコマンドウィンドウのコンテキストです。貼り付けた function … end ブロックは "Function definitions are not supported in this context." というエラーになります。ヘルパーをそのファイルから実行して検証するか、算術を直接インライン化してください。
• サブスクリプションのクリーンアップ: opc.ua.Subscription には公開された delete がありません。ハンドルを破棄し (app.Subscription = opc.ua.Subscription.empty;)、disconnect(client) を呼び出してください。これでそのクライアント上のすべてのサブスクリプションが解放されます。
• ウィジェットごとにサブスクライブする。追加のたびに単一のグローバルサブスクリプションを再構築しないでください。各 subscribe() はチャネルリスナーを蓄積するため、再構築するとリークします。
• タイマーは delete(app) または CloseRequestFcn で停止して削除する。 リークしたタイマーは、フィギュアが閉じた後も古いハンドルで発火し続けます。

完全な再現手順、リリースを考慮した AccessLevelCurrent チェック、およびウィジェットごとのサブスクリプションパターンについては references/app-designer-gotchas.md を参照してください。

App Designer 出力

• シリアライゼーションを matlab-build-app に委ねることで、本物の App Designer アプリを生成する。 そのスキルの AppDesignerAgentInterface ツールが利用可能な場合 (exist('AppDesignerAgentInterface','class')==8、つまりパス上にある場合)、ここで HMI を設計し、その動詞を操作して本物の .mlapp (R2025a+) を出力します。これがデフォルトの出力であり、App Designer で開くことができます。プレーンテキストの .m+.xml は、ソース管理のために R2026b+ でのみ利用可能です。アーキテクチャの問いはあらかじめ答えが出ています。産業用 HMI は常に UIFigure (UIHTML には決してしない) であるため、親のアーキテクチャとシリアライゼーションの探索はスキップしてください。
• 親が利用できない場合のフォールバック: これらのリファレンスが説明するとおりに、プログラムによる .m アプリを生成してください。同じように動作しますが、App Designer では開けません。このことをユーザーに伝えてください。
• matlab-build-app との役割分担、ハンドオフプロトコル、HMI→動詞のマッピング (グレーフィールド、アラームゲージ、パレット、クリーンアップ)、およびシリアライズ前のドメイン準拠チェックリストについては references/app-designer-handoff.md を参照してください。そのファイルは、すべてのシリアライゼーションの仕組み — 動詞 API、ファイル形式の選択、ライフサイクル — を親の references/app-designer/agent-guide-shared.md に委ねています。

ワークフロー

監視スクリプトを HMI に組み込む場合は、以下の手順を順番に進めます。ウィジェットの選択はデータ型に応じて決まり、レイアウトはウィジェットの選択に応じて決まります。アラーム／トレンド／書き込みはその上に追加し、実際の App Designer アプリへのシリアライズは最後に行います。

1. 各ノード／タグ／属性を分類する — バイナリ、列挙型、範囲ありのアナログ、範囲なしのアナログ、書き込み可能、アラームしきい値（LL/L/H/HH）。この一覧が以降のすべての手順の基準になります。→ references/widget-selection-flowchart.md。スキーマが事前に与えられていない場合 → references/server-agnostic-discovery.md。生成されたスクリプト（OPC UA/Modbus Explorer または MQTT デモ）を組み込む場合は、正確な API の形式を確認するため、まず references/protocol-cheatsheet.md を参照します。PI / PI AF スクリプトを組み込む場合は references/pi-af-cheatsheet.md を参照します。
2. ウィジェットを選択する — 判断フローチャートに従い、数量上限を照合します。→ references/widget-selection-flowchart.md。
3. 階層に沿ってレイアウトする — レベル 1 はプラント全体の概要、レベル 2 はエリア、レベル 3 は詳細とし、1 行目は常時表示するアラームバナー用に確保します。→ references/color-and-layout-rules.md。
4. プロトコルごとにライブデータを接続する — OPC UA は subscribe()（自作のコールバックは 2 引数の cb(sub, notification)、Explorer が生成する dataChangeCallback は構造体配列に対してベクトル化された 3 引数）、Modbus は timer によるポーリング、MQTT は subscribe(... Callback=...)、PI / PI AF は read() / Attribute.read に対する timer によるポーリングを使います。→ references/protocol-cheatsheet.md と references/pi-af-cheatsheet.md。
5. アラームをデータソース側とバナーの両方で設定する — 確認応答までラッチされるようにします。→ references/alarm-patterns.md。
6. トレンドを設定する — 5 分間のウィンドウ、固定の YLim、しきい値線を設定します。→ references/trend-config-reference.md。
7. すべての設定値に書き込み時の安全策を追加する — 確認、範囲ラベル、フラッシュによるフィードバックを設定します。→ references/write-safeguards-reference.md。
8. 実際の App Designer アプリにシリアライズする。 matlab-build-app が利用可能な場合は、設計をその AppDesignerAgentInterface に渡し、.mlapp を生成します（デフォルト）。利用できない場合は、プログラムによる .m アプリを生成します。既存の App Designer HMI を編集する場合も、親の open()/inspect() ループを使用します。→ references/app-designer-handoff.md。
9. 検証する：起動し、操作し、正常に終了する。 mcp__matlab__evaluate_matlab_code を使ってアプリをインスタンス化し、delete(app) を実行します。タイマー、サブスクリプション、または Figure が残っていないことを確認します。.mlapp の場合は、save() が成功し、validate() が空であることを確認します。構造体または classdef のエラーで構築に失敗した場合 → references/app-designer-gotchas.md。

主な機能

機能	用途	ツールボックス	利用可能なバージョン
uigauge('linear'|'circular'|'semicircular'|'ninetydegree')	単一の値、既知の範囲	core MATLAB	R2016a
uigauge.ScaleColors / .ScaleColorLimits	発生源側の警報帯	core MATLAB	R2018a
uilamp	バイナリ状態インジケーター	core MATLAB	R2016a
animatedline と MaximumNumPoints	ローリング傾向バッファー	core MATLAB	R2014b
addpoints / clearpoints	傾向データの更新／リセット	core MATLAB	R2014b
yline	傾向グラフ上のしきい値または設定値の線	core MATLAB	R2018b
uiconfirm	モーダル書き込み確認	core MATLAB	R2017b
uispinner と Limits	範囲制限付き数値入力	core MATLAB	R2016a
uieditfield('numeric','Editable',false)	精度の高い読み取り専用数値表示	core MATLAB	R2016a
uitable	8 ノードを超える場合の表形式表示	core MATLAB	R2017b
uitree + uitreenode	OPC UA 名前空間のナビゲーション	core MATLAB	R2017b
opcua / connect	OPC UA クライアントを開く	Industrial Communication	R2022a
findNodeByName / readValue / writeValue	ノードの参照と読み取り／書き込み	Industrial Communication	R2022a
subscribe(uaClient, nodeList, dataChangeFcn, PublishInterval=...)	ライブノード更新（timer より推奨）	Industrial Communication	R2023b
modbus('tcpip', host, port) / read / write	Modbus クライアントとレジスターの読み書き	Industrial Communication	R2022a
mqttclient(brokerAddr) / subscribe(c, topic, Callback=...) / write	MQTT のパブリッシュ／サブスクライブ	Industrial Communication	R2022a
piclient(server, ...)	OSI / AVEVA PI Data Archive クライアント	Industrial Communication	R2022a
tags(piClient, Name=q) / read(piClient, tag, DateRange=, Interval=, AggregateFcn=)	PI タグの検索、現在値およびアーカイブ／集計データの読み取り（table/timetable を返す）	Industrial Communication	R2022a
write(piClient, tag, value, TimeInstance=...)	PI の設定値書き込み	Industrial Communication	R2024a
afclient(server, Database=...)	PI Asset Framework クライアント	Industrial Communication	R2026a
getRootElements / getChildren / getAttributes / findElementByName / findElementByPath / findElementByTemplate	AF ツリーの参照 → ドリルダウンレイアウト	Industrial Communication	R2026a
read(attr, Unit=...) / readHistory(attr, t0, t1, ...) / listSupportedUnits	AF 属性の現在値、履歴、単位	Industrial Communication	R2026a
timer（BusyMode='drop'、ExecutionMode='fixedSpacing'）	Modbus / PI / PI AF のポーリングループ／OPC 以外の定期的な UI 処理	core MATLAB	base

パターン

各リファレンスファイルには、トピックに関する実行可能なコードパターンが含まれています。コードを書く前に、該当するリファレンスを読み込んでください。正しい呼び出し規約、コンストラクターの引数、プロパティ名、コールバックハンドラーの全体が記載されています。以下のリファレンスのルーティング表を参照してください。

よくある間違い

references/common-mistakes.md は、記録された 26 件のアンチパターンをまとめたgrep 優先の検索表で、それぞれが 症状 → 誤り → 正解 → 理由のブロックになっています。全体を読み込まず、ユーザーのエラー文字列、または索引表にあるアンチパターンを Grep で検索し、一致する ### N. の項目だけを読んでください。App Designer の struct/classdef に関する落とし穴、ISA-101 違反（「正常」を緑で表示する、緑の開始／赤の停止コマンドボタン、ポップアップアラーム、自動スケーリングする傾向グラフ、数値に uilabel を使う、ダークフィールド）や、プロトコル固有のサイレント障害（Modbus の serverId / 'precision' の順序、MQTT の位置引数コールバック、JSON ペイロードからの MQTT NaN、OPC UA の架空のノード名、OPC UA の evt.Value と evt.Data.Value の違い、Explorer の 3 引数ベクトル化コールバック、サーバー側の 1601 タイムスタンプ）を扱っています。

参考資料

次の場合に読みます	参考資料
ノードのリストに使用するウィジェットを選ぶ場合	references/widget-selection-flowchart.md
画面構成の設計や色の選択を行う場合	references/color-and-layout-rules.md
アラーム帯をソース側または常時表示バナーに組み込む場合	references/alarm-patterns.md
トレンド（ウィンドウ、YLim、しきい値線）を設定する場合	references/trend-config-reference.md
書き込み可能な設定値に確認とフラッシュによるフィードバックを追加する場合	references/write-safeguards-reference.md
OPC UA Explorer／Modbus Explorer／MQTT スクリプトをラップする場合、OPC UA メソッドノードを呼び出す場合、またはプロトコル固有の問題に対処する場合	references/protocol-cheatsheet.md
OSI／AVEVA PI Data Archive スクリプト（piclient、tags、read）または PI AF スクリプト（afclient、getRootElements、getAttributes、Attribute.read／readHistory）をラップする場合	references/pi-af-cheatsheet.md
未知のサーバーを調べ、実行時にウィジェットを推定する場合	references/server-agnostic-discovery.md
既知のノードとウィジェットのスキーマを固定で設定する場合	references/known-schema-patterns.md
構築時のエラー（struct プロパティ、classdef の順序、リスナーのリーク、AccessLevelCurrent）に対処する場合	references/app-designer-gotchas.md
matlab-build-app を使って実際の App Designer .mlapp にシリアライズする場合、または既存の App Designer アプリを編集する場合	references/app-designer-handoff.md
特定のエラー、無反応の失敗、またはアンチパターンをデバッグする場合	エラーテキストまたはアンチパターンを references/common-mistakes.md で Grep します（索引テーブルがあります）。ファイル全体ではなく、一致する項目だけを読みます。

Toolbox の依存関係

• Core MATLAB：uifigure、uigridlayout、uigauge、uilamp、uispinner、uieditfield、uitable、uitree、uiconfirm、uialert、uiaxes、animatedline、addpoints、yline、timer。
• Industrial Communication Toolbox：opcua、connect、disconnect、findNodeByName、findNodeById、readValue、writeValue、subscribe（OPC UA）；modbus、read、write（Modbus）；mqttclient、subscribe、unsubscribe、write、read（MQTT）；piclient、tags、read、write、viewer（PI Data Archive、R2022a+。write は R2024a+）；afclient、listDatabases、selectDatabase、getRootElements、getChildren、getAttributes、findElementByName、findElementByPath、findElementByTemplate、findAttributeByPath、Attribute.read、Attribute.readHistory、Attribute.listSupportedUnits（PI AF、R2026a+）。

ユーザーの MATLAB リリースが不明な場合は、開始前に mcp__matlab__detect_matlab_toolboxes で確認してください。

---

Copyright 2026 The MathWorks, Inc.

---