关于 OpenISAC

通信感知一体化 (ISAC) 被认为是 6G 的关键技术之一。OpenISAC 是一个通用且高性能的开源平台，旨在弥合理论与实践之间的差距。

它完全基于开源软件 (UHD、C++、Python) 构建，支持基于 OFDM 的实时通信和感知。其核心特性是新颖的空口 (Over-the-Air) 感知同步机制，无需有线连接即可实现稳定的双站感知。

如果您觉得这个仓库有用，请引用我们的论文：

Z. Zhou, C. Zhang, X. Xu, and Y. Zeng, "OpenISAC: An Open-Source Real-Time Experimentation Platform for OFDM-ISAC with Over-the-Air Synchronization," submitted to IEEE Trans. Wireless Commun., Jan. 2026.

[arXiv]

所属机构

东南大学移动通信国家重点实验室 & 紫金山实验室 曾勇课题组

社区

• 加入我们的 QQ 群
• Bilibili 频道 (曾勇课题组)

微信公众号:

它是什么，又不是什么？

OpenISAC 是什么？

OpenISAC 是一个基于 OFDM 的通信与感知一体化（ISAC）系统，专为学术实验和快速算法验证而设计。

其目标是提供一个简洁且易于修改的 OFDM 平台，使研究人员能够快速迭代通信与感知算法，而无需处理复杂的标准协议栈（如 WIFI、LTE、NR 等）。

由于专注于简洁性，OpenISAC 通常需要更少的计算资源，因此相较于更复杂、功能更全面的系统，能够实现更高的采样率。

OpenISAC 不是什么？

OpenISAC 不旨在成为兼容标准的实现（它不符合 Wi-Fi 或 5G NR 等标准）。

它也不旨在替代或竞争全栈开源标准实现，如 openwifi 或 OpenAirInterface。如果您的目标是互操作性、标准合规性或生产级协议栈，那么上述项目是正确的方向。

何时使用它

• 原型设计以及测试新的通信、感知算法
• 使用极简 PHY 快速实现新想法
• 不需要互操作性的研究

何时不使用它

• 构建兼容 Wi-Fi/NR 的系统
• 需要标准通信系统的研究（完整的 MAC/协议栈、互操作性等）

感知演示

通信演示

硬件要求

后端 (C++)

要设置完整的系统，您需要以下硬件：

• USRP 设备: 2 台 (例如 USRP X310, B210 等)
• 计算机: 2 台 (推荐使用高主频CPU)
• 天线: 3 根
• OCXO/GPSDO: 2 个 (两台 USRP 都需要)

连接设置

该系统由两个主要节点组成：

基站 (BS) 节点: 1x 计算机, 1x USRP (连接 2 根天线: 1 发送, 1 接收), OCXO 连接到 REFIN。

用户 (UE) 节点: 1x 计算机, 1x USRP (连接 1 根天线: RX), OCXO 连接到 REFIN (可选高精度 DAC)。

接口要求

为了支持高带宽和采样率，请确保计算机和 USRP 之间的连接使用：

• >= 10 Gigabit Ethernet (10GbE) (X 系列)
• USB 3.0 (B 系列)

前端 (Python)

• 计算机: 1x 计算机 (Windows 或 Linux)。可以是后端计算机之一，也可以是单独的机器。
• CPU: 如果没有 GPU，建议使用高性能 CPU (i7 10700 或更高)。
• GPU: 建议使用 Nvidia GPU 进行加速。

软件要求

后端 (C++)

操作系统

Ubuntu 24.04 LTS

依赖项和安装

1. UHD (USRP 硬件驱动程序)

按照 Ettus 官方指南 安装 (UHD v4.9.0.1)。

2. 安装 Aff3ct

sudo apt-get install nlohmann-json3-dev
git clone https://github.com/aff3ct/aff3ct.git
cd aff3ct
git submodule update --init --recursive
mkdir build
cd build
cmake .. -G"Unix Makefiles" -DCMAKE_CXX_COMPILER="g++" -DCMAKE_BUILD_TYPE="Release" \
-DCMAKE_CXX_FLAGS="-funroll-loops -march=native" -DAFF3CT_COMPILE_EXE="OFF" \
-DAFF3CT_COMPILE_SHARED_LIB="ON" -DSPU_STACKTRACE="OFF" -DSPU_STACKTRACE_SEGFAULT="OFF" \
-DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} -faligned-new"
make -j$(nproc)
sudo make install

3. 克隆并构建 OpenISAC

# 安装 libyaml-cpp-dev
sudo apt-get install libyaml-cpp-dev

cd ~
git clone https://github.com/zhouzhiwen2000/OpenISAC.git
cd OpenISAC
mkdir build
cd build
cmake ..
make -j$(nproc)

4. 系统性能调优

cd ~/OpenISAC
chmod +x set_performance.bash
./set_performance.bash

注意: 如果您需要启用 RT_RUNTIME_SHARE 功能，则需要在 BIOS 设置中关闭 secure_boot。

UHD 线程优先级配置

如果看到 [WARNING] [UHD] Failed to set desired affinity for thread，需要启用实时优先级：

sudo groupadd usrp
sudo usermod -aG usrp $USER

然后将以下行添加到 /etc/security/limits.conf 的末尾：

@usrp - rtprio  99

注销并重新登录以使更改生效。

5. CPU 隔离和执行

为了确保稳定的实时性能，建议为信号处理任务隔离 CPU 核心。

步骤 1: 隔离CPU核心

