WeebLabs/DSPi
GitHub: WeebLabs/DSPi
将树莓派Pico变成一块功能强大的廉价USB音频DSP处理器，支持参数均衡、有源分频、房间校正等全套音频处理功能。
Stars: 782 | Forks: 27
# DSPi 固件
**DSPi** 可将 Raspberry Pi Pico 或其他基于 RP2040 的开发板变成一个非常强大且廉价的小型数字音频处理器。它充当一个带有板载 DSP 引擎的 USB 声卡，允许你使用房间校正、有源分频、参数均衡器 (EQ)、时间对齐、响度补偿和耳机交叉馈入等基本工具。
我希望 RP2040 和 RP2350 能获得“比一杯咖啡还便宜的音频瑞士军刀”的美誉。
欢迎加入[官方 Discord 服务器](https://discord.gg/RCyqxAQ5xS)获取开发更新、参与讨论或寻求帮助！
## 目录
- [核心功能](#key-capabilities)
- [平台支持](#platform-support)
- [音频信号链](#audio-signal-chain)
- [硬件设置](#hardware-setup)
- [DSP 功能](#dsp-features)
- [矩阵混音器](#matrix-mixer)
- [参数均衡](#parametric-equalization)
- [响度补偿](#loudness-compensation)
- [耳机交叉馈入](#headphone-crossfeed)
- [音量均衡器](#volume-leveller)
- [每通道前置放大器](#per-channel-preamp)
- [主音量](#master-volume)
- [I2S 输出](#i2s-output)
- [超低音 PDM 输出](#subwoofer-pdm-output)
- [用户预设](#user-presets)
- [开发者参考](#developer-reference)
- [系统架构](#system-architecture)
- [性能调优](#performance-tuning)
- [USB 控制协议](#usb-control-protocol)
- [系统遥测](#reqgetstatus-0x50---system-telemetry)
- [数据结构](#data-structures)
- [从源码构建](#building-from-source)
- [详细规格](#detailed-specifications)
- [许可证](#license)
## 核心功能
* **USB 音频接口：** 在 macOS、Windows、Linux 和 iOS 下即插即用。支持 44.1、48 和 96 kHz 下的 16 位和 24 位 PCM 输入。
* **24 位 S/PDIF 或 I2S 输出：** 最多四个独立的立体声输出插槽（RP2350 上为 8 个通道，RP2040 上为 4 个通道）。每个插槽都可以在运行时在 S/PDIF 和 I2S 之间切换，允许直接连接到任何标准的 DAC。I2S 插槽共享一个公共的 BCK/LRCLK，并可选择产生 128×/256× 主时钟。
* **每通道前置放大器：** 每个 USB 输入通道（左/右）的独立增益控制，作为 DSP 管道的 PASS 1 在任何其他处理之前应用。
* **矩阵混音器：** 将任意一个或两个 USB 输入通道路由到任何输出，每个交叉点具有独立的增益和反相。RP2350 上为 2x9，RP2040 上为 2x5。
* **参数均衡：** 每个通道最多 10 个 PEQ 频段，具有 6 种滤波器类型。RP2350 上共有 110 个滤波器频段，RP2040 上为 70 个。RP2350 采用混合 SVF/biquad 架构，提供卓越的低频精度。
* **音量均衡器：** 基于 RMS、立体声联动、软拐点向上压缩器，可将较安静的内容提升至目标电平，而不会放大响亮的部分。可选的 10 ms 前视，可配置的速度和最大增益上限，以及 -6 dBFS 增益衰减安全限幅器。
* **响度补偿：** 基于 ISO 226:2003 等响度轮廓标准的依赖音量的 EQ。在低收听电平下自动提升低音和高音，以保持感知的音调平衡。
* **耳机交叉馈入：** 基于 BS2B 的交叉馈入，带有双耳时间延迟 (ITD)，可减少耳机收听时不自然的立体声分离度。三种经典预设以及完全可定制的参数。
* **主音量：** 设备端输出上限（-128 至 0 dB，带有真正的静音哨兵值），在信号链的最末端应用，独立于 USB 主机音量和 DSP 处理。两种持久化模式：独立于预设存储（默认——重启后保留，不受预设切换影响）或作为每个预设的一部分保存/恢复。
* **每输出增益与静音：** 每个输出通道的独立增益和静音控制。
* **时间对齐：** 每输出延迟（最高 85ms）用于扬声器/超低音扬声器对齐，在 S/PDIF/I2S 和 PDM 输出路径之间自动延迟补偿。
* **超低音输出：** 带有高性能二阶 Delta-Sigma 调制器的专用单声道 PDM 输出通道，可直接输出超低音，而无需第二个 DAC。
* **双核 DSP：** 两个平台上的 EQ 处理都分布在两个内核上，以便在多个输出处于活动状态时实现最大的吞吐量。
* **可配置的输出引脚：** 所有输出 GPIO 引脚（包括 I2S BCK/MCK）都可以在运行时重新分配，以适应自定义的 PCB 布局，无需重新刷写。
* **10 插槽预设系统：** 使用用户定义的名称保存、加载和管理多达 10 个完整的 DSP 配置。包括每通道命名、可配置的启动插槽和用于快速状态同步的批量参数传输。
* **诊断：** 每通道峰值/削波测量、USB PHY 错误计数器（CRC、位填充、超时、溢出、序列）、缓冲区填充统计、每个输出插槽的 S/PDIF DMA 饥饿计数器以及每个核心的 CPU 负载报告。
* **通过 USB 进行固件更新：** 供应商命令将设备重启至 UF2 引导加载程序，允许主机应用推送新固件而无需物理按下 BOOTSEL 键。
## 平台支持
| 功能 | RP2040 (Pico) | RP2350 (Pico 2) |
|---------|---------------|-----------------|
| **系统时钟** | 307.2 MHz (超频) | 307.2 MHz |
| **核心电压** | 1.15 V | 1.15 V |
| **采样率** | 44.1 / 48 / 96 kHz | 44.1 / 48 / 96 kHz |
| **音频处理** | Q28 定点 | 单精度浮点 |
| **EQ 频段** | 每通道 10 个（共 70 个） | 每通道 10 个（共 110 个） |
| **总通道数** | 7 (2 主通道 + 4 S/PDIF·I2S + 1 PDM) | 11 (2 主通道 + 8 S/PDIF·I2S + 1 PDM) |
| **输出插槽** | 2 个立体声（每个为 S/PDIF 或 I2S） | 4 个立体声（每个为 S/PDIF 或 I2S） |
| **输出位深** | 24-bit | 24-bit |
| **PDM 输出** | 1 (超低音) | 1 (超低音) |
| **最大延迟** | 每输出 85ms | 每输出 85ms |
| **数学引擎** | 手动优化的 ARM 汇编 | 硬件 FPU (混合 SVF/biquad EQ) |
| **双核 EQ** | 是 (Core 1 处理输出 3-4) | 是 (Core 1 处理输出 3-8) |
| **用户预设** | 10 个插槽 | 10 个插槽 |
| **状态** | 生产 | 生产 |
这两个平台都经过了全面测试，可投入生产。RP2040 在电压轻微提升的情况下可达到 307.2 MHz；RP2350 在相同电压下达到相同的频率。时钟是固定的（没有依赖速率的切换），并且在每个支持的采样率下 PIO 分频器都是整数。得益于其硬件浮点单元，RP2350 提供了显著更多的处理余量，支持更多的输出通道以及用于提高低频精度的混合 SVF/biquad 滤波器架构。
## 音频信号链
DSPi 在一个线性、低延迟的管道中处理音频：
**RP2350（11 个通道，9 个输出）：**
```
USB Input (16/24-bit PCM Stereo, 44.1 / 48 / 96 kHz)
|
PASS 1: Per-Channel Preamp (independent L/R gain) + USB Volume
|
PASS 2: Master EQ (10 bands per channel, Left/Right)
|
PASS 2.5: Volume Leveller (RMS upward compression, optional)
|
PASS 3: Headphone Crossfeed (BS2B + ITD, optional) + Master Peak Metering
|
Loudness Compensation (volume-dependent EQ, optional)
|
PASS 4: Matrix Mixer (2 inputs x 9 outputs, per-crosspoint gain & phase)
|
PASS 5: Per-Output EQ -> Gain/Mute -> Delay -> Output Gain × Master Volume
|
+-- Out 1-2 --> S/PDIF or I2S slot 0 (data: GPIO 6 default)
+-- Out 3-4 --> S/PDIF or I2S slot 1 (data: GPIO 7 default)
+-- Out 5-6 --> S/PDIF or I2S slot 2 (data: GPIO 8 default)
+-- Out 7-8 --> S/PDIF or I2S slot 3 (data: GPIO 9 default)
+-- Out 9 --> PDM Sub (data: GPIO 10 default)
(I2S BCK/LRCLK shared on GPIO 14/15 default; optional MCK on GPIO 13 default)
```
**RP2040（7 个通道，5 个输出）：**
```
USB Input (16/24-bit PCM Stereo, 44.1 / 48 / 96 kHz)
|
PASS 1: Per-Channel Preamp + USB Volume
|
PASS 2: Master EQ (10 bands per channel, Left/Right)
|
PASS 2.5: Volume Leveller (RMS upward compression, optional)
|
PASS 3: Headphone Crossfeed (BS2B + ITD, optional) + Master Peak Metering
|
Loudness Compensation (volume-dependent EQ, optional)
|
PASS 4: Matrix Mixer (2 inputs x 5 outputs, per-crosspoint gain & phase)
|
PASS 5: Per-Output EQ -> Gain/Mute -> Delay -> Output Gain × Master Volume
|
+-- Out 1-2 --> S/PDIF or I2S slot 0 (data: GPIO 6 default)
+-- Out 3-4 --> S/PDIF or I2S slot 1 (data: GPIO 7 default)
+-- Out 5 --> PDM Sub (data: GPIO 10 default)
(I2S BCK/LRCLK shared on GPIO 14/15 default; optional MCK on GPIO 13 default)
```
### 信号链细节
1. **输入 (USB)：** 44.1、48 或 96 kHz 下的 16 位或 24 位 PCM 立体声音频。位深通过 USB 替代设置选择；采样率通过 USB 音频类速率设置请求选择。
2. **每通道前置放大器 (PASS 1)：** 以 dB 为单位的 USB 左右输入通道的独立增益控制。在 DSP 链的最开始应用，因此其设置会影响所有下游处理。
3. **主 EQ (PASS 2)：** 每个通道（左/右）最多 10 个频段的参数 EQ。支持峰值、低搁架、高搁架、低通和高通滤波器类型。
4. **音量均衡器 (PASS 2.5)：** 可选的前馈、立体声联动、单频段 RMS 压缩器，具有软拐点向上压缩功能——较安静的内容被提升至目标电平，而高于阈值的内容则原封不动地通过。可配置的速度、最大增益上限和噪声门。可选的 10 ms 前视。一个 -6 dBFS 增益衰减安全限幅器可防止输出过冲。
5. **耳机交叉馈入 (PASS 3)：** 可选的 BS2B 交叉馈入，将每个通道经过滤波和延迟的部分混合到相反的通道中。采用互补滤波器设计，通过全通滤波器实现双耳时间延迟 (ITD)。三种预设（默认、Chu Moy、Jan Meier）加上自定义频率和馈送电平。ITD 可以独立切换。主峰值测量在此阶段接入。
6. **响度补偿：** 可选的 ISO 226:2003 等响度 EQ，适应于当前音量级别。在低音量下，低音和高音被提升，以补偿人耳降低的敏感度。可配置的参考 SPL 和强度。由 USB 主机音量位置驱动，因此无论下游的主音量衰减如何，它都能保持正确。
7. **矩阵混音器 (PASS 4)：** 将两个 USB 输入通道（左/右）路由到所有输出通道。每个交叉点都有独立的启用、增益（-inf 至 +12 dB）和反相功能。输出可以单独启用/禁用以节省 CPU。RP2350 有一个 2x9 矩阵（9 个输出），RP2040 有一个 2x5 矩阵（5 个输出）。
8. **输出 EQ (PASS 5)：** 两个平台上每个输出通道的独立 10 频段 EQ。是分频滤波器和每驱动器校正的理想选择。在 RP2350 上，低于 Fs/7.5 的滤波器使用 SVF 拓扑结构，以获得卓越的低频精度；较高频率使用传统的 biquad。
9. **每输出增益与静音：** 每个输出通道的独立增益（-inf 至 +12 dB）和静音控制。
10. **时间对齐：** 用于扬声器对齐的每输出延迟，最高可达 85 ms（在 48 kHz 下为 4096 个采样）。在 S/PDIF/I2S 和 PDM 输出路径之间的自动延迟补偿。
11. **主音量：** 设备端输出上限，-128 至 0 dB，在 -128 处具有真正的静音哨兵值。在 PASS 5 时折叠到每输出乘法器中，因此在 CPU 消耗上几乎是免费的。独立于 USB 主机音量——两者相乘。不影响响度补偿行为。
12. **输出：** 每个编号的插槽都可以配置为 24 位 S/PDIF 或 24 位 I2S（左对齐，MSB 优先）。I2S 插槽共享一个公共的 BCK/LRCLK 时钟对（由于 PIO 侧置约束，LRCLK 始终为 BCK + 1）。可选的 128× 或 256× Fs 主时钟 (MCK) 可以路由到单独的 GPIO。PDM 超低音始终在其专用的输出和引脚上。
## 硬件设置
### 刷写固件
1. 下载适用于您开发板的最新 `DSPi.uf2` 版本。
2. 按住 Pico 上的 **BOOTSEL** 按钮并将其插入计算机。
3. 将出现一个名为 `RPI-RP2` 的驱动器。
4. 将 `.uf2` 文件拖放到此驱动器上。
5. Pico 将重新启动并显示为“Weeb Labs DSPi”音频设备。
. 下载并启动 DSPi Console 应用程序来控制 DSPi。
### 接线指南
**RP2350 (Pico 2) — 最多 8 个输出引脚：**
| 功能 | 引脚 | 连接 |
| :--- | :--- | :--- |
| **输出插槽 0** (Out 1-2) | `GPIO 6` (默认) | 主 L/R 或多声道对 1 的 S/PDIF 或 I2S 数据 |
| **输出插槽 1** (Out 3-4) | `GPIO 7` (默认) | 多声道对 2 的 S/PDIF 或 I2S 数据 |
| **输出插槽 2** (Out 5-6) | `GPIO 8` (默认) | 多声道对 3 的 S/PDIF 或 I2S 数据 |
| **输出插槽 3** (Out 7-8) | `GPIO 9` (默认) | 多声道对 4 的 S/PDIF 或 I2S 数据 |
| **超低音输出** (PDM, Out 9) | `GPIO 10` (默认) | 有源超低音或 PDM 转模拟滤波器 |
| **I2S BCK** (共享, 仅 I2S) | `GPIO 14` (默认) | 配置为 I2S 的任何插槽的位时钟 |
| **I2S LRCLK** (仅 I2S) | `GPIO 15` (BCK + 1, 固定) | 字/帧时钟；始终为 BCK + 1 |
| **I2S MCK** (可选) | `GPIO 13` (默认) | 启用 MCK 时的 128× 或 256× Fs 主时钟 |
| **USB** | `Micro-USB` | 主机设备 (PC/Mac/移动设备) |
**RP2040 (Pico) — 最多 6 个输出引脚：**
| 功能 | 引脚 | 连接 |
| :--- | :--- | :--- |
| **输出插槽 0** (Out 1-2) | `GPIO 6` (默认) | 主 L/R 或立体声对 1 的 S/PDIF 或 I2S 数据 |
| **输出插槽 1** (Out 3-4) | `GPIO 7` (默认) | 立体声对 2 的 S/PDIF 或 I2S 数据 |
| **超低音输出** (PDM, Out 5) | `GPIO 10` (默认) | 有源超低音或 PDM 转模拟滤波器 |
| **I2S BCK** (共享, 仅 I2S) | `GPIO 14` (默认) | 配置为 I2S 的任何插槽的位时钟 |
| **I2S LRCLK** (仅 I2S) | `GPIO 15` (BCK + 1, 固定) | 字/帧时钟；始终为 BCK + 1 |
| **I2S MCK** (可选) | `GPIO 13` (默认) | 启用 MCK 时的 128× 或 256× Fs 主时钟 |
| **USB** | `Micro-USB` | 主机设备 (PC/Mac/移动设备) |
### 自定义引脚分配
上面的所有默认引脚分配都可以开箱即用，但是每个输出引脚——包括 I2S BCK 和 MCK——都可以在运行时通过 DSPi Console 应用程序重新分配。无需重新刷写。这在设计自定义 PCB 或适应默认 GPIO 不方便的开发板时非常有用。
引脚分配保存到闪存中，并在启动时自动恢复。有一些 GPIO 被保留，不可用于输出：GPIO 12 (UART TX) 和 GPIO 23-25 (电源控制和 LED)。由于 PIO 侧置约束，LRCLK 始终固定为 BCK + 1。
## DSP 功能
### 矩阵混音器
矩阵混音器将 USB 立体声输入路由到所有输出通道。RP2350 有一个 2x9 矩阵（9 个输出），RP2040 有一个 2x5 矩阵（5 个输出）。每个交叉点（输入/输出对）具有：
* **启用/禁用：** 路由活动或非活动。
* **增益：** 每个交叉点 -inf 至 +12 dB。
* **反相：** 用于驱动器对齐的极性翻转。
每个输出通道还具有：
* **启用：** 禁用的输出跳过所有处理（EQ、延迟、转换）以节省 CPU。
* **增益：** 每输出增益（-inf 至 +12 dB）。
* **静音：** 每输出的软静音。
* **延迟：** 每输出的时间对齐。
**输出可用性：** Core 1 在 PDM 超低音调制器与处理较高端编号的 S/PDIF 输出的 EQ worker 之间共享。PDM 和 EQ worker 模式是互斥的：
**RP2350：**
| 模式 | 可用输出 | Core 1 使用情况 |
|------|-------------------|--------------|
| **PDM 启用** (Out 9 开启) | Out 1-2 (S/PDIF 1) + Out 9 (PDM) | Delta-sigma 调制器 |
| **PDM 禁用** (Out 9 关闭) | Out 1-8 (S/PDIF 1-4) | Out 3-8 的 EQ worker |
**RP2040：**
| 模式 | 可用输出 | Core 1 使用情况 |
|------|-------------------|--------------|
| **PDM 启用** (Out 5 开启) | Out 1-2 (S/PDIF 1) + Out 5 (PDM) | Delta-sigma 调制器 |
| **PDM 禁用** (Out 5 关闭) | Out 1-4 (S/PDIF 1-2) | Out 3-4 的 EQ worker |
当 PDM 超低音处于活动状态时，Core 1 完全专用于 Delta-Sigma 调制器，因此较高端编号的 S/PDIF 输出不可用。当 PDM 关闭时，Core 1 作为 EQ worker 与 Core 0 并行处理这些输出。
**常见配置 (RP2350)：**
| 用例 | 路由 | 模式 |
|----------|---------|------|
| 立体声 + 超低音 | L→Out1, R→Out2, L+R→Out9 | PDM 开启 (3 个输出) |
| 2 分频有源 | L→Out1(高音), L→Out3(低音), R→Out2(高音), R→Out4(低音) | PDM 关闭 (4 个输出) |
| 3 分频有源 | 同上，加上中音在 Out5-6 | PDM 关闭 (6 个输出) |
| 4 分频有源 | 同上，加上超高音在 Out7-8 | PDM 关闭 (8 个输出) |
**常见配置 (RP2040)：**
| 用例 | 路由 | 模式 |
|----------|---------|------|
| 立体声 | L→Out1, R→Out2 | PDM 关闭 (2 个输出) |
| 立体声 + 超低音 | L→Out1, R→Out2, L+R→Out5 | PDM 开启 (3 个输出) |
| 2 分频有源 | L→Out1(高音), L→Out3(低音), R→Out2(高音), R→Out4(低音) | PDM 关闭 (4 个输出) |
### 参数均衡
每个滤波器频段支持 6 种类型：
| 类型 | 描述 |
|------|-------------|
| Flat | 直通（不处理） |
| Peaking | 参数钟形滤波器 |
| Low Shelf | 低频搁架滤波器 |
| High Shelf | 高频搁架滤波器 |
| Low Pass | 低通滤波器 |
| High Pass | 高通滤波器 |
在 RP2040 上，所有滤波器都使用 biquad IIR（转置直接 II 型）和 Q28 定点算术。在 RP2350 上，固件使用混合 SVF/biquad 架构：低于 Fs/7.5（在 48 kHz 时约为 6.4 kHz）的滤波器使用 Cytomic SVF（线性梯形）拓扑结构，以便在低频下获得卓越的数值精度，而较高频率则使用传统的 TDF2 biquad。所有滤波器都具有可配置的频率、Q 值和增益。Flat 滤波器自动旁路，CPU 开销为零。
**通道布局：**
**RP2350（11 个通道）：**
| 通道 | 索引 | EQ 频段 |
|---------|-------|----------|
| Master Left | 0 | 10 |
| Master Right | 1 | 10 |
| Output 1-8 (S/PDIF) | 2-9 | 每个 10 个 |
| Output 9 (PDM Sub) | 10 | 10 |
**RP2040（7 个通道）：**
| 通道 | 索引 | EQ 频段 |
|---------|-------|----------|
| Master Left | 0 | 10 |
| Master Right | 1 | 10 |
| Output 1-4 (S/PDIF) | 2-5 | 每个 10 个 |
| Output 5 (PDM Sub) | 6 | 10 |
### 响度补偿
基于 ISO 226:2003 等响度轮廓标准。在低收听音量下，人耳对低频和高频的敏感度较低。响度补偿应用一个随音量变化的 EQ 曲线，以在所有收听电平下保持感知的音调平衡。
* **参考 SPL：** 可配置（40-100 dB）。将此设置为您的系统在满音量下听起来音调平衡时的 SPL。
* **强度：** 可在标准 ISO 曲线的 0-200% 之间调节。
* **实现：** 为所有 91 个音量步进预计算系数表，双缓冲以实现无故障更新。
### 耳机交叉馈入
实现了 Bauer Stereophonic-to-Binaural (BS2B) 交叉馈入，采用互补滤波器设计，减少了耳机收听时不自然的立体声分离度。每个通道接收来自相反通道的低通滤波、时间延迟的混合，模拟使用扬声器收听时发生的声学交叉馈入。
* **互补设计：** 直达路径 = 输入 - 低通(输入)。保证单声道信号以单位增益通过，且不产生音染。
* **双耳时间延迟 (ITD)：** 一阶全通滤波器向交叉馈入路径增加约 220us 的延迟，模拟声音绕过头部到达的情况，适用于 60 度的立体声扬声器放置。ITD 可以独立启用/禁用。
* **预设：**
| 预设 | 截止频率 | 馈送电平 | 特征 |
|--------|--------|------------|-----------|
| Default | 700 Hz | 4.5 dB | 平衡，最受欢迎 |
| Chu Moy | 700 Hz | 6.0 dB | 更强的空间效果 |
| Jan Meier | 650 Hz | 9.5 dB | 微妙，自然 |
| Custom | 500-2000 Hz | 0-15 dB | 用户自定义 |
### 音量均衡器
一种前馈、立体声联动、单频段 RMS 动态范围压缩器，可在响度不同的内容之间保持一致的感知音量。
* **向上压缩：** 提升低于阈值的内容，而高于阈值的内容完全不受影响。不需要补充增益。
* **基于 RMS 的检测：** 跟踪均方根包络，与峰值检测相比，它与感知响度的相关性更好。
* **软拐点：** 在完全提升和单位增益之间平稳过渡，实现透明、无伪影的效果。
* **立体声联动：** 两个通道中较响的一个决定两者的增益，从而保留了立体声声像。
* **增益衰减安全限幅器：** 通过增益衰减（瞬时启动，100 ms 释放）而不是硬削波来强制执行 -6 dBFS 上限。由于响亮的内容以单位增益通过，因此很少触发。
* **可选的 10 ms 前视** 用于更平滑的过渡。
* **可配置：** 速度（启动/释放）、最大增益上限（限制安静内容可以被提升的程度）和门限阈值（低于此阈值时均衡器停止提升，以避免放大静音/噪声）。
该均衡器位于 PASS 2.5——在主 EQ 之后、交叉馈入之前。独立于响度补偿；两者可以同时启用而不会发生冲突。
### 每通道前置放大器
每个 USB 输入通道（左右）都有一个以 dB 为单位的前置放大器增益，在任何其他处理之前的 PASS 1 处应用。适用于修整通道不平衡、在 EQ 前衰减过热的输入或匹配不同源的电平。出于向后兼容性，保留了旧版单值命令（将两个通道设置为相同的值）。
### 主音量
在信号链最末端应用的设备端输出上限，独立于 USB 主机音量。
* **范围：** -128 至 0 dB。-128 是真正静音（静音）的哨兵值。
* **独立于 USB 主机音量：** 两者相乘。主机滑块在主音量允许的任何范围内运行。
* **独立于 DSP 处理：** 响度补偿、EQ、均衡器和交叉馈入均由原始 USB 音量驱动，而不是主音量——无论主音量如何设置，它们的行为都不会改变。
* **两种持久化模式**（可在运行时选择，重启后保留）：
* **模式 0 — 独立（默认）。** 主音量是一个独立的设备设置。应用程序调用保存命令将当前值捕获到目录中；该值在随后的每次启动时应用。预设保存/加载不会触及主音量——切换预设绝不会改变音量。
* **模式 1 — 随预设。** 主音量是每个预设的一部分。与预设一起保存，在预设加载时恢复，与任何其他 DSP 参数一样。当不同的预设针对具有不同灵敏度/最大输出要求的扬声器设置时非常有用。
* **首次启动时的默认值：** -20 dB（可通过固件中的 `MASTER_VOL_DEFAULT_DB` 配置）。
### I2S 输出
每个输出插槽可以在运行时在 S/PDIF（默认）和 I2S 之间切换，每个插槽独立。单个设备可以驱动混合信号——例如，插槽 0 作为 I2S 输入到 DAC 芯片，插槽 1 作为 S/PDIF 通过 Toslink 输出到外部接收器，所有这些都来自同一个音频管道。
* **I2S 格式：** 24 位数据，左对齐，MSB 优先，32 位帧。可直接替代大多数标准 I2S DAC（PCM5102、ES9038Q2M 等）。
* **共享时钟：** 所有 I2S 插槽共享一个单独的 BCK/LRCLK 对。LRCLK 始终为 BCK + 1（PIO 侧置硬件限制）。
* **可选 MCK：** 启用时，在可配置的 GPIO 上生成 128× 或 256× Fs 主时钟。某些没有内部 PLL 的 DAC 需要此信号。在 96 kHz 时，由于 PIO 时钟分频器的限制，只能选择 128×。
* **采样对齐启动：** I2S 插槽可以同时启动，以便多个 DAC 保持相位锁定。
两种输出类型的 DSP 管道是相同的——只是最终的编码不同（S/PDIF 使用 BMC/NRZI，而 I2S 使用原始的左对齐 PCM）。
### 超低音 PDM 输出
超低音输出使用在 Core 1 上运行的高性能软件定义的 Delta-Sigma 调制器。
* **调制：** 二阶 Delta-Sigma
* **过采样率：** 256x（在 48 kHz 时为 12.288 MHz 位时钟）
* **抖动：** TPDF（三角概率密度函数），带噪声整形
* **直流保护：** 泄漏积分器设计，防止直流偏移累积
其目的是尽可能多地利用 Core 1 产生一个可用于全频段且听起来完美的输出，即使它仅用于馈送超低音扬声器。此实现非常稳定，没有爆音、咔嗒声或空闲音调。
## 用户预设
DSPi 包含一个 10 插槽预设系统，可将完整的 DSP 配置存储在闪存中。预设始终处于活动状态——不存在“无预设”状态。
* **10 个预设插槽：** 每个插槽存储完整的 DSP 状态：每通道前置放大器、EQ 频段、延迟、响度、均衡器、交叉馈入、矩阵混音器、输出增益/静音、输出类型（S/PDIF 或 I2S）、I2S 时钟配置、引脚分配、主音量（在模式 1 中使用）和每通道名称。
* **每通道名称：** 每个通道都可以被赋予一个用户定义的名称（最多 31 个字符），并与预设一起存储。
* **启动配置：** 选择启动时加载的预设——可以是特定的默认插槽或上次活动的插槽。
* **引脚配置包含：** 在保存/加载预设时，可选择包含或排除 GPIO 引脚分配（默认：包含——引脚布局随预设一起移动）。
* **主音量模式：** 选择主音量是每个预设的一部分（模式 1）还是独立存储在预设目录中（模式 0，默认）。参见 [主音量](#master-volume)。
* **预设切换静音：** 在预设过渡期间，音频输出会被短暂静音（约 10 ms），以防止听得见的故障。
* **旧版命令：** 原始的保存/加载/重置命令（0x51-0x53）通过预设系统重定向，对当前活动的插槽进行操作。
* **批量参数传输：** 完整的 DSP 状态可以在单个 USB 控制传输（约 2.9 KB）中读取或写入，以便与主机应用程序快速同步。
* **自动迁移：** 较旧的预设目录在新固件首次启动时会透明地升级——插槽名称、启动配置和其他持久化状态都会被保留。
## 开发者参考
### 系统架构
* **Core 0：** USB 通信、音频流、DSP 处理（主 EQ、交叉馈入、响度、矩阵混音、S/PDIF 对 1 的输出 EQ）和控制逻辑。
* **Core 1（三种模式）：**
* **PDM 模式：** 用于超低音输出的 Delta-Sigma 调制器（当 PDM 输出启用时）。
* **EQ Worker 模式：** 与 Core 0 并行处理较高端编号输出的输出 EQ、延迟和 S/PDIF 转换。在 RP2350 上：输出 3-8。在 RP2040 上：输出 3-4。当这些输出中的任何一个被启用且 PDM 被禁用时激活。
* **空闲模式：** 当没有需要 Core 1 的输出被启用时。
* **PIO & DMA：** S/PDIF 编码（PIO0）和 PDM 比特流生成（PIO1）的硬件卸载确保了 I/O 的零 CPU 开销。
* **数学引擎：**
* **RP2040：** 32 位定点 (Q28) 处理，内部 DSP 循环使用手动优化的 ARM 汇编。
* **RP2350：** 具有硬件 FPU 的单精度浮点管道。混合 SVF/biquad EQ——低频（低于 Fs/7.5）使用 Cytomic SVF，高频使用 TDF2 biquad。在 biquad 系数量化出现问题的低频滤波器中，SVF 提供了卓越的数值精度。
### 性能调优
两个平台都以固定的 307.2 MHz 系统时钟（VCO 1536 MHz / 5 / 1）运行，因此 PIO 分频器在每个支持的采样率下保持整数，从而消除了依赖采样率的时钟切换故障。
| 平台 | 系统时钟 | 核心电压 |
|----------|--------------|--------------|
| **RP2040** | 307.2 MHz (超频) | 1.15 V |
| **RP2350** | 307.2 MHz | 1.15 V |
RP2040 在略高于 1.10 V 标称电压的微小提升下达到 307.2 MHz；RP2350 在相同电压下达到此时钟频率非常轻松。电压阶跃在频率更改之前应用。采样率更改不会重新调整系统时钟，只会重新调整 PIO 分频器，因此 44.1 / 48 / 96 kHz 之间的转换是无缝的。
闪存访问也进行了调整：`PICO_FLASH_SPI_CLKDIV` 设置为 6，以使 XIP 和擦除/编程操作在此时钟下安全地低于 W25Q080 的 104–133 MHz 规格。在 RP2350 上，运行时 QMI 寄存器管理由 `firmware/DSPi/flash_clkdiv.c` 处理，因为引导 ROM 在该平台上不遵循 boot2 设置。
### USB 控制协议
配置是通过 **Interface 2**（供应商接口）使用 Windows 下的控制传输，以及通过 macOS 下的 **Interface 0** 进行的。该设备支持 WinUSB/WCID，可在 Windows 上自动免驱安装。
**请求表**
| 代码 | 名称 | 方向 | 负载 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| `0x42` | `REQ_SET_EQ_PARAM` | OUT | 16 字节 | 上传滤波器参数 |
| `0x43` | `REQ_GET_EQ_PARAM` | IN | 16 字节 | 读取滤波器参数 |
| `0x44` | `REQ_SET_PREAMP` | OUT | 4 字节 | 设置全局增益 (float dB) |
| `0x45` | `REQ_GET_PREAMP` | IN | 4 字节 | 获取全局增益 |
| `0x46` | `REQ_SET_BYPASS` | OUT | 1 字节 | 旁路主 EQ (1=开, 0=关) |
| `0x47` | `REQ_GET_BYPASS` | IN | 1 字节 | 获取旁路状态 |
| `0x48` | `REQ_SET_DELAY` | OUT | 4 字节 | 设置通道延迟 (float ms) |
| `0x49` | `REQ_GET_DELAY` | IN | 4 字节 | 获取通道延迟 |
| `0x50` | `REQ_GET_STATUS` | IN | 4-12 字节 | 获取系统统计信息 (wValue 选择字段) |
| `0x51` | `REQ_SAVE_PARAMS` | IN | 1 字节 | 保存到活动预设插槽 |
| `0x52` | `REQ_LOAD_PARAMS` | IN | 1 字节 | 重新加载活动预设插槽 |
| `0x53` | `REQ_FACTORY_RESET` | IN | 1 字节 | 将实时状态重置为默认值 |
| `0x54` | `REQ_SET_CHANNEL_GAIN` | OUT | 4 字节 | 设置输出通道增益 (float dB) |
| `0x55` | `REQ_GET_CHANNEL_GAIN` | IN | 4 字节 | 获取输出通道增益 |
| `0x56` | `REQ_SET_CHANNEL_MUTE` | OUT | 1 字节 | 静音输出通道 (1=静音) |
| `0x57` | `REQ_GET_CHANNEL_MUTE` | IN | 1 字节 | 获取静音状态 |
| `0x58` | `REQ_SET_LOUDNESS` | OUT | 1 字节 | 启用/禁用响度 (1=开) |
| `0x59` | `REQ_GET_LOUDNESS` | IN | 1 字节 | 获取响度状态 |
| `0x5A` | `REQ_SET_LOUDNESS_REF` | OUT | 4 字节 | 设置参考 SPL (float, 40-100) |
| `0x5B` | `REQ_GET_LOUDNESS_REF` | IN | 4 字节 | 获取参考 SPL |
| `0x5C` | `REQ_SET_LOUDNESS_INTENSITY` | OUT | 4 字节 | 设置强度 % (float, 0-200) |
| `0x5D` | `REQ_GET_LOUDNESS_INTENSITY` | IN | 4 字节 | 获取强度 |
| `0x5E` | `REQ_SET_CROSSFEED` | OUT | 1 字节 | 启用/禁用交叉馈入 (1=开) |
| `0x5F` | `REQ_GET_CROSSFEED` | IN | 1 字节 | 获取交叉馈入状态 |
| `0x60` | `REQ_SET_CROSSFEED_PRESET` | OUT | 1 字节 | 设置预设 (0-3) |
| `0x61` | `REQ_GET_CROSSFEED_PRESET` | IN | 1 字节 | 获取当前预设 |
| `0x62` | `REQ_SET_CROSSFEED_FREQ` | OUT | 4 字节 | 设置自定义频率 (float Hz, 500-2000) |
| `0x63` | `REQ_GET_CROSSFEED_FREQ` | IN | 4 字节 | 获取自定义频率 |
| `0x64` | `REQ_SET_CROSSFEED_FEED` | OUT | 4 字节 | 设置自定义馈送电平 (float dB, 0-15) |
| `0x65` | `REQ_GET_CROSSFEED_FEED` | IN | 4节 | 获取自定义馈送电平 |
| `0x66` | `REQ_SET_CROSSFEED_ITD` | OUT | 1 字节 | 启用/禁用 ITD (1=开) |
| `0x67` | `REQ_GET_CROSSFEED_ITD` | IN | 1 字节 | 获取 ITD 状态 |
| `0x70` | `REQ_SET_MATRIX_ROUTE` | OUT | 8 字节 | 设置矩阵交叉点 |
| `0x71` | `REQ_GET_MATRIX_ROUTE` | IN | 8 字节 | 获取矩阵交叉点 |
| `0x72` | `REQ_SET_OUTPUT_ENABLE` | OUT | 1 字节 | 启用/禁用输出通道 |
| `0x73` | `REQ_GET_OUTPUT_ENABLE` | IN | 1 字节 | 获取输出启用状态 |
| `0x74` | `REQ_SET_OUTPUT_GAIN` | OUT | 4 字节 | 设置每输出增益 (float dB) |
| `0x75` | `REQ_GET_OUTPUT_GAIN` | IN | 4 字节 | 获取每输出增益 |
| `0x76` | `REQ_SET_OUTPUT_MUTE` | OUT | 1 字节 | 静音输出 (1=静音) |
| `0x77` | `REQ_GET_OUTPUT_MUTE` | IN | 1 字节 | 获取输出静音状态 |
| `0x78` | `REQ_SET_OUTPUT_DELAY` | OUT | 4 字节 | 设置每输出延迟 (float ms) |
| `0x79` | `REQ_GET_OUTPUT_DELAY` | IN | 4 字节 | 获取每输出延迟 |
| `0x7A` | `REQ_GET_CORE1_MODE` | IN | 1 字节 | 获取 Core 1 模式 (0=空闲, 1=PDM, 2=EQ Worker) |
| `0x7B` | `REQ_GET_CORE1_CONFLICT` | IN | 1 字节 | 检查是否存在 PDM 与 EQ Worker 冲突 |
| `0x7C` | `REQ_SET_OUTPUT_PIN` | IN | 1 字节 | 更改输出 GPIO 引脚（返回状态） |
| `0x7D` | `REQ_GET_OUTPUT_PIN` | IN | 1 字节 | 获取输出的当前 GPIO 引脚 |
| `0x7E` | `REQ_GET_SERIAL` | IN | 可变 | 获取唯一的板子序列号 |
| `0x7F` | `REQ_GET_PLATFORM` | IN | 1 字节 | 获取平台 ID (0=RP2040, 1=RP2350) |
| `0x83` | `REQ_CLEAR_CLIPS` | OUT | — | 清除削波检测锁存器 |
| `0x90` | `REQ_PRESET_SAVE` | IN | 1 字节 | 将实时状态保存到预设插槽 (wValue=slot) |
| `0x91` | `REQ_PRESET_LOAD` | IN | 1 字节 | 将预设插槽加载到实时状态 (wValue=slot) |
| `0x92` | `REQ_PRESET_DELETE` | IN | 1 字节 | 删除预设插槽 (wValue=slot) |
| `0x93` | `REQ_PRESET_GET_NAME` | IN | 32 字节 | 获取预设名称 (wValue=slot) |
| `0x94` | `REQ_PRESET_SET_NAME` | OUT | 32 字节 | 设置预设名称 (wValue=slot) |
| `0x95` | `REQ_PRESET_GET_DIR` | IN | 可变 | 获取预设目录（占用情况、启动配置） |
| `0x96` | `REQ_PRESET_SET_STARTUP` | OUT | 2 字节 | 设置启动模式和默认插槽 |
| `0x97` | `REQ_PRESET_GET_STARTUP` | IN | 2 字节 | 获取启动配置 |
| `0x98` | `REQ_PRESET_SET_INCLUDE_PINS` | OUT | 1 字节 | 设置引脚配置包含 (1=包含) |
| `0x99` | `REQ_PRESET_GET_INCLUDE_PINS` | IN | 1 字节 | 获取引脚配置包含设置 |
| `0x9A` | `REQ_PRESET_GET_ACTIVE` | IN | 1 字节 | 获取当前活动的预设插槽索引 |
| `0x9B` | `REQ_SET_CHANNEL_NAME` | OUT | 32 字节 | 设置通道名称 (wValue=channel) |
| `0x9C` | `REQ_GET_CHANNEL_NAME` | IN | 32 字节 | 获取通道名称 (wValue=channel) |
| `0xA0` | `REQ_GET_ALL_PARAMS` | IN | 约 2896 字节 | 批量读取整个 DSP 状态（多包） |
| `0xA1` | `REQ_SET_ALL_PARAMS` | OUT | 约 2896 字节 | 批量写入整个 DSP 状态（多包） |
| `0xB0` | `REQ_GET_BUFFER_STATS` | IN | 可变 | 读取缓冲区填充统计信息 |
| `0xB1` | `REQ_RESET_BUFFER_STATS` | IN | 1 字节 | 重置缓冲区统计计数器 |
| `0xB2` | `REQ_GET_USB_ERROR_STATS` | IN | 24 字节 | 读取 USB PHY 错误计数器（CRC/位填充/超时/溢出/序列） |
| `0xB3` | `REQ_RESET_USB_ERROR_STATS` | IN | 1 字节 | 重置 USB PHY 错误计数器 |
| `0xB4` | `REQ_SET_LEVELLER_ENABLE` | OUT | 1 字节 | 启用/禁用音量均衡器 |
| `0xB5` | `REQ_GET_LEVELLER_ENABLE` | IN | 1 字节 | 获取均衡器启用状态 |
| `0xB6` | `REQ_SET_LEVELLER_AMOUNT` | OUT | 4 字节 | 设置均衡器目标/数量 |
| `0xB7` | `REQ_GET_LEVELLER_AMOUNT` | IN | 4 字节 | 获取均衡器数量 |
| `0xB8` | `REQ_SET_LEVELLER_SPEED` | OUT | 1 字节 | 设置均衡器启动/释放速度 |
| `0xB9` | `REQ_GET_LEVELLER_SPEED` | IN | 1 字节 | 获取均衡器速度 |
| `0xBA` | `REQ_SET_LEVELLER_MAX_GAIN` | OUT | 4 字节 | 设置最大向上增益 |
| `0xBB` | `REQ_GET_LEVELLER_MAX_GAIN` | IN | 4 字节 | 获取最大向上增益 |
| `0xBC` | `REQ_SET_LEVELLER_LOOKAHEAD` | OUT | 1 字节 | 启用/禁用 10 ms 前视 |
| `0xBD` | `REQ_GET_LEVELLER_LOOKAHEAD` | IN | 1 字节 | 获取前视状态 |
| `0xBE` | `REQ_SET_LEVELLER_GATE` | OUT | 4 字节 | 设置噪声门阈值 |
| `0xBF` | `REQ_GET_LEVELLER_GATE` | IN | 4 字节 | 获取噪声门阈值 |
| `0xC0` | `REQ_SET_OUTPUT_TYPE` | OUT | 1 字节 | 设置插槽输出类型 (0=S/PDIF, 1=I2S; wValue=slot) |
| `0xC1` | `REQ_GET_OUTPUT_TYPE` | IN | 1 字节 | 获取插槽输出类型 (wValue=slot) |
| `0xC2` | `REQ_SET_I2S_BCK_PIN` | OUT | 1 字节 | 设置共享的 I2S BCK GPIO（LRCLK 自动 = BCK + 1） |
| `0xC3` | `REQ_GET_I2S_BCK_PIN` | IN | 1 字节 | 获取当前 I2S BCK 引脚 |
| `0xC4` | `REQ_SET_MCK_ENABLE` | OUT | 1 字节 | 启用/禁用 I2S 主时钟输出 |
| `0xC5` | `REQ_GET_MCK_ENABLE` | IN | 1 字节 | 获取 MCK 启用状态 |
| `0xC6` | `REQ_SET_MCK_PIN` | OUT | 1 字节 | 设置 MCK GPIO |
| `0xC7` | `REQ_GET_MCK_PIN` | IN | 1 字节 | 获取 MCK GPIO |
| `0xC8` | `REQ_SET_MCK_MULTIPLIER` | OUT | 1 字节 | 设置 MCK 倍频 (0=128×, 1=256×) |
| `0xC9` | `REQ_GET_MCK_MULTIPLIER` | IN | 1 字节 | 获取 MCK 倍频 |
| `0xD0` | `REQ_SET_PREAMP_CH` | OUT | 4 字节 | 设置每通道前置放大器 (wValue=channel, payload=float dB) |
| `0xD1` | `REQ_GET_PREAMP_CH` | IN | 4 字节 | 获取每通道前置放大器 (wValue=channel) |
| `0xD2` | `REQ_SET_MASTER_VOLUME` | OUT | 4 字节 | 设置主音量（-128 静音哨兵值，-127..0 dB） |
| `0xD3` | `REQ_GET_MASTER_VOLUME` | IN | 4 字节 | 获取当前实时主音量 |
| `0xD4` | `REQ_SET_MASTER_VOLUME_MODE` | OUT | 1 字节 | 设置持久化模式 (0=独立, 1=随预设) |
| `0xD5` | `REQ_GET_MASTER_VOLUME_MODE` | IN | 1 字节 | 获取持久化模式 |
| `0xD6` | `REQ_SAVE_MASTER_VOLUME` | IN | 1 字节 | 将实时主音量保存到目录（模式 0 持久化） |
| `0xD7` | `REQ_GET_SAVED_MASTER_VOLUME` | IN | 4 字节 | 读取目录中已保存的主音量值 |
| `0xF0` | `REQ_ENTER_BOOTLOADER` | IN | 1 字节 | 重启进入 UF2 引导加载程序以进行固件更新 |
### REQ_GET_STATUS (0x50) - 系统遥测
`REQ_GET_STATUS` 请求根据 `wValue` 字段返回数据：
| wValue | 返回 | 描述 |
| :--- | :--- | :--- |
| `0` | uint32 | 通道 0-1 的峰值（打包的 16 位值） |
| `1` | uint32 | 通道 2-3 的峰值（打包的 16 位值） |
| `2` | uint32 | 通道 4 的峰值 + CPU0/CPU1 负载（打包） |
| `3` | uint32 | PDM 环形缓冲区溢出 |
| `4` | uint32 | PDM 环形缓冲区欠载 |
| `5` | uint32 | PDM DMA 溢出 |
| `6` | uint32 | PDM DMA 欠载 |
| `7` | uint32 | S/PDIF 溢出 |
| `8` | uint32 | S/PDIF 欠载 |
| `9` | 12 字节 | 组合：所有 5 个峰值 + CPU 负载 |
| `10` | uint32 | USB 音频包计数 |
| `11` | uint32 | USB 替代设置 |
| `12` | uint32 | USB 音频挂载状态 |
| `13` | uint32 | 系统时钟频率 |
| `14` | uint32 | 核心电压（毫伏） |
| `15` | uint32 | 采样率 |
| `16` | int32 | 系统温度（摄氏度百分之一度） |
| `17` | uint32 | S/PDIF DMA 总饥饿数（所有插槽合计） |
| `18` | uint32 | S/PDIF 插槽 0 饥饿数 (Out 1-2) |
| `19` | uint32 | S/PDIF 插槽 1 饥饿数 (Out 3-4) |
| `20` | uint32 | S/PDIF 插槽 2 饥饿数 (Out 5-6, RP2350) |
| `21` | uint32 | S/PDIF 插槽 3 饥饿数 (Out 7-8, RP2350) |
饥饿事件意味着 S/PDIF DMA 需要缓冲区，但消费者池为空，因此固件为该传输替换了静音缓冲区。这是比较旧的 `spdif_underruns` USB 包间隙启发式算法更直接的输出端丢失信号。
### 数据结构
**滤波器数据包（16 字节）：**
```
struct __attribute__((packed)) {
uint8_t channel; // RP2350: 0-10, RP2040: 0-6
uint8_t band; // 0-9
uint8_t type; // 0=Flat, 1=Peak, 2=LS, 3=HS, 4=LP, 5=HP
uint8_t reserved;
float freq; // Hz
float Q;
float gain_db;
}
```
**矩阵路由数据包（8 字节）：**
```
struct __attribute__((packed)) {
uint8_t input; // 0-1 (USB L/R)
uint8_t output; // RP2350: 0-8, RP2040: 0-4
uint8_t enabled; // 0 or 1
uint8_t phase_invert; // 0 or 1
float gain_db; // -inf to +12dB
}
```
### 运行时引脚配置
输出 GPIO 引脚可以在运行时重新分配，而无需重新刷写。这在自定义 PCB 布局或默认引脚分配与其他硬件时非常有用。
**`REQ_SET_OUTPUT_PIN` (0x7C)** — IN 传输，返回 1 字节状态：
* `wValue` = `(new_pin << 8) | output_index`
* RP2350：`output_index` 0-3 对应 S/PDIF 输出 1-4，4 对应 PDM 超低音
* RP2040：`output_index` 0-1 对应 S/PDIF 输出 1-2，2 对应 PDM 超低音
* 在引脚更改期间，S/PDIF 输出会自动禁用并重新启用（仅在该输出上有约 1ms 的音频丢失）
* PDM 输出必须首先禁用（通过 `REQ_SET_OUTPUT_ENABLE` 禁用），否则返回 `PIN_CONFIG_OUTPUT_ACTIVE`
| 状态码 | 值 | 含义 |
|-------------|-------|---------|
| `PIN_CONFIG_SUCCESS` | 0x00 | 引脚成功更改 |
| `PIN_CONFIG_INVALID_PIN` | 0x01 | 引脚超出范围或被保留（GPIO 12、23-25） |
| `PIN_CONFIG_PIN_IN_USE` | 0x02 | 引脚已分配给另一个输出 |
| `PIN_CONFIG_INVALID_OUTPUT` | 0x03 | 输出索引超出范围 |
| `PIN_CONFIG_OUTPUT_ACTIVE` | 0x04 | PDM 输出在更改其引脚之前必须被禁用 |
**`REQ_GET_OUTPUT_PIN` (0x7D)** — IN 传输，返回 1 字节：
* `wValue` = output_index
* 返回该输出的当前 GPIO 引脚编号
引脚分配存储在每个预设中，并可以在预设保存/加载期间选择性地包含（通过 `REQ_PRESET_SET_INCLUDE_PINS` 控制）。
## 从源码构建
要自行构建固件，您需要一个标准的 Raspberry Pi Pico C/C++ 开发环境。
### 1. 安装前置条件
请确保您已安装以下工具：
* **CMake**（3.13 或更新版本）
* **Arm GNU Toolchain**（`arm-none-eabi-gcc` 等）
* **Python 3**（用于 Pico SDK 脚本）
* **Git**
### 2. 克隆代码库
递归克隆项目以包含 Pico SDK 和其他子模块：
```
git clone --recursive https://github.com/WeebLabs/DSPi.git
cd DSPi
```
*如果您已经克隆但没有加 `--recursive`，请运行：*
```
git submodule update --init --recursive
```
### 3. 构建固件
您可以为标准的 **RP2040** (Raspberry Pi Pico) 或较新的 **RP2350** (Raspberry Pi Pico 2) 进行构建。构建系统使用单独的目录以避免冲突。
**选项 A：为 RP2040 构建 (标准 Pico)**
```
mkdir build-rp2040
cd build-rp2040
cmake -DPICO_BOARD=pico -DPICO_EXTRAS_PATH=../firmware/pico-extras ../firmware
make
```
*输出：* `DSPi/DSPi.uf2`
**选项 B：为 RP2350 构建 (Pico 2)**
```
mkdir build-rp2350
cd build-rp2350
cmake -DPICO_BOARD=pico2 -DPICO_EXTRAS_PATH=../firmware/pico-extras ../firmware
make
```
*输出：* `DSPi/DSPi.uf2`
### 4. 刷写设备
1. 在插入开发板时按住 **BOOTSEL** 按钮。
2. 将生成的 `.uf2` 文件拖放到 `RPI-RP2`（或 `RP2350`）驱动器上。
或者，可以通过发送 `REQ_ENTER_BOOTLOADER` (0xF0) 将已运行的 DSPi 置于引导加载程序模式，而无需按下按钮。DSPi Console 应用程序即使用此功能进行一键固件更新。有关协议详细信息，请参见 [`Documentation/Features/firmware_update.md`](Documentation/Features/firmware_update.md)。
## 详细规格
每个子系统的深入规格保存在 [`Documentation/Features/`](Documentation/Features/) 下。这些是协议格式、接线布局、边缘情况和主机应用集成模式的权威来源。
| 功能 | 规格 |
|---------|------|
| 矩阵混音器 | [`matrixmixer_spec.md`](Documentation/Features/matrixmixer_spec.md) |
| 用户预设 | [`user_presets_spec.md`](Documentation/Features/user_presets_spec.md) |
| 主音量 | [`master_volume_spec.md`](Documentation/Features/master_volume_spec.md) |
| 每通道前置放大器 | [`per_channel_preamp_spec.md`](Documentation/Features/per_channel_preamp_spec.md) |
| 音量均衡器 | [`volume_leveller_spec.md`](Documentation/Features/volume_leveller_spec.md) |
| I2S 输出 | [`i2s_output_spec.md`](Documentation/Features/i2s_output_spec.md) |
| 峰值 / 削波测量 | [`peak_clip_metering_spec.md`](Documentation/Features/peak_clip_metering_spec.md) |
| 缓冲区统计 | [`buffer_statistics_spec.md`](Documentation/Features/buffer_statistics_spec.md) |
| S/PDIF DMA 饥饿 | [`spdif_starvation_spec.md`](Documentation/Features/spdif_starvation_spec.md) |
| USB 错误诊断 | [`usb_errors_spec.md`](Documentation/Features/usb_errors_spec.md) |
| Core 1 模式 | [`core1_modes_spec.md`](Documentation/Features/core1_modes_spec.md) |
| 设备识别 | [`device_identification_spec.md`](Documentation/Features/device_identification_spec.md) |
| S/PDIF 输入（计划中） | [`SPDIF_input_spec.md`](Documentation/Features/SPDIF_input_spec.md) |
| 通过 USB 进行固件更新 | [`Documentation/Features/firmware_update.md`](Documentation/Features/firmware_update.md) |
| 路线图 | [`roadmap.md`](Documentation/Features/roadmap.md) |
## 许可证
本项目基于 GNU General Public License v3.0 授权。有关详细信息，请参见 [LICENSE](LICENSE)。
## DSP 功能
### 矩阵混音器
矩阵混音器将 USB 立体声输入路由到所有输出通道。RP2350 有一个 2x9 矩阵（9 个输出），RP2040 有一个 2x5 矩阵（5 个输出）。每个交叉点（输入/输出对）具有：
* **启用/禁用：** 路由活动或非活动。
* **增益：** 每个交叉点 -inf 至 +12 dB。
* **反相：** 用于驱动器对齐的极性翻转。
每个输出通道还具有：
* **启用：** 禁用的输出跳过所有处理（EQ、延迟、转换）以节省 CPU。
* **增益：** 每输出增益（-inf 至 +12 dB）。
* **静音：** 每输出的软静音。
* **延迟：** 每输出的时间对齐。
**输出可用性：** Core 1 在 PDM 超低音调制器与处理较高端编号的 S/PDIF 输出的 EQ worker 之间共享。PDM 和 EQ worker 模式是互斥的：
**RP2350：**
| 模式 | 可用输出 | Core 1 使用情况 |
|------|-------------------|--------------|
| **PDM 启用** (Out 9 开启) | Out 1-2 (S/PDIF 1) + Out 9 (PDM) | Delta-sigma 调制器 |
| **PDM 禁用** (Out 9 关闭) | Out 1-8 (S/PDIF 1-4) | Out 3-8 的 EQ worker |
**RP2040：**
| 模式 | 可用输出 | Core 1 使用情况 |
|------|-------------------|--------------|
| **PDM 启用** (Out 5 开启) | Out 1-2 (S/PDIF 1) + Out 5 (PDM) | Delta-sigma 调制器 |
| **PDM 禁用** (Out 5 关闭) | Out 1-4 (S/PDIF 1-2) | Out 3-4 的 EQ worker |
当 PDM 超低音处于活动状态时，Core 1 完全专用于 Delta-Sigma 调制器，因此较高端编号的 S/PDIF 输出不可用。当 PDM 关闭时，Core 1 作为 EQ worker 与 Core 0 并行处理这些输出。
**常见配置 (RP2350)：**
| 用例 | 路由 | 模式 |
|----------|---------|------|
| 立体声 + 超低音 | L→Out1, R→Out2, L+R→Out9 | PDM 开启 (3 个输出) |
| 2 分频有源 | L→Out1(高音), L→Out3(低音), R→Out2(高音), R→Out4(低音) | PDM 关闭 (4 个输出) |
| 3 分频有源 | 同上，加上中音在 Out5-6 | PDM 关闭 (6 个输出) |
| 4 分频有源 | 同上，加上超高音在 Out7-8 | PDM 关闭 (8 个输出) |
**常见配置 (RP2040)：**
| 用例 | 路由 | 模式 |
|----------|---------|------|
| 立体声 | L→Out1, R→Out2 | PDM 关闭 (2 个输出) |
| 立体声 + 超低音 | L→Out1, R→Out2, L+R→Out5 | PDM 开启 (3 个输出) |
| 2 分频有源 | L→Out1(高音), L→Out3(低音), R→Out2(高音), R→Out4(低音) | PDM 关闭 (4 个输出) |
### 参数均衡
每个滤波器频段支持 6 种类型：
| 类型 | 描述 |
|------|-------------|
| Flat | 直通（不处理） |
| Peaking | 参数钟形滤波器 |
| Low Shelf | 低频搁架滤波器 |
| High Shelf | 高频搁架滤波器 |
| Low Pass | 低通滤波器 |
| High Pass | 高通滤波器 |
在 RP2040 上，所有滤波器都使用 biquad IIR（转置直接 II 型）和 Q28 定点算术。在 RP2350 上，固件使用混合 SVF/biquad 架构：低于 Fs/7.5（在 48 kHz 时约为 6.4 kHz）的滤波器使用 Cytomic SVF（线性梯形）拓扑结构，以便在低频下获得卓越的数值精度，而较高频率则使用传统的 TDF2 biquad。所有滤波器都具有可配置的频率、Q 值和增益。Flat 滤波器自动旁路，CPU 开销为零。
**通道布局：**
**RP2350（11 个通道）：**
| 通道 | 索引 | EQ 频段 |
|---------|-------|----------|
| Master Left | 0 | 10 |
| Master Right | 1 | 10 |
| Output 1-8 (S/PDIF) | 2-9 | 每个 10 个 |
| Output 9 (PDM Sub) | 10 | 10 |
**RP2040（7 个通道）：**
| 通道 | 索引 | EQ 频段 |
|---------|-------|----------|
| Master Left | 0 | 10 |
| Master Right | 1 | 10 |
| Output 1-4 (S/PDIF) | 2-5 | 每个 10 个 |
| Output 5 (PDM Sub) | 6 | 10 |
### 响度补偿
基于 ISO 226:2003 等响度轮廓标准。在低收听音量下，人耳对低频和高频的敏感度较低。响度补偿应用一个随音量变化的 EQ 曲线，以在所有收听电平下保持感知的音调平衡。
* **参考 SPL：** 可配置（40-100 dB）。将此设置为您的系统在满音量下听起来音调平衡时的 SPL。
* **强度：** 可在标准 ISO 曲线的 0-200% 之间调节。
* **实现：** 为所有 91 个音量步进预计算系数表，双缓冲以实现无故障更新。
### 耳机交叉馈入
实现了 Bauer Stereophonic-to-Binaural (BS2B) 交叉馈入，采用互补滤波器设计，减少了耳机收听时不自然的立体声分离度。每个通道接收来自相反通道的低通滤波、时间延迟的混合，模拟使用扬声器收听时发生的声学交叉馈入。
* **互补设计：** 直达路径 = 输入 - 低通(输入)。保证单声道信号以单位增益通过，且不产生音染。
* **双耳时间延迟 (ITD)：** 一阶全通滤波器向交叉馈入路径增加约 220us 的延迟，模拟声音绕过头部到达的情况，适用于 60 度的立体声扬声器放置。ITD 可以独立启用/禁用。
* **预设：**
| 预设 | 截止频率 | 馈送电平 | 特征 |
|--------|--------|------------|-----------|
| Default | 700 Hz | 4.5 dB | 平衡，最受欢迎 |
| Chu Moy | 700 Hz | 6.0 dB | 更强的空间效果 |
| Jan Meier | 650 Hz | 9.5 dB | 微妙，自然 |
| Custom | 500-2000 Hz | 0-15 dB | 用户自定义 |
### 音量均衡器
一种前馈、立体声联动、单频段 RMS 动态范围压缩器，可在响度不同的内容之间保持一致的感知音量。
* **向上压缩：** 提升低于阈值的内容，而高于阈值的内容完全不受影响。不需要补充增益。
* **基于 RMS 的检测：** 跟踪均方根包络，与峰值检测相比，它与感知响度的相关性更好。
* **软拐点：** 在完全提升和单位增益之间平稳过渡，实现透明、无伪影的效果。
* **立体声联动：** 两个通道中较响的一个决定两者的增益，从而保留了立体声声像。
* **增益衰减安全限幅器：** 通过增益衰减（瞬时启动，100 ms 释放）而不是硬削波来强制执行 -6 dBFS 上限。由于响亮的内容以单位增益通过，因此很少触发。
* **可选的 10 ms 前视** 用于更平滑的过渡。
* **可配置：** 速度（启动/释放）、最大增益上限（限制安静内容可以被提升的程度）和门限阈值（低于此阈值时均衡器停止提升，以避免放大静音/噪声）。
该均衡器位于 PASS 2.5——在主 EQ 之后、交叉馈入之前。独立于响度补偿；两者可以同时启用而不会发生冲突。
### 每通道前置放大器
每个 USB 输入通道（左右）都有一个以 dB 为单位的前置放大器增益，在任何其他处理之前的 PASS 1 处应用。适用于修整通道不平衡、在 EQ 前衰减过热的输入或匹配不同源的电平。出于向后兼容性，保留了旧版单值命令（将两个通道设置为相同的值）。
### 主音量
在信号链最末端应用的设备端输出上限，独立于 USB 主机音量。
* **范围：** -128 至 0 dB。-128 是真正静音（静音）的哨兵值。
* **独立于 USB 主机音量：** 两者相乘。主机滑块在主音量允许的任何范围内运行。
* **独立于 DSP 处理：** 响度补偿、EQ、均衡器和交叉馈入均由原始 USB 音量驱动，而不是主音量——无论主音量如何设置，它们的行为都不会改变。
* **两种持久化模式**（可在运行时选择，重启后保留）：
* **模式 0 — 独立（默认）。** 主音量是一个独立的设备设置。应用程序调用保存命令将当前值捕获到目录中；该值在随后的每次启动时应用。预设保存/加载不会触及主音量——切换预设绝不会改变音量。
* **模式 1 — 随预设。** 主音量是每个预设的一部分。与预设一起保存，在预设加载时恢复，与任何其他 DSP 参数一样。当不同的预设针对具有不同灵敏度/最大输出要求的扬声器设置时非常有用。
* **首次启动时的默认值：** -20 dB（可通过固件中的 `MASTER_VOL_DEFAULT_DB` 配置）。
### I2S 输出
每个输出插槽可以在运行时在 S/PDIF（默认）和 I2S 之间切换，每个插槽独立。单个设备可以驱动混合信号——例如，插槽 0 作为 I2S 输入到 DAC 芯片，插槽 1 作为 S/PDIF 通过 Toslink 输出到外部接收器，所有这些都来自同一个音频管道。
* **I2S 格式：** 24 位数据，左对齐，MSB 优先，32 位帧。可直接替代大多数标准 I2S DAC（PCM5102、ES9038Q2M 等）。
* **共享时钟：** 所有 I2S 插槽共享一个单独的 BCK/LRCLK 对。LRCLK 始终为 BCK + 1（PIO 侧置硬件限制）。
* **可选 MCK：** 启用时，在可配置的 GPIO 上生成 128× 或 256× Fs 主时钟。某些没有内部 PLL 的 DAC 需要此信号。在 96 kHz 时，由于 PIO 时钟分频器的限制，只能选择 128×。
* **采样对齐启动：** I2S 插槽可以同时启动，以便多个 DAC 保持相位锁定。
两种输出类型的 DSP 管道是相同的——只是最终的编码不同（S/PDIF 使用 BMC/NRZI，而 I2S 使用原始的左对齐 PCM）。
### 超低音 PDM 输出
超低音输出使用在 Core 1 上运行的高性能软件定义的 Delta-Sigma 调制器。
* **调制：** 二阶 Delta-Sigma
* **过采样率：** 256x（在 48 kHz 时为 12.288 MHz 位时钟）
* **抖动：** TPDF（三角概率密度函数），带噪声整形
* **直流保护：** 泄漏积分器设计，防止直流偏移累积
其目的是尽可能多地利用 Core 1 产生一个可用于全频段且听起来完美的输出，即使它仅用于馈送超低音扬声器。此实现非常稳定，没有爆音、咔嗒声或空闲音调。
## 用户预设
DSPi 包含一个 10 插槽预设系统，可将完整的 DSP 配置存储在闪存中。预设始终处于活动状态——不存在“无预设”状态。
* **10 个预设插槽：** 每个插槽存储完整的 DSP 状态：每通道前置放大器、EQ 频段、延迟、响度、均衡器、交叉馈入、矩阵混音器、输出增益/静音、输出类型（S/PDIF 或 I2S）、I2S 时钟配置、引脚分配、主音量（在模式 1 中使用）和每通道名称。
* **每通道名称：** 每个通道都可以被赋予一个用户定义的名称（最多 31 个字符），并与预设一起存储。
* **启动配置：** 选择启动时加载的预设——可以是特定的默认插槽或上次活动的插槽。
* **引脚配置包含：** 在保存/加载预设时，可选择包含或排除 GPIO 引脚分配（默认：包含——引脚布局随预设一起移动）。
* **主音量模式：** 选择主音量是每个预设的一部分（模式 1）还是独立存储在预设目录中（模式 0，默认）。参见 [主音量](#master-volume)。
* **预设切换静音：** 在预设过渡期间，音频输出会被短暂静音（约 10 ms），以防止听得见的故障。
* **旧版命令：** 原始的保存/加载/重置命令（0x51-0x53）通过预设系统重定向，对当前活动的插槽进行操作。
* **批量参数传输：** 完整的 DSP 状态可以在单个 USB 控制传输（约 2.9 KB）中读取或写入，以便与主机应用程序快速同步。
* **自动迁移：** 较旧的预设目录在新固件首次启动时会透明地升级——插槽名称、启动配置和其他持久化状态都会被保留。
## 开发者参考
### 系统架构
* **Core 0：** USB 通信、音频流、DSP 处理（主 EQ、交叉馈入、响度、矩阵混音、S/PDIF 对 1 的输出 EQ）和控制逻辑。
* **Core 1（三种模式）：**
* **PDM 模式：** 用于超低音输出的 Delta-Sigma 调制器（当 PDM 输出启用时）。
* **EQ Worker 模式：** 与 Core 0 并行处理较高端编号输出的输出 EQ、延迟和 S/PDIF 转换。在 RP2350 上：输出 3-8。在 RP2040 上：输出 3-4。当这些输出中的任何一个被启用且 PDM 被禁用时激活。
* **空闲模式：** 当没有需要 Core 1 的输出被启用时。
* **PIO & DMA：** S/PDIF 编码（PIO0）和 PDM 比特流生成（PIO1）的硬件卸载确保了 I/O 的零 CPU 开销。
* **数学引擎：**
* **RP2040：** 32 位定点 (Q28) 处理，内部 DSP 循环使用手动优化的 ARM 汇编。
* **RP2350：** 具有硬件 FPU 的单精度浮点管道。混合 SVF/biquad EQ——低频（低于 Fs/7.5）使用 Cytomic SVF，高频使用 TDF2 biquad。在 biquad 系数量化出现问题的低频滤波器中，SVF 提供了卓越的数值精度。
### 性能调优
两个平台都以固定的 307.2 MHz 系统时钟（VCO 1536 MHz / 5 / 1）运行，因此 PIO 分频器在每个支持的采样率下保持整数，从而消除了依赖采样率的时钟切换故障。
| 平台 | 系统时钟 | 核心电压 |
|----------|--------------|--------------|
| **RP2040** | 307.2 MHz (超频) | 1.15 V |
| **RP2350** | 307.2 MHz | 1.15 V |
RP2040 在略高于 1.10 V 标称电压的微小提升下达到 307.2 MHz；RP2350 在相同电压下达到此时钟频率非常轻松。电压阶跃在频率更改之前应用。采样率更改不会重新调整系统时钟，只会重新调整 PIO 分频器，因此 44.1 / 48 / 96 kHz 之间的转换是无缝的。
闪存访问也进行了调整：`PICO_FLASH_SPI_CLKDIV` 设置为 6，以使 XIP 和擦除/编程操作在此时钟下安全地低于 W25Q080 的 104–133 MHz 规格。在 RP2350 上，运行时 QMI 寄存器管理由 `firmware/DSPi/flash_clkdiv.c` 处理，因为引导 ROM 在该平台上不遵循 boot2 设置。
### USB 控制协议
配置是通过 **Interface 2**（供应商接口）使用 Windows 下的控制传输，以及通过 macOS 下的 **Interface 0** 进行的。该设备支持 WinUSB/WCID，可在 Windows 上自动免驱安装。
**请求表**
| 代码 | 名称 | 方向 | 负载 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| `0x42` | `REQ_SET_EQ_PARAM` | OUT | 16 字节 | 上传滤波器参数 |
| `0x43` | `REQ_GET_EQ_PARAM` | IN | 16 字节 | 读取滤波器参数 |
| `0x44` | `REQ_SET_PREAMP` | OUT | 4 字节 | 设置全局增益 (float dB) |
| `0x45` | `REQ_GET_PREAMP` | IN | 4 字节 | 获取全局增益 |
| `0x46` | `REQ_SET_BYPASS` | OUT | 1 字节 | 旁路主 EQ (1=开, 0=关) |
| `0x47` | `REQ_GET_BYPASS` | IN | 1 字节 | 获取旁路状态 |
| `0x48` | `REQ_SET_DELAY` | OUT | 4 字节 | 设置通道延迟 (float ms) |
| `0x49` | `REQ_GET_DELAY` | IN | 4 字节 | 获取通道延迟 |
| `0x50` | `REQ_GET_STATUS` | IN | 4-12 字节 | 获取系统统计信息 (wValue 选择字段) |
| `0x51` | `REQ_SAVE_PARAMS` | IN | 1 字节 | 保存到活动预设插槽 |
| `0x52` | `REQ_LOAD_PARAMS` | IN | 1 字节 | 重新加载活动预设插槽 |
| `0x53` | `REQ_FACTORY_RESET` | IN | 1 字节 | 将实时状态重置为默认值 |
| `0x54` | `REQ_SET_CHANNEL_GAIN` | OUT | 4 字节 | 设置输出通道增益 (float dB) |
| `0x55` | `REQ_GET_CHANNEL_GAIN` | IN | 4 字节 | 获取输出通道增益 |
| `0x56` | `REQ_SET_CHANNEL_MUTE` | OUT | 1 字节 | 静音输出通道 (1=静音) |
| `0x57` | `REQ_GET_CHANNEL_MUTE` | IN | 1 字节 | 获取静音状态 |
| `0x58` | `REQ_SET_LOUDNESS` | OUT | 1 字节 | 启用/禁用响度 (1=开) |
| `0x59` | `REQ_GET_LOUDNESS` | IN | 1 字节 | 获取响度状态 |
| `0x5A` | `REQ_SET_LOUDNESS_REF` | OUT | 4 字节 | 设置参考 SPL (float, 40-100) |
| `0x5B` | `REQ_GET_LOUDNESS_REF` | IN | 4 字节 | 获取参考 SPL |
| `0x5C` | `REQ_SET_LOUDNESS_INTENSITY` | OUT | 4 字节 | 设置强度 % (float, 0-200) |
| `0x5D` | `REQ_GET_LOUDNESS_INTENSITY` | IN | 4 字节 | 获取强度 |
| `0x5E` | `REQ_SET_CROSSFEED` | OUT | 1 字节 | 启用/禁用交叉馈入 (1=开) |
| `0x5F` | `REQ_GET_CROSSFEED` | IN | 1 字节 | 获取交叉馈入状态 |
| `0x60` | `REQ_SET_CROSSFEED_PRESET` | OUT | 1 字节 | 设置预设 (0-3) |
| `0x61` | `REQ_GET_CROSSFEED_PRESET` | IN | 1 字节 | 获取当前预设 |
| `0x62` | `REQ_SET_CROSSFEED_FREQ` | OUT | 4 字节 | 设置自定义频率 (float Hz, 500-2000) |
| `0x63` | `REQ_GET_CROSSFEED_FREQ` | IN | 4 字节 | 获取自定义频率 |
| `0x64` | `REQ_SET_CROSSFEED_FEED` | OUT | 4 字节 | 设置自定义馈送电平 (float dB, 0-15) |
| `0x65` | `REQ_GET_CROSSFEED_FEED` | IN | 4节 | 获取自定义馈送电平 |
| `0x66` | `REQ_SET_CROSSFEED_ITD` | OUT | 1 字节 | 启用/禁用 ITD (1=开) |
| `0x67` | `REQ_GET_CROSSFEED_ITD` | IN | 1 字节 | 获取 ITD 状态 |
| `0x70` | `REQ_SET_MATRIX_ROUTE` | OUT | 8 字节 | 设置矩阵交叉点 |
| `0x71` | `REQ_GET_MATRIX_ROUTE` | IN | 8 字节 | 获取矩阵交叉点 |
| `0x72` | `REQ_SET_OUTPUT_ENABLE` | OUT | 1 字节 | 启用/禁用输出通道 |
| `0x73` | `REQ_GET_OUTPUT_ENABLE` | IN | 1 字节 | 获取输出启用状态 |
| `0x74` | `REQ_SET_OUTPUT_GAIN` | OUT | 4 字节 | 设置每输出增益 (float dB) |
| `0x75` | `REQ_GET_OUTPUT_GAIN` | IN | 4 字节 | 获取每输出增益 |
| `0x76` | `REQ_SET_OUTPUT_MUTE` | OUT | 1 字节 | 静音输出 (1=静音) |
| `0x77` | `REQ_GET_OUTPUT_MUTE` | IN | 1 字节 | 获取输出静音状态 |
| `0x78` | `REQ_SET_OUTPUT_DELAY` | OUT | 4 字节 | 设置每输出延迟 (float ms) |
| `0x79` | `REQ_GET_OUTPUT_DELAY` | IN | 4 字节 | 获取每输出延迟 |
| `0x7A` | `REQ_GET_CORE1_MODE` | IN | 1 字节 | 获取 Core 1 模式 (0=空闲, 1=PDM, 2=EQ Worker) |
| `0x7B` | `REQ_GET_CORE1_CONFLICT` | IN | 1 字节 | 检查是否存在 PDM 与 EQ Worker 冲突 |
| `0x7C` | `REQ_SET_OUTPUT_PIN` | IN | 1 字节 | 更改输出 GPIO 引脚（返回状态） |
| `0x7D` | `REQ_GET_OUTPUT_PIN` | IN | 1 字节 | 获取输出的当前 GPIO 引脚 |
| `0x7E` | `REQ_GET_SERIAL` | IN | 可变 | 获取唯一的板子序列号 |
| `0x7F` | `REQ_GET_PLATFORM` | IN | 1 字节 | 获取平台 ID (0=RP2040, 1=RP2350) |
| `0x83` | `REQ_CLEAR_CLIPS` | OUT | — | 清除削波检测锁存器 |
| `0x90` | `REQ_PRESET_SAVE` | IN | 1 字节 | 将实时状态保存到预设插槽 (wValue=slot) |
| `0x91` | `REQ_PRESET_LOAD` | IN | 1 字节 | 将预设插槽加载到实时状态 (wValue=slot) |
| `0x92` | `REQ_PRESET_DELETE` | IN | 1 字节 | 删除预设插槽 (wValue=slot) |
| `0x93` | `REQ_PRESET_GET_NAME` | IN | 32 字节 | 获取预设名称 (wValue=slot) |
| `0x94` | `REQ_PRESET_SET_NAME` | OUT | 32 字节 | 设置预设名称 (wValue=slot) |
| `0x95` | `REQ_PRESET_GET_DIR` | IN | 可变 | 获取预设目录（占用情况、启动配置） |
| `0x96` | `REQ_PRESET_SET_STARTUP` | OUT | 2 字节 | 设置启动模式和默认插槽 |
| `0x97` | `REQ_PRESET_GET_STARTUP` | IN | 2 字节 | 获取启动配置 |
| `0x98` | `REQ_PRESET_SET_INCLUDE_PINS` | OUT | 1 字节 | 设置引脚配置包含 (1=包含) |
| `0x99` | `REQ_PRESET_GET_INCLUDE_PINS` | IN | 1 字节 | 获取引脚配置包含设置 |
| `0x9A` | `REQ_PRESET_GET_ACTIVE` | IN | 1 字节 | 获取当前活动的预设插槽索引 |
| `0x9B` | `REQ_SET_CHANNEL_NAME` | OUT | 32 字节 | 设置通道名称 (wValue=channel) |
| `0x9C` | `REQ_GET_CHANNEL_NAME` | IN | 32 字节 | 获取通道名称 (wValue=channel) |
| `0xA0` | `REQ_GET_ALL_PARAMS` | IN | 约 2896 字节 | 批量读取整个 DSP 状态（多包） |
| `0xA1` | `REQ_SET_ALL_PARAMS` | OUT | 约 2896 字节 | 批量写入整个 DSP 状态（多包） |
| `0xB0` | `REQ_GET_BUFFER_STATS` | IN | 可变 | 读取缓冲区填充统计信息 |
| `0xB1` | `REQ_RESET_BUFFER_STATS` | IN | 1 字节 | 重置缓冲区统计计数器 |
| `0xB2` | `REQ_GET_USB_ERROR_STATS` | IN | 24 字节 | 读取 USB PHY 错误计数器（CRC/位填充/超时/溢出/序列） |
| `0xB3` | `REQ_RESET_USB_ERROR_STATS` | IN | 1 字节 | 重置 USB PHY 错误计数器 |
| `0xB4` | `REQ_SET_LEVELLER_ENABLE` | OUT | 1 字节 | 启用/禁用音量均衡器 |
| `0xB5` | `REQ_GET_LEVELLER_ENABLE` | IN | 1 字节 | 获取均衡器启用状态 |
| `0xB6` | `REQ_SET_LEVELLER_AMOUNT` | OUT | 4 字节 | 设置均衡器目标/数量 |
| `0xB7` | `REQ_GET_LEVELLER_AMOUNT` | IN | 4 字节 | 获取均衡器数量 |
| `0xB8` | `REQ_SET_LEVELLER_SPEED` | OUT | 1 字节 | 设置均衡器启动/释放速度 |
| `0xB9` | `REQ_GET_LEVELLER_SPEED` | IN | 1 字节 | 获取均衡器速度 |
| `0xBA` | `REQ_SET_LEVELLER_MAX_GAIN` | OUT | 4 字节 | 设置最大向上增益 |
| `0xBB` | `REQ_GET_LEVELLER_MAX_GAIN` | IN | 4 字节 | 获取最大向上增益 |
| `0xBC` | `REQ_SET_LEVELLER_LOOKAHEAD` | OUT | 1 字节 | 启用/禁用 10 ms 前视 |
| `0xBD` | `REQ_GET_LEVELLER_LOOKAHEAD` | IN | 1 字节 | 获取前视状态 |
| `0xBE` | `REQ_SET_LEVELLER_GATE` | OUT | 4 字节 | 设置噪声门阈值 |
| `0xBF` | `REQ_GET_LEVELLER_GATE` | IN | 4 字节 | 获取噪声门阈值 |
| `0xC0` | `REQ_SET_OUTPUT_TYPE` | OUT | 1 字节 | 设置插槽输出类型 (0=S/PDIF, 1=I2S; wValue=slot) |
| `0xC1` | `REQ_GET_OUTPUT_TYPE` | IN | 1 字节 | 获取插槽输出类型 (wValue=slot) |
| `0xC2` | `REQ_SET_I2S_BCK_PIN` | OUT | 1 字节 | 设置共享的 I2S BCK GPIO（LRCLK 自动 = BCK + 1） |
| `0xC3` | `REQ_GET_I2S_BCK_PIN` | IN | 1 字节 | 获取当前 I2S BCK 引脚 |
| `0xC4` | `REQ_SET_MCK_ENABLE` | OUT | 1 字节 | 启用/禁用 I2S 主时钟输出 |
| `0xC5` | `REQ_GET_MCK_ENABLE` | IN | 1 字节 | 获取 MCK 启用状态 |
| `0xC6` | `REQ_SET_MCK_PIN` | OUT | 1 字节 | 设置 MCK GPIO |
| `0xC7` | `REQ_GET_MCK_PIN` | IN | 1 字节 | 获取 MCK GPIO |
| `0xC8` | `REQ_SET_MCK_MULTIPLIER` | OUT | 1 字节 | 设置 MCK 倍频 (0=128×, 1=256×) |
| `0xC9` | `REQ_GET_MCK_MULTIPLIER` | IN | 1 字节 | 获取 MCK 倍频 |
| `0xD0` | `REQ_SET_PREAMP_CH` | OUT | 4 字节 | 设置每通道前置放大器 (wValue=channel, payload=float dB) |
| `0xD1` | `REQ_GET_PREAMP_CH` | IN | 4 字节 | 获取每通道前置放大器 (wValue=channel) |
| `0xD2` | `REQ_SET_MASTER_VOLUME` | OUT | 4 字节 | 设置主音量（-128 静音哨兵值，-127..0 dB） |
| `0xD3` | `REQ_GET_MASTER_VOLUME` | IN | 4 字节 | 获取当前实时主音量 |
| `0xD4` | `REQ_SET_MASTER_VOLUME_MODE` | OUT | 1 字节 | 设置持久化模式 (0=独立, 1=随预设) |
| `0xD5` | `REQ_GET_MASTER_VOLUME_MODE` | IN | 1 字节 | 获取持久化模式 |
| `0xD6` | `REQ_SAVE_MASTER_VOLUME` | IN | 1 字节 | 将实时主音量保存到目录（模式 0 持久化） |
| `0xD7` | `REQ_GET_SAVED_MASTER_VOLUME` | IN | 4 字节 | 读取目录中已保存的主音量值 |
| `0xF0` | `REQ_ENTER_BOOTLOADER` | IN | 1 字节 | 重启进入 UF2 引导加载程序以进行固件更新 |
### REQ_GET_STATUS (0x50) - 系统遥测
`REQ_GET_STATUS` 请求根据 `wValue` 字段返回数据：
| wValue | 返回 | 描述 |
| :--- | :--- | :--- |
| `0` | uint32 | 通道 0-1 的峰值（打包的 16 位值） |
| `1` | uint32 | 通道 2-3 的峰值（打包的 16 位值） |
| `2` | uint32 | 通道 4 的峰值 + CPU0/CPU1 负载（打包） |
| `3` | uint32 | PDM 环形缓冲区溢出 |
| `4` | uint32 | PDM 环形缓冲区欠载 |
| `5` | uint32 | PDM DMA 溢出 |
| `6` | uint32 | PDM DMA 欠载 |
| `7` | uint32 | S/PDIF 溢出 |
| `8` | uint32 | S/PDIF 欠载 |
| `9` | 12 字节 | 组合：所有 5 个峰值 + CPU 负载 |
| `10` | uint32 | USB 音频包计数 |
| `11` | uint32 | USB 替代设置 |
| `12` | uint32 | USB 音频挂载状态 |
| `13` | uint32 | 系统时钟频率 |
| `14` | uint32 | 核心电压（毫伏） |
| `15` | uint32 | 采样率 |
| `16` | int32 | 系统温度（摄氏度百分之一度） |
| `17` | uint32 | S/PDIF DMA 总饥饿数（所有插槽合计） |
| `18` | uint32 | S/PDIF 插槽 0 饥饿数 (Out 1-2) |
| `19` | uint32 | S/PDIF 插槽 1 饥饿数 (Out 3-4) |
| `20` | uint32 | S/PDIF 插槽 2 饥饿数 (Out 5-6, RP2350) |
| `21` | uint32 | S/PDIF 插槽 3 饥饿数 (Out 7-8, RP2350) |
饥饿事件意味着 S/PDIF DMA 需要缓冲区，但消费者池为空，因此固件为该传输替换了静音缓冲区。这是比较旧的 `spdif_underruns` USB 包间隙启发式算法更直接的输出端丢失信号。
### 数据结构
**滤波器数据包（16 字节）：**
```
struct __attribute__((packed)) {
uint8_t channel; // RP2350: 0-10, RP2040: 0-6
uint8_t band; // 0-9
uint8_t type; // 0=Flat, 1=Peak, 2=LS, 3=HS, 4=LP, 5=HP
uint8_t reserved;
float freq; // Hz
float Q;
float gain_db;
}
```
**矩阵路由数据包（8 字节）：**
```
struct __attribute__((packed)) {
uint8_t input; // 0-1 (USB L/R)
uint8_t output; // RP2350: 0-8, RP2040: 0-4
uint8_t enabled; // 0 or 1
uint8_t phase_invert; // 0 or 1
float gain_db; // -inf to +12dB
}
```
### 运行时引脚配置
输出 GPIO 引脚可以在运行时重新分配，而无需重新刷写。这在自定义 PCB 布局或默认引脚分配与其他硬件时非常有用。
**`REQ_SET_OUTPUT_PIN` (0x7C)** — IN 传输，返回 1 字节状态：
* `wValue` = `(new_pin << 8) | output_index`
* RP2350：`output_index` 0-3 对应 S/PDIF 输出 1-4，4 对应 PDM 超低音
* RP2040：`output_index` 0-1 对应 S/PDIF 输出 1-2，2 对应 PDM 超低音
* 在引脚更改期间，S/PDIF 输出会自动禁用并重新启用（仅在该输出上有约 1ms 的音频丢失）
* PDM 输出必须首先禁用（通过 `REQ_SET_OUTPUT_ENABLE` 禁用），否则返回 `PIN_CONFIG_OUTPUT_ACTIVE`
| 状态码 | 值 | 含义 |
|-------------|-------|---------|
| `PIN_CONFIG_SUCCESS` | 0x00 | 引脚成功更改 |
| `PIN_CONFIG_INVALID_PIN` | 0x01 | 引脚超出范围或被保留（GPIO 12、23-25） |
| `PIN_CONFIG_PIN_IN_USE` | 0x02 | 引脚已分配给另一个输出 |
| `PIN_CONFIG_INVALID_OUTPUT` | 0x03 | 输出索引超出范围 |
| `PIN_CONFIG_OUTPUT_ACTIVE` | 0x04 | PDM 输出在更改其引脚之前必须被禁用 |
**`REQ_GET_OUTPUT_PIN` (0x7D)** — IN 传输，返回 1 字节：
* `wValue` = output_index
* 返回该输出的当前 GPIO 引脚编号
引脚分配存储在每个预设中，并可以在预设保存/加载期间选择性地包含（通过 `REQ_PRESET_SET_INCLUDE_PINS` 控制）。
## 从源码构建
要自行构建固件，您需要一个标准的 Raspberry Pi Pico C/C++ 开发环境。
### 1. 安装前置条件
请确保您已安装以下工具：
* **CMake**（3.13 或更新版本）
* **Arm GNU Toolchain**（`arm-none-eabi-gcc` 等）
* **Python 3**（用于 Pico SDK 脚本）
* **Git**
### 2. 克隆代码库
递归克隆项目以包含 Pico SDK 和其他子模块：
```
git clone --recursive https://github.com/WeebLabs/DSPi.git
cd DSPi
```
*如果您已经克隆但没有加 `--recursive`，请运行：*
```
git submodule update --init --recursive
```
### 3. 构建固件
您可以为标准的 **RP2040** (Raspberry Pi Pico) 或较新的 **RP2350** (Raspberry Pi Pico 2) 进行构建。构建系统使用单独的目录以避免冲突。
**选项 A：为 RP2040 构建 (标准 Pico)**
```
mkdir build-rp2040
cd build-rp2040
cmake -DPICO_BOARD=pico -DPICO_EXTRAS_PATH=../firmware/pico-extras ../firmware
make
```
*输出：* `DSPi/DSPi.uf2`
**选项 B：为 RP2350 构建 (Pico 2)**
```
mkdir build-rp2350
cd build-rp2350
cmake -DPICO_BOARD=pico2 -DPICO_EXTRAS_PATH=../firmware/pico-extras ../firmware
make
```
*输出：* `DSPi/DSPi.uf2`
### 4. 刷写设备
1. 在插入开发板时按住 **BOOTSEL** 按钮。
2. 将生成的 `.uf2` 文件拖放到 `RPI-RP2`（或 `RP2350`）驱动器上。
或者，可以通过发送 `REQ_ENTER_BOOTLOADER` (0xF0) 将已运行的 DSPi 置于引导加载程序模式，而无需按下按钮。DSPi Console 应用程序即使用此功能进行一键固件更新。有关协议详细信息，请参见 [`Documentation/Features/firmware_update.md`](Documentation/Features/firmware_update.md)。
## 详细规格
每个子系统的深入规格保存在 [`Documentation/Features/`](Documentation/Features/) 下。这些是协议格式、接线布局、边缘情况和主机应用集成模式的权威来源。
| 功能 | 规格 |
|---------|------|
| 矩阵混音器 | [`matrixmixer_spec.md`](Documentation/Features/matrixmixer_spec.md) |
| 用户预设 | [`user_presets_spec.md`](Documentation/Features/user_presets_spec.md) |
| 主音量 | [`master_volume_spec.md`](Documentation/Features/master_volume_spec.md) |
| 每通道前置放大器 | [`per_channel_preamp_spec.md`](Documentation/Features/per_channel_preamp_spec.md) |
| 音量均衡器 | [`volume_leveller_spec.md`](Documentation/Features/volume_leveller_spec.md) |
| I2S 输出 | [`i2s_output_spec.md`](Documentation/Features/i2s_output_spec.md) |
| 峰值 / 削波测量 | [`peak_clip_metering_spec.md`](Documentation/Features/peak_clip_metering_spec.md) |
| 缓冲区统计 | [`buffer_statistics_spec.md`](Documentation/Features/buffer_statistics_spec.md) |
| S/PDIF DMA 饥饿 | [`spdif_starvation_spec.md`](Documentation/Features/spdif_starvation_spec.md) |
| USB 错误诊断 | [`usb_errors_spec.md`](Documentation/Features/usb_errors_spec.md) |
| Core 1 模式 | [`core1_modes_spec.md`](Documentation/Features/core1_modes_spec.md) |
| 设备识别 | [`device_identification_spec.md`](Documentation/Features/device_identification_spec.md) |
| S/PDIF 输入（计划中） | [`SPDIF_input_spec.md`](Documentation/Features/SPDIF_input_spec.md) |
| 通过 USB 进行固件更新 | [`Documentation/Features/firmware_update.md`](Documentation/Features/firmware_update.md) |
| 路线图 | [`roadmap.md`](Documentation/Features/roadmap.md) |
## 许可证
本项目基于 GNU General Public License v3.0 授权。有关详细信息，请参见 [LICENSE](LICENSE)。标签：DSP, EQ, I2S, PDM, Raspberry Pi Pico, RP2040, RP2350, S/PDIF, UML, USB声卡, 主动分频, 参数均衡器, 响度补偿, 客户端加密, 嵌入式系统, 开源硬件, 微控制器, 房间校准, 数字信号处理, 时间对齐, 耳机交叉馈送, 音频固件, 音频处理