doc: update USB MicArray guideline and SLogic Combo8 description of uart's DTR and RTS (#893)

* doc: update UART interface pin description in CKLink and DAPLink documentation * doc: enhance user guide for MicArray UAC Drive Board MA-USB8 with detailed setup and troubleshooting instructions * doc: add note about reserved DTR and RTS pins in CKLink and DAPLink UART interface descriptions
2026-09-11 00:22:49 -05:00 · 2025-11-24 17:12:01 +08:00
parent 04615aa972
commit 184ea2afd5
6 changed files with 298 additions and 119 deletions
--- a/docs/hardware/en/logic_analyzer/combo8/use_cklink_function.md
+++ b/docs/hardware/en/logic_analyzer/combo8/use_cklink_function.md
@@ -32,7 +32,7 @@ Press the toggle button to switch the indicator light to yellow.

 In CKLink mode, it can simultaneously support one CKLink interface and one UART interface.

-The pins on the left side of the diagram (TXD, RXD, DTR, RTS) can be used as a UART interface.
+The pins on the left side of the diagram (TXD, RXD) can be used as a UART interface. (note: DTR and RTS are reserved.)

 The pins on the right side of the diagram (TCK, TDI, TDO, TMS) are used for CKLink debugging.

--- a/docs/hardware/en/logic_analyzer/combo8/use_daplink_function.md
+++ b/docs/hardware/en/logic_analyzer/combo8/use_daplink_function.md
@@ -32,7 +32,7 @@ Here's a step-by-step guide on using the STM32F103C8T6 chip with Windows MDK IDE

 In DAPLink mode, it can simultaneously support one DAPLink interface and one UART interface.

-The pins on the left side of the diagram (TXD, RXD, DTR, RTS) can be used as a UART interface.
+The pins on the left side of the diagram (TXD, RXD) can be used as a UART interface. (note: DTR and RTS are reserved.)

 The pins on the right side of the diagram (TCK, TDI, TDO, TMS) are used for DAPLink debugging.

--- a/docs/hardware/en/modules/micarray_usbboard_bl616.md
+++ b/docs/hardware/en/modules/micarray_usbboard_bl616.md
@@ -1,106 +1,202 @@
-# MicArray UAC Drive Board (MA-USB8)
+# MicArray UAC Drive Board MA-USB8 — User Guide

-## Introduction
+## Product overview

 ![](../../assets/modules/micarray_usbboard_bl616/product-front.png)

-Driving a [microphone array module]((./micarray.md)), it provides UAC2.0 + CDC ACM + UART interfaces.
+MA-USB8 is a USB audio + serial interface drive board designed for MicArray microphone modules. It forwards the array’s audio (via UAC2.0, 8 channels) and sends soundfield hotmap frames (via CDC ACM or UART) to a host PC or MCU. Common use cases include voice capture, noise suppression, beamforming, and soundfield visualization.

- UAC2.0: 8CH S16_LE 48000HZ
- CDC ACM: 16x16 Hotmap Frame
- UART: 16x16 Hotmap Frame on baudrate:2000000 
+- UAC2.0 (USB Audio Class): 8 channels, PCM S16_LE, 48 kHz
+- CDC ACM (USB virtual COM): 16×16 raw hotmap frames
+- UART: 16×16 raw / HEX + pseudo-color hotmap frames at 2,000,000 bps (suitable for MCUs)

-### Hotmap Frame Format:
+> This document is a user guide for MA-USB8. It covers connection, device verification, audio capture, beamforming, how to read/parse hotmap frames, and common troubleshooting.

-| frame| bytes        | value    |
-|------|--------------|----------|
-| head | 16           | 16x 0xFF |
-| data | 16x16 (HxW)  | ...      |
+## Quick start

+### Hardware and basic setup

-## Connection
+1. Use a data-capable 5V USB cable.
+2. Connect MA-USB8 to your host PC or to your MCU board via USB/USB2TTL.
+3. Choose a mode:
+   - Preferred: USB (UAC2.0 audio + CDC ACM serial) — on PC you can get multi-channel audio and hotmap frames together.
+   - Alternate: UART / USB2TTL (2,000,000 bps) — for MCU/embedded environments to get hotmap frames (HEX/pseudocolor) only.

