1. 系统要求

最小硬件配置

  • ARM Cortex-A7+ / x86_64 处理器
  • 256MB RAM 以上
  • 100MB 磁盘空间

操作系统

  • Ubuntu 20.04 LTS (Focal) 或更高版本
  • Linux Kernel 4.15+（支持 mac80211 HWSIM）

2. 依赖库安装

在嵌入式 Ubuntu 环境中，需要以下系统包：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 基础编译工具链
sudo apt-get update
sudo apt-get install -y build-essential cmake git pkg-config

# libevent (异步事件驱动)
sudo apt-get install -y libevent-dev

# libsodium (加密: X25519 + ChaCha20-Poly1305)
sudo apt-get install -y libsodium-dev

# 可选: GStreamer RTSP (仅编译 rtsp_server 时需要)
# sudo apt-get install -y libgstreamer1.0-dev libgst-rtsp-server1.0-dev

# Linux 内核头文件 (用于 TUN/TAP 和 radiotap)
sudo apt-get install -y linux-headers-generic

如果系统包管理器没有 libsodium，手动编译:

1
2
3
4
5
6
7
cd /tmp
git clone https://github.com/jedisct1/libsodium.git
cd libsodium
./configure --prefix=/usr/local --disable-shared
make -j$(nproc)
sudo make install
sudo ldconfig

如果系统包管理器没有 libevent，手动编译:

1
2
3
4
5
6
7
8
cd /tmp
wget https://github.com/libevent/libevent/releases/download/release-2.1.12-stable/libevent-2.1.12-stable.tar.gz
tar xzf libevent-2.1.12-stable.tar.gz
cd libevent-2.1.12-stable
./configure --prefix=/usr/local --disable-shared --disable-libevent-regress
make -j$(nproc)
sudo make install
sudo ldconfig

3. 编译 WFB-ng

3.1 配置 CMake

1
2
3
4
5
6
7
8
9
10
11
12
13
cd /path/to/wfb-ng
mkdir -p build && cd build

# 最小化编译（仅核心组件，无 GStreamer）
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DENABLE_RTSP_SERVER=OFF \
    -DCMAKE_C_FLAGS="-Os" \
    -DCMAKE_CXX_FLAGS="-Os"

# 如果需要 RTSP server:
# cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -DENABLE_RTSP_SERVER=ON

3.2 ARM 交叉编译（可选）

对于 ARM 嵌入式目标：

1
2
3
4
5
6
7
8
# 安装交叉编译器
sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=../toolchain-arm64.cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DENABLE_RTSP_SERVER=OFF

创建 toolchain-arm64.cmake:

1
2
3
4
5
6
7
8
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_FIND_ROOT_PATH /usr/aarch64-linux-gnu)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

3.3 编译与安装

1
2
3
make -j$(nproc)
sudo make install
sudo ldconfig

3.4 生成的二进制文件

文件名 说明 大小（约）
wfb_tx 发射端发送器 ~150KB
wfb_rx 接收端聚合器 ~200KB
wfb_tun TUN 设备代理 ~30KB
tx_cmd 控制命令行工具 ~20KB
rtsp_server RTSP/RTP 服务器（可选） ~50KB

4. 快速启动指南

4.1 生成密钥对

1
2
3
4
# wfb_tx 和 wfb_rx 共享同一密钥对
# 使用 libsodium 工具或以下命令生成:
wfb_tx --genkeypair > /etc/wfbng.key
chmod 600 /etc/wfbng.key

4.2 发射端 (TX) 配置

方法 A: 通过 TUN 设备发送（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 启动 wfb_tx，监听 TUN 设备
sudo wfb_tx -d wlan0 \
    -k /etc/wfbng.key \
    --tx-iface=wlan0 \
    --channel=36 \
    --bandwidth=20 \
    --mcs-index=1

# 2. 配置 TUN 设备 IP
sudo ip link set wfb-tx up
sudo ip addr add 10.5.0.1/24 dev wfb-tx

# 3. 发送数据（示例: ping）
ping -I wfb-tx 10.5.0.2

