matlab-simulate-wireless-network

ワイヤレスネットワークシミュレーションの基礎

システムレベルのワイヤレスシミュレーションで使用する基本パターンです。各技術に特化したスキルでは、ノードの作成、接続の設定、KPI の抽出について説明します。

使用する場面

• wirelessNetworkSimulator を使用してシステムレベルのワイヤレスネットワークシミュレーションを作成する場合
• トラフィックソース（networkTrafficOnOff、networkTrafficFTP、networkTrafficVoIP、networkTrafficVideoConference）を追加する場合
• ノードのモビリティ（ランダムウェイポイント、カスタムモデル）を設定する場合
• wirelessNetworkEventTracer または IQ ロガーでイベントや IQ サンプルを記録する場合
• wirelessTrafficViewer でトラフィックを、wirelessNetworkViewer でネットワークレイアウトを可視化する場合
• scheduleAction でシミュレーション中のアクションをスケジュールする場合
• シミュレーションパラメーターのパラメトリックスイープを実行する場合
• pcapWriter または技術固有の PCAP ライターで PCAP ファイルを書き込む場合
• wnet.Node のサブクラス化によってカスタムノードを作成する場合
• ワイヤレスノードにイベントコールバックを登録する場合

使用しない場面

• wirelessNetworkSimulator を使用しない PHY レイヤーまたはリンクレベルのシミュレーション
• Bluetooth 固有のトポロジー設定（代わりに matlab-simulate-bluetooth-network を使用してください）
• WLAN 固有または 5G NR 固有の設定（それぞれの技術に対応したスキルを使用してください）
• 信号処理または波形生成のタスク

ノードの作成

シミュレーター内のすべてのノードは wnet.Node を継承します。適切なノードタイプを選択してください。

技術	ノードコンストラクター	備考
Bluetooth LE	bluetoothLENode("central") / bluetoothLENode("peripheral")	matlab-simulate-bluetooth-network スキルを使用してください
Classic Bluetooth BR/EDR	bluetoothNode("central") / bluetoothNode("peripheral")	matlab-simulate-bluetooth-network スキルを使用してください
WLAN	wlanNode(...)	WLAN Toolbox が必要です
5G NR	nrGNB(...) / nrUE(...)	5G Toolbox が必要です
その他すべて／カスタム	wnet.Node をサブクラス化	references/custom-node.md を参照してください

wnet.Node は抽象クラスです。直接インスタンス化しないでください。 シナリオで上記の特定技術を使用しない場合は、wnet.Node を継承するカスタムノードクラスを必ず作成してください。技術ノード（bluetoothLENode、bluetoothNode、wlanNode、nrGNB、nrUE）は内部で wnet.Node インターフェイスを実装しています。Position、ID、Name、Velocity、addMobility、registerEventCallback、statistics などのプロパティやメソッドは、すべてのノードタイプで使用できます。

ワークフロー

システムレベルのシミュレーションは、すべて次の順序で実行します。

1. wirelessNetworkSimulator.init（必ず最初に実行）
2. ノードを作成 — 技術固有のコンストラクターが利用できる場合はそれを使用し、利用できない場合は wnet.Node をサブクラス化します（references/custom-node.md を参照）
3. 接続を設定（技術固有）
4. addTrafficSource（技術ノードのみ。複数の宛先にはベクトル化して指定します。カスタムノードは run() でトラフィックを生成します）
5. addMobility（任意）
6. 計測機能を設定 — イベントトレーサー、IQ ロガー、トラフィックビューアー（任意）
7. addNodes(sim, nodes)（バッチで追加し、技術タイプごとに 1 回呼び出します）
8. run(sim, duration) を実行、または IsLastStep=false を指定して複数ステップで実行
9. statistics() または技術固有の KPI 関数を呼び出す

シミュレーターの初期化

wirelessNetworkSimulator.init は、最初の実行可能ステートメントでなければなりません。シミュレーターはシングルトンであり、.init を呼び出すと再初期化されます。コンストラクター（存在しない wirelessNetworkSimulator()）は使用しないでください。

clearvars;
rng("default");
sim = wirelessNetworkSimulator.init;

カスタムノード（wnet.Node のサブクラス）

