0x19b0 · hapticFeedback
设备级触感配置、能力门控的波形播放和就绪检查,用于 MX Master 4 的 Actions Ring。
此功能控制设备的触感执行器。它报告波形支持、设备级触感标志、强度和就绪状态。OpenLogi 在 Actions Ring 中为 MX Master 4 使用两个类型化波形。
**规格:**罗技没有公开规格。布局从 Logi Options+ 2.8(静态分析)逆向得出。**交叉核对:**Solaar。用于:MX Master 4 上的 Actions Ring。
函数参考
HapticFeedbackFeature(0x19b0)提供以下方法。
方法
| 函数 | HID++ fn | 签名 | 返回值 |
|---|---|---|---|
get_capabilities | 0 | () | HapticCapabilities |
get_configuration | 1 | () | HapticConfiguration |
set_configuration | 2 | (flags: HapticConfigFlags, intensity: HapticIntensity) | HapticConfiguration |
get_haptic_status | 3 | () | HapticStatus |
play | 4 | (waveform: HapticWaveform) | () |
所有方法都是 async,并返回 Result<…, Hidpp20Error>。
类型
SupportedWaveforms
此掩码会保留未知位。supports 检查波形 ID N 的位 N。OpenLogi 仅命名它使用的两个波形。
| 字段 | 位 | 说明 |
|---|---|---|
DAMP_STATE_CHANGE | 1 | 动作执行后的确认脉冲。 |
SUBTLE_COLLISION | 4 | 格位变化的轻微边界脉冲。 |
HapticWaveform
| 变体 | 值 | 说明 |
|---|---|---|
DampStateChange | 1 | 确认脉冲。 |
SubtleCollision | 4 | 边界脉冲。 |
HapticConfigFlags
HapticConfigFlags 会保留未知位。写入时应基于 get_configuration() 的结果,以保留未建模的标志。
| 字段 | 位 | 说明 |
|---|---|---|
ENABLED | 0 | 固件触感播放已启用。 |
POWER_SAVE | 1 | 节省电池的触感设置。Options+ 可独立控制它。 |
HapticConfiguration
| 字段 | 类型 | 说明 |
|---|---|---|
flags | HapticConfigFlags | 报告的标志字节,包含保留的未知位。 |
intensity | HapticIntensity | 当前强度百分比。 |
level_count | u8 | 回复字节 2 的低半字节。 |
level_step | u8 | 回复字节 2 的高半字节。 |
HapticIntensity
HapticIntensity::new(value) 接受 0~100。大于此范围时,它返回 None。get() 返回在线格式发送的百分比。
HapticStatus
HapticStatus 包装 fn 3 的原始状态字节。仅当值为 0 时,is_ready() 返回 true。其他值保持原始形式,因为其含义尚未确定。
事件
HapticFeedbackFeature 不实现 EmittingFeature。OpenLogi 不提供触感报告事件。
线格式
所有已实现请求均使用 3 字节短载荷。波形掩码为 BE u32。能力字节 0–3 的确切含义和完整的级别格式定义尚未确认。
get_capabilities(fn 0)
请求:[0x00, 0x00, 0x00]
| 字节 | 字段 | 备注 |
|---|---|---|
| 0–3 | unknown_prefix | 含义尚未确认。 |
| 4–7 | waveforms | BE u32;位 N 通告波形 ID N。 |
get_configuration(fn 1)
请求:[0x00, 0x00, 0x00]
| 字节 | 字段 | 备注 |
|---|---|---|
| 0 | flags | 位 0 是 ENABLED;位 1 是 POWER_SAVE;更高位会保留。Options+ 2.8 |
| 1 | intensity | 从 0 到 100 的百分比。 |
| 2 | 级别格式 | 高半字节是 level_step;低半字节是 level_count。完整语义尚未确认。 |
set_configuration(fn 2)
请求:[flags, intensity, 0x00]。
回复使用 fn 1 的配置布局。OpenLogi 会解码并返回它。回复是设备状态,不是假定的请求回显。
get_haptic_status(fn 3)
请求:[0x00, 0x00, 0x00]
| 字节 | 字段 | 备注 |
|---|---|---|
| 0 | 状态 | 0 表示就绪。任何非零值均表示未就绪。Options+ 2.8 |
play(fn 4)
请求:[waveform_id, 0x00, 0x00]。
字节 0 是波形 ID。Options+ 2.8 使用字节 1 请求波形信息报告。OpenLogi 写入 0,因为它不接收该报告。回复是确认。
stopHapticWaveForm(fn 5)
Logi Options+ 2.8 在检查播放状态后调用 fn 5,以停止波形。OpenLogi 不提供此函数。其请求和回复布局尚未确认。
getPlayingWaveForm(fn 6)
Logi Options+ 2.8 在决定停止波形前调用 fn 6。OpenLogi 不提供此函数。其请求和回复布局尚未确认。
报告
Logi Options+ 2.8 静态分析识别了两种非请求报告布局。OpenLogi 不解析这两种报告。
| 子 ID | 载荷 | 备注 |
|---|---|---|
| 0 | 字节 0 是触感状态。 | Options+ 2.8 |
| 1 | 2 个字节。 | 波形信息字段尚未确认。Options+ 2.8 |
OpenLogi 的用法
Actions Ring 会话开始时,OpenLogi 解析 0x19b0、读取能力掩码并读取触感状态。状态读取的时限为 250 ms。超时或读取错误会将状态视为未知,并允许播放。
如果掩码未通告波形,OpenLogi 会在发送前拒绝播放。如果成功读取的状态为非零,它也会拒绝播放。Actions Ring 在格位变化时使用 SubtleCollision,在激活动作时使用 DampStateChange。
启用路径会读取配置。如果 ENABLED 未置位且强度非零,它仅改变此位,并写入完整标志字节。它会保留 POWER_SAVE、未知标志位和强度。仅当返回的配置具有 ENABLED 时,它才接受此修复。
零强度表示用户关闭。自 v0.8.14 起,OpenLogi 不会将其替换为 25。取消 Actions Ring 只会取消会话。OpenLogi 没有 fn 5 停止操作或报告监听器。
未确认的细节
Options+ 将全局触感和每个事件来源作为播放条件。Actions Ring 启动时,OpenLogi 可以重新启用设备级 ENABLED 位。先前实现的证据表明,电源转换可能清除此位。硬件测试尚未证明它是否仅为临时启用状态。
会话关闭时,OpenLogi 不会恢复 ENABLED。它会保留其他配置位和强度。产品策略尚未确定:应在触感关闭时跳过反馈,还是使用会话级覆盖并恢复。
完整的字节 2 级别格式、fn 5 和 fn 6 的布局,以及波形信息报告字段都需要硬件抓包。配置标志的协议持久化边界也尚未确认。
Rust 用法
use hidpp::{
device::Device,
feature::{
haptic_feedback::{
HapticConfigFlags, HapticFeedbackFeature, HapticWaveform,
},
},
};
// `device` 已为 HID++ 通道和设备索引创建。
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<HapticFeedbackFeature>() {
let capabilities = feature.get_capabilities().await?;
let status = feature.get_haptic_status().await?;
if capabilities.waveforms.supports(HapticWaveform::SubtleCollision)
&& status.is_ready()
{
let configuration = feature.get_configuration().await?;
let applied = feature
.set_configuration(
configuration.flags | HapticConfigFlags::ENABLED,
configuration.intensity,
)
.await?;
if applied.flags.contains(HapticConfigFlags::ENABLED) {
feature.play(HapticWaveform::SubtleCollision).await?;
}
}
}