> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WiFi 与蓝牙

Qualcomm Dragonwing IQ-9075 EVK 通过 M.2 接口上的 **NFA765A** 模块（WCN6856 NSP288 芯片）提供集成的 Wi-Fi 和 Bluetooth 连接。

## 规格

### Wi-Fi

| 特性            | 规格                       |
| ------------- | ------------------------ |
| **标准**        | Wi-Fi 6E（802.11ax）       |
| **频段**        | 2.4 GHz、5 GHz、6 GHz（三频段） |
| **峰值 PHY 速率** | 2.9 Gbps（1K QAM）         |
| **工作模式**      | 双频同时工作（DBS）、STA 和 AP 模式  |
| **驱动**        | ath11k                   |

### Bluetooth

| 特性         | 规格                  |
| ---------- | ------------------- |
| **标准**     | Bluetooth 核心规范 v5.2 |
| **BLE 速率** | 最高 2 Mbps           |
| **远距离**    | 500 Kbps 和 125 Kbps |
| **协议栈**    | BlueZ               |

## 硬件设置

<img src="https://mintcdn.com/qualcomm-prod/pewhzjRBud-6f-rm/Ubuntu/images/peripheral-interfaces/IQ9075_hw_connection_diagram.png?fit=max&auto=format&n=pewhzjRBud-6f-rm&q=85&s=14b24c894308ca8d279b5698abf2410e" width="991" height="879" data-path="Ubuntu/images/peripheral-interfaces/IQ9075_hw_connection_diagram.png" />

<Steps>
  <Step title="安装 Wi-Fi 模块">
    以 30 度角将 NFA765A 模块插入 M.2 插槽，按平，然后用随附的螺丝固定。
  </Step>

  <Step title="连接天线">
    * **ANT0** — 支持 Wi-Fi 2.4 GHz、5 GHz 和 6 GHz；在 2.4 GHz 工作时与 Bluetooth 共享
    * **ANT1** — 支持 Wi-Fi 2.4 GHz、5 GHz 和 6 GHz
  </Step>

  <Step title="连接 UART 调试线缆">
    将 UART 线缆连接到调试端口，并记录分配的 COM 端口或 `/dev/ttyUSB` 设备。
  </Step>

  <Step title="连接电源并启动">
    上电并通过 UART 控制台观察启动序列。默认登录：`ubuntu` / `ubuntu`。
  </Step>
</Steps>

## 架构

### Wi-Fi 软件架构

<img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/peripheral-interfaces/wifi_software_architecture.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=94f7604ccc59ff326d4d767b7540d187" width="585" height="766" data-path="Ubuntu/images/peripheral-interfaces/wifi_software_architecture.png" />

| 组件                 | 描述                        |
| ------------------ | ------------------------- |
| **hostapd**        | 接入点与认证服务器（WPA/WPA2/WPA3）  |
| **cfg80211**       | 无线设备配置管理                  |
| **mac80211**       | 开源 WLAN 协议实现              |
| **ath11k MAC 接口**  | mac80211 与 ath11k 下层之间的接口 |
| **ath11k 控制/数据通路** | 扫描、认证、关联；数据流量管理           |
| **WMI/HTT**        | 主机驱动与固件之间的高级协议            |

### Bluetooth 软件架构

<img src="https://mintcdn.com/qualcomm-prod/P0rmO3AZfXx7cgqQ/Ubuntu/images/peripheral-interfaces/bluetooth_sw_architecture.png?fit=max&auto=format&n=P0rmO3AZfXx7cgqQ&q=85&s=f023439240ad1a2e2391c6fb23d38ed9" width="922" height="913" data-path="Ubuntu/images/peripheral-interfaces/bluetooth_sw_architecture.png" />

| 组件                 | 描述                            |
| ------------------ | ----------------------------- |
| **bluetoothd**     | 提供 D-Bus 接口的核心 Bluetooth 守护进程 |
| **bluetoothctl**   | 用于 Bluetooth 功能测试的 CLI 工具     |
| **HCI 核心**         | 在用户空间与驱动之间发送/接收 HCI 命令        |
| **L2CAP**          | 将大数据包拆分为帧；处理 QoS              |
| **Qualcomm BT 驱动** | GPIO 配置、调节器、补丁和 NV 数据下载       |

## 验证组件

### Wi-Fi