5 つのメソッドをオーバーライドします：run、pullTransmittedPacket、pushReceivedPacket、isPacketRelevant、statistics。パケット構造体の作成には、必ず pkt = wirelessPacket を使用してください。これにより、チャネルモデルに必要な Metadata.Channel を含む、すべての必須フィールドが初期化されます。TechnologyType フィールドには wnet.TechnologyType.Custom1～Custom9 を使用してください。すべてのメソッドの一覧、パケットフィールド、受信バッファリングのパターン、サンプルについては、references/custom-node.md を参照してください。

アクセス指定子： オーバーライドするすべてのメソッドは、親クラス wnet.Node のアクセス指定子と一致させる必要があります。R2026a では、run、pullTransmittedPacket、pushReceivedPacket、isPacketRelevant、statistics はすべて wnet.Node で public です。コンストラクターとともに、単一の methods ブロック（既定で public）に配置してください。異なるアクセス指定子（例：protected）を使用すると、MATLAB エラーが発生します。

重要： run() での送信は、NextTxTime と round(..., 9) を使用してガードする必要があります。シミュレーターは受信パケットを配信した後、同じ currentTime で run() を再度呼び出すためです。このガードがないと、ノードが 2 つ以上の場合に無限ループが発生します。

トラブルシューティング： カスタムノードの作成時にエラーが発生する場合は、動作する実装例として、組み込みの例 openExample("wnet/CreateAndSimulateWirelessNetworkOfCustomNodesExample") を参照してください。カスタムノードのクラスコードを確認し、メソッドシグネチャとアクセス指定子が正しいか確認してください。

ノードのベクトル化作成

サポートされる任意のノードタイプで、Position=[N×3] および Name=[1×N string] を指定して複数のノードを作成できます。

nodes = NodeConstructor(Position=[5 0 0; 0 5 0; -5 0 0], Name=["N1", "N2", "N3"]);

nodePositionRandom によるランダム配置

region = nsidedpoly(6, Center=[0 0], SideLength=50);
positions = nodePositionRandom(region, NumNodes=10, ZCoordinate=0);
nodes = NodeConstructor(Position=positions, Name="N"+(1:10));

addNodes の一括実行

テクノロジータイプごとに addNodes を 1 回実行します。ノードごとに呼び出してはいけません。

addNodes(sim, [sourceNode; destNodes(:)]);    % same type
addNodes(sim, nodesTypeA);                     % mixed sim: separate calls
addNodes(sim, nodesTypeB);

トラフィックソース

addTrafficSource は、テクノロジーノード（BLE、BR/EDR、WLAN、NR）でのみ使用できます。カスタム wnet.Node サブクラスでは使用できません。

networkTrafficOnOff の DataRate の単位は Kbps（キロビット/秒）です。generate() メソッドは、パケット間の時間を ms 単位で返します。

traffic = networkTrafficOnOff(DataRate=100, PacketSize=50, OnTime=Inf);

よくある間違い： 100 Kbps を指定するために DataRate=100000 とすると、これは 100 Mbps（1000 倍の速度）になります。エラーなく実行されますが、現実離れしたトラフィックが生成されます。すべてのトラフィックソースタイプとそのパラメーターについては、references/traffic-models.md を参照してください。

同一のフローには、1 つのトラフィックオブジェクトを再利用してください。DestinationNode にはベクトルを指定できます。

addTrafficSource(central, traffic, DestinationNode=[p1; p2; p3]);

統計のベクトル化

テクノロジーノード（BLE、BR/EDR、WLAN、NR）では、ベクトル化された statistics は 1×N の構造体配列を返します。

allStats = statistics(nodes);  % 1×N struct array (technology nodes)
rxBytes = [allStats.App];      % Concatenate sub-structs

カスタム wnet.Node サブクラスでは、ベクトル化時の動作は statistics() メソッドの実装によって異なります。返される構造体がノードごとに異なる場合は、ノードごとに呼び出してください。

モビリティ

ノードベクトルに対して直接 addMobility を実行します（ノードごとに実行するのではありません）。境界は [x_center, y_center, width, height] です（[xmin, ymin, xmax, ymax] ではありません）。

addMobility(nodes, MobilityModel="random-waypoint", SpeedRange=[1.0 1.5], Bounds=[10 0 12 4]);

モデル："random-waypoint"、"random-walk"、"constant-velocity"。すべてのノードは、x_center から ±width/2、y_center から ±height/2 の範囲内に配置する必要があります。詳しい例については、references/mobility-models.md を参照してください。

複数ステップのシミュレーション

各 run で指定するのは、絶対的な終了時刻ではなく、追加の実行時間（相対値）です。

run(sim, 0.3, IsLastStep=false);   % Run 0.3s, keep state
stats_mid = statistics(node);
run(sim, 0.2);                      % Additional 0.2s (0.5s total)

スケジュールされたアクション

scheduleAction(sim, @myCallback, userData, 0.3);         % one-shot at t=0.3s
scheduleAction(sim, @myCallback, userData, 0.1, 0.05);   % periodic: start 0.1s, repeat 0.05s

コールバックのシグネチャ — 引数は 2 つ (actionID, userData) です。

function myCallback(actionID, userData)
    stats = statistics(userData.node);
end

シミュレーション中に有効な操作： statistics(node)、node.Position の変更、テクノロジー固有のシミュレーション中メソッド。ほとんどの RF プロパティは、run() の開始後に変更できません。

カスタムチャネルモデル

addChannelModel(sim, @myChannelModel);

function txData = myChannelModel(rxInfo, txData)
    dist = norm(rxInfo.Position - txData.TransmitterPosition);
    fspl = 20*log10(dist) + 20*log10(txData.CenterFrequency) - 147.55;
    txData.Metadata.Channel.PathDelays = 0;
    txData.Metadata.Channel.PathGains = -fspl;
end

シグネチャ：function txData = fcn(rxInfo, txData) — 入力は 1 つではなく 2 つです。

rxInfo フィールド：ID、Position、Velocity、NumReceiveAntennas。

主な txData フィールド：Power、CenterFrequency、StartTime、TransmitterPosition、TransmitterVelocity、Bandwidth、Metadata.Channel（PathGains、PathDelays、PathFilters、SampleTimes）。

既定では FSPL を使用します。距離に応じたフェージング、マルチパス、または環境固有の伝搬には、addChannelModel を使用してください。

パラメトリックスイープ

（シングルトンは状態を保持するため）wirelessNetworkSimulator.init はすべてのループ反復の先頭に置く必要があります。複数次元および parfor のパターンについては、references/parametric-sweep-pattern.md を参照してください。

計測（R2026a）

すべてのツールは run() の前に作成する必要があります。詳細については、references/event-tracing-iq-logging.md を参照してください。

eventTracer = wirelessNetworkEventTracer(FileName="events.mat");
addNodes(eventTracer, nodes, EventName=["TransmissionStarted", "ReceptionEnded"]);

iqLogger = wirelessIQLogger(receiverNodes, FileName="iq_samples.mat");

viewer = wirelessTrafficViewer;
addNodes(viewer, nodes);

• イベントトレーサー：すべてのノードタイプに対応します。addNodes は、指定された各 EventName について各ノードで registerEventCallback を呼び出します。カスタム wnet.Node サブクラスでイベント名に対応するには、ノードで registerEventCallback をオーバーライドする必要があります（references/custom-node.md を参照）。MAT ファイルがすでに存在する場合はエラーになります。read(eventTracer, EventName=..., NodeName=..., TimeRange=...) で読み取ります。
• IQ ロガー：ノードは作成時に固定されます（addNodes はありません）。80 MHz で 0.1 秒あたりノードごとに約 4～5 MB を使用します。テクノロジーノード専用です。カスタム wnet.Node サブクラスには対応していません。
• ネットワークビューアー：wirelessNetworkViewer(NetworkSimulator=sim) ＋ addNodes(viewer, nodes, Type="Transmitter"/"Receiver") ＋ showBoundary(viewer, BoundaryShape="circle", Bounds=radius, Position=[x y z])。形状は "circle"、"rectangle"、"hexagon" です。
• トラフィックビューアー：状態遷移とチャネル占有状況をリアルタイムで表示します。テクノロジーノード専用です。カスタム wnet.Node サブクラスには対応していません。

PCAP キャプチャ

