DS5Dongle v0.8.0 Release Notes / 发布说明

版本 / Version: 0.8.0
对比基线 / Baseline: v0.7.2-hotfix
范围 / Scope: 82 个提交，46 个文件变更（+3384 / −1156），2026-06-21 → 2026-10-18

English

0.8.0 is the largest update since 0.7.x: it adds button remapping and custom button chords / shortcuts, replaces the fixed Xbox Game Bar mapping with nine configurable slots (keyboard, media or firmware actions), rebuilds the audio path around double-frame packet packing, fixes the macOS microphone jitter/echo problems, and hardens Bluetooth, config storage and USB output-report handling.

✨ Highlights

• Button remapping — remap all 28 controller buttons (including Edge paddles/functions) or disable an individual button.
• Custom chords — nine slots supporting single tap, double tap, two-button chords and chord double-taps, emitting keyboard shortcuts, media keys or firmware actions (e.g. disconnect), plus hold mappings.
• Mic/speaker routing — mic_select / speaker_select replace the old "disable mic/speaker" toggles with auto, built-in, headset or disabled.
• Volume lock — new lock_volume switch that ignores volume, mute and mute-light requests sent by games.
• Polling rate — 250 Hz / 500 Hz / 1000 Hz / Real-Time, plus new single/double packet audio modes.
• Reliability — config storage moved off the Bluetooth pairing sector; authentication, inquiry and reconnect handling rewritten; USB output reports now validated for length and emptiness.
• Observability — status GPIO output, an ENABLE_DEBUG build and Core1 stack-watermark reporting.

🎮 Button remapping and chords

Remapping (0xFA)

• Covers all 28 button IDs, including the DualSense Edge LeftFunction / RightFunction / LeftPaddle / RightPaddle.
• Three forms: A=B (map), A=disable (swallow the button), A=nomap (restore identity).
• Remapping is applied after shortcut evaluation, so shortcuts always fire from the physical button.
• Stored in the new Button area and resettable as a whole.

Shortcuts (0xFB)

• Nine slots. Triggers:
  • Button — single tap;
  • Button*2 — two presses within 250 ms;
  • Button1+Button2 — fires when both are held, and can fire again after either is released;
  • Button1+Button2*2 — the chord must be formed twice.
• Actions:
  • Keyboard — modifiers plus one key such as Win+Shift+S, Win+PrintScreen, Win+G or F13; raw HID usages (0x16) also work;
  • Media — VolumeUp, VolumeDown, Mute, PlayPause, Next, Prev, Stop, BrightnessUp, BrightnessDown, sent on the Consumer Control interface;
  • Firmware — bt_disconnect.
• Hold mappings — shortcut "1=Cross@hold:Space" presses on button-down and releases on button-up; active slots are merged with key/modifier de-duplication.
• While the config UI is "listening" for a trigger, 0xF6 funcid 0x05 pauses shortcut output for five seconds so the captured press does not also fire.
• Linux limitation — the Linux kernel module prevents creating a virtual keyboard, so keyboard/media shortcuts do not work on Linux.

🔊 Audio