```bash theme={null}
# Check driver
lsmod | grep ath11k

# Check interface
iw dev

# Check firmware
ls -la /lib/firmware/ath11k/
```

### Bluetooth

```bash theme={null}
# Check driver
sudo lsmod | grep bt

# Check HCI device
hciconfig

# Check firmware
ls -la /lib/firmware/qca/

# Check BlueZ daemon
systemctl status bluetooth
```

## Wi-Fi 配置

### 站点模式

```bash theme={null}
# Scan for networks
nmcli dev wifi list

# Connect
nmcli dev wifi connect <SSID> password <password>

# Verify connection
nmcli general status
nmcli dev status
ifconfig wlp1s0
ping 8.8.8.8
```

### 设置 MAC 地址（可选）

<Warning>
  手动设置的 MAC 地址仅在下次重启前有效，之后会恢复为出厂 OTP 地址。
</Warning>

```bash theme={null}
ifconfig wlp1s0 down
ifconfig wlp1s0 hw ether XX:XX:XX:XX:XX:XX
ifconfig wlp1s0 up
```

### 热点模式

<Steps>
  <Step title="添加 SoftAP 接口">
    ```bash theme={null}
    iw dev wlp1s0 interface add wlp1s0 type managed
    ```
  </Step>

  <Step title="配置并启动 hostapd">
    ```bash theme={null}
    # Pull default config (optional)
    scp -r ubuntu@<IP>:/etc/hostapd.conf .
    # Edit and push back, then start:
    hostapd -B /etc/hostapd.conf
    ```
  </Step>

  <Step title="启动 DHCP 服务器">
    ```bash theme={null}
    brctl addbr br0
    brctl addif br0 wlp1s0
    ifconfig br0 192.168.225.1 netmask 255.255.255.0 up
    dnsmasq --conf-file=/etc/dnsmasq.conf \
      --dhcp-range=br0,192.168.225.20,192.168.225.60,255.255.255.0,43200
    ```
  </Step>

  <Step title="监控连接">
    ```bash theme={null}
    hostapd_cli -i wlp1s0 -p /var/run/hostapd
    ```
  </Step>
</Steps>

**停止热点：**

```bash theme={null}
killall hostapd
ifconfig wlp1s0 down
rm -rf /var/run/hostapd/wlp1s0
```

### 配置链路速率

```bash theme={null}
sudo ethtool -s end0 autoneg on speed 1000 duplex full
```

## Bluetooth 配置

### 设置 Bluetooth MAC 地址（可选）

<Warning>
  手动设置的 Bluetooth MAC 地址在重启后不会保留。
</Warning>

```bash theme={null}
# Power off Bluetooth first
hciconfig hci0 down

# Set address
btmgmt public-addr 22:22:9B:2C:79:1E

# Verify
hciconfig
```

### GAP 操作

<img src="https://mintcdn.com/qualcomm-prod/tRWO8v_Df_ujnDuD/Ubuntu/images/peripheral-interfaces/Bluetooth_GAP_sequence_diagram.png?fit=max&auto=format&n=tRWO8v_Df_ujnDuD&q=85&s=3142bcd08e19b986dff07af91a1683f2" width="1020" height="956" data-path="Ubuntu/images/peripheral-interfaces/Bluetooth_GAP_sequence_diagram.png" />

```bash theme={null}
# Launch bluetoothctl
bluetoothctl

# Enable Bluetooth
power on

# Scan for devices
scan on

# Pair with device
pair F8:7D:76:9D:9B:6B

# List paired devices
devices

# Enable discoverable mode
discoverable on

# Disable Bluetooth
power off
```

### 支持的 Bluetooth 配置文件

| 配置文件 | 角色      | 版本   |
| ---- | ------- | ---- |
| GAP  | 中心和外围   | —    |
| SPP  | 客户端和服务器 | v1.2 |
| GATT | 中心和外围   | —    |
| OPP  | 客户端和服务器 | v1.2 |
| FTP  | 客户端和服务器 | v1.2 |
| PBAP | 客户端和服务器 | v1.1 |
| MAP  | 客户端和服务器 | v1.2 |

<Note>
  WCN6750/WCN6856 支持 A2DP、AVRCP 和 HFP。
</Note>

## 调试

### Wi-Fi 调试日志