-Choose one of the following connection methods:
+We recommend installing Audacity on your PC for testing/recording.

-  - Preferred: USB <---> UAC2.0 + CDC ACM (Full functionality: obtain audio data and sound field map simultaneously)
+Before proceeding, check:
+- That the USB cable is firmly connected and the board is powered (check LEDs).
+- That the device appears in your system (Linux: `/dev/ttyACM0` or `/dev/ttyUSB0`; Windows: look for MA-USB8 audio/CDC device in Device Manager).

-  - Or: UART/USB2TTL <---> UART (Limited performance scenarios, e.g., MCU: obtain sound field map only)
+### Verify the device (Linux)
+
+- After plugging in, run:
+  - `dmesg | tail` — you should see `/dev/ttyACM0` and `SipeedUSB MicArray`.
+  - `lsusb` — to inspect device IDs.
+- Check audio devices with:
+  - `arecord -l` — you should find an 8-channel UAC device.
+  - `pactl list short sources` — PulseAudio users can check sources.

-### Linux
 ![](../../assets/modules/micarray_usbboard_bl616/dmesg.png)
 ![](../../assets/modules/micarray_usbboard_bl616/lsusb.png)

-### Windows
+### Verify the device (Windows)
+
+Open Device Manager and confirm the device appears as a multi-channel audio device and a CDC ACM serial port. Use software that supports multi-channel UAC capture (e.g., Audacity configured with WASAPI) to record all 8 channels.
+
 ![](../../assets/modules/micarray_usbboard_bl616/devmgmt.png)

+## Record 8 channels (UAC2.0)

+### Linux (CLI)

-## Usage
+Find the card/device and record 8 channels using `arecord`:
+
+```bash
+arecord -l  # find the card / device
+arecord -D hw:1,0 -f S16_LE -c 8 -r 48000 -t wav -d 10 test_8ch.wav
+```
+
+Extract and play one channel (e.g., CH6):
+
+```bash
+sudo apt install sox
+sox test_8ch.wav ch6.wav remix 7  # sox uses 1-based channel indexing; `remix 7` extracts CH6 (zero-based→1-based)
+aplay ch6.wav
+```
+
+Notes:
+- Device indexes and channel mapping may vary between systems and drivers. Use `arecord -l` / `aplay -l` to confirm hw index and channel mapping.
+- If Windows only shows 2 channels, use WASAPI in Audacity or use Linux for full multi-channel capture.
+
+### Audacity (GUI)
+
+1. Open Audacity → Edit → Preferences → Devices, and select MA-USB8 as the recording device.
+2. Choose the number of channels (8) in the recording options.
+3. Record and inspect the tracks; you can solo or export an individual channel as needed.

-### USB UAC2.0 (Audacity)
 ![](../../assets/modules/micarray_usbboard_bl616/audacity-linux-sine1k.png)

-**Windows WASAPI**
+**Windows: Use WASAPI to enable 8-channel capture**
+Windows requires using WASAPI in Audacity to expose all 8 channels — choose the MA-USB8 device under WASAPI and select 8 channels.
 <div style="display: flex; justify-content: space-between;">
  <img src="../../assets/modules/micarray_usbboard_bl616/audacity-windows-wasapi-step-1.png" style="width: 48%;">
  <img src="../../assets/modules/micarray_usbboard_bl616/audacity-windows-wasapi-step-2.png" style="width: 48%;">
 </div>

-### USB UAC2.0 Beamforming (Audacity)
+## Beamforming demo

-This board supports 12-direction beamforming, which suppresses audio from other directions than the user-set monitoring direction, thereby achieving noise reduction and gain for the target monitoring direction. The following example uses a sine wave audio test for demonstration:
+MA-USB8 supports 12 beamforming directions: `0..9`, `A`, `B` (each step = 30°).

-Mic0(CH0) is near the 500HZ SINE wave and Mic3(CH3) is near the 1000HZ SINE wave.
+To point the beam to CH0 (0°) and monitor the beamformed output on CH6:

-Type `0` in serial so that CH6 is the output of beamforming at CH0.
+1. Open the CDC ACM serial device (e.g., `/dev/ttyACM0`) with a serial terminal:

-Obviously on CH6, the gain of the 500 Hz sine wave signal near CH0 has been increased, while the impact of the 1000 Hz sine wave signal from other directions has been eliminated.
+```bash
+minicom -D /dev/ttyACM0 -H
+```
+
+2. Type a single character (e.g., `0`) to set the beam direction to 0°. The beamformed audio will be output on CH6.
+3. Record or play CH6 and confirm that sound from the selected direction is amplified and other directions are suppressed.
+
+Note: `0..9, A, B` map to angles `0°, 30°, …, 330°`.

 ![](../../assets/modules/micarray_usbboard_bl616/sine500hz@ch0_and_sine1000hz@ch3_with_beamforming@ch0.png)

-### USB CDC ACM RAW (Minicom) and USB2TTL UART HEX-CMAP (Picocom)
+## Observe hotmap frames (CDC ACM / UART)
+
+The board outputs hotmap frames via CDC ACM (`/dev/ttyACM0`) or via UART (`/dev/ttyUSB0` at 2,000,000 bps).
+
+### Quick check with minicom / picocom
+
+- CDC ACM (raw):
+
+```bash
+minicom -D /dev/ttyACM0 -H
+```
+
+- UART (picocom raw/hex):
+
+```bash
+picocom -b 2000000 --imap 8bithex /dev/ttyUSB0
+```
+
+- In picocom, press `F` and then `C` to switch to HEX + color map (some versions/devices).

 ![](../../assets/modules/micarray_usbboard_bl616/minicom_acm&picocom_uart-combine.png)

-### USB CDC ACM RAW (Minicom)
-
-`minicom -D /dev/ttyACM0 -H`
-![](../../assets/modules/micarray_usbboard_bl616/minicom_acm-raw.png)
-
-
-### USB2TTL UART RAW (Minicom)
-
-`minicom -D /dev/ttyUSB0 -b 2000000 -H`
-![](../../assets/modules/micarray_usbboard_bl616/minicom_uart-raw.png)
-
-
-### USB2TTL UART RAW,HEX-CMAP (Picocom)
-
-1. `picocom -b 2000000 /dev/ttyUSB0`
-![](../../assets/modules/micarray_usbboard_bl616/picocom_uart-raw-errcode.png)
-
-2. type `F` and then `C`
 <div style="display: flex; justify-content: space-between;">
  <img src="../../assets/modules/micarray_usbboard_bl616/picocom_uart-hex.png" style="width: 45%;">
  <img src="../../assets/modules/micarray_usbboard_bl616/picocom_uart-hex-cmap.png" style="width: 45%;">
 </div>

-3. type `f`
-![](../../assets/modules/micarray_usbboard_bl616/picocom_uart-hex-to-raw-errcode.png)
+(Developer note: use `hexdump -C` or `cat /dev/ttyACM0 | hexdump -C -v | head -n 20` to validate frame structure manually.)

+## Quick serial commands (user cheat sheet)

-## Commands
+- Set beamforming direction: send `0..9`, `A`, or `B` to the serial port; CH6 will be the beamformed output.
+- LED on/off: `e` (off) / `E` (on).
+- Toggle 16×16 ASCII hotmap print: `f` / `F` (UART only).

