matlab-set-up-usrp-radio

使用 Wireless Testbench 设置 USRP 无线电

连接、配置并验证受支持的 NI USRP 无线电，以便在 MATLAB 中与 Wireless Testbench 配合使用。

必需参考资料 — 立即加载

• references/troubleshooting.md — 诊断检查清单、Mender 更新、网络路径隔离

适用场景

• 首次将 USRP 无线电连接到主机计算机
• 配置用于 USRP 数据流传输的网络设置（NIC、IP 地址、MTU）
• 运行 radioSetupWizard 或 radioConfigurations
• 排查“未找到无线电”、连接错误或样本丢失问题
• 验证无线电设置能否端到端正常工作

不适用场景

以下工作流都需要先建立正常的无线电连接 — 请使用此技能完成该设置步骤。

• FPGA 目标配置或 HDL 工作流 — 查找专用技能，或参阅 Target NI USRP Radios
• 生成或传输波形 — 查找专用技能，或参阅 Transmit and Capture
• 使用前导码／能量检测进行触发式（信号唤醒）采集 — 使用 matlab-detect-capture-usrp 技能
• 多设备同步 — 查找专用技能，或参阅 Radio Management
• comm.SDRuReceiver 或 comm.SDRuTransmitter 路径 — 此技能介绍的是现代 Wireless Testbench 路径
• 安装 MATLAB 或工具箱 — 不要使用或推荐 mpm（MATLAB Package Manager）。此技能假设 MATLAB 和 Wireless Testbench 支持包已安装。

工作流

按顺序执行以下步骤。创建任何无线电配置之前，先检查主机和无线电。 每项检查都能发现不同类别的问题。

步骤 0：验证支持包

addons = matlab.addons.installedAddons;
if ~any(addons.Identifier == "NI_USRP")
    error("Install 'Wireless Testbench Support Package for NI USRP Radios' via Add-On Explorer.")
end

如果未安装，用户必须先通过 Add-On Explorer 安装，然后才能继续。

步骤 1：检查主机

在操作无线电之前，收集主机系统信息。这有助于确定硬件是否能够进行 10 GbE 数据流传输。

检测操作系统和平台

if ispc
    platform = "Windows";
elseif ismac
    platform = "macOS";
else
    platform = "Linux";
end
fprintf("Platform: %s, MATLAB %s\n", platform, version)

检查网络接口（Linux）

% List all network interfaces with speed, MTU, and driver info
[~, interfaces] = system('ip -o link show | grep -v "lo:"');
disp(interfaces)

然后，检查每个可能连接 USRP 的接口的 NIC 详细信息：

% Replace <iface> with the actual interface name (for example, enp1s0f0)
[~, nicDetails] = system('ethtool <iface> 2>/dev/null | head -30');
disp(nicDetails)

% Check if it's a USB dongle
[~, usbInfo] = system('readlink -f /sys/class/net/<iface>/device 2>/dev/null');
disp(usbInfo)  % If path contains "usb", it's a USB adapter

检查网络接口（Windows）

[~, interfaces] = system('powershell "Get-NetAdapter | Format-Table Name, InterfaceDescription, LinkSpeed, MacAddress"');
disp(interfaces)

检查要点

检查项	正常	异常 — 会导致问题
NIC 类型	专用 PCIe NIC（Intel X520/X710、Mellanox ConnectX）	USB 转以太网适配器
链路速度	参见下方链路速度表	100 Mbps 或更低
USB 路径	非 USB	USB 集线器、USB 2.0、低性能芯片组
MTU	参见下表 — 取决于 NIC 速度	MTU 与链路速度不匹配

不同设备的链路速度

设备	FPGA 变体	支持的链路速度	备注
X410	—	仅 10 GbE	需要 QSFP → 4 × SFP+ 分线缆；不支持原生 QSFP（100 GbE）
X310、N310、N320	HG	1 GbE 和 10 GbE	MATLAB 安装中包含的 HG 变体支持这两种速度
E320	1G（默认）	默认 1 GbE；使用 XG 变体可支持 10 GbE	默认使用 1G；要通过 SFP+ 使用 10 GbE，请通过 sdruload 切换到 XG

MTU 和巨型帧