cd ~/OpenISAC
chmod +x isolate_cpus.bash
sudo ./isolate_cpus.bash

步骤 2: 在隔离核心上运行应用程序

使用脚本在隔离核心上启动应用程序：

cd build
sudo ../isolate_cpus.bash run ./OFDMModulator

注意: 启用 CPU 隔离时请务必使用脚本启动。

重置配置 (可选)

sudo ./isolate_cpus.bash reset

6. 配置

系统现已支持 YAML 配置，以便更轻松地管理参数。

• 默认行为: 如果执行目录中存在 Modulator.yaml 或 Demodulator.yaml，它将被自动加载。
• 指定配置文件: 使用 -c 或 --config 指定自定义配置文件：

  ./OFDMModulator -c my_config.yaml

• 保存配置: 使用 -s 或 --save-config 将当前参数保存到 YAML 文件：

  ./OFDMModulator --save-config

  这将生成 Modulator.yaml (或 Demodulator.yaml) 包含当前设置。

  您也可以指定自定义文件名：

  ./OFDMModulator -s myconfig.yaml

前端 (Python)

建议使用 Python 3.13 的 conda 或 venv 环境。

Miniconda 安装教程:

• Windows: Miniconda Windows 安装教程
• Linux: Miniconda Linux 安装教程

新建 conda 环境:

conda create -n OpenISAC python=3.13
conda activate OpenISAC

安装依赖项

pip install -r requirements.txt

注意: 视频流演示需要 ffmpeg。

• Ubuntu: sudo apt install ffmpeg
• Windows: 从 ffmpeg.org 下载并添加到 PATH。

启用 GPU 加速 (可选)

如果有 Nvidia GPU，请安装 cupy-cuda12x：

注意: 安装 CuPy 之前，请务必先安装 CUDA Toolkit。

pip install cupy-cuda12x

启用 Intel 集成显卡加速 (可选)

如果您的设备配备 Intel 集成显卡（如 Intel UHD Graphics、Intel Iris Xe 等），可以通过 dpctl 和 dpnp 启用 GPU 加速。这对于没有 Nvidia 独立显卡的笔记本电脑和台式机特别有用。

1. 安装 Intel 显卡官方驱动

首先确保您的系统已安装最新的 Intel 显卡驱动：

• Windows: 从 Intel 官方下载中心 下载并安装最新驱动
• Ubuntu: 安装 Intel compute-runtime:

  sudo apt install intel-opencl-icd libze-intel-gpu1 libze1 intel-media-va-driver-non-free

2. 安装 Python 依赖

pip install dpctl dpnp

3. 验证安装

运行以下命令检查 Intel GPU 是否被正确识别：

python -c "import dpctl; print(dpctl.get_devices())"

如果安装成功，您应该能看到类似以下的输出：

[<dpctl.SyclDevice [backend_type.level_zero, device_type.gpu, Intel(R) UHD Graphics] at 0x...>]

4. 使用说明

OpenISAC 前端会自动检测可用的 GPU 后端。优先级顺序为：Nvidia GPU (CUDA) → Intel iGPU (dpnp) → CPU (回退选项)。无需修改代码，系统会自动选择最佳可用后端。

典型使用示例

1. 启动 BS

sudo -s
cd build
# 对于 X310:
cp ../Modulator_X310.yaml Modulator.yaml
sudo ../isolate_cpus.bash run ./OFDMModulator

# 对于 B210:
cp ../Modulator_B210.yaml Modulator.yaml
sudo ../isolate_cpus.bash run ./OFDMModulator

如果您使用单独的计算机作为前端，请添加 --default-ip=<your front end IP>。

2. 启动 UE

sudo -s
cd build
# 对于 X310:
cp ../Demodulator_X310.yaml Demodulator.yaml
sudo ../isolate_cpus.bash run ./OFDMDemodulator

# 对于 B210:
cp ../Demodulator_B210.yaml Demodulator.yaml
sudo ../isolate_cpus.bash run ./OFDMDemodulator

如果您使用单独的计算机作为前端，请添加 --default-ip=<your front end IP>。

3. 将视频流传输到 BS

ffmpeg -re -stream_loop -1 -fflags +genpts -i video.mp4 -an -c:v libx264 -x264-params keyint=5:min-keyint=1 -b:v 3000k -minrate 3000k -maxrate 3000k -bufsize 1M -f rtp -sdp_file video.sdp "rtp://<your IP of the BS>:50000"

如果您在BS本地传输视频流，BS 的 IP 可以设置为 127.0.0.1。

4. 从 UE 播放视频

将 video.sdp 复制到视频接收端，将 m=video 50000 RTP/AVP 96 修改为 m=video 50001 RTP/AVP 96。

ffplay -protocol_whitelist file,rtp,udp -i video1.sdp

注意：此命令应在前端运行。

5. 运行单站感知前端

python3 ./plot_sensing.py

如果您的计算机配备了 NVIDIA 显卡，可以使用以下脚本以获得更好的实时显示性能：

python3 ./plot_sensing_fast.py

6. 运行双站感知前端

python3 ./plot_bi_sensing.py

如果您的计算机配备了 NVIDIA 显卡，可以使用以下脚本以获得更好的实时显示性能：

python3 ./plot_bi_sensing_fast.py

OFDM 调制器 (OFDMModulator)

OFDMModulator (BS 节点) 可以使用以下命令行参数配置:

OFDM 解调器 (OFDMDemodulator)

OFDMDemodulator (UE 节点) 支持以下参数: