matlab-transmit-capture-usrp

Wireless Testbench で波形を送信・キャプチャする

MATLAB で NI USRP 無線機を使用して、RF 波形を生成、送信、キャプチャします。

使用する場合

• 波形（テストトーン、標準準拠信号、カスタム IQ）を無線で送信する場合
• 周波数帯域から IQ データをキャプチャする場合
• ループバックテスト（同じ無線機で送信とキャプチャを行う場合）
• 複数アンテナで送信またはキャプチャする場合
• 長時間のテストで連続送信する場合
• 長時間の取得に向けてバックグラウンドでキャプチャする場合

使用しない場合

• USRP 無線機を初めて設定または接続する場合 — matlab-set-up-usrp-radio スキルを使用してください
• FPGA ターゲティングのワークフロー — NI USRP 無線機をターゲットにするを参照してください
• プリアンブル／エネルギー検出を使用したトリガー式（信号検出による起動）キャプチャの場合 — matlab-detect-capture-usrp スキルを使用してください
• 複数デバイスの同期 — 無線機の管理を参照してください

前提条件

送信／キャプチャオブジェクトを使用する前に、無線機の設定を保存しておく必要があります。利用可能な設定を一覧表示し、使用するものをユーザーに選んでもらいます。

configs = radioConfigurations;
disp(configs)

複数の設定がある場合は、どれを使用するかユーザーに尋ねてください。設定がない場合は、まず設定を行うよう案内してください（matlab-set-up-usrp-radio スキルを参照してください）。

コードを生成する前に、まだ指定されていない場合は、次のパラメーターをユーザーに確認してください。

• 中心周波数 — 無線機の対応範囲内であれば、任意の数値を受け付けます。帯域の候補を限定して提示せず、ユーザーが周波数を入力できるようにしてください。
• サンプルレート — 必要なサンプルレートを尋ねてください。一般的な値（30.72 MHz、61.44 MHz、122.88 MHz、245.76 MHz）を提案しますが、有効な値であればどれでも受け付けます。

適切なオブジェクトの選択

既定では basebandTransceiver を使用してください。 送信のみ、キャプチャのみ、または両方を同時に行うすべてのワークフローに対応しています。特別な理由がない限り、これを使用してください。

オブジェクト	使用する場合
basebandTransceiver	既定の選択肢。 送信、キャプチャ、またはその両方に使用します。ループバック、信号生成、スペクトラム監視、全二重に対応しています
basebandTransmitter	送信専用のオブジェクトが必要な場合のみ使用します（例：TX を個別に制御する別のスクリプト）
basebandReceiver	受信専用のオブジェクトが必要な場合のみ使用します（例：RX を個別に制御する別のスクリプト）

既定で basebandTransceiver を使用する理由： 1 つの無線機設定を使用できるオブジェクトは、一度に 1 つだけです。basebandTransceiver は送信、キャプチャ、またはその両方に対応するため、オブジェクトを切り替えることなく、ほとんどのワークフローをカバーできます。スタンドアロンオブジェクト（basebandTransmitter、basebandReceiver）は、別々のスクリプトやアプリケーションで送信方向または受信方向を個別に制御する必要がある場合に便利です。

プロパティ名はオブジェクトの種類によって異なります。

	basebandTransceiver	basebandTransmitter / basebandReceiver
ゲイン	TransmitRadioGain、CaptureRadioGain	RadioGain
周波数	TransmitCenterFrequency、CaptureCenterFrequency	CenterFrequency
アンテナ	TransmitAntennas、CaptureAntennas	Antennas

トランシーバーでは、方向を区別するために Transmit／Capture の接頭辞を使用します。スタンドアロンオブジェクトは一方向のみを扱うため、接頭辞は不要です。

ワークフロー

ステップ 1：無線機オブジェクトを作成する

radio = radioConfigurations("MyN310");
bbtrx = basebandTransceiver(radio);

プリロードオプション： Preload=true を渡すと、初回使用時ではなく、オブジェクトの構築時に FPGA アプリケーションが読み込まれます。これにより、最初の transmit または capture の呼び出しで数秒かかる遅延を回避できます。