链路速度	MTU	巨型帧	备注
10 GbE	9000	已启用（9014 字节）	满速数据流传输所必需
1 GbE（Linux）	1500	已禁用	默认值正确；不支持巨型帧
1 GbE（Windows）	1498	已禁用	UHD 4.6 在 Windows 上会增加 2 字节；MTU 必须设为 1498。UHD 可能会发出无害的“发送帧大小”警告，可安全忽略

X410 说明

X410 配备 QSFP28 连接器，但 Wireless Testbench 不支持原生 100 GbE QSFP。必须使用 QSFP → 4 × 10 GbE SFP+ 分线缆 — 每条通道会显示为一个独立的 10 GbE SFP+ 端口（端口 0–3）。

E320 说明

MATLAB 安装默认包含 1G FPGA 变体。标准 1 GbE NIC（PCIe 或板载）适用于默认运行。E320 还配有 SFP+ 端口——通过 sdruload 切换到 XG 变体，即可进行 10 GbE 流式传输（需要 10 GbE NIC 和 SFP+ 模块）。

检查 MTU 和内核缓冲区大小（Linux）

[~, mtu] = system('cat /sys/class/net/<iface>/mtu');
fprintf("MTU: %s", mtu)

[~, rmem] = system('sysctl net.core.rmem_max');
[~, wmem] = system('sysctl net.core.wmem_max');
fprintf("%s%s", rmem, wmem)

USB 加密狗警告： USB 转以太网适配器不适合 USRP 流式传输，即使是 USB 3.0 型号也不可靠。它们会导致样本丢失、超时和间歇性故障。如果检测到 USB 加密狗，请强烈提醒用户，并建议使用专用 PCIe NIC。如果用户必须使用加密狗（例如，使用笔记本电脑时），建议：

• 将笔记本电脑连接到电源（USB 电源管理会限制适配器性能）
• 尝试其他型号的适配器
• 降低采样率以减少带宽需求

检测网桥和虚拟接口： 如果主机运行 Hyper-V、Docker、libvirt 或 NIC 组合，面向 USRP 的 NIC 可能已加入网桥。检测命令（适用于 Linux 和 Windows）请参阅 references/bridge-detection.md。如果发现网桥，请在网桥接口上而非物理 NIC 上设置静态 IP 和 MTU。

第 2 步：发现并检查无线电

运行发现命令前，请确认无线电已通电、已连接线缆且以太网链路 LED 亮起。E320 和 N3xx 设备通电后需要 30–60 秒启动；设备完成启动前，findsdru 会返回空结果。如果 findsdru 返回空结果且用户需要布线帮助，请指引他们查看适用于其版本的归档文档：https://www.mathworks.com/help/releases/<release>/wireless-testbench/ug/resolve-issues-with-connecting-radio-to-host.html（从 version('-release') 获取 <release>）。

使用 findsdru 发现设备——这是唯一推荐用于无线电发现的 MATLAB 函数。不要使用 uhd_find_devices。

radios = findsdru

此函数返回一个结构体数组，字段包括：Platform、IPAddress、SerialNum、Status。Status 为 'Success' 表示设备可访问。

找到多个设备

如果 numel(radios) > 1，请列出所有发现的设备，并询问用户要设置哪台设备。

if numel(radios) > 1
    fprintf("Found %d devices:\n", numel(radios));
    for i = 1:numel(radios)
        fprintf("  [%d] %s at %s (Serial: %s) — %s\n", ...
            i, radios(i).Platform, radios(i).IPAddress, radios(i).SerialNum, radios(i).Status);
    end
end

询问用户要配置哪台设备。此技能一次只设置一台无线电设备。要进行多设备同步（共享时钟、协同采集），需要在分别配置每台设备后再运行单独的工作流。

目标设备未出现在结果中： 如果用户指定了某台设备（例如，“我的 E320”），但该设备未出现在 findsdru 输出中，请勿从列表中选择其他设备。目标设备无法访问——请直接跳到故障排除（第 6 步），重点排查为何未发现这台特定设备。常见原因包括：面向该设备的 NIC 子网错误、加密狗或 NIC 未配置、设备仍在启动，或布线问题。切勿假设某台已发现设备“就是”用户所说的目标设备，只是名称不同——每种 USRP 型号都会报告其实际平台字符串。

