From db5d9d9854d91ddd82796148d3e14951f558cdcf Mon Sep 17 00:00:00 2001 From: taorye Date: Mon, 3 Aug 2026 17:31:38 +0800 Subject: [PATCH] docs: improve MA-USB8 usage and troubleshooting guide --- .../zh/modules/micarray_usbboard_bl616.md | 120 +++++++++++++----- 1 file changed, 90 insertions(+), 30 deletions(-) diff --git a/docs/hardware/zh/modules/micarray_usbboard_bl616.md b/docs/hardware/zh/modules/micarray_usbboard_bl616.md index 0e40b193..a72eac4c 100644 --- a/docs/hardware/zh/modules/micarray_usbboard_bl616.md +++ b/docs/hardware/zh/modules/micarray_usbboard_bl616.md @@ -4,12 +4,22 @@ ![](../../assets/modules/micarray_usbboard_bl616/product-front.png) -MA-USB8 是一块为麦克风阵列提供 USB 音频与串口数据接口的驱动板，主要用于把麦克风阵列采集到的音频（通过 UAC2.0 8通道）和声场成像/声源定位热力图（通过 CDC ACM / UART 帧）输出到上位机或 MCU。常见应用场景有语音采集/降噪/波束指向与声场可视化等。 +MA-USB8 是一块为麦克风阵列提供 USB 音频与串口数据接口的驱动板，主要用于把麦克风阵列采集到的音频（通过 UAC2.0 8 通道）和声场成像/声源定位热力图（通过 CDC ACM / UART 帧）输出到上位机或 MCU。常见应用场景有语音采集、降噪、波束指向与声场可视化等。 -- UAC2.0（USB Audio Class）: 8 通道，PCM s16_le，48 kHz +- UAC2.0（USB Audio Class）：8 通道，PCM S16_LE，48 kHz - CDC ACM（USB 虚拟串口）: 16×16 原始格式声场热力图（Hotmap Frame）串行输出 - UART: 通过 UART (2,000,000 bps) 输出 16×16 原始/HEX+彩色格式声场热力图（适合 MCU 场景） +UAC 通道定义如下： + +| 通道 | 数据 | +| --- | --- | +| CH0～CH5 | PEC 采集的原始有符号 16-bit PCM | +| CH6 | CH0～CH5 延时对齐后的平均值，用作波束合成输出 | +| CH7 | PEC 采集的原始有符号 16-bit PCM | + +所有通道的采样率均为 48 kHz。UAC 传输期间，CH6 对应的 PEC 原始数据会被波束合成结果覆盖。 + > 本文是 MA-USB8 的使用指南，覆盖从接线、验证设备、音频录制、波束成形到如何读取/解析声场热力图与常见故障排查。 ## 快速上手 @@ -41,7 +51,9 @@ MA-USB8 是一块为麦克风阵列提供 USB 音频与串口数据接口的驱 ![](../../assets/modules/micarray_usbboard_bl616/lsusb.png) ### 验证设备（Windows） -在设备管理器中可看到：音频接口 MicArray (UAC2.0) 和虚拟串口 USB串行设备 (CDC ACM)；如需 8 通道录制，请在录音软件（如 Audacity）中选择正确设备并设置为 8 通道采样。详细可见下节介绍。 +在设备管理器中可看到音频接口 MicArray（UAC2.0）和虚拟串口 USB 串行设备（CDC ACM）。如需录制 8 通道音频，请在录音软件中选择 MicArray，并将格式设置为 8 通道、PCM 16-bit、48 kHz。 + +如果录音软件只能选择 1 或 2 通道，请参见[Windows 只能选择 1 或 2 通道](#Windows-只能选择-1-或-2-通道)。 ![](../../assets/modules/micarray_usbboard_bl616/devmgmt.png) @@ -54,7 +66,7 @@ MA-USB8 是一块为麦克风阵列提供 USB 音频与串口数据接口的驱 ```bash arecord -D hw:1,0 -f S16_LE -c 8 -r 48000 -t wav -d 10 test_8ch.wav ``` -这条命令录制 10s 的 8 通道 WAV（PCM S16_LE，48kHz）。 +这条命令录制 10 秒的 8 通道 WAV（PCM S16_LE，48 kHz）。 3. （可选）使用 sox 提取指定通道（如 CH6）进行回放或分析： ```bash @@ -63,16 +75,16 @@ sox test_8ch.wav ch6.wav remix 7 # sox 的通道编号从 1 开始，7 表示 aplay ch6.wav ``` -> 注意：硬件编号与频道索引关系与系统环境有关，录制或回放时请根据 `arecord -l`/`aplay -l` 输出确认硬件编号。 +> 注意：硬件编号与通道索引关系与系统环境有关，录制或回放时请根据 `arecord -l`/`aplay -l` 输出确认硬件编号。如果无法访问串口设备，请参见[Linux 无法访问串口设备](#Linux-无法访问串口设备)。 #### Audacity（GUI） 1. 打开 Audacity -> 编辑 -> 首选项 -> 设备，选择 MA-USB8 采集设备。 -2. 在录音通道处选择 8×通道。 +2. 在录音通道处选择 8 通道。 3. 开始录制，你会看到多通道波形，停止后可以选择某一路音轨听/导出。 ![](../../assets/modules/micarray_usbboard_bl616/audacity-linux-sine1k.png) -**Windows 需要使用 WASAPI 才会出现 8 声道的选择** +**Windows 下请选择 WASAPI；如果仍然只有 1 或 2 通道，请参见[Windows 只能选择 1 或 2 通道](#Windows-只能选择-1-或-2-通道)。**
@@ -95,23 +107,45 @@ minicom -D /dev/ttyACM0 -H ## 读取并解析声场热力图（CDC ACM / UART） -驱动板通过 CDC ACM（/dev/ttyACM0）或 UART（2,000,000 bps）发送热力图帧。帧格式上方已给出。下面给出串口读取/解析的示例： +驱动板通过 CDC ACM（`/dev/ttyACM0`）或 UART（2,000,000 bps）输出声场热力图，两个接口的默认显示方式不同： + +- CDC ACM 连续输出原始二进制数据。每帧包含 16 字节帧头和 256 字节数据，详见 [Hotmap Frame 格式](#Hotmap-Frame-格式（开发者视角）)。 +- UART 默认输出原始二进制数据。在串口中输入大写 `F` 后，开启 16×16 文本热力图；再输入大写 `C`，开启伪彩显示。输入小写 `f`、`c` 可分别关闭对应功能，详见[完整指令表](#完整指令表（开发者）)。 ### 通过 minicom / picocom 观察（快速） -- CDC ACM Raw（minicom）: `minicom -D /dev/ttyACM0 -H`（`-H` 使显示十六进制/无回显，视 minicom 版本而定） -- UART（picocom）: `picocom -b 2000000 /dev/ttyUSB0` （仅物理串口 UART 支持 十六进制/颜色映射视图） - - 按 `F` 切换为十六进制视图 (HEX)，然后按下 `C` （大写）切换为十六进制+颜色映射视图 (HEX-CMAP)。 +CDC ACM 使用 minicom 观察原始帧： -![](../../assets/modules/micarray_usbboard_bl616/minicom_acm&picocom_uart-combine.png) +```bash +minicom -D /dev/ttyACM0 -H +``` -
- - +UART 使用 picocom，波特率固定为 2,000,000 bps： + +```bash +picocom -b 2000000 /dev/ttyUSB0 +``` + +打开 picocom 后输入大写 `F`，将原始二进制流切换为 16×16 文本热力图；需要伪彩显示时，再输入大写 `C`。 + +如果串口没有数据或输出乱码，请分别参见[CDC ACM 不输出热力图](#CDC-ACM-不输出热力图)和[UART 输出乱码或无法显示](#UART-输出乱码或无法显示)。 + +
+ +
左：CDC ACM 原始二进制帧的十六进制预览。右：UART 开启 16×16 打印后，从普通文本热力图切换到伪彩热力图的过程。
+
+ +
+
+ +
UART 16×16 文本热力图：输入 F 开启。
+
+
+ +
UART 伪彩热力图：开启 16×16 打印后输入 C。
+
-（开发者参考：hexdump 检查方法与数据格式说明请参见本文末的 “开发者参考” 部分。） - ### MCU 解析串口数据帧 如果要在 MCU 端解析这个帧，原则相同：丢弃 16 字节头并把后 256 字节按行/列解析。 @@ -121,7 +155,7 @@ minicom -D /dev/ttyACM0 -H - 设置波束方向（0..9, A, B）：向串口直接输入字符（例如 `0`、`3`、`A`）来设置波束方向。 - 打开/关闭 LED 指示灯：输入 `e` / `E` （小写关，大写开）。 -- 切换 UART 热力图打印：输入 `f` / `F`（切换 16×16 ASCII 打印）。 +- 切换 UART 热力图打印：输入 `f` 关闭、`F` 开启 16×16 ASCII 打印。 更多详细指令及行为参见本文末的“开发者参考”中的完整指令表。 @@ -130,28 +164,57 @@ minicom -D /dev/ttyACM0 -H 2. 在 Audacity 中监听 CH6：你应该在 CH6 听到来自目标方向的声音被增强，或在系统中录制 CH6 再回放分析。 ## 常见问题与故障排查 -- Windows 上如果仅能看到 2 通道，可能是 Windows USB 音频驱动/软件对 USB 多通道的限制；需要使用 `WASAPI`。 -- Linux 权限问题：无法访问 `/dev/ttyACM0` 或 `/dev/ttyUSB0` 可通过添加 udev 规则或将当前用户加入 `plugdev` 组来解决： - - `sudo usermod -a -G plugdev $USER` 然后重新登录。 - - 创建 udev 规则（示例，替换 vendor/product id）： + +### Windows 只能选择 1 或 2 通道 + +先选择 `WASAPI`，再进入“设置 → 系统 → 声音 → 输入 → MicArray”，将“音频增强（Audio Enhancements）”设为“关闭”，然后重新打开录音软件。Windows 的 Voice Clarity 等音频增强可能限制应用可用的录音通道数。 + +### Linux 无法访问串口设备 + +无法访问 `/dev/ttyACM0` 或 `/dev/ttyUSB0` 时，可将当前用户加入 `plugdev` 组，然后重新登录： + +```bash +sudo usermod -a -G plugdev $USER +``` + +也可以创建 udev 规则（示例，替换 vendor/product id）： + ```bash # /etc/udev/rules.d/99-ma-usb8.rules SUBSYSTEM=="tty", ATTRS{idVendor}=="359F", MODE="0666", GROUP="plugdev" ``` -- CDC ACM/ttyACM0 不输出热力图：请确认设备同时处于 CDC ACM/UAC 模式（并不是只用作 UAC 音频），尝试断开其他使用该串口的软件后再打开。 -- UART 串口乱码或无法显示：请确认波特率为 `2000000 bps`，且使用 `picocom -b 2000000`、`minicom -b 2000000` 等工具；在 Windows 下需要安装正确的 USB 串口驱动（CH340/CH341/CH552 等）。 +### CDC ACM 不输出热力图 + +确认设备同时处于 CDC ACM/UAC 模式，而不是仅用作 UAC 音频。关闭其他占用该串口的软件，然后重新打开串口。 + +### UART 输出乱码或无法显示 + +确认波特率为 `2000000 bps`，并使用 `picocom -b 2000000`、`minicom -b 2000000` 等工具。Windows 下需要安装正确的 USB 串口驱动（CH340/CH341/CH552 等）。 ## 固件升级 -下载 [固件](../../assets/modules/micarray_usbboard_bl616/firmware/MA-USB8-251201.bin) 并参考 [固件刷写教程](../logic_analyzer/combo8/update_firmware.html#Burn-firmware) 进行升级。 + +本页提供的固件仅适用于 MA-USB8： + +- 文件：[MA-USB8-251201.bin](../../assets/modules/micarray_usbboard_bl616/firmware/MA-USB8-251201.bin) +- 文件大小：87552 字节 +- SHA-256：`f2381d1f5a50b0fc7a15e6723f61c4204dfae9dc394bfa349a18404ecd0c2905` + +升级步骤： + +1. 下载固件并核对文件大小或 SHA-256。 +2. 按照[固件刷写教程](../logic_analyzer/combo8/update_firmware.html#Burn-firmware)连接设备、进入烧录模式并写入固件。 +3. 烧录完成后重新插拔设备。 +4. 在 Linux 下使用 `lsusb -v` 和 `arecord -l`，或在 Windows 声音设置中确认 MicArray 已提供 8 通道、PCM 16-bit、48 kHz 格式。 +5. 如果 Windows 录音软件仍然只能选择 1 或 2 通道，请参见[Windows 只能选择 1 或 2 通道](#Windows-只能选择-1-或-2-通道)。 + +升级前请记录当前固件版本和设备描述符，便于升级失败时核对设备状态。固件升级过程中不要断开 USB 连接或关闭烧录工具。 --- ## 开发者参考（协议、代码示例、完整指令表） 以下内容针对需要二次开发或深入调试的用户；普通用户可以忽略其中的协议细节。 -![](../../assets/modules/micarray_usbboard_bl616/picocom_uart-raw-errcode.png) - ### Hotmap Frame 格式（开发者视角） | frame | bytes | value | | ----- | --------- | ----- | @@ -160,9 +223,6 @@ SUBSYSTEM=="tty", ATTRS{idVendor}=="359F", MODE="0666", GROUP="plugdev" 说明：总长度为 16 + 256 = 272 字节；head 用于对齐与帧头检测，payload 为 256 字节，每个字节表示该网格点的强度（0 最小，255 最大）。 -![](../../assets/modules/micarray_usbboard_bl616/minicom_acm-raw.png) -![](../../assets/modules/micarray_usbboard_bl616/minicom_uart-raw.png) - ### 完整指令表（开发者） | 指令 | 输入(小/大写: 关/开) | 默认值 | 作用 | 输入源 | | - | - | - | - | - |