bbtrx = basebandTransceiver(radio, Preload=true);

スタンドアロンオブジェクト（独立した一方向制御が必要な場合のみ）：

bbtx = basebandTransmitter(radio);  % TX only
bbrx = basebandReceiver(radio);     % RX only

ステップ 2：プロパティを設定する

送信またはキャプチャを開始する前に、オブジェクトを設定します。オブジェクトの作成後にプロパティを設定することもできますが、変更内容によっては再読み込みに時間がかかります。

bbtrx.SampleRate = 30.72e6;
bbtrx.TransmitCenterFrequency = 3.5e9;
bbtrx.CaptureCenterFrequency = 3.5e9;
bbtrx.TransmitRadioGain = 20;
bbtrx.CaptureRadioGain = 40;

必要な方向のプロパティだけを設定してください。送信のみのワークフローでは、Capture* プロパティは省略します（その逆も同様です）。

スタンドアロンオブジェクト（basebandTransmitter ／ basebandReceiver）を使用する場合、プロパティに接頭辞は付きません。

bbtx.SampleRate = 30.72e6;
bbtx.CenterFrequency = 3.5e9;    % not TransmitCenterFrequency
bbtx.RadioGain = 20;              % not TransmitRadioGain

プロパティの設定ガイド：

プロパティ	ガイド
SampleRate	波形の帯域幅に合わせる必要があります。一般的な値：30.72 MHz（LTE/NR）、61.44 MHz、122.88 MHz、245.76 MHz
TransmitRadioGain	クリッピングを防ぐため、低い値（10～20 dB）から始めます。信号強度が十分になるまで上げてください
CaptureRadioGain	中程度の値（30～40 dB）から始めます。高すぎると ADC でクリッピングが発生し、低すぎると信号がノイズに埋もれます
TransmitCenterFrequency / CaptureCenterFrequency	無線機がサポートする範囲内に設定する必要があります（デバイスによって異なり、通常は 1 MHz～6/8 GHz）
DroppedSamplesAction	開発中は、サンプルがドロップしても処理を続けるために "warning" を設定します。本番環境では "error" を使用してください

ステップ 3：送信波形を準備する

波形は、複素列ベクトル（単一アンテナの場合）または複素行列（複数アンテナの場合。アンテナごとに 1 列）にする必要があります。値は [-1, 1] の範囲に正規化してください。

テストトーン：

numSamples = 30720;
t = (0:numSamples-1)' / bbtrx.SampleRate;
txWaveform = 0.8 * exp(1j*2*pi*1e6*t);

OFDM に似たランダム信号：

numSamples = 30720;
txWaveform = complex(randn(numSamples,1), randn(numSamples,1));
txWaveform = 0.7 * txWaveform / max(abs(txWaveform));

事前生成した波形をファイルから読み込む：

waveStruct = load("myWaveform.mat");
txWaveform = waveStruct.waveform;
txWaveform = 0.8 * txWaveform / max(abs(txWaveform));

このパターンは、5G Toolbox、LTE Toolbox、WLAN Toolbox、またはカスタムの信号生成ワークフローで生成した波形に使用できます。

波形の要件：

要件	詳細
データ型	複素 double、single、または int16（TransmitDataType で指定）
振幅	double/single の場合、ピーク振幅は 1.0 以下（1 を超える値は DAC でクリッピングします）
次元	列ベクトル（単一アンテナ）または N×M 行列（M = TX アンテナ数）
行数	偶数にする必要があります
最小長	513 サンプル未満の波形では、アンダーフロー保護のため最大 1024 サンプルが予約されます

Preload=true を使用する場合は、コンストラクターに TransmitDataType を渡してください。

FPGA アプリケーションでは、構築時に特定の送信データクラスが設定されます。プリロードしない場合、最初の transmit 呼び出し時に波形からクラスが推定されます。プリロードする場合、トランシーバーには推定元となる波形がないため、TransmitDataType を明示的に渡してください。指定しないと、最初の transmit 呼び出し時に FPGA が再読み込みされ、プリロードの意味がなくなります。