方法 B: 通过 UDP socket 发送

1
2
3
4
5
6
7
8
# 启动 wfb_tx，从 UDP 端口接收数据
sudo wfb_tx -d wlan0 \
    -k /etc/wfbng.key \
    --listen=10.5.0.1:5700 \
    --tx-iface=wlan0

# 使用 netcat 发送测试数据
echo "Hello WFB-ng" | nc -u -w1 127.0.0.1 5700

4.3 接收端 (RX) 配置

方法 A: 输出到 TUN 设备（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
# 启动 wfb_rx，聚合多个无线网卡的数据
sudo wfb_rx -d wlan1,wlan2 \
    -k /etc/wfbng.key \
    --rx-iface=wlan1,wlan2 \
    --output=tun:wfb-rx

# 配置 TUN 设备 IP
sudo ip link set wfb-rx up
sudo ip addr add 10.5.0.2/24 dev wfb-rx

# 验证连接
ping -I wfb-rx 10.5.0.1

方法 B: 输出到 UDP socket

1
2
3
4
5
6
7
8
# 启动 wfb_rx，输出到 UDP
sudo wfb_rx -d wlan1,wlan2 \
    -k /etc/wfbng.key \
    --rx-iface=wlan1,wlan2 \
    --output=udp:10.5.0.3:5800

# 使用 netcat 接收数据
nc -u -l -p 5800

4.4 TUN 代理模式（wfb_tun）

当需要在 wfb_tx/rx 和外部应用之间建立桥接时：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 启动 wfb_tun，连接 TUN 设备和 UDP socket
sudo wfb_tun -t wfb-tun \
    -a 10.5.0.2/24 \
    -c 127.0.0.1 \
    -u 5801 \
    -l 5800 \
    -T 5

# 参数说明:
#   -t: TUN 设备名称
#   -a: TUN 设备 IP 地址
#   -c: wfb_tx/rx 的监听地址
#   -u: wfb_tx/rx 的监听端口
#   -l: wfb_tun 自身监听的 UDP 端口
#   -T: 聚合超时（毫秒）

4.5 动态控制 (tx_cmd)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 查看当前 FEC 参数
./tx_cmd 2700 get_fec

# 调整 FEC 参数（增加冗余度以应对高丢包环境）
./tx_cmd 2700 set_fec -k 16 -n 32

# 查看当前射频配置
./tx_cmd 2700 get_radio

# 修改射频参数
./tx_cmd 2700 set_radio \
    -B 40 \      # 40MHz 带宽
    -M 5 \       # MCS index 5 (65 Mbps for 1SS)
    -G s \       # Short Guard Interval
    -S 1         # STBC enabled

5. 完整部署示例

场景: FPV 无人机图传系统

1
2
3
4
5
[无人机端]                          [地面站]
   |                                    |
wfb_tx --> (WiFi) --> wlan0          wlan1 <-- (WiFi) <-- wfb_rx
   |                                    |
GStreamer/H.264                    VLC/ffplay

发射端（无人机）启动脚本:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
#!/bin/bash
# tx_start.sh - 发射端启动脚本

KEY="/etc/wfbng.key"
WLAN="wlan0"
CHANNEL=36
BANDWIDTH=20
MCS=1

# 配置无线网卡为 monitor 模式
sudo ip link set $WLAN down
sudo iw dev $WLAN set type monitor
sudo ip link set $WLAN up

# 设置信道
sudo iw dev $WLAN set channel $CHANNEL

# 启动 wfb_tx
sudo wfb_tx -d $WLAN \
    -k "$KEY" \
    --tx-iface=$WLAN \
    --channel=$CHANNEL \
    --bandwidth=$BANDWIDTH \
    --mcs-index=$MCS \
    --stbc=0 \
    --ldpc=1 \
    --short-gi=1

# 配置 TUN 设备
sudo ip link set wfb-tx up
sudo ip addr add 10.5.0.1/24 dev wfb-tx

echo "TX started on $WLAN, channel=$CHANNEL"

接收端（地面站）启动脚本:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/bin/bash
# rx_start.sh - 接收端启动脚本