• Double-frame packing — two haptics frames and two Opus frames go into one 0x39 report by default, halving the report rate and reducing jitter.
• Single packet mode — packet_mode=1 emits the same 0x36 single-frame report as 0.7.2, as a compatibility fallback.
• Haptics-only packet — with the speaker disabled, a 142-byte 0x32 report is used so no room is reserved for Opus.
• Opus mode — the encoder now uses OPUS_APPLICATION_RESTRICTED_CELT for a response closer to the wired connection.
• Haptics resampler filter removed — matches the wired path (the controller itself runs near 3 kHz internally).
• macOS fix (#232) — larger mic buffer, CoreAudio-timed slice draining and no work on empty queues, resolving digital echo, jitter and dropouts.
• Mic re-armed on reconnect (#242) — the controller is told to start streaming again after it reconnects, so users no longer have to re-select the recording device.
• Speaker attenuation fix (#263) — NoiseCancelEnable is preserved whenever AudioControl is set; Linux hid-playstation sends that report on every headset change, which halved the speaker level until reconnecting on 0.7.2.
• Default audio buffer (the fallback for invalid values) changed from 64 to 48; trigger_reduce, speaker_gain and mute-light settings now apply correctly when set to 0.
• Live feature reports — 0x80–0x81 and 0x60–0x62 are forwarded in real time; 0x81 and 0x70–0x7B are queried from the controller within a 250 ms budget instead of returning cached values.
• Firmware information fix — a DSE running in DS5 mode now reports DS5 firmware information, matching the mode it presents.

📶 Bluetooth and connectivity

• Inquiry by name prefix — results are filtered by the DualSense prefix during inquiry, covering both DualSense and DualSense Edge, for faster and more reliable pairing.
• Link key retention — the stored key is dropped only on Authentication Failure / PIN or Key Missing; timeouts and mid-authentication link losses keep the pairing.
• Recovery after auth failure — the link is disconnected and inquiry restarts instead of stalling with no connection.
• Input frame length checks (#280) — short frames are dropped instead of read past their end, which could fake the dock bit and disconnect the controller.
• No hang on CYW43 start failure (#280) — the board reboots after 500 ms and retries instead of stopping at return 1.
• BOOTSEL-hold blacklist is additive (#203) — repeated holds no longer wipe the list, so a "forgotten" controller cannot silently auto-reconnect.
• Auto disconnect on dock — new disconnect_on_dock option with latching to ignore dock-detect jitter.
• First-connect low polling rate — inquiry is stopped as soon as a connection is accepted, avoiding a degraded report rate.
• Edge detection — DSE is identified from firmware information rather than a fixed report length.

⌨️ USB HID and wake

• New Consumer Control interface (0x88); media keys no longer use the keyboard page (Windows silently ignores the 0x7F–0x81 volume usages there).
• enable_keyboard replaces the Xbox Game Bar toggle: the keyboard and consumer interfaces enumerate when either enable_wake or enable_keyboard is on; with both off those two interfaces disappear, and the descriptor only gains the remap/shortcut feature reports compared with 0.7.2.
• With enable_wake on and no controller connected, only the wake-only keyboard is exposed; while the wake sequence owns the endpoint, shortcut output pauses and resumes from fresh input.
• Ghost device fix — with BIOS "Keep USB Charge" enabled, the host no longer keeps a phantom controller device after boot/resume.
• Output report 0x02 (#282) — accepted over both the interrupt OUT endpoint and the control pipe (HidD_SetOutputReport); empty and short reports are ignored or copied only for their own length, instead of reading past the buffer.
• The 0x03 reconnect command now goes through usb_reconnect(), distinguishing keyboard-only from full reconnect.

⚙️ Configuration and web config

• New storage layout — ConfigStorage = a 64-byte config area plus a Button area (28 B remap table + 63 B shortcut slots), with compile-time size/alignment checks.
• Config sector relocated — config now lives in the sector before the BTstack flash bank, so it no longer shares a sector with pairing data (TLV) and cannot overwrite it (#244); the old sector is read once on first boot.
• New feature reports — 0xFA (remap) and 0xFB (shortcut slots) read/write, plus 0xF6 funcid 0x05 (pause shortcuts for five seconds).
• Default trigger voltage fix (#277) — the default was not applied after upgrading from 0.6.0.
• Status GPIO (#225) — drive a usable GPIO as a connected indicator, or pulse it on connect.
• SMPS coil whine (#207) — the CYW43 SMPS pin is now driven to a fixed level, removing the audible whine.
• Web config localization — a Russian (RU) interface was added by @Arisius (#274 / ds5dongle-config-web#17).

🐞 Other fixes

• Config fields that could not be applied when set to 0.
• First connection of a new device, reconnect speed and low-polling-rate issues.
• LED initial colour, and low-battery blinking now reads struct fields instead of hard-coded byte offsets.
• Removed the legacy dse.cpp, state_mgr.cpp and ps_shortcut.cpp modules; interrupt_in_data is now a USBGetStateData.
• CI/release: TinyUSB is pinned by commit, and artifacts are named consistently.

🔧 Build and development

• Upgraded to Pico SDK 2.3.1, TinyUSB 98741b55 and ARM GCC 15.2.rel1.
• tools/build-macos.sh and tools/build-windows.ps1 check and switch to those versions; the Windows script also no longer reuses a stale SDK checkout.
• New -DENABLE_DEBUG=ON build with Core1 stack-watermark logging.
• More hot paths moved to RAM: l2cap_request_can_send_now_event, BTstack linked-list iterators, the CRC32 table and TinyUSB FIFO bulk movers (#233).
• New host-side regression tests tests/test_hold.py + tests/hold_state_test.cpp covering the hold-mapping state machine.

⚠️ Upgrade notes (read first)

1. The config structure changed while the schema number stayed at 5: the firmware does not reset it, so old values are reinterpreted — please review or reconfigure after upgrading:
   • ps_shortcut_enabled → enable_keyboard (same 0/1 meaning);
   • disable_mic / disable_speaker (1 = disabled) → mic_select / speaker_select (1 = built-in): users who had disabled the mic or speaker will now force the built-in device — set them to 3 (disable);
   • polling_rate_mode: the old 2 (Real-Time) now means 1000 Hz; Real-Time is 3;
   • speaker_volume / headset_volume are deprecated (volume is controlled by the game); use lock_volume if you want it fixed;
   • new fields default to off: lock_volume=0, status_gpio disabled, packet_mode=0 (double), disconnect_on_dock=0.
2. The Xbox Game Bar presets are gone: recreate them as shortcut slots, e.g. shortcut 4=PS:Win+G, shortcut 6=PS*2:Win+Tab.
3. Update the config tool / web config to 0.8.0: 0.7.x tools do not know the new fields, the 0xFA/0xFB reports or the Button area.
4. The config sector moved: it is read from the old sector once on first boot, and Bluetooth pairings live in the BTstack bank, so they survive the upgrade.
5. Replug USB after enabling keyboard/media actions so the interfaces enumerate.
6. If you hit audio compatibility issues, try packet_mode=1 (the 0.7.2 single-packet mode) first.

📄 Known limitations

• Trigger buttons are not swallowed, so chords using PS may also open the Steam overlay or Game Bar.
• Two DPad directions cannot form a chord (the DPad reports one direction at a time); the tool rejects such pairs.
• Due to a Windows limitation, volume actions adjust the DualSense audio endpoint only, not the current default playback device.
• Wake is S3 only; Modern Standby (S0ix) is not supported.
• More than six simultaneous ordinary keys emit HID ErrorRollOver until the count drops to six or fewer.
• On Linux the kernel module blocks creating a virtual keyboard, so keyboard/media shortcuts are unavailable.

🙏 Pull requests and thanks

Thanks to the following contributors and reporters — most of 0.8.0's fixes came from the community:

中文

0.8.0 是这个项目自 0.7.x 以来最大的一次更新：新增了按键重映射与自定义组合键（快捷键），把 Xbox Game Bar 的固定映射升级为 9 组可配置的按键/媒体/固件动作；音频链路重构为双帧打包并修好了 macOS 的麦克风抖动与回声问题；蓝牙连接、配置存储和 USB 输出报告的健壮性也做了系统性加固。

✨ 主要亮点

• 按键重映射：28 个手柄按键（含 Edge 的拨片/功能键）可任意改键，或单独禁用某个按键。
• 自定义组合键：9 组槽位，支持单击、双击、双键组合与组合双击，可输出键盘快捷键、媒体键或固件动作（如断连），并支持按住式映射。
• 麦克风/扬声器路由：mic_select / speaker_select 取代原来的“禁用麦克风/扬声器”开关，可选自动、内置、耳机或禁用。
• 音量锁定：新开关 lock_volume，忽略游戏下发的音量、静音与静音灯指令。
• 轮询率：250 Hz / 500 Hz / 1000 Hz / Real-Time 四档，并新增单包/双包音频模式。
• 可靠性：配置区与蓝牙配对数据分离到不同 flash 扇区；蓝牙鉴权、查询与断线恢复逻辑重写；USB 输出报告做了长度与空包校验。
• 可观测性：新增状态 GPIO 输出、ENABLE_DEBUG 调试构建与 Core1 栈水位统计。

🎮 按键重映射与组合键

按键重映射（0xFA）

• 覆盖全部 28 个按键 ID，含 DualSense Edge 的 LeftFunction / RightFunction / LeftPaddle / RightPaddle。
• 支持三种写法：A=B（映射）、A=disable（吞掉该按键）、A=nomap（恢复默认）。
• 重映射在快捷操作读取之后应用，所以快捷键始终按物理按键触发。
• 存储在新的 Button 区，可整体重置。

组合键 / 快捷操作（0xFB）

• 9 个槽位，触发器支持：
  • 按键：单击；
  • 按键*2：250 ms 内双击；
  • 按键1+按键2：两键同时按下触发，松开任意一个后可再次触发；
  • 按键1+按键2*2：组合需要重复两次。
• 动作类型：
  • 键盘：修饰键 + 一个按键，如 Win+Shift+S、Win+PrintScreen、Win+G、F13，也接受原始 HID usage（0x16）；
  • 媒体：VolumeUp / VolumeDown / Mute / PlayPause / Next / Prev / Stop / BrightnessUp / BrightnessDown，走 Consumer Control 接口；
  • 固件：bt_disconnect（断开当前手柄）。
• 按住式映射：1=Cross@hold:Space，按下即按住，松开即释放；多个槽位同时生效时会合并、去重按键与修饰键。
• 配置界面“监听手柄按键”时会通过 0xF6 funcid 0x05 暂停快捷操作输出 5 秒，避免录制触发的按键又动作一次。
• Linux 限制：受 Linux 内核模块限制无法创建虚拟键盘，因此键盘/媒体类组合键在 Linux 上不可用。

🔊 音频

• 双帧打包：默认把两帧 haptics + 两帧 Opus 装进一个 0x39 报文，报文速率减半、抖动更低。
• 单包模式：packet_mode=1 使用与 0.7.2 相同的 0x36 单帧报文，遇到兼容性问题可切回。
• 纯 haptics 报文：扬声器被禁用时改用 142 字节的 0x32 报文，不再为 Opus 预留空间。
• Opus 模式：编码器切到 OPUS_APPLICATION_RESTRICTED_CELT，低频响应更接近有线手感。
• 去除 haptics 重采样滤波器：与有线连接一致（手柄内部本身工作在 3 kHz 采样率附近）。
• macOS 修复（#232）：加大麦克风缓冲、按 CoreAudio 时序切片排空、队列为空时不做无意义处理，解决数字回声、抖动与掉音。
• 麦克风重连恢复（#242）：手柄重连后重新下发麦克风开启指令，不再需要用户在系统里重新选择录音设备。
• 避免扬声器被衰减（#263）：在设置 AudioControl 时保留 NoiseCancelEnable；Linux hid-playstation 每次耳机插拔都会下发该报文，0.7.2 会因此把扬声器音量砍半直到重连。
• 音频缓冲默认值（无效值回退）由 64 调整为 48；trigger_reduce / speaker_gain / 静音灯在数值为 0 时也能正确生效。
• 实时特性报告：0x80–0x81、0x60–0x62 改为实时转发；0x81 与 0x70–0x7B 会以 250 ms 为预算向手柄实时查询，而不是返回缓存值。
• 固件信息修正：DSE 工作在 DS5 模式下时返回的是 DS5 的固件信息，不再报成 DSE。

📶 蓝牙与连接

• 按名称前缀查询配对：配对查询阶段按 DualSense 前缀筛选查询结果（同时覆盖 DualSense 与 DualSense Edge），配对更快、误配更少。
• 鉴权失败处理：仅在 Authentication Failure / PIN or Key Missing 时丢弃链路密钥，其余失败（超时、链路中断）保留密钥，避免已经配好的手柄被无故解绑。
• 鉴权失败后自恢复：失败后断连并重新进入查询，不再卡死在无连接状态。
• 输入帧长度校验（#280）：短帧不再越过缓冲区读取，避免伪造出“已入坞”标志而误断连。
• CYW43 启动失败不再挂死（#280）：初始化失败后 500 ms 重启重试，而不是停在 return 1 等用户拔电。
• BOOTSEL 长按黑名单改为累加（#203）：多次长按不再清空黑名单，被“忘记”的手柄不会在下次按 PS 时自动连回来。
• 自动断连（入坞检测）：新增 disconnect_on_dock，检测到手柄放回充电底座后自动断开，带锁存避免抖动。
• 首次连接时误入低回报率：连接建立后立即停止 inquiry，避免查询与连接并行导致的低轮询率。
• Edge 识别：改为读取固件信息判断 DSE，不再依赖固定的报告长度。

⌨️ USB HID / 唤醒

• 新增 Consumer Control 接口（0x88），媒体键不再借用键盘页（Windows 会静默忽略键盘页的音量 usage）。
• enable_keyboard 取代原 Xbox Game Bar 开关：键盘与媒体接口由 enable_wake 或 enable_keyboard 任一开启时枚举；二者都关闭时不会多出这两个接口，描述符相比 0.7.2 只多出重映射/快捷键两个 feature report。
• 开启 enable_wake 且手柄未连接时，只暴露唤醒专用键盘；唤醒序列独占键盘端点期间，快捷键输出自动暂停并在拿到新输入后恢复。
• 幽灵设备修复：BIOS 开启 “Keep USB Charge” 时，主机启动/唤醒后不再残留一个不存在的控制器设备。
• 输出报告 0x02（#282）：现在同时接受中断 OUT 端点与控制管道（HidD_SetOutputReport）两条路径；空报文与超短报文被丢弃，短报文只拷贝自身长度，不再把越界数据写进手柄状态。
• 配置命令 0x03 重连统一走 usb_reconnect()，区分“只重连键盘”与“完整重连”。

⚙️ 配置与网页配置

• 存储布局重做：ConfigStorage = 64 字节配置区 + Button 区（重映射 28 B + 快捷操作 63 B），并做编译期尺寸与对齐检查。
• 配置扇区迁移：配置改写到 BTstack flash bank 之前的扇区，不再与配对数据（TLV）共用扇区，避免两者互相覆盖（#244）；首次启动会自动从旧扇区读取一次。
• 新特性报告：0xFA（重映射）、0xFB（快捷操作槽位）读写；0xF6 新增 funcid 0x05（暂停快捷操作 5 秒）。
• 默认扳机马达电压修复（#277）：从 0.6.0 升级后默认电压没有生效的问题。
• 状态 GPIO（#225）：可指定一个可用 GPIO 输出连接状态，或在连接时输出一个按键脉冲。
• SMPS 啸叫（#207）：把 CYW43 的 SMPS 引脚置为固定电平，消除可闻的电源啸叫。
• 网页配置本地化：新增俄语（RU）界面（@Arisius，#274 / ds5dongle-config-web#17）。

🐞 其他修复

• 配置中部分字段设为 0 时无法生效的问题。
• 新设备首次连接、重连速度与低回报率问题。
• LED 初始颜色、低电量闪烁逻辑改为读取结构体字段（不再硬编码字节偏移）。
• 移除 dse.cpp、state_mgr.cpp、ps_shortcut.cpp 等遗留模块，interrupt_in_data 统一为 USBGetStateData。
• CI/发布流程：TinyUSB 改为按 commit 固定，发布产物统一命名。

🔧 构建与开发

• 升级到 Pico SDK 2.3.1、TinyUSB 98741b55、ARM GCC 15.2.rel1。
• tools/build-macos.sh 与 tools/build-windows.ps1 会检查并切换到上述版本，Windows 脚本同时修正了 SDK 版本切换后残留旧构建的问题。
• 新增 -DENABLE_DEBUG=ON：输出 Core1 栈水位，便于排查音频核栈溢出。
• 关键热路径继续下沉到 RAM：l2cap_request_can_send_now_event、BTstack 链表迭代、CRC32 表、TinyUSB FIFO 搬运函数（#233）。
• 新增宿主机回归测试 tests/test_hold.py + tests/hold_state_test.cpp，覆盖按住式映射的状态机。

⚠️ 升级注意（请先读）

1. 配置结构变了，但 schema 版本号仍是 5：固件不会自动重置配置，旧值会按新字段解释，请升级后逐项核对（或重新配置）：
   • ps_shortcut_enabled → enable_keyboard（值 0/1 语义一致）；
   • disable_mic / disable_speaker（1 = 禁用）→ mic_select / speaker_select（1 = 内置）：原先禁用麦克风或扬声器的用户，升级后会变成强制使用内置设备，请改为 3（disable）；
   • polling_rate_mode：原来的 2（Real-Time）现在表示 1000 Hz，Real-Time 改为 3；
   • speaker_volume / headset_volume 已废弃（音量改由游戏控制），需要固定音量请用 lock_volume；
   • 新增字段默认全关：lock_volume=0、status_gpio=off、packet_mode=0（双包）、disconnect_on_dock=0。
2. Xbox Game Bar 固定映射已移除：需要的话用快捷操作重建，例如 shortcut 4=PS:Win+G、shortcut 6=PS*2:Win+Tab。
3. 配置工具/网页配置需同步升级到 0.8.0：0.7.x 的工具不认识新字段、0xFA/0xFB 报文与 Button 区。
4. 配置扇区位置变了：首次启动会从旧扇区读取一次配置；蓝牙配对信息保存在 BTstack bank 中，升级不会丢失配对。
5. 启用键盘/媒体动作后需要重新插拔 USB，接口才会枚举出来。
6. 若遇到音频兼容性问题，可先试 packet_mode=1（与 0.7.2 相同的单包模式）。

📄 已知限制

• 组合键的触发按键不会被吞掉，用 PS 组成的组合仍可能同时打开 Steam 覆盖层或 Game Bar。
• 两个方向键无法组成组合（DPad 同时只上报一个方向），工具会直接拒绝。
• 受 Windows 限制，音量类动作只能调整 DualSense 音频端点，无法调整系统当前默认播放设备。
• 唤醒仅支持 S3，不支持 Modern Standby（S0ix）。
• 同时按下超过 6 个普通按键时会输出 HID ErrorRollOver，直到按键数降到 6 个以内。
• Linux 下受内核模块限制无法创建虚拟键盘，键盘/媒体类组合键不可用。

🙏 PR 与致谢

感谢以下贡献者与问题报告者，0.8.0 的大部分修复来自社区：

完整提交对比 / Full changelog: v0.7.2-hotfix...v0.8.0