bbtrx = basebandTransceiver(radio, Preload=true, TransmitDataType="double");
% ... configure frequency/gain/sample rate ...
transmit(bbtrx, txWaveform, "continuous");   % waveform class must match TransmitDataType

ステップ 4：送信する

1 回のみ（シングルショット）— 波形をちょうど 1 回送信します。

transmit(bbtrx, txWaveform, "once");

無線機は波形を 1 回送信した後、自動的に停止します。パルス送信や 1 回限りのテストに使用します。このモードでは、信頼性を高めるために波形の末尾に余分なサンプルを追加してください。

連続 — 停止するまで繰り返し送信します。

transmit(bbtrx, txWaveform, "continuous");

stopTransmission が呼び出されるまで、無線機は波形を連続してループ再生します。次の用途に使用します。

• 干渉または信号の継続的な生成
• キャプチャのタイミングと送信のタイミングを切り離したループバックテスト
• 受信機が継続的な信号を必要とする無線通信テスト

連続送信を停止する：

stopTransmission(bbtrx);

ステップ 5：キャプチャする

フォアグラウンドキャプチャ（完了するまで MATLAB をブロックします）：

[data, timestamp, droppedSamples] = capture(bbtrx, milliseconds(10));

length 引数には、duration 値（例：seconds(1)、milliseconds(10)）または正の整数のサンプル数を指定できます。

出力引数：

出力	型	説明
data	複素ベクトル／行列	IQ サンプル。行 = サンプル、列 = アンテナ。データ型は CaptureDataType プロパティと一致します。最初のサンプルには過渡応答が含まれる場合があります
timestamp	datetime	ハードウェアへのキャプチャ要求の直前に作成されるタイムスタンプ
droppedSamples	logical	サンプルがドロップした場合は true（ネットワーク／ホストの問題）、正常に取得できた場合は false

CaptureDataType の既定値は int16 です。FFT、フィルタリング、演算の前に型変換してください。 キャプチャした data は複素ベクトル／行列であり、そのクラスは CaptureDataType と一致します。メモリ使用量を抑えるため、デフォルトは固定小数点の "int16" です。fft、abs、filter、bandpass、pwelch、要素単位の演算を含む、ほとんどの MATLAB 信号処理関数は複素 int16 を受け付けないため、実行時にエラーになります。次のいずれかの方法で対処してください。

% Option A — set the property before capture (all downstream code sees double)
bbtrx.CaptureDataType = "double";
[data, ~, dropped] = capture(bbtrx, milliseconds(10));
X = fft(data);   % works

% Option B — cast after capture (keep the memory savings during transfer)
[data, ~, dropped] = capture(bbtrx, milliseconds(10));
data = double(data);
X = fft(data);   % works

デフォルトではオプション A を使用してください。キャプチャ中のメモリに余裕がなく、処理を始めるまでコンパクトな int16 ペイロードを保持したい場合に限り、オプション B を優先してください。

バックグラウンドキャプチャ（ノンブロッキング）：

次の場合はバックグラウンドキャプチャを使用してください。

• キャプチャ時間が長く（数秒以上）、MATLAB の応答性を保つ必要がある
• 取得中に後処理、表示の更新、その他の作業を行いたい
• キャプチャと連続送信を組み合わせ、両方を監視する必要がある

次の場合はフォアグラウンドキャプチャ（デフォルト）を使用してください。

• キャプチャが短く、次のステップですぐにデータが必要である
• スクリプトが直線的である（並行して行う作業がない）

適切なパターンの選択：

シナリオ	パターン
短時間のキャプチャで、すぐにデータが必要	[data,~,dropped] = capture(bbtrx, milliseconds(100));
長時間のキャプチャで、データが RAM に収まる	capture(bbtrx, seconds(30), Background=true); の後に captureOutputs
長時間のキャプチャで、データが RAM に収まらない	capture(bbtrx, seconds(60), Background=true, SaveLocation="data.mat", UseRadioBuffer=false);
完了時に通知が必要	CompletionFcn=@(data,ts,dropped) myCallback(data) を追加

ポーリングを使用したバックグラウンドキャプチャ：

capture(bbtrx, seconds(30), Background=true);

% Poll until complete
while isCapturing(bbtrx)
    pause(1);