KEY="/etc/wfbng.key"
WLANS="wlan1,wlan2"

# 配置无线网卡为 monitor 模式
for wlan in $(echo $WLANS | tr ',' ' '); do
    sudo ip link set $wlan down
    sudo iw dev $wlan set type monitor
    sudo ip link set $wlan up
done

# 启动 wfb_rx
sudo wfb_rx -d $WLANS \
    -k "$KEY" \
    --rx-iface=$WLANS \
    --output=tun:wfb-rx

# 配置 TUN 设备
sudo ip link set wfb-rx up
sudo ip addr add 10.5.0.2/24 dev wfb-rx

echo "RX started on $WLANS"

视频流传输:

1
2
3
4
5
6
7
# 发射端 - 编码并发送 H.264 视频流
ffmpeg -re -i /dev/video0 \
    -c:v libx264 -preset ultrafast -tune zerolatency \
    -f mpegts udp://10.5.0.2:8554

# 接收端 - 接收并播放视频流
ffplay -i udp://@:8554 -framedrop -autoexit

6. 性能调优参数

FEC 参数选择指南

环境 K (数据块) N (总块) 冗余度 适用场景
室内/近距离 8 12 33% WiFi 信号良好，丢包 < 5%
室外/中距离 16 32 50% 有遮挡或干扰，丢包 5-15%
远距离/高干扰 8 24 67% 严重干扰环境，丢包 > 15%

射频参数选择指南

MCS Index 调制方式 1SS (20MHz) 适用条件
0-7 BPSK/QPSK/16QAM 6.5-72 Mbps 远距离或弱信号
8-20 64-QAM 90-144 Mbps 中等距离，良好信号
21-77 256-QAM (VHT) 150-867 Mbps 近距离，强信号

系统级优化

1
2
3
4
5
6
7
8
9
10
11
12
13
# 增加 UDP 缓冲区大小
sudo sysctl -w net.core.rmem_max=134217728
sudo sysctl -w net.core.wmem_max=134217728
sudo sysctl -w net.ipv4.udp_mem="131072 262144 524288"

# 禁用 WiFi 电源管理
sudo iw dev wlan0 set power_save off

# 设置 CPU 实时优先级（发射端）
sudo chrt -f 99 ./wfb_tx ...

# 绑定网卡到特定 CPU 核心
sudo ethtool -X wlan0 combined 1

7. 故障排查

常见问题

问题 可能原因 解决方案
Unable to decrypt session key 密钥不匹配或 epoch 过期 检查两端使用相同的 keypair，重启 wfb_tx 刷新 epoch
FEC recovered X packets (过多) FEC 参数不足 增加 N/K 比例：tx_cmd <port> set_fec -k 16 -n 32
Packets lost WiFi 信号弱或干扰 检查 RSSI，调整 MCS index 降低速率
TUN 设备无法创建 权限不足 使用 sudo 运行，确保 /dev/net/tun 存在
Short packet (fec header) 数据包损坏 检查无线网卡驱动，确认 monitor 模式正确配置

调试命令

1
2
3
4
5
6
7
8
9
10
11
12
# 查看 wfb_rx 统计信息（通过 IPC socket）
cat /tmp/wfb-rx.ipc

# 监控 WiFi 接口流量
sudo tcpdump -i wlan0 -nn udp port 5700

# 检查 TUN 设备状态
ip link show wfb-tx
ip addr show wfb-tx

# 查看内核日志中的无线事件
dmesg | tail -20

8. 最小系统打包清单

对于嵌入式部署，以下文件是必需的：

1
2
3
4
5
6
7
/usr/local/bin/wfb_tx
/usr/local/bin/wfb_rx
/usr/local/bin/wfb_tun
/usr/local/bin/tx_cmd
/etc/wfbng.key                          # 密钥对（自行生成）
/lib/*/libevent-2.1.so.*               # libevent 运行时库
/lib/*/libsodium.so.*                  # libsodium 运行时库

最小镜像大小估算：~5MB（不含内核和基础系统）