任意のテクノロジーには汎用の pcapWriter を使用します。テクノロジー固有のライター（blePCAPWriter、wlanPCAPWriter、nrPCAPWriter）は、Node= プロパティを介してノードから自動的にキャプチャします。

% Generic (manual write)
pcapObj = pcapWriter(FileName="my_capture");
writeGlobalHeader(pcapObj, linkType);
write(pcapObj, packetBytes, round(simTime * 1e6));  % timestamp in microseconds (integer)

% Technology-specific (auto-capture, no write calls needed)
blePcap = blePCAPWriter(FileName="ble_capture", Node=[central; peripheral]);

一般的なリンクタイプ：LINKTYPE_USER0（147）、LINKTYPE_IEEE802_11（105）。読み取り：readAll(pcapReader("file.pcap"))。

Bluetooth 固有の PCAP キャプチャについては、references/bluetooth-capture.md を参照してください。

イベントコールバック（registerEventCallback）

特定のイベントが発生したときに呼び出されるコールバックをノードに登録します。コールバックには単一の引数（イベントデータ構造体）が渡されます。

registerEventCallback(node, "ReceptionEnded", @myCallback);

function myCallback(eventData)
    disp(eventData.Timestamp);          % sim time (seconds)
    disp(eventData.EventData.SINR);     % technology-specific nested payload
end

テクノロジーノード（BLE、BR/EDR、WLAN、NR）：registerEventCallback を呼び出して登録します。ノードの内部実装により、シミュレーション中の適切なタイミングでコールバックが自動的に呼び出されます。

カスタム wnet.Node サブクラス：基底クラスの wnet.Node.registerEventCallback は何もしないスタブです。引数は受け取りますが、コールバックを保存したり呼び出したりしません。サブクラスで registerEventCallback をオーバーライドしてコールバックを保存し、適切なタイミング（例：run() での送信後、pushReceivedPacket() での受信後）に明示的に呼び出す必要があります。完全な実装パターンについては、references/custom-node.md を参照してください。

トップレベルのフィールド：EventName、NodeName、NodeID、Timestamp、TechnologyType、EventData（ネストされた構造体）。

Bluetooth 固有のイベントデータフィールドについては、references/bluetooth-capture.md を参照してください。

よくある間違い

間違い	正しい記述
node = wnet.Node(...) とする、または抽象クラスのまま wnet.Node を作成する	wnet.Node は抽象クラスです。サブクラス化してください：classdef MyNode < wnet.Node
Bluetooth 以外の用途に bluetoothLENode／bluetoothNode を使用する	汎用またはカスタムのワイヤレスノードには、カスタムの wnet.Node サブクラスを使用してください
TechnologyType = "custom"（文字列）	wnet.TechnologyType.Custom1（数値定数 101～109）を使用してください
Bounds=[0 0 20 20] を [xmin,ymin,xmax,ymax] として指定する	Bounds=[x_center, y_center, width, height] と指定してください
scheduleAction 用に function myFcn(userData) を指定する	function myFcn(actionID, userData) と指定します（引数は 2 つ）
addChannelModel 用に function txData = fcn(txData) を指定する	function txData = fcn(rxInfo, txData) と指定します（入力は 2 つ）
addMobility(sim, nodes, ...) とする	addMobility(nodes, ...) とします。これはノードのメソッドであり、sim のメソッドではありません
100 Kbps に DataRate=100000 を指定する	DataRate=100 とします。単位は Kbps です
writeGlobalHeader を呼び出さずに pcapWriter() を使用する	write() の前に必ず writeGlobalHeader(pcapObj, linkType) を呼び出してください
ロギング用にファイル書き込みコールバックを作成する	代わりに wirelessNetworkEventTracer を使用してください
registerEventCallback をオーバーライドせずにカスタムノードで呼び出す	基底クラスの wnet.Node.registerEventCallback は何もしません。コールバックを保存するようにオーバーライドし、run()／pushReceivedPacket() から手動で発火させてください
カスタムの wnet.Node に addTrafficSource(customNode, traffic, ...) を使用する	addTrafficSource はテクノロジーノード専用です
pushReceivedPacket で受信パケットを無視する	wnet.internal.interferenceBuffer と addPacket を使用して受信パケットを保存してください