end

% Retrieve results
[data, timestamp, droppedSamples] = captureOutputs(bbtrx);

コールバックを使用したバックグラウンドキャプチャ（ポーリング不要）：

capture(bbtrx, seconds(30), Background=true, ...
    CompletionFcn=@(data, ts, dropped) handleCapture(data, dropped));

ファイルへの長時間キャプチャ（バックグラウンド＋SaveLocation＋ホストへの直接転送）：

オンボードバッファまたは RAM に収まらないキャプチャでは、次の 3 つのオプションを組み合わせます。

capture(bbtrx, seconds(60), ...
    Background=true, ...
    SaveLocation="captured_data.mat", ...
    UseRadioBuffer=false);

while isCapturing(bbtrx)
    pause(5);
end
filePath = captureOutputs(bbtrx);
fprintf("Saved to: %s\n", filePath);

SaveLocation を指定すると、captureOutputs はデータをワークスペースに読み込む代わりにファイルパスを返します。

バックグラウンドキャプチャを途中で停止する：

stopCapture(bbtrx);
[data, timestamp, droppedSamples] = captureOutputs(bbtrx);

UseRadioBuffer — 無線バッファとホストへの直接転送の選択：

UseRadioBuffer の名前と値の引数は、取得中にキャプチャしたサンプルを保存する場所を制御します。適切な選択は、キャプチャ時間、サンプルレート、ホストのネットワーク性能によって異なります。

% Radio buffer (default) — data is stored in onboard radio memory, then
% transferred to the host after capture completes. Most reliable option.
[data, ~, dropped] = capture(bbtrx, milliseconds(100));

% Direct-to-host — data streams continuously from radio to host over the
% network during the capture. Required when capture exceeds onboard memory.
[data, ~, dropped] = capture(bbtrx, seconds(30), UseRadioBuffer=false);

次の場合は UseRadioBuffer=true（デフォルト）を使用してください。

• キャプチャ長が無線機のオンボードメモリに収まる
• 最も信頼性の高いキャプチャが必要である（ホストの継続的なスループットに依存しない）
• サンプルレートが高く、サンプルのドロップを一切許容できない

次の場合は UseRadioBuffer=false を使用してください。

• キャプチャ長が無線機のオンボードバッファ容量を超える（下表を参照）
• TwinRX ドーターボードを搭載した USRP X310 で、2 つを超えるアンテナチャネルをキャプチャする
• 任意の長さ（数分から数時間）のキャプチャが必要である

オンボードバッファ容量（ホストへの直接転送が必要になる条件）：

デバイス	最大サンプル数	30.72 MHz での概算時間
USRP E320 / N-series	2^29 (~537M)	~17.5 s
USRP X300 / X310	2^28 (~268M)	~8.7 s
USRP X410	2^30 (~1.07B)	~34.8 s

ホストへの直接転送に関するパフォーマンス上の考慮事項：

ホストへの直接転送によるキャプチャでは、キャプチャ時間全体にわたってネットワークの継続的なスループットが必要です。達成可能な最大サンプルレートは、ホストとネットワークの構成によって異なり、システム負荷に応じて実行ごとに変動します。ドロップが発生する場合は、サンプルレートを下げるか、アンテナ数を減らすか、radioSetupWizard を実行してプラットフォーム向けにホストのネットワーク設定を最適化してください。

ホストの性能評価： ドロップしたサンプルを無視する DroppedSamplesAction="none" を指定し、成功するまでサンプルレートを下げながらキャプチャを繰り返すことで、ホストへの直接転送で持続可能な最大レートを確認できます。

bbrx.DroppedSamplesAction = "none";
sampleRates = 245.76e6 : -10e6 : 10e6;
for idx = 1:numel(sampleRates)
    bbrx.SampleRate = sampleRates(idx);
    [~, ~, dropped] = capture(bbrx, 2*2^28, UseRadioBuffer=false);
    if ~dropped
        fprintf("Max sustained rate: %.1f MHz\n", sampleRates(idx)/1e6);
        break
    end
end

バックグラウンドキャプチャを途中で停止する：

stopCapture(bbtrx);
[data, timestamp, droppedSamples] = captureOutputs(bbtrx);