```bash theme={null}
# Enable logging
echo "module ath11k +p" > /sys/kernel/debug/dynamic_debug/control
echo "module ath11k_pci +p" > /sys/kernel/debug/dynamic_debug/control

# Collect logs
dmesg > /tmp/dmesg.txt
scp ubuntu@<IP>:/tmp/dmesg.txt .

# Collect firmware dump (on crash)
cat /sys/class/devcoredump/devcd*/data > /tmp/firmware_dump.bin
```

### Bluetooth 调试日志

```bash theme={null}
# Enable HCI snoop log (edit bluetooth.service)
# ExecStart=.../bluetoothd --noplugin=* --debug

# HCI snoop log location
/var/log/btsnoop_hci.log

# Enable kernel debug
echo "module bluetooth +p" > /sys/kernel/debug/dynamic_debug/control
echo "module btqca +p" > /sys/kernel/debug/dynamic_debug/control
echo "module hci_uart +p" > /sys/kernel/debug/dynamic_debug/control

dmesg > /tmp/bt_dmesg.txt
```

## 故障排查

<AccordionGroup>
  <Accordion title="未找到 wlp1s0 接口">
    **原因：** 驱动未加载或固件缺失。

    ```bash theme={null}
    dmesg | grep ath11k
    ls /lib/firmware/ath11k/
    ```
  </Accordion>

  <Accordion title="无法连接到 AP">
    **原因：** 密码错误或安全设置不匹配。

    确认 SSID 和密码；检查 AP 安全设置。
  </Accordion>

  <Accordion title="未分配 IP 地址">
    **原因：** DHCP 服务器问题。

    检查 AP 上的 DHCP 服务器；可手动分配静态 IP 进行测试。
  </Accordion>

  <Accordion title="热点客户端无法连接">
    **原因：** hostapd 配置错误。

    确认 `hostapd.conf` 设置；检查信道和安全参数。
  </Accordion>

  <Accordion title="Bluetooth 无法开启">
    **原因：** 驱动未加载或固件缺失。

    ```bash theme={null}
    dmesg | grep -i bluetooth
    ls /lib/firmware/qca/
    ```
  </Accordion>

  <Accordion title="配对失败">
    **原因：** 配对码不匹配或超时。

    确保两台设备确认相同的配对码；重新尝试配对。
  </Accordion>

  <Accordion title="音频配置文件不工作">
    **原因：** NFA765A 不支持 A2DP/HFP。

    确认配置文件支持情况 — A2DP 和 HFP 需要 WCN6750/WCN6856。
  </Accordion>

  <Accordion title="连接掉线">
    **原因：** 2.4 GHz 干扰或电源管理。

    禁用电源管理；检查来自 Wi-Fi 的 2.4 GHz 干扰。
  </Accordion>
</AccordionGroup>

## 快速上手检查清单

<AccordionGroup>
  <Accordion title="Wi-Fi 站点模式">
    * [ ] NFA765A 模块已安装到 M.2 插槽
    * [ ] 天线已连接（ANT0 和 ANT1）
    * [ ] 固件文件存在（`/lib/firmware/ath11k/`）
    * [ ] `wlp1s0` 接口存在（`iw dev`）
    * [ ] 已连接到 AP（`nmcli dev wifi connect ...`）
    * [ ] 已分配 IP 地址（`ifconfig wlp1s0`）
    * [ ] 可访问互联网（`ping 8.8.8.8`）
  </Accordion>

  <Accordion title="Bluetooth">
    * [ ] NFA765A 芯片组已初始化
    * [ ] Bluetooth 固件存在（`/lib/firmware/qca/`）
    * [ ] `hci0` 控制器存在（`hciconfig`）
    * [ ] `bluetoothd` 正在运行（`systemctl status bluetooth`）
    * [ ] `bluetoothctl` 可用
    * [ ] Bluetooth 已开启（`power on`）
    * [ ] 扫描和配对成功
  </Accordion>
</AccordionGroup>

## 资源

* [Wi-Fi 联盟](https://www.wi-fi.org/certification)
* [Bluetooth SIG](https://www.bluetooth.com/specifications/)
* [Linux Wireless](https://wireless.wiki.kernel.org/)
* [ath11k](https://wireless.wiki.kernel.org/en/users/drivers/ath11k)
* [hostapd 文档](https://w1.fi/cgit/hostap/plain/hostapd/README)
* [nmcli 手册](https://www.linux.org/docs/man1/nmcli.html)