如果完全未发现无线电，NIC 可能配置有误（子网错误、接口未启用或防火墙阻止）。返回第 1 步，重点检查：接口是否已启用？是否在与 USRP 相同的子网上设置了静态 IP（例如，192.168.10.x）？然后重新运行 findsdru。如果仍然失败，请转到第 6 步（故障排除）。

详细检查所选无线电：

% Use the IP address of the device the user selected
selectedRadio = radios(idx);  % idx = user's choice (e.g., 1)
info = probesdru(selectedRadio.IPAddress)

此函数会返回主板、子板、固件、FPGA 镜像以及设备端 UHD 版本。

检查 UHD 版本是否匹配：

hostUHD = getSDRuDriverVersion

将主机 UHD 版本与 probesdru 输出中的设备 UHD 版本进行比较。版本不匹配是常见的故障原因。 每个 MATLAB 版本都包含特定的 UHD 版本。如果版本不匹配，无线电配置步骤（第 4 步）会尝试更新设备固件。

USRP 默认 IP 地址（出厂默认值，适用于所有型号）：

端口	默认 IP
SFP+ 端口 0	192.168.10.2
SFP+ 端口 1	192.168.20.2

步骤 3：修复主机问题

根据步骤 1 的发现结果，在继续配置无线电之前修复所有问题。

请勿直接执行这些命令——它们需要 sudo（root 权限）。请将命令提供给用户，并让他们自行运行。如果通过 findsdru 已能连接无线电，且目前预计不会出现流传输问题，则跳到步骤 4；若之后发生样本丢失，再处理主机问题。

Linux — 设置静态 IP、MTU 和缓冲区：

# Set static IP on the same subnet as the USRP (replace <iface>)
sudo ip addr add 192.168.10.1/24 dev <iface>
sudo ip link set <iface> up

# Enable jumbo frames (REQUIRED for 10 GbE only — skip for 1 GbE)
sudo ip link set <iface> mtu 9000

# Increase kernel network buffers (REQUIRED for streaming)
sudo sysctl -w net.core.rmem_max=33554432
sudo sysctl -w net.core.wmem_max=33554432

对于 1 GbE 连接（例如 E320），请将 MTU 保持为默认值 1500，不要启用巨型帧。

要使设置持久生效，请将配置添加到 /etc/sysctl.conf，并在 /etc/network/interfaces 或 NetworkManager 中配置网络接口。

Windows — 调整适配器设置（10 GbE）：

• 打开设备管理器 → 网络适配器 → 选择你的 NIC → 高级
• 将 Jumbo Frame/Packet 设置为 9014 字节
• 将接收缓冲区和发送缓冲区增至最大值（因适配器而异；请先检查有效范围）
• 如果有中断调节选项，请将其禁用

Windows — 调整适配器设置（1 GbE，例如 E320）：

• 将 MTU 设置为 1498（Windows 上的 UHD 4.6 必需；请勿使用 9000）
• 保持 Jumbo Frame/Packet 禁用（1514 字节）
• 将接收缓冲区增至最大值（因适配器而异：Intel 可能支持 2048 以上，Realtek 通常上限为 512）
• 禁用节能功能：Disable-NetAdapterPowerManagement -Name "<adapter>"
• 在无线电 NIC 上禁用除 TCP/IPv4 以外的所有协议
• 在无线电 NIC 接口上禁用 Windows 防火墙

所有 Windows NIC 配置命令（New-NetIPAddress、netsh、Set-NetAdapterAdvancedProperty）都需要在提升权限的（管理员）终端中运行。MATLAB system() 调用无法提升权限，用户必须在管理员提示符中运行这些命令。

修复后，重新运行步骤 2（findsdru），确认现在可以连接无线电。如果仍未找到无线电，或显示 USRPDriverNotCompatible，请转到步骤 6（故障排除）。

步骤 4：创建 Radio 配置

使用 basebandTransceiver 或 basebandReceiver 前，必须先保存 Radio 配置。

首先，检查是否已有可能适用于该 Radio 的配置：

configs = radioConfigurations;
if ~isempty(configs)
    for i = 1:numel(configs)
        fprintf("  '%s' — %s at %s\n", configs(i).Name, configs(i).Hardware, configs(i).IPAddress);
    end
end