-| Command                                          | Input (Lower/Uppercase: Off/On) | Default | Remarks                                      | Input Sources   |
-|--------------------------------------------------|---------------------------------|---------|----------------------------------------------|-----------------|
-| Set UAC CH6 Beamforming Direction Angle          | 0,1,..9,A,B | 0  | Actual angle = input value × 30 (0,1,..B => 0°,30°,...,330°). Corresponds to the clockwise direction starting from microphone 0, as per the [microphone array](./micarray.md).                                                           | Any             |
-| UART Sound Source Map Pseudocolor Mapping Toggle | c, C        | c  | Requires precondition: UART 16x16 sound source map printing enabled.  | UART input only |
-| UART Internal Debug Info Toggle                  | d, D        | d  | Controls internal debugging output.                                   | UART input only |
-| LED Real-Time Sound Direction Indicator Toggle   | e, E        | E  | Controls LED indicators.                                              | Any             |
-| UART 16x16 Sound Field Map Print Toggle          | f, F        | f  | Toggles printing of 16x16 sound source map (ASCII).                   | UART input only |
-| Restore Default Settings                         | R           | \  |Restores a series of configurations to default values.                 | Any             |
+Other developer-level commands are shown in the Developer Reference section.

+## Troubleshooting
+
+- Windows shows only 2 channels: This is either a Windows driver limitation or your recording software. Use WASAPI in Audacity or switch to Linux for full 8-channel capability.
+- Cannot access serial device: user permission issue — add your user to the `plugdev` group or create a udev rule (see Developer Reference):
+
+```bash
+sudo usermod -a -G plugdev $USER
+# Log out and log in again for the group change to take effect
+```
+
+- CDC ACM does not output frames: Confirm the board is in CDC ACM + UAC modes (not only UAC). Close other applications that may occupy the serial port.
+- UART output appears garbled: Ensure `2000000 bps` selection; use `picocom -b 2000000` or `minicom -b 2000000`. On Windows, ensure the correct USB-serial driver for your adapter (e.g., CH340/CH341/CH552) is installed.

 ## Firmware

