概要
Model Composer のプログラム生成用スクリプト (PG API スクリプト) は、xBlock
、xSignal
、xInport
、および xOutport
の各オブジェクトをインスタンシエーションして相互に接続することにより、Model Composer サブシステムを構築する MATLAB M 関数ファイルです。これは、Model Composer のダイアグラム (サブシステムなど) をプログラムで構築する方法です。この後例を挙げて説明するように、Model Composer のプログラム スクリプトの最上位の関数は、そのエントリ ポイントであり、xBlock
コントラクターを使用して呼び出す必要があります。コンストラクターの終了時に、MATLAB は対応する Model Composer サブシステムを対応するモデルに追加します。モデルが開いていない場合は、新しい無題のモデルが作成され、その中に Model Composer サブシステムが挿入されます。
xBlock
コンストラクターにより、xBlock
オブジェクトが生成されます。オブジェクトはライブラリ ブロックから作成でき、またはサブシステムにもなります。xSignal
オブジェクトは、ソース ブロックとターゲットを接続するワイヤに相当します。xInport
オブジェクトは Simulink Inport をインスタンシエートし、xOutport
オブジェクトは Simulink Outport をインスタンシエートします。
この API には、Simulink ダイアグラムをプログラミング生成スクリプトに変換する xlsub2script
というヘルパー関数もあります。
API は、学習モード、プロダクション モード、デバッグ モードの 3 つのモードで動作します。 学習モードでは、物理的なスクリプト ファイルなしで、コマンドを入力できます。API を習得する際には非常に便利です。このモードでは、すべてのブロック、ポート、サブシステムが untiled という名前の Simulink モデルに追加されます。新しい学習セッションを始める前に必ず、引数なしで xBlock を実行するか、無題のモデルを閉じてください。プロダクション モードでは、M 関数ファイルが必要で、xBlock コンストラクターから起動します。サブシステムが生成されます。サブシステムは、既存のモデルに組み込むことも、新しいモデルに挿入することもできます。デバッグ モードは、新しいオブジェクトが作成されるか新しい接続が確立されるたびに、Simulink ダイアグラムで再配線が実行されることを除き、プロダクション モードと同様に動作します。スクリプトにブレークポイントを設定、スクリプトをシングル ステップ実行するなど、スクリプトをデバッグする際に非常に便利です。
xBlock
xBlock
コンストラクターにより、xBlock
オブジェクトが生成されます。オブジェクトはライブラリ ブロックから作成でき、またはサブシステムにもなります。xBlock
コンストラクターには、3 つの使い方があります。
- 現在のサブシステムにリーフ ブロックを追加する。
- 現在のサブシステムにサブシステムを追加する。
- 最上位サブシステムをモデルに添付する。
xBlock
には 4 つの引数を指定し、次のように起動します。
block = xBlock(source, params, inports, outports);
source 引数が文字列の場合は、ライブラリ ブロック名であると想定されます。ソース ブロックが xbsIndex_r4 ライブラリまたは Simulink のビルトイン ライブラリにある場合は、ライブラリ名を付けずにブロック名を使用できます。たとえば、xBlock('AddSub', ...)
を呼び出すのは、xBlock('xbsIndex_r4/AddSub',...)
と同じです。xbsIndex_r4
ライブラリまたはビルトイン ライブラリにないソース ブロックには、xBlock('xbsTest_r4/Assert Relation', ...)
のように、絶対パスを使用する必要があります。source 引数が関数ハンドルの場合は、PG API 関数として解釈されます。MATLAB 構造体であれば、最上位をモデルにどのように添付するのかを指定するコンフィギュレーション構造体として扱われます。
params
引数は、パラメーターを設定します。位置ベースのバインディングの場合はセル配列、名前ベースのバインディングの場合は MATLAB 構造体を指定します。source パラメーターがライブラリ内のブロックの場合、この引数はセル配列である必要があります。source パラメーターが関数ポインターの場合、この引数はセル配列である必要があります。
inports
および outports
引数は、サブシステムの入力および出力ポートの結合方法を指定します。バインディングは、位置ベースのバインディングではセル配列、名前ベースのバインディングでは MATLAB 構造体となります。Inport/Outport のバインディングを指定する際、セル配列の要素には xSignal
、xInport
、または xOutport
オブジェクトを指定できます。ポート バインディング引数が MATLAB 構造体の場合、構造体のフィールドはブロックのポート名、構造体の値はポートがバインディングされるオブジェクトになります。
2 つのポート バインディング引数はオプションです。xBlock
オブジェクトの構築時に引数がない場合は、xBlock
オブジェクトの bindPort
メソッドでポート バインディングを指定できます。bindPort
メソッドは次のように実行します。
block.bindPort(inports, outports)
ここで、inports
および outports
引数は、入力ポートと出力ポートのバインディングを指定します。この場合、xBlock
はソースとパラメーター バインディングの 2 つの引数のみでオブジェクト ブロックを作成します。
xBlock
には、ほかに次のようなメソッドがあります。
-
names = block.getOutportNames
: outport 名のセル配列を返します。 -
names = block.getInportNames
: inport 名のセル配列を返します。 -
nin = block.getNumInports
: inport の数を返します。 -
nout = block.getNumoutports
: outport の数を返します。 -
insigs = block.getInSignals
: 入力信号名のセル配列を返します。 -
outsigs = block.getOutSignals
: 出力信号名のセル配列を返します。
xInport
xInport
オブジェクトは、サブシステムの入力ポートを表します。
コンストラクター
port = xInport(port_name)
port_name という名前の xInport オブジェクトを作成します。
[port1, port2, port3, ...] = xInport(name1,
name2, name2, ...)
名前付きの入力ポートのリストを作成します。
port = xInport
自動生成された名前の入力ポートを作成します。
xInport
オブジェクトはポート バインディング用に渡すことができます。
メソッド
outsigs = port.getOutSignals
出力信号名のセル配列を返します。
xOutport
xOutport
オブジェクトは、サブシステムの出力ポートを表します。
コンストラクター
port = xOutport(port_name)
port_name
という名前の xOutport
オブジェクトを作成します。
[port1, port2, port3, ...] =
xOutport(name1, name2, name2, ...)
名前付きの出力ポートのリストを作成します。
port = xOutport
自動生成された名前の出力ポートを作成します。
xOutport
オブジェクトはポート バインディング用に渡すことができます。
メソッド
port.bind(obj)
オブジェクトをポートに接続します。port は xOutport オブジェクト、obj は xSignal
または xInport
オブジェクトです。
insigs = port.getInSignals
入力信号名のセル配列を返します。
xSignal
xSignal
オブジェクトは、ソースとターゲットを接続する信号オブジェクトを表します。
コンストラクター
sig = xSignal(sig_name)
sig_name という名前の xSignal
オブジェクトが作成されます。
[sig1, sig2, sig3, ...] = xSignal(name1, name2, name2, ...)
名前付きの信号のリストを作成します。
sig = xSignal
自動生成された名前の xSignal
を作成します。
xSignal
オブジェクトはポート バインディング用に渡すことができます。
メソッド
sig.bind(obj)
obj to sig
を接続します。sig
は xSignal
オブジェクト、obj
は xSignal
または xInport
オブジェクトです。
src = sig.getSrc
xSignal
オブジェクトを駆動しているソース オブジェクトのセル配列を返します。セル配列には、最大で 1 つの要素を含めることができます。ソースが入力ポートの場合、ソース オブジェクトは xInport オブジェクトとなります。ソースがブロックの出力ポートの場合、ソース オブジェクトは構造体で、block と port の 2 つのフィールドがあります。block フィールドには xBlock
オブジェクト、port フィールドにはポート インデックスが入ります。
dst = sig.getDst
xSignal
オブジェクトが駆動しているデスティネーション オブジェクトのセル配列を返します。各要素は、構造体またはxOutport
オブジェクトのいずれかになります。getSrc
メソッドの戻り値と同じように定義されています。
xlsub2script
xlsub2script
は、サブシステムを System Generator スクリプトの最上位に変換するヘルパー関数です。
xlsub2script(Subsystem)
は、サブシステムを最上位のスクリプトに変換します。引数にはモデルも指定できます。
デフォルトでは、生成される M 関数ファイルの名前には、サブシステムの名前が使用され、スペースはアンダースコアに置き換えられます。xlsub2script
が終了すると、生成されたスクリプトの使用方法を説明するヘルプ メッセージが表示されます。この xlsub2script
関数の主な目的は、System Generator スクリプトの学習を容易にすることです。これは、グラフィックを使用してサブシステムを構築し、そのサブシステムを PG API の M 関数に変換できる優れたユーティリティでもあります。
xlsub2script(block)
(block は最下位ブロック) は、ブロックを作成する xBlock
呼び出しを出力します。
xlsub2script
の制限は次のとおりです。
- サブシステムのマスク初期化コードに
gcb
、set_param
、get_param
、add_block などの関数呼び出しが含まれている場合、関数はエラーになるので、マスク初期化コードを修正してこれらの Simulink 呼び出しを削除する必要があります。 - サブシステム内でグローバル変数にアクセスできる場合は、
xlsub2script
を実行するトップ サブシステムに、対応するマスク パラメーターを追加する必要があります。 - ブロックのリンクが切れていると、そのブロックは省略されます。
xlsub2script
は、次のように読み出すこともできます。
xlsub2script(subsyste, options)
options
は、MATLAB 構造体です。options
構造体は、forcewrite
と basevars
の 2 つのフィールドを持つことができます。
同じサブシステムに対し xlsub2script
を 2 回目に呼び出すと、xlsub2script
は既存の M 関数ファイルを上書きしようとします。デフォルトでは、xlsub2script
により、ファイルを上書きするかどうかを確認する質問ダイアログ ボックスが表示されます。options
引数の forcewrite
フィールドが true または 1 に設定されている場合は、xlsub2script
により M 関数ファイルは強制的に上書きされます。
サブシステムは、MATLAB ベースのワークスペースにある一部の変数に依存していることがあります。その場合は、xlsub2script
を実行したときに、xlsub2script
がこれらのベース ワークスペース変数を取得し、ベース ワークスペース変数を処理する適切なコードを生成するようにする必要があります。options
引数の basevars
フィールドはそのためのものです。xlsub2script
がベース ワークスペースのすべての変数を取得するようにする必要がある場合は、basevars
フィールドを all
に設定します。xlsub2script
に変数を選択的に取得する必要がある場合は、basevars
フィールドを文字列のセル配列 (各文字列は変数名) を設定します。
次に、options 引数を指定して xlsub2script
を呼び出した例を示します。
xlsub2script(Subsystem, struct('forcewrite', true));
xlsub2script(Subsystem, struct('forcewrite', true, 'basevars',
'all'));
options.basevars = {'var1', 'var2', 'var3');
xlsub2script(Subsystem, options);
xlsub2script(Subsystem, struct('basevars', {{'var1', 'var2',
'var3'}}));
MATLAB では、構造体のフィールドがセル配列の場合、struct() 関数を呼び出すときに追加の {} が必要になります。
xBlockHelp
xBlockHelp(<block_name>)
は、パラメーター名と、そのパラメーターに有効な値を出力します。パラメーターを指定せずに xBlockHelp
を実行すると、xbsIndex_r4
ライブラリで使用可能なブロックが一覧表示されます。
たとえば、MATLAB のコマンド ラインで次を実行したとします。
xBlockHelp('AddSub')
この場合、次の表が表示されます。
'xbsIndex_r4/AddSub' Parameter Table
Parameter Acceptable value Type
============ ================== ========
mode 'Addition' String
'Subtraction'
'Addition or Subtraction'
------------ ------------------ --------
use_carryin 'off' String
'on'
------------ ------------------ --------
use_carryout 'off' String
'on'
------------ ------------------ --------
en 'off' String
'on'
------------ ------------------ --------
latency An Int value Int
------------ ------------------ --------
precision 'Full' String
'User Defined'
------------ ------------------ --------
arith_type 'Signed (2's comp)' String
'Unsigned'
------------ ------------------ --------
n_bits An Int value Int
------------ ------------------ --------
bin_pt An Int value Int
------------ ------------------ --------
quantization 'Truncate' String
'Round (unbiased: +/- Inf)'
------------ ------------------ --------
overflow 'Wrap' String
'Saturate'
'Flag as error'
------------ ------------------ --------
use_behavioral_HDL 'off' String
'on'
------------ ------------------ --------
pipelined 'off' String
'on'
------------ ------------------ --------
use_rpm 'off' String
'on'
------------ ------------------ --------