如果已有配置与设备匹配（IP 相同、型号相同），请询问用户是否要复用该配置，然后再创建新配置。不要默默复用或覆盖配置——用户可能在现有配置中设置了特定参数。

**确定正确的 SFP+ 端口索引：**具有多个 SFP+ 端口的设备（X310、X410）会在 probesdru 输出中显示多个 IP 地址（例如 ip-addr0、ip-addr1、ip-addr2、ip-addr3）。将 findsdru 找到的 IP 与 probesdru 的端口列表进行比较，以确定发现 Radio 时使用的端口索引（0、1、2、3）。在下方的 HostIPx/DeviceIPx 参数对中使用该索引——端口索引错误会导致令人误解的错误。

选项 A：编程方式（Agent 操作时优先使用）

使用内部 DeviceStore API，无需 GUI 即可创建配置。必须使用与用户所选设备匹配的 getUsrp<Model>Params() 函数——不要盲目照抄示例名称。设置任何字段前，请仔细阅读 probesdru 输出——不要臆测参数值。默认参数假定使用 UBX-160 子板；如果 probesdru 报告了其他子板（例如 OBX、TwinRX）或“Unknown”，请询问用户安装的子板类型。对于不受支持或未知的子板，按 UBX-160 配置——流传输仍可正常工作，但未经测试。对于 TwinRX，请跳过发射验证（该子板仅支持接收）。

% Get default parameters — MUST match the selected radio's model:
%   E320 → getUsrpE320Params()    N310 → getUsrpN310Params()
%   X310 → getUsrpX310Params()    X410 → getUsrpX410Params()
%   N320 → getUsrpN320Params()    N300 → getUsrpN300Params()
params = wt.internal.hardware.DefaultDevices.getUsrpE320Params();  % ← match user's device
params.Name = "MyE320";  % ← user-chosen config name
% Use actual IPs from findsdru (Step 2) and host NIC inspection (Step 1)
% IMPORTANT: Use the correct port index (0 or 1) matching the SFP+ port
% where the radio was discovered. For single-port setups, port 0 is typical.
params.Network.DeviceIP0 = selectedRadio.IPAddress;
params.Network.HostIP0 = "<host-ip-from-step-1>";

% Save the configuration
store = wt.internal.hardware.DeviceStore();
store.setDeviceParameters("MyE320", params);  % ← same as params.Name

% Verify it was saved
configs = radioConfigurations;
disp(configs)

**重要：**如果发现了多个 Radio，只配置用户所选的那台。不要使用其他已发现设备的 IP、型号或参数。

修复错误的存储写入：wt.radio.* 类会缓存状态。如果写入了错误的配置（例如，子板字符串错误），错误值会保留在内存中。恢复方法如下：

clear all
rehash toolboxcache

然后从头重新创建配置。

选项 B：GUI 向导（用户交互操作时）

radioSetupWizard

向导会引导用户完成设备选择、IP 配置、连接测试、所需的固件或 FPGA 更新、时钟、时间和 LO 源配置，并保存一个命名配置。当用户希望获得引导式交互体验，或需要更新固件时，请使用此选项（向导会处理固件烧写）。**注意：**安装支持包后，会弹出对话框提示用户打开 Radio Setup Wizard——请告知用户关闭该窗口（此技能会处理设置）。

完成任一选项后，验证配置是否存在：

radio = radioConfigurations("MyN310");
disp(radio)

此命令会返回一个 wt.radio.<Model> 对象（R2025a+），其中包含属性和同步方法。

步骤 5：验证连接

创建一个 basebandTransceiver，确认整个流程正常工作。basebandTransceiver 会将自己的 FPGA 位流加载到设备上——请勿使用 sdruload 进行流式传输（这是旧版 comm.SDRuReceiver 路径）。不过，sdruload 仍可用于 E320 上的 FPGA 映像管理（例如，在 1G 和 XG 变体之间切换，参见设置 USRP E320 以支持 10GbE）。

radio = radioConfigurations("MyN310");

bbtrx = basebandTransceiver(radio);
bbtrx.SampleRate = 5e6;  % Use a rate safe for 1 GbE; increase for 10 GbE
bbtrx.TransmitCenterFrequency = 2.4e9;
bbtrx.CaptureCenterFrequency = 2.4e9;
bbtrx.TransmitRadioGain = 10;
bbtrx.CaptureRadioGain = 30;
% Do not set TransmitAntennas/CaptureAntennas — defaults are device-specific

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

