企业官网建设流程全解析

• 通信
• 网络
• 硬件开发
• 嵌入式

openwifi 平台的基带具备"全双工（Full Duplex）"能力——WiFi 基带能够接收自己发射的无线信号，这一特性使其可以像雷达一样感知周围环境：当 TX/RX 两副定向天线对准同一片空间时，自发射信号的 CSI（Channel State Information，信道状态信息）会随目标物体的位置变化而实时改变。本指南以 doc/app_notes/radar-self-csi.md 为骨架，完整演示如何在 openwifi SDR 板卡上搭建"自发自收"的 CSI 雷达系统，读者将掌握驱动/FPGA 包构建部署、侧信道 CSI 采集、802.11 数据包注入、实时 waterfall 可视化与离线 Matlab 分析的一整套实战方案。

全双工自感知：openwifi 的"雷达"原理

传统 WiFi 网卡在发射时接收链路是关闭的，因此无法观察自己发射信号的回波。openwifi 打破了这个限制：其可编程基带允许接收机监听自身的发射信号，就像雷达发射脉冲并接收反射回波一样。将两副定向天线分别接在 openwifi 的 TX 端口和 RX 端口，让发射信号经目标物体反射后进入接收链路，此时提取到的 CSI 就包含了目标物体对无线信道的影响——物体移动、离开或进入波束覆盖范围，都会反映在 CSI 幅度/相位的连续变化中。

上图展示了 openwifi 雷达自 CSI 采集的核心思路：TX 天线持续注入自发射的 802.11 数据包，RX 天线接收被目标反射的信号，基带 OFDM 接收机解码后由 side channel（侧信道）提取 CSI 并上传到上位机。这一"联合雷达与通信（joint radar and communication）"能力是 openwifi 平台独有的优势之一——同一套硬件、同一条射频链路，既承担无线通信，又兼作环境感知传感器。

提示：本文假设读者已经理解 openwifi 的基础 CSI 采集机制。建议先阅读基础应用笔记 doc/app_notes/csi.md（侧信道架构、CSI 信息格式、条件捕获配置），再进入本文的全双工雷达实战。

实验拓扑与前置准备

雷达实验的最小系统包含三个角色：

操作步骤：

1. 给 SDR 板卡上电。
2. 用网线将电脑与 SDR 板卡直连，电脑配置静态 IP192.168.10.1。
3. 打开终端 SSH 登录板卡：

ssh root@192.168.10.122 # 密码：openwifi

4. 在电脑上预装实时绘图依赖（仅在电脑侧需要）：

sudo apt install python3-numpy python3-matplotlib python3-tk

构建驱动与 FPGA 包并部署到板卡

雷达实验需要把最新版本的 openwifi 驱动与 FPGA 镜像打包后上传到板卡。在电脑上克隆/更新 openwifi 与 openwifi-hw-img 仓库后，按以下步骤构建：

export XILINX_DIR=your_Xilinx_install_directory # 示例：export XILINX_DIR=/opt/Xilinx # Xilinx 安装目录应包含类似 Downloads、Vitis 等子目录 export OPENWIFI_HW_IMG_DIR=your_openwifi-hw-img_directory # 通过 git clone 获得 open-sdr/openwifi-hw-img 仓库后所在的目录 export BOARD_NAME=your_board_name # 具体的 BOARD_NAME 定义请查看仓库根目录 [README.md](https://link.gitcode.com/i/bca0bb97743df2750f18612117c21933) cd openwifi/user_space ./drv_and_fpga_package_gen.sh $OPENWIFI_HW_IMG_DIR $XILINX_DIR $BOARD_NAME

构建成功后，把生成的驱动/FPGA 包以及本次实验用到的用户空间源码上传到板卡：

