OpenLogi

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_info0()ThumbwheelInfo
get_thumbwheel_status1()ThumbwheelStatus
set_thumbwheel_reporting2(mode: ThumbwheelReportingMode, invert_direction: bool)()
listenevent()async_channel::Receiver<ThumbwheelEvent>

前三个方法是 async,并返回 Result<…, Hidpp20Error>。listen 是同步方法。

类型

ThumbwheelInfo

字段类型说明
native_resolutionu16原生 HID 模式中每圈的棘齿数。
diverted_resolutionu16转向 HID++ 模式中每圈的转动增量数。
time_unitu16time_elapsed 的微秒单位。没有 TIME_STAMP 时为 0。
default_directionThumbwheelDirection设备专属的正转方向。
capabilitiesThumbwheelCapabilities设备公布的能力位。未知位会保留。

ThumbwheelCapabilities

字段值说明
TIME_STAMP1 << 0事件报告经过时间。
TOUCH1 << 1滚轮报告触摸状态。
PROXY1 << 2滚轮报告近接状态。
SINGLE_TAP1 << 3滚轮报告单击。

ThumbwheelDirection

变体值说明
PositiveWhenLeftOrBack0对此设备方向,正转是向左或向后。
PositiveWhenRightOrFront1对此设备方向,正转是向右或向前。

ThumbwheelStatus

字段类型说明
reporting_modeThumbwheelReportingMode原生 HID 或转向 HID++ 上报。
direction_invertedbool默认方向已反转。
touchbool支持时的当前触摸状态。
proxybool支持时的当前近接状态。

ThumbwheelReportingMode

变体值说明
Native0仅通过原生 HID 上报。
Diverted1仅通过 HID++ 上报。listen 需要此模式。

事件

ThumbwheelFeature 实现 EmittingFeature<ThumbwheelEvent>。它只接受事件子 ID 0。

ThumbwheelEvent

变体说明
StatusUpdate(ThumbwheelStatusUpdate)一条转向滚轮状态更新。

ThumbwheelStatusUpdate

字段类型说明
rotationi16当前上报分辨率中的带符号转动增量。
time_elapsedu16以 ThumbwheelInfo::time_unit 为单位的经过时间。
rotation_statusThumbwheelRotationStatus转动生命周期状态。
touchbool当前触摸状态。
proxybool当前近接状态。
single_tapbool单击指示。

ThumbwheelRotationStatus

变体值说明
Inactive0滚轮没有转动。
Start1转动开始。
Active2转动继续。
Stop3转动结束。
Other(u8)其他包装器保留未建模的状态字节。

线格式

读取方法发送三个零字节。OpenLogi 读取其扩展响应负载。它忽略下表未列出的响应字节。

get_thumbwheel_info(fn 0)

字节字段备注
0–1native_resolutionu16,BE。
2–3diverted_resolutionu16,BE。
4 bit[0]default_direction0 = PositiveWhenLeftOrBack;1 = PositiveWhenRightOrFront。bits[7:1] 会被忽略。
5 bits[3:0]capabilitiesTIME_STAMP、TOUCH、PROXY 和 SINGLE_TAP。bits[7:4] 保留在位标志值中,但没有命名语义。
6–7time_unitu16,BE。
8–15—OpenLogi 忽略这些字节。

get_thumbwheel_status(fn 1)

字节字段备注
0reporting_mode0 = 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)

字节字段备注
0mode0 = Native;1 = Diverted。
1invert_direction0 = 默认方向;1 = 反转方向。
2—OpenLogi 总是写入 0x00。

OpenLogi 接受成功的传输响应,但不解码响应负载。

StatusUpdate 事件(fn 0)

字节字段备注
0–1rotationi16,BE。
2–3time_elapsedu16,BE。
4rotation_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:?}");
    }
}

本页目录