-Download it from [here](../../assets/modules/micarray_usbboard_bl616/firmware/MA-USB8-250822.bin) and then refer to [this guide](../logic_analyzer/combo8/update_firmware.html#Burn-firmware) to update the firmware.
+Download the firmware from the assets and follow the combo8 firmware update guide:
+
+- Firmware: `../../assets/modules/micarray_usbboard_bl616/firmware/MA-USB8-250822.bin`
+- Burn instructions: `../logic_analyzer/combo8/update_firmware.html#Burn-firmware`
+
+---
+## Developer Reference (protocol, code examples, full command list)
+
+### Hotmap Frame Format
+
+| frame | bytes | value |
+| ----- | ----- | ----- |
+| head  | 16    | 16 × 0xFF |
+| data  | 16×16 | 256 bytes (one byte per cell, 0..255), row-major order (HxW) |
+
+Total packet length = 16 + 256 = 272 bytes. The header is used for frame alignment and detection; payload is the 256-byte matrix of intensity values.
+
+### Full command table
+
+| Command | Input (Lower/Uppercase: Off/On) | Default | Remarks | Input Source |
+| ------- | ------------------------------ | ------- | ------- | ------------ |
+| Set UAC CH6 beam direction | 0..9, A, B | 0 | angle = value × 30° (0..B → 0°,30°,…330°). Corresponds to the clockwise direction starting from microphone 0 as per the [microphone array](./micarray.md). | Any (serial/CDC) |
+| UART sound-map pseudocolor toggle | c/C | c | Requires ASCII 16×16 printing enabled | UART only |
+| UART internal debug info toggle | d/D | d | Enables/disables debug output | UART only |
+| LED indicator toggle | e/E | E | E = on, e = off | Any |
+| UART 16×16 ASCII print toggle | f/F | f | Toggle printing 16×16 sound-field map as ASCII | UART only |
+| Restore defaults | R | - | Restore board default settings | Any |
+
+### udev & Permission (Linux)
+
+Create a udev rule if needed (replace vendor/product with your device’s `lsusb` IDs):
+
+```bash
+# /etc/udev/rules.d/99-ma-usb8.rules
+SUBSYSTEM=="tty", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0666", GROUP="plugdev"
+# Example (Sipeed vendor id)
+SUBSYSTEM=="tty", ATTRS{idVendor}=="359F", MODE="0666", GROUP="plugdev"
+```
+
+### Serial/USB Notes
+- CDC ACM (`/dev/ttyACM0`) is bound to the Linux `cdc_acm` driver. If hotmap frames don’t appear, ensure the device is not held by another program.
+- UART (`/dev/ttyUSB0`) typically uses USB-to-serial adapters (CH34x/CH340/CH552); install proper drivers on Windows if necessary.
+
+
+That’s it — this English translation mirrors the Chinese guide and preserves the commands, examples, and images.
--- a/docs/hardware/zh/logic_analyzer/combo8/use_cklink_function.md
+++ b/docs/hardware/zh/logic_analyzer/combo8/use_cklink_function.md
@@ -32,7 +32,7 @@ SLogic Combo 8 具备高速CK-Link功能，且速率远超CK-Link Lite，接近C

 CKLink模式下可以同时支持一路CKLink和一路UART

- 上图左侧的引脚（TXD、RXD、DTR、RTS）可以作为串口使用
+- 上图左侧的引脚（TXD、RXD）可以作为串口使用（注：DTR、RTS 保留未使用）
 - 上图右侧的引脚（TCK、TDI、TDO、TMS）作为CKLink调试使用

 ### 使用方法
--- a/docs/hardware/zh/logic_analyzer/combo8/use_daplink_function.md
+++ b/docs/hardware/zh/logic_analyzer/combo8/use_daplink_function.md
@@ -32,7 +32,7 @@ SLogic Combo 8 具备高速DAP-Link功能，适用于各种常规芯片，尤其

 DAPLink模式下可以同时支持一路DAPLink和一路UART

- 上图左侧的引脚（TXD、RXD、DTR、RTS）可以作为串口使用
+- 上图左侧的引脚（TXD、RXD）可以作为串口使用（注：DTR、RTS 保留未使用）

 - 上图右侧的引脚（TCK(SWCLK)、TDI、TDO、TMS(SWDIO)）作为DAPLink调试使用

--- a/docs/hardware/zh/modules/micarray_usbboard_bl616.md
+++ b/docs/hardware/zh/modules/micarray_usbboard_bl616.md
@@ -1,104 +1,187 @@
-# 麦克风阵列UAC驱动板 MA-USB8
+# 麦克风阵列 UAC 驱动板 MA-USB8（使用指南）

-## 产品介绍
+## 产品概览

 ![](../../assets/modules/micarray_usbboard_bl616/product-front.png)

-搭配麦克风阵列模块使用,提供 UAC2.0 + CDC ACM + UART 接口.
+MA-USB8 是一块为麦克风阵列提供 USB 音频与串口数据接口的驱动板，主要用于把麦克风阵列采集到的音频（通过 UAC2.0 8通道）和声场成像/声源定位热力图（通过 CDC ACM / UART 帧）输出到上位机或 MCU。常见应用场景有语音采集/降噪/波束指向与声场可视化等。

- UAC2.0: 8CH S16_LE 48000HZ
- CDC ACM: 16x16 Hotmap Frame
- UART: 16x16 Hotmap Frame on baudrate:2000000 
+- 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 场景）

-### Hotmap Frame Format:
+> 本文是 MA-USB8 的使用指南，覆盖从接线、验证设备、音频录制、波束成形到如何读取/解析声场热力图与常见故障排查。

-| frame| bytes        | value    |
-|------|--------------|----------|
-| head | 16           | 16x 0xFF |
-| data | 16x16 (HxW)  | ...      |
+## 快速上手

+### 硬件接线与基础准备

-## 硬件连接
+1. 准备 5V/USB2.0 数据线。
+2. 将 MA-USB8 通过 USB 连接 PC（或杜邦线连接到 MCU 主板）。
+3. 选择一种模式：
+   - 首选：USB（UAC2.0 音频 + CDC ACM 串口）—— 在 PC 上同时获取多通道音频与声场帧。
+   - 备用：UART / USB2TTL（2,000,000-bit baudrate）—— 在 MCU/嵌入式场景下只获取（HEX/伪彩）声场帧。

-以下连接方式选择其一即可:
- 首选 USB <---> UAC2.0 + CDC ACM (全量功能: 获取音频数据,同时获取声场图)
- 或 UART/USB2TTL <---> UART (有限性能场景如MCU: 仅获取声场图)
+建议在 PC 主机上安装 [Audacity](https://www.audacityteam.org/download/) 常用音频处理软件。
+
+继续前请检查：
+- 确认 USB 数据线连接牢靠、设备上电（LED 是否闪烁），并使用 PC 的设备管理/终端确认出现 `/dev/ttyACM0` 或 Windows 下出现 `MA-USB8` 设备。
+- 如果在 Windows 下使用 [Audacity](https://www.audacityteam.org/download/) 录音，请先打开设备管理或 [Audacity](https://www.audacityteam.org/download/) 的设置确认 MA-USB8 可见。
+
+### 验证设备（Linux）
+- 插入设备后运行：
+  - 查 USB 复合设备：
+    - dmesg | tail  # 看到 /dev/ttyACM0 和 `SipeedUSB MicArray`。
+    - lsusb           # 查看设备 id，便于 udev 规则或故障排查
+  - 音频设备：
+    - arecord -l      # 列出可用录音设备（应该看到 8 通道 UAC 设备）
+    - pactl list short sources  # Pulseaudio 环境下查看来源

-### Linux
 ![](../../assets/modules/micarray_usbboard_bl616/dmesg.png)
 ![](../../assets/modules/micarray_usbboard_bl616/lsusb.png)

-### Windows
+### 验证设备（Windows）
+在设备管理器中可看到：音频接口 MicArray (UAC2.0) 和虚拟串口 USB串行设备 (CDC ACM)；如需 8 通道录制，请在录音软件（如 Audacity）中选择正确设备并设置为 8 通道采样。详细可见下节介绍。
+
 ![](../../assets/modules/micarray_usbboard_bl616/devmgmt.png)

+### 录音：录制 8 通道音频（UAC2.0）
+下面给出 Linux CLI 与 Audacity 的常见步骤。

+#### Linux（命令行，arecord 示例）
+1. 确认设备 `arecord -l`。记下 card:id，例如 hw:1,0。
+2. 使用 arecord 录制：
+```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）。

-## 使用体验
+3. （可选）使用 sox 提取指定通道（如 CH6）进行回放或分析：
+```bash
+sudo apt install sox
+sox test_8ch.wav ch6.wav remix 7  # sox 的通道编号从 1 开始，7 表示第 7 个通道 (0-based->1-based 转换)
+aplay ch6.wav
+```
+
+> 注意：硬件编号与频道索引关系与系统环境有关，录制或回放时请根据 `arecord -l`/`aplay -l` 输出确认硬件编号。
+
+#### Audacity（GUI）
+1. 打开 Audacity -> 编辑 -> 首选项 -> 设备，选择 MA-USB8 采集设备。
+2. 在录音通道处选择 8×通道。
+3. 开始录制，你会看到多通道波形，停止后可以选择某一路音轨听/导出。

-### USB UAC2.0 (Audacity)
 ![](../../assets/modules/micarray_usbboard_bl616/audacity-linux-sine1k.png)

-**Windows WASAPI**
+**Windows 需要使用 WASAPI 才会出现 8 声道的选择**
 <div style="display: flex; justify-content: space-between;">
  <img src="../../assets/modules/micarray_usbboard_bl616/audacity-windows-wasapi-step-1.png" style="width: 48%;">
  <img src="../../assets/modules/micarray_usbboard_bl616/audacity-windows-wasapi-step-2.png" style="width: 48%;">
 </div>

-### USB UAC2.0 Beamforming (Audacity)
+## 波束成形（Beamforming）示例
+MA-USB8 支持 12 方向的波束成形（0..B），每步为 30°。

-驱动板支持12方向的波束成型，即抑制用户设置的监听方向之外的音频，达到给目标监听方向增益降噪的效果。以下以正弦波音频实例测试讲解:
+示例：要把波束指向 CH0（0°）并在输出通道 CH6 获取波束合成后的音频：
+1. 打开串口（ttyACM0）：
+```bash
+minicom -D /dev/ttyACM0 -H
+```
+2. 在 minicom 中直接输入 `0`（字符）设置波束为方向 0°。
+3. 在音频软件（[Audacity](https://www.audacityteam.org/download/) / arecord）监听或录制 CH6：CH6 会包含指向 CH0 的波束合成音频（例如输入 0 对应角度 0°）。

-Mic0(CH0) 接近 500HZ 正弦波，Mic3(CH3) 接近 1000HZ 正弦波。
-
-串口输入 `0`，这样 CH6 就是 CH0 处波束成形的输出。
-
-显然在 CH6 上，增益了靠近 CH0 处的 500hz 正弦波信号并消除了其他角度的 1000hz 正弦波信号带来的影响。
+备注：输入 0..9, A, B 分别对应 0°,30°,…,330° 的 12 个方向；默认值 0。

 ![](../../assets/modules/micarray_usbboard_bl616/sine500hz@ch0_and_sine1000hz@ch3_with_beamforming@ch0.png)

-### USB CDC ACM RAW (Minicom) and USB2TTL UART HEX-CMAP (Picocom)
+## 读取并解析声场热力图（CDC ACM / UART）
+
+驱动板通过 CDC ACM（/dev/ttyACM0）或 UART（2,000,000 bps）发送热力图帧。帧格式上方已给出。下面给出串口读取/解析的示例：
+
+### 通过 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)。
+

 ![](../../assets/modules/micarray_usbboard_bl616/minicom_acm&picocom_uart-combine.png)

-### USB CDC ACM RAW (Minicom)
-
-`minicom -D /dev/ttyACM0 -H`
-![](../../assets/modules/micarray_usbboard_bl616/minicom_acm-raw.png)
-
-
-### USB2TTL UART RAW (Minicom)
-
-`minicom -D /dev/ttyUSB0 -b 2000000 -H`
-![](../../assets/modules/micarray_usbboard_bl616/minicom_uart-raw.png)
-
-
-### USB2TTL UART RAW,HEX-CMAP (Picocom)
-
-1. `picocom -b 2000000 /dev/ttyUSB0`
-![](../../assets/modules/micarray_usbboard_bl616/picocom_uart-raw-errcode.png)
-
-2. 输入 `F` 然后再输入 `C`
 <div style="display: flex; justify-content: space-between;">
  <img src="../../assets/modules/micarray_usbboard_bl616/picocom_uart-hex.png" style="width: 45%;">
  <img src="../../assets/modules/micarray_usbboard_bl616/picocom_uart-hex-cmap.png" style="width: 45%;">
 </div>

-3. 输入 `f`
-![](../../assets/modules/micarray_usbboard_bl616/picocom_uart-hex-to-raw-errcode.png)
+（开发者参考：hexdump 检查方法与数据格式说明请参见本文末的 “开发者参考” 部分。）

+### MCU 解析串口数据帧

-## 指令详解
+如果要在 MCU 端解析这个帧，原则相同：丢弃 16 字节头并把后 256 字节按行/列解析。

-| 指令                          | 输入(小/大写: 关/开) | 默认值 | 备注                                         |   输入源        |
-|------------------------------|--------------------|-------|---------------------------------------------|----------------|
-| 设置 UAC CH6 波束成型方向角度    | 0,1,..9,A,B        | 0     | 实际角度为输入值x30 (0,1,..B => 0,30,..,330)对应 0 号麦克风起始沿标号递增方向,搭配[麦克风阵列](./micarray.md)即为沿顺时针方向    | 任意            |
-| UART 声源定位图底色 伪彩映射 开关 | c, C               | c     | 需要前置条件:UART 打印 16x16 声源定位图 开       | 仅 UART 输入有效 |
-| UART 打印内部调试信息 开关       | d, D               | d     | 控制内部调试                                  | 仅 UART 输入有效 |
-| LED 声源方向实时指示 开关        | e, E               | E     | 控制LED灯                                    | 任意            |
-| UART 16x16 声源定位图 打印开关   | f, F               | f     | 切换打印 16x16 声源定位图(ascii)               | 仅 UART 输入有效 |
-| 恢复默认值                      | R                  | \     |恢复一系列配置默认值                            | 任意            |
+## 常用串口命令 (用户速查)
+下面摘录最常用且对普通用户最有用的串口命令，便于现场调试：

+- 设置波束方向（0..9, A, B）：向串口直接输入字符（例如 `0`、`3`、`A`）来设置波束方向。
+- 打开/关闭 LED 指示灯：输入 `e` / `E` （小写关，大写开）。
+- 切换 UART 热力图打印：输入 `f` / `F`（切换 16×16 ASCII 打印）。

-## 更新固件
+更多详细指令及行为参见本文末的“开发者参考”中的完整指令表。

-下载 [固件](../../assets/modules/micarray_usbboard_bl616/firmware/MA-USB8-250822.bin) 然后参考 [这篇教程](../logic_analyzer/combo8/update_firmware.html#Burn-firmware) 更新板载固件.
+### 示例：设置并验证波束方向
+1. 在串口中输入 `3`（示例）设置方向为 90°（3×30=90）。
+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）：
+```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 等）。
+
+## 固件升级
+下载 [固件](../../assets/modules/micarray_usbboard_bl616/firmware/MA-USB8-250822.bin) 并参考 [固件刷写教程](../logic_analyzer/combo8/update_firmware.html#Burn-firmware) 进行升级。
+
+---
+## 开发者参考（协议、代码示例、完整指令表）
+
+以下内容针对需要二次开发或深入调试的用户；普通用户可以忽略其中的协议细节。
+
+![](../../assets/modules/micarray_usbboard_bl616/picocom_uart-raw-errcode.png)
+
+### Hotmap Frame 格式（开发者视角）
+| frame | bytes     | value |
+| ----- | --------- | ----- |
+| head  | 16        | 16 × 0xFF |
+| data  | 16 × 16   | 每点 1 字节 (0-255)，按行优先 (HxW) | 
+
+说明：总长度为 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)
+
+### 完整指令表（开发者）
+| 指令 | 输入(小/大写: 关/开) | 默认值 | 作用 | 输入源 |
+| - | - | - | - | - |
+| 设置 UAC CH6 波束成型方向角度 | 0,1,..9,A,B | 0 | 将波束指向以 30° 步进的方向（实际角度 = 输入 × 30）；CH6 会输出合成后的音频 | 任意（串口/CDC） |
+| UART 声源定位图伪彩映射开关 (c/C) | c, C | c | 打开/关闭热力图伪彩（color map），需要先开启 16×16 打印 | 仅 UART |
+| UART 打印内部调试信息 (d/D) | d, D | d | 启用/禁用调试信息输出 | 仅 UART |
+| LED 指示灯开关 (e/E) | e, E | E | 启用/禁用 LED 实时指示显示 | 任意 |
+| UART 16×16 打印开关 (f/F) | f, F | f | 切换 UART 打印 16×16 声场矩阵 (ASCII) | 仅 UART |
+| 恢复默认设置 (R) | R | - | 恢复驱动板所有默认设置 | 任意 |
+
+### udev 与权限建议
+若运行 Linux 且经常使用串口，建议为设备创建 udev 规则来简化权限管理：
+
+```bash
+# /etc/udev/rules.d/99-ma-usb8.rules
+SUBSYSTEM=="tty", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0666", GROUP="plugdev"
+```
+替换 `XXXX` / `YYYY` 为 `lsusb` 显示的设备 Vendor/Product id。
+
+### 串口/USB 注意事项
+- CDC ACM（/dev/ttyACM0）在 Linux 下通常为内核 cdc_acm 驱动映射；若发现与 UAC 音频冲突，请先确认没有其他程序占用端口。
+- UART/TTY（/dev/ttyUSB0）一般由 USB转串口芯片（CH34x、CH340、CH552）驱动映射。