scp drv_and_fpga.tar.gz root@192.168.10.122:openwifi/ scp ./side_ch_ctl_src/side_ch_ctl.c root@192.168.10.122:openwifi/ scp ./inject_80211/* root@192.168.10.122:openwifi/inject_80211/

其中drv_and_fpga_package_gen.sh是 user_space/drv_and_fpga_package_gen.sh 提供的打包脚本；side_ch_ctl.c与inject_80211目录分别来自 user_space/side_ch_ctl_src/ 和 user_space/inject_80211/。

板卡端配置：监视模式、侧信道驱动与 CSI 过滤

在板卡的/root/openwifi目录下依次执行：

cd /root/openwifi/ ./wgd.sh drv_and_fpga.tar.gz # 解包并加载驱动与 FPGA 镜像 ./monitor_ch.sh sdr0 1 # 将 sdr0 置于监视模式，工作信道 1 insmod ./drv_and_fpga/side_ch.ko # 加载侧信道内核模块 gcc -o side_ch_ctl side_ch_ctl.c # 在板卡上就地编译侧信道控制程序 ./side_ch_ctl wh1h4001 # 开启 addr2（源地址）匹配过滤 ./side_ch_ctl wh7h4433225a # 只采集来自 XX:XX:44:33:22:5a 的数据包 CSI ./sdrctl dev sdr0 set reg xpu 1 1 # 解除基带自接收静音，接收 openwifi 自己的 TX 信号 ./side_ch_ctl g0 # 以最小间隔持续抓取 CSI

各命令的作用说明：

• ./wgd.sh drv_and_fpga.tar.gz：调用 user_space/wgd.sh，完成驱动模块加载与 FPGA 比特流配置。
• ./monitor_ch.sh sdr0 1：使用 user_space/monitor_ch.sh 把无线接口切入监视模式并指定信道。雷达实验中信道号要与后文注入数据包的 radiotap 信道保持一致。
• insmod ./drv_and_fpga/side_ch.ko：加载侧信道驱动。源码 driver/side_ch/side_ch.c 中，dev_probe会初始化 Netlink 内核 socket、将SIDE_CH_REG_CONFIG写为最严格条件0x7001（先禁止一切采集）再放宽为0x0001（默认允许所有包），并完成tx_dma_s2mmDMA 通道的申请，用于从 FPGA 侧信道核拉取 CSI 数据。
• ./side_ch_ctl wh1h4001/./side_ch_ctl wh7h4433225a：配置条件捕获，确保只接收来自我们自己的包注入器（后文会设定源地址）的数据包 CSI，避免环境中的其他 WiFi 流量干扰雷达测量。关于whXhY参数格式的完整说明见下文"条件捕获与采样间隔配置"小节。
• ./sdrctl dev sdr0 set reg xpu 1 1：雷达实验最关键的一步。默认情况下 openwifi 的接收基带在自身发射期间会被静音（mute），防止自干扰；向 xpu 寄存器 1 写入 1 即解除该静音，使基带能够接收自己的发射信号。相关实现可参考 driver/xpu/xpu.c 中围绕 xpu 寄存器的读写接口（XPU_REG_SRC_SEL等）。
• ./side_ch_ctl g0：以g前缀的获取命令持续拉取侧信道信息。g后面跟的数字是以毫秒为单位的抓取间隔，g0表示间隔为 0，即以硬件允许的最快速度连续采集（不带数字的g默认间隔为 100ms，见 user_space/side_ch_ctl_src/side_ch_ctl.c 中parse_para_string对interval_ms的处理）。

执行./side_ch_ctl g0后，若链路正常，终端会周期性打印类似下面的计数：

loop 64 side info count 61 loop 128 side info count 99 ...

其中第二个数字（61、99……）是累计采集到的侧信道信息条数——只要它持续递增，就说明 CSI 正在从板卡流向电脑。

注入自发射的 802.11 数据包

另开一个 SSH 会话登录板卡，编译并运行包注入工具，让板卡持续发射自己的雷达探测信号：

cd /root/openwifi/inject_80211 make ./inject_80211 -m g -r 4 -t d -e 0 -b 5a -n 99999999 -s 20 -d 1000 sdr0

802.11n 模式的注入命令为：

./inject_80211 -m n -r 4 -t d -e 8 -b 5a -n 99999999 -s 20 -d 1000 sdr0

inject_80211是 openwifi 提供的 802.11 原始帧注入工具，源码位于 user_space/inject_80211/inject_80211.c，通过 pcap 向监视模式接口注入携带自定义 radiotap 头与 IEEE 802.11 MAC 头的帧。常用参数含义如下表：

参数细节可对照源码中的usage()输出：其中 g/a 模式的速率表为 6/9/12/18/24/36/48/54 Mbps（u8aRatesToUse），n 模式则直接使用 MCS 索引并可选 SGI。-b 5a设置的源地址与前面wh7h4433225a的过滤目标配合，确保侧信道只对雷达自己的探测包采集 CSI。

两个 SSH 会话并行运行时，第一个会话（运行side_ch_ctl g0）中的计数应持续增长，说明自发射数据包正被接收链路解码并产生 CSI。

实时 CSI 可视化：waterfall 与均衡器输出

回到电脑（注意：不要在 SSH 会话里执行），运行实时显示脚本：

cd openwifi/user_space/side_ch_ctl_src python3 side_info_display.py 8 waterfall

脚本运行后会弹出多幅实时更新的图：CSI 幅度/相位、CSI waterfall（瀑布图）、均衡器输出（Equalizer out）以及频率偏移（frequency offset）。8是num_eq（均衡器输出数量），waterfall是任意非空参数，用于开启 CSI 瀑布图模式。

下图是文档作者在两副定向天线（Tx/Rx）前起身离开座位时，瀑布图中 CSI 发生的明显变化——这正是"目标物体移动 → 信道状态改变"的直接可视化证据：

从数据通路看，CSI 的实时流转为（相关源码已在上文给出路径）：

FPGA 侧信道核（DMA）→ side_ch.ko（Netlink）→ side_ch_ctl（UDP 4000 端口） → 电脑 side_info_display.py（UDP 监听 192.168.10.1:4000）

• user_space/side_ch_ctl_src/side_ch_ctl.c 通过 Netlink 向内核驱动请求侧信息，随后用sendto()将数据以 UDP 发往目标地址192.168.10.1:4000（-s参数可改目标 IP）。
• user_space/side_ch_ctl_src/side_info_display.py 在电脑上bind端口 4000 接收 UDP 数据，解析出 timestamp、freq_offset、csi、equalizer，并实时绘制；其parse_side_info()函数还实现了子载波顺序重排（FPGA 输出为倒序，脚本将其还原为标准 OFDM 子载波顺序）。

离线分析：side_info.txt 与 Matlab 脚本

实时显示期间，所有 CSI 数据会同时落盘保存到文件side_info.txt（由side_info_display.py在运行目录下创建并追加写入）。这使得实验结束后仍可进行精确的离线分析。仓库提供了 Matlab 离线分析脚本 user_space/side_ch_ctl_src/test_side_info_file_display.m：

test_side_info_file_display % 默认参数：num_eq=8，文件 side_info.txt，查看第 1 条

脚本的函数签名为：

function [timestamp, csi, freq_offset, equalizer_out] = test_side_info_file_display(num_eq, side_info_filename, idx_to_check)

它按"每包一条"的结构解析side_info.txt，还原 64 位 TSF 时间戳、频率偏移、56 个子载波的复数 CSI 与均衡器输出，并绘制 CSI 幅度/相位、均衡器星座散点、时间戳序列与频偏曲线，还可通过idx_to_check参数单独查看指定数据包索引的 CSI 细节（图题中会同时打印该包的时间戳）。

上图即雷达实验后使用该 Matlab 脚本离线分析得到的 CSI 图形。用户应根据自己的需求研读 Python 与 Matlab 脚本，掌握"每包 CSI 数据结构"的确切字段布局。

深入理解 CSI 数据结构与侧信道架构

雷达自 CSI 复用的正是 openwifi 的side channel（侧信道）基础设施，其详细架构（模块划分与源码文件对应关系）与信息格式见基础笔记 doc/app_notes/csi.md。此处给出与自雷达分析最相关的数据格式要点：

侧信道每"条"信息由若干 64bit 元素组成（源码 driver/side_ch/side_ch.h 与 user_space/side_ch_ctl_src/side_info_display.py 中的常量保持一致）：

• CSI_LEN = 56：单条 CSI 的长度（56 个子载波，含数据与导频）；
• EQUALIZER_LEN = 52：均衡器输出长度（非 HT 模式本应为 48，FPGA 会填充 4 个{32767, 32767}补齐到 52）；
• HEADER_LEN = 2：头部元素数量（时间戳 + 频率偏移）。

每条完整侧信道信息的 DMA 符号数计算公式：

num_dma_symbol_per_trans = HEADER_LEN + CSI_LEN + num_eq * EQUALIZER_LEN

单个 64bit 元素的字段含义：

• timestamp：64bit TSF 定时器值，与 tcpdump、wireshark 等抓包工具或 openwifi dmesg 打印中看到的时间戳同源，是"数据包 ↔ CSI"关联的唯一身份标识；
• freq_offset：仅使用低 16bit；Python 脚本中的换算关系为(20e6 * int16(value) / 512) / (2π)，单位为 Hz；
• csi 与 equalizer：仅使用前两个 16bit 分别承载 I/Q（实部/虚部），剩余两个 16bit 保留给未来的多天线场景。

side_ch.ko加载时还可通过模块参数控制采集内容（见 driver/side_ch/side_ch.c）：

insmod side_ch.ko num_eq_init=3 # 0~8，默认 8；每个均衡器输出 52 个复数 insmod side_ch.ko iq_len_init=8187 # 若大于 0 则进入 IQ 捕获模式（CSI 被禁用），雷达实验不使用

条件捕获与采样间隔配置（whXhY 详解）

默认g命令会采集 OFDM 接收机解码出的所有数据包的 CSI。若只想采集满足特定条件（FC 帧控制字段、addr1 目标地址、addr2 源地址）的包，须在side_ch_ctl g之前下发配置命令。配置命令的通用格式为：

whXhY

• w：write（写操作）；
• h：hardware（硬件寄存器）；
• X：寄存器索引；
• h：后接十六进制；
• Y：寄存器值（十六进制）。

开启/关闭条件捕获（寄存器 X=1），值 Y 的位定义：bit11~bit0 固定为001，bit12 为 FC 匹配开关，bit13 为 addr1 匹配开关，bit14 为 addr2 匹配开关。例如：

# 仅匹配 FC ./side_ch_ctl wh1h1001 # 仅匹配 addr2（源地址）—— 雷达实验常用 ./side_ch_ctl wh1h4001 # 同时匹配 FC 和 addr1（目标地址） ./side_ch_ctl wh1h3001 # 关闭条件捕获（采集所有包） ./side_ch_ctl wh1h0001

指定匹配目标（对应寄存器）：

# 指定 FC 匹配目标（寄存器 5） ./side_ch_ctl wh5hY # Y 为 FC 值（十六进制） # 指定 addr1（目标地址）匹配目标（寄存器 6） ./side_ch_ctl wh6hY # 指定 addr2（源地址）匹配目标（寄存器 7） ./side_ch_ctl wh7hY # Y 为 MAC 地址十六进制值，只需后 32bit # 例如 56:5b:01:ec:e2:8f 应输入 01ece28f

上述寄存器编号与 driver/side_ch/side_ch.h 中的地址定义一一对应：SIDE_CH_REG_CONFIG_ADDR（1）、SIDE_CH_REG_FC_TARGET_ADDR（5）、SIDE_CH_REG_ADDR1_TARGET_ADDR（6）、SIDE_CH_REG_ADDR2_TARGET_ADDR（7）。

采样间隔：side_ch_ctl g默认每 100ms 采集一次；使用side_ch_ctl gN可改为每N*1ms采集一次。雷达实验中为了获得密集的时间采样，常使用g0让抓取循环以最快速度运行（interval_ms=0时usleep(0)相当于立即返回，参见 user_space/side_ch_ctl_src/side_ch_ctl.c 主循环）。

num_eq 配置：控制均衡器输出数量

num_eq（均衡器输出数量）用于在不需要太多均衡器信息时降低数据量，合法取值为0~8。修改后必须在三个位置保持一致：

1. 加载内核模块时（默认 8，无需显式指定）：

   insmod side_ch.ko num_eq_init=3

2. 启动 Python 显示脚本时：

   side_info_display.py 3

3. 使用 Matlab 脚本时，将脚本中的num_eq变量改为同样的值（如 3）。

对齐原因从数据格式即可看出：每条侧信道信息的大小为2 + 56 + num_eq*52个 64bit 符号，驱动、Python 解析器与 Matlab 解析器必须使用相同的num_eq才能正确切分数据包边界。

将 CSI 映射到 WiFi 数据包

若需要把 CSI 与具体的 WiFi 数据包关联起来，做法是：在采集 CSI 的同时用 tcpdump/wireshark 等工具抓取 WiFi 包，然后以TSF 时间戳为键进行匹配——该时间戳是同一个数据包及其 CSI 的唯一共同身份标识。openwifi 社区对此有专门的讨论说明（可查阅项目讨论区的相关主题了解详细映射方法）。

与其他工作模式的组合使用

侧信道 CSI 采集并不局限于监视模式：在 AP-Client 或 ad-hoc 模式完成正常通信功能后，同样可以执行insmod side_ch.ko与./side_ch_ctl g来提取 CSI。这意味着"联合雷达与通信"既能以专用雷达模式运行（本文演示的自发自收），也能叠加在真实通信链路上，在收发业务数据的同时持续感知环境。

常见问题与调试要点

• side_ch_ctl g0打印的计数不增长：检查wh1h4001/wh7h...过滤条件是否与注入器的源地址一致；确认两个 SSH 会话分别在运行注入与采集；确认sdrctl dev sdr0 set reg xpu 1 1已执行（未解除自接收静音时，自己的发射信号不会进入接收链路）。
• 电脑端收不到数据：确认电脑 IP 为192.168.10.1，side_info_display.py与side_ch_ctl的 UDP 端口一致（均为 4000）；必要时用-s参数指定板卡发往的服务器 IP（side_ch_ctl g -s 192.168.10.2）。
• 雷达感知目标不清晰：两副天线应为定向天线且波束覆盖同一空间；可降低-d（包间隔）提高探测速率，或使用g0提高时间采样密度；随后用离线 Matlab 脚本逐包查看 CSI 突变时刻。
• 需要更多 CSI 维度时：可按上文调整num_eq（0~8）在数据量与均衡器细节之间取舍，并保持驱动、Python、Matlab 三处配置一致。

• 通信
• 网络
• 硬件开发
• 嵌入式