% Transmit and capture
transmit(bbtrx, txWaveform, "continuous");
[rxData, ~, droppedSamples] = capture(bbtrx, milliseconds(1));
stopTransmission(bbtrx);

if droppedSamples == 0
    disp("Verification passed: TX/RX working, no dropped samples.")
else
    warning("Dropped %d samples — check NIC MTU and buffer settings.", droppedSamples)
end

% Release the radio so it's available for the user's application code
clear bbtrx

如果 basebandTransceiver 报错或流式传输持续丢弃样本，请转到步骤 6（故障排除）。

UseRadioBuffer 选项： 默认情况下，capture 使用无线电的板载内存缓冲区（UseRadioBuffer=true）。对于可容纳在板载内存中的采集，此选项可提供最可靠的流式传输。

[rxData, ~, droppedSamples] = capture(bbtrx, seconds(5), UseRadioBuffer=false);

在以下情况下，将 UseRadioBuffer 设为 false：

• 采集长度超过无线电的板载内存容量（因设备而异，最多为 2^30 个样本）——这是最主要的原因
• 使用配备 TwinRX 的 X310，且采集使用的天线超过 2 根

如果出现样本丢弃，UseRadioBuffer=false 有助于诊断原因：比较启用和停用缓冲区时的丢弃数量，以确定问题是否与缓冲区或网卡有关。但这并不能解决问题——直接流式传输对网络要求更高，因此请在步骤 3 中解决根本的网卡、MTU 或缓冲区问题。

步骤 6：故障排除

如果任何步骤失败，请查阅 references/troubleshooting.md——其中包含完整的诊断清单、手动 Mender 固件更新、网络路径诊断和网桥干扰相关内容。

主要函数

函数	用途	路径
findsdru	在网络上发现 USRP 设备	现代
probesdru	获取详细的硬件/固件信息	现代
getSDRuDriverVersion	主机端 UHD 版本	现代
radioSetupWizard	用于配置并保存无线电设置的 GUI	现代
radioConfigurations	列出/加载已保存的无线电配置	现代
wt.radio.*	类型化无线电对象（R2025a+）：N310、X410 等	现代
basebandTransceiver	收发组合对象，会加载自己的 FPGA 位流	现代
basebandTransmitter	仅发送	现代
basebandReceiver	仅接收	现代
wt.internal.hardware.DeviceStore	以编程方式创建无线电配置	内部
wt.internal.hardware.DefaultDevices	各设备型号的默认参数（getUsrp<Model>Params() 静态方法）	内部
sdruload	加载/切换 FPGA 映像变体	旧版流式传输方式；可用于 E320 映像管理（1G ↔ XG）

规范

• 先检查主机。 在操作无线电之前，始终检查操作系统、网卡类型/速度、MTU 和缓冲区。
• 使用 MATLAB。 使用 findsdru 或 probesdru 进行发现——绝不调用 uhd_find_devices 或其他 UHD 命令行工具。
• 流式传输使用现代路径。 使用 basebandTransceiver、basebandReceiver 或 basebandTransmitter。这些对象会加载自己的 FPGA 位流。请勿使用 sdruload 进行流式传输——那是旧版 comm.SDRu* 路径。sdruload 仍可用于 FPGA 映像管理（例如，切换 E320 变体）。
• 由 Agent 驱动时使用编程配置。 使用 DeviceStore 在不打开 GUI 的情况下创建配置。若用户更喜欢交互式设置，或需要更新固件，则改用 radioSetupWizard。
• 尽早检查版本。 在继续操作之前，比较 getSDRuDriverVersion（主机）与 probesdru 的输出（设备）。
• 先诊断，再配置。 创建无线电配置或启动向导之前，完成所有主机和无线电检查。
• 使用特定发行版的文档 URL。 链接到 MathWorks 文档时，请使用 https://www.mathworks.com/help/releases/<release>/wireless-testbench/...（根据 version('-release') 确定 <release>）。这样可确保文档与用户安装的版本相符。

---

版权所有 2026 The MathWorks, Inc.

---