ステップ 6：ループバックテスト（同じ無線機で送信＋キャプチャ）

ループバックテストでは、basebandTransceiver を使用して TX/RX チェーン全体を検証します。TransmitCenterFrequency と CaptureCenterFrequency に同じ値を設定すると、信号が内部で結合されます。

方法 A：連続送信してからキャプチャ

連続送信を開始し、無線機のフロントエンドが安定するまで少し待ってから、キャプチャします。

radio = radioConfigurations("MyN310");
bbtrx = basebandTransceiver(radio, Preload=true);
bbtrx.SampleRate = 61.44e6;
bbtrx.TransmitCenterFrequency = 2.4e9;
bbtrx.CaptureCenterFrequency = 2.4e9;
bbtrx.TransmitRadioGain = 10;
bbtrx.CaptureRadioGain = 30;

% Generate test tone
numSamples = 61440;
t = (0:numSamples-1)' / bbtrx.SampleRate;
txWaveform = 0.8 * exp(1j*2*pi*1e6*t);

% Transmit continuously, pause for stabilization, then capture
transmit(bbtrx, txWaveform, "continuous");
pause(1);
[rxData, ~, droppedSamples] = capture(bbtrx, milliseconds(10));
stopTransmission(bbtrx);

% Verify
if ~droppedSamples
    fprintf("Loopback OK: captured %d samples, no drops.\n", size(rxData,1));
else
    warning("Samples were dropped during loopback.");
end

% Visualize
sa = spectrumAnalyzer(SampleRate=bbtrx.SampleRate);
sa(rxData);

ステップ 7：マルチアンテナ構成

MIMO またはマルチチャネルで動作させる場合は、アンテナのプロパティを配列に設定し、行列形式の波形を指定します。

radio = radioConfigurations("MyX410");
bbtrx = basebandTransceiver(radio);
bbtrx.SampleRate = 61.44e6;

% Configure 2 TX and 2 RX antennas
bbtrx.TransmitAntennas = ["DB0:RF0:TX/RX0", "DB0:RF1:TX/RX0"];
bbtrx.CaptureAntennas = ["DB0:RF0:RX1", "DB0:RF1:RX1"];
bbtrx.TransmitCenterFrequency = [3.5e9, 3.5e9];
bbtrx.CaptureCenterFrequency = [3.5e9, 3.5e9];
bbtrx.TransmitRadioGain = [15, 15];
bbtrx.CaptureRadioGain = [35, 35];

% Waveform: N×2 matrix (one column per TX antenna)
numSamples = 61440;
t = (0:numSamples-1)' / bbtrx.SampleRate;
tx1 = 0.7 * exp(1j*2*pi*1e6*t);
tx2 = 0.7 * exp(1j*2*pi*2e6*t);
txWaveform = [tx1, tx2];

transmit(bbtrx, txWaveform, "continuous");
[rxData, ~, dropped] = capture(bbtrx, milliseconds(10));
stopTransmission(bbtrx);

% rxData is N×2: one column per RX antenna
fprintf("Captured %d samples on %d antennas.\n", size(rxData,1), size(rxData,2));

アンテナ名はデバイスによって異なります — TX ポートと RX ポートでは名前が異なります：

デバイス	TransmitAntennas	CaptureAntennas
X410	"DB0:RF0:TX/RX0", "DB0:RF1:TX/RX0", "DB1:RF0:TX/RX0", "DB1:RF1:TX/RX0"	"DB0:RF0:RX1", "DB0:RF1:RX1", "DB1:RF0:RX1", "DB1:RF1:RX1"
X310 (UBX)	"RFA:TX/RX", "RFB:TX/RX"	"RFA:RX2", "RFB:RX2"
N310	"RF0:TX/RX", "RF1:TX/RX", "RF2:TX/RX", "RF3:TX/RX"	"RF0:RX2", "RF1:RX2", "RF2:RX2", "RF3:RX2"
N320/N321	"RF0:TX/RX", "RF1:TX/RX"	"RF0:RX2", "RF1:RX2"
E320	"RFA:TX/RX"	"RFA:RX2", "RFB:RX2"

