0x2150 · thumbwheel
查询和转向横向拇指轮,并接收其转动、触摸、近接和轻点状态。
0x2150 控制受支持 MX 鼠标的横向拇指轮。该功能报告滚轮能力和当前上报状态。转向上报会通过 HID++ 发送转动和触摸更新,而不通过原生 HID。
**规格:**Logitech HID++ 2.0 —— x2150 thumbwheel(v0)。**交叉核对:**Logi Options+ 2.8(静态分析)、Solaar。用于:滚动和重新映射按钮。
函数参考
ThumbwheelFeature 实现 feature 版本 0。
方法
| 函数 | HID++ fn | 签名 | 返回值 |
|---|---|---|---|
get_thumbwheel_info | 0 | () | ThumbwheelInfo |
get_thumbwheel_status | 1 | () | ThumbwheelStatus |
set_thumbwheel_reporting | 2 | (mode: ThumbwheelReportingMode, invert_direction: bool) | () |
listen | event | () | async_channel::Receiver<ThumbwheelEvent> |
前三个方法是 async,并返回 Result<…, Hidpp20Error>。listen 是同步方法。
类型
ThumbwheelInfo
| 字段 | 类型 | 说明 |
|---|---|---|
native_resolution | u16 | 原生 HID 模式中每圈的棘齿数。 |
diverted_resolution | u16 | 转向 HID++ 模式中每圈的转动增量数。 |
time_unit | u16 | time_elapsed 的微秒单位。没有 TIME_STAMP 时为 0。 |
default_direction | ThumbwheelDirection | 设备专属的正转方向。 |
capabilities | ThumbwheelCapabilities | 设备公布的能力位。未知位会保留。 |
ThumbwheelCapabilities
| 字段 | 值 | 说明 |
|---|---|---|
TIME_STAMP | 1 << 0 | 事件报告经过时间。 |
TOUCH | 1 << 1 | 滚轮报告触摸状态。 |
PROXY | 1 << 2 | 滚轮报告近接状态。 |
SINGLE_TAP | 1 << 3 | 滚轮报告单击。 |
ThumbwheelDirection
| 变体 | 值 | 说明 |
|---|---|---|
PositiveWhenLeftOrBack | 0 | 对此设备方向,正转是向左或向后。 |
PositiveWhenRightOrFront | 1 | 对此设备方向,正转是向右或向前。 |
ThumbwheelStatus
| 字段 | 类型 | 说明 |
|---|---|---|
reporting_mode | ThumbwheelReportingMode | 原生 HID 或转向 HID++ 上报。 |
direction_inverted | bool | 默认方向已反转。 |
touch | bool | 支持时的当前触摸状态。 |
proxy | bool | 支持时的当前近接状态。 |
ThumbwheelReportingMode
| 变体 | 值 | 说明 |
|---|---|---|
Native | 0 | 仅通过原生 HID 上报。 |
Diverted | 1 | 仅通过 HID++ 上报。listen 需要此模式。 |
事件
ThumbwheelFeature 实现 EmittingFeature<ThumbwheelEvent>。它只接受事件子 ID 0。
ThumbwheelEvent
| 变体 | 说明 |
|---|---|
StatusUpdate(ThumbwheelStatusUpdate) | 一条转向滚轮状态更新。 |
ThumbwheelStatusUpdate
| 字段 | 类型 | 说明 |
|---|---|---|
rotation | i16 | 当前上报分辨率中的带符号转动增量。 |
time_elapsed | u16 | 以 ThumbwheelInfo::time_unit 为单位的经过时间。 |
rotation_status | ThumbwheelRotationStatus | 转动生命周期状态。 |
touch | bool | 当前触摸状态。 |
proxy | bool | 当前近接状态。 |
single_tap | bool | 单击指示。 |
ThumbwheelRotationStatus
| 变体 | 值 | 说明 |
|---|---|---|
Inactive | 0 | 滚轮没有转动。 |
Start | 1 | 转动开始。 |
Active | 2 | 转动继续。 |
Stop | 3 | 转动结束。 |
Other(u8) | 其他 | 包装器保留未建模的状态字节。 |
线格式
读取方法发送三个零字节。OpenLogi 读取其扩展响应负载。它忽略下表未列出的响应字节。
get_thumbwheel_info(fn 0)
| 字节 | 字段 | 备注 |
|---|---|---|
| 0–1 | native_resolution | u16,BE。 |
| 2–3 | diverted_resolution | u16,BE。 |
4 bit[0] | default_direction | 0 = PositiveWhenLeftOrBack;1 = PositiveWhenRightOrFront。bits[7:1] 会被忽略。 |
5 bits[3:0] | capabilities | TIME_STAMP、TOUCH、PROXY 和 SINGLE_TAP。bits[7:4] 保留在位标志值中,但没有命名语义。 |
| 6–7 | time_unit | u16,BE。 |
| 8–15 | — | OpenLogi 忽略这些字节。 |
get_thumbwheel_status(fn 1)
| 字节 | 字段 | 备注 |
|---|---|---|
| 0 | reporting_mode | 0 = Native;1 = Diverted。其他值返回 Hidpp20Error::UnsupportedResponse。 |
1 bit[0] | direction_inverted | 设置时表示默认方向已反转。 |
1 bit[1] | touch | 当前触摸状态。 |
1 bit[2] | proxy | 当前近接状态。 |
1 bits[7:3]、2–15 | — | OpenLogi 忽略这些位和字节。 |
set_thumbwheel_reporting(fn 2)
| 字节 | 字段 | 备注 |
|---|---|---|
| 0 | mode | 0 = Native;1 = Diverted。 |
| 1 | invert_direction | 0 = 默认方向;1 = 反转方向。 |
| 2 | — | OpenLogi 总是写入 0x00。 |
OpenLogi 接受成功的传输响应,但不解码响应负载。
StatusUpdate 事件(fn 0)
| 字节 | 字段 | 备注 |
|---|---|---|
| 0–1 | rotation | i16,BE。 |
| 2–3 | time_elapsed | u16,BE。 |
| 4 | rotation_status | 值 0–3 映射到命名变体。其他值成为 Other(u8)。 |
5 bit[1] | touch | 触摸状态。 |
5 bit[2] | proxy | 近接状态。 |
5 bit[3] | single_tap | 单击指示。 |
5 bit[0]、bits[7:4]、6–15 | — | OpenLogi 忽略这些位和字节。 |
OpenLogi 的用法
设备层使用自己的 0x2150 访问器进行捕获。它会在转向滚轮前读取 getThumbwheelInfo 和 getThumbwheelStatus。随后,它根据 default_direction 统一转动极性,并把转向增量缩放为原生分辨率。
自 v0.8.14 起,PR #1753 会在转向前读取先前状态。退出时,OpenLogi 恢复原生上报。只有先前模式是原生模式时,它才保留先前的反转状态。恢复失败会保持待恢复状态,并在当前设备路由上重试。
捕获路径把非零转动转为滚动。如果当前状态正在转动,或先前状态是 Start 或 Active,它会抑制零转动轻点。稳定状态的 single_tap 会成为 Thumbwheel 按钮脉冲。
未确认的细节
类型化包装器把未知事件状态保留为 Other(u8)。设备捕获访问器却把未知状态归为 Inactive。因此,带有 single_tap 的零转动未知状态更新仍可能成为按钮脉冲。尚无硬件抓包验证此组合。
如果 getThumbwheelInfo 失败,捕获路径仍会转向滚轮。它随后使用默认极性和未缩放的 1.0 分辨率比率。尚未在硬件上验证此回退是否安全。
Rust 用法
use hidpp::{
device::Device,
feature::{
EmittingFeature,
thumbwheel::{ThumbwheelFeature, ThumbwheelReportingMode},
},
};
// device: &mut Device, already created via Device::new(channel, index)
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<ThumbwheelFeature>() {
let info = feature.get_thumbwheel_info().await?;
println!("{} / {}", info.native_resolution, info.diverted_resolution);
feature
.set_thumbwheel_reporting(ThumbwheelReportingMode::Diverted, false)
.await?;
let receiver = feature.listen();
while let Ok(event) = receiver.recv().await {
println!("{event:?}");
}
}