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

# WiFi 和 Bluetooth

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 速率** | 采用 1K QAM 时为 2.9 Gbps    |
| **运行模式**      | 双频同时(DBS)、STA 和 AP 模式    |
| **驱动**        | ath11k                   |

### Bluetooth

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

## 硬件设置

<img src="https://mintcdn.com/qualcomm-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/IQ9075_hw_connection_diagram.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=1814b9d2ce49bc3e7dadcfd8e80e67be" 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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/wifi_software_architecture.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=78ee07e62993461a08d31891499c242a" 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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/bluetooth_sw_architecture.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=a84610d8252c01980a6e78d14ca2df3f" width="922" height="913" data-path="Ubuntu/images/peripheral-interfaces/bluetooth_sw_architecture.png" />

| 组件                 | 说明                            |
| ------------------ | ----------------------------- |
| **bluetoothd**     | 提供 D-Bus 接口的核心 Bluetooth 守护进程 |
| **bluetoothctl**   | 用于 Bluetooth 功能测试的 CLI 工具     |
| **HCI Core**       | 在用户空间与驱动之间发送/接收 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 配置

### 站点模式(Station Mode)

```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-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/Bluetooth_GAP_sequence_diagram.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=1422a93bf094f4300b8b0a6ddfcb3e4e" 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)