無効な値を割り当てると、お使いのデバイスで使用できるアンテナ名の一覧が表示されます。

トラブルシューティング

症状	原因	対処方法
サンプルが欠落する	ホスト／ネットワークがスループットを維持できない	radioSetupWizard を実行してホスト設定を最適化するか、サンプルレート／アンテナ数を減らします
キャプチャした信号がクリッピングする	CaptureRadioGain が高すぎる	ピーク振幅が 0.9 未満になるまでゲインを下げます
キャプチャした信号がノイズフロアに埋もれる	CaptureRadioGain が低すぎる	ゲインを少しずつ上げます
TX 信号が歪む	波形の振幅が 1.0 を超えている	正規化します：waveform = waveform / max(abs(waveform))
初回呼び出しで数秒の遅延が発生する	FPGA アプリケーションを読み込み中	作成時に Preload=true を使用します
"Resource not available" エラー	別のオブジェクトが無線機を使用している	既存のオブジェクトを消去します：clear bbtrx
キャプチャ長がバッファを超える	オンボードメモリが不足している	長時間のキャプチャでは UseRadioBuffer=false を使用します
バックグラウンドキャプチャが完了しない	キャプチャがまだ実行中	isCapturing() を確認し、停止している場合は stopCapture() を使用します

主要関数リファレンス

関数／メソッド	用途
basebandTransceiver	無線機オブジェクトを作成します（デフォルト — TX、RX、またはその両方を処理）
basebandTransmitter	TX 専用の無線機オブジェクトを作成します（単独使用のみ）
basebandReceiver	RX 専用の無線機オブジェクトを作成します（単独使用のみ）
transmit(obj, waveform, "once")	1 回限りの送信
transmit(obj, waveform, "continuous")	連続送信（停止するまでループ）
stopTransmission(obj)	連続送信を停止します
capture(obj, length)	フォアグラウンドキャプチャ（ブロッキング）
capture(obj, length, Background=true)	バックグラウンドキャプチャ（ノンブロッキング）
captureOutputs(obj)	バックグラウンドキャプチャの結果を取得します
isCapturing(obj)	バックグラウンドキャプチャが実行中かどうかを確認します
stopCapture(obj)	バックグラウンドキャプチャを停止します
radioConfigurations	保存済みの無線機構成を一覧表示／読み込みします

規則

• デフォルトでは basebandTransceiver を使用してください。 送信のみ、受信のみ、または両方の場合に使用します。別のスクリプトで送信と受信を個別に制御する必要がある場合に限り、basebandTransmitter／basebandReceiver を使用してください。
• 波形を正規化してください。 ヘッドルームを確保し、DAC のクリッピングを防ぐため、ピーク振幅が常に 0.8 以下になるようにスケーリングしてください。
• 低ゲインから開始してください。 TX ゲインは 10～20 dB、RX ゲインは 30～40 dB から始め、観測した信号レベルに応じて調整してください。
• キャプチャの前に連続送信を開始してください。 ループバックでは、最初に transmit(..., "continuous") を開始し、その後 capture を実行してください。これにより、キャプチャ開始時に信号が存在することを確保できます。
• 送信は必ず停止してください。 終了時に stopTransmission を呼び出し、無線リソースを解放してください。
• サンプルのドロップを確認してください。 capture の 3 番目の出力を必ず確認してください。これは論理値で、true はドロップが発生したことを示します。true の場合は、radioSetupWizard を実行してホスト設定を最適化するか、サンプルレートを下げてください。
• 出力を取得する前に待機してください。 isCapturing が false を返すか、stopCapture が呼び出されるまで、captureOutputs を呼び出さないでください。キャプチャの実行中に呼び出すと、エラーになります。
• キャプチャ長の指定には時間を使用してください。 読みやすさとサンプルレート間の移植性を高めるため、生のサンプル数よりも milliseconds(N) または seconds(N) を使用してください。
• オブジェクトをクリーンアップしてください。 終了時に無線オブジェクトに対して clear を呼び出し、他のアプリケーションがハードウェアを使用できるようにしてください。

---

Copyright 2026 The MathWorks, Inc.

---