0x2110 · smartShift – OpenLogi Docs

旧版 smartShift 功能控制滚轮的自由滚动或棘轮模式。例如，MX Master 2S 使用此功能。较新的 SmartShift 滚轮使用 0x2111 smartShiftEnhanced。

**规格：**Logitech HID++ 2.0 —— smartShift。**交叉核对：**Logi Options+ 2.8（静态分析）、Solaar。用于：SmartShift。

函数参考

SmartShiftFeature 是功能 0x2110 的版本 0 封装。

方法

函数	HID++ fn	签名	返回值
`get_ratchet_control_mode`	0	`()`	`RatchetControlMode`
`set_ratchet_control_mode`	1	`(wheel_mode: Option<WheelMode>, auto_disengage: Option<NonZeroU8>, auto_disengage_default: Option<NonZeroU8>)`	`RatchetControlMode`

两种方法都是 async。两种方法都返回 Result<…, Hidpp20Error>。

类型

`RatchetControlMode`

字段	类型	说明
`wheel_mode`	`WheelMode`	软件或按钮选择的滚轮模式。此字段不表示瞬时自动脱开。
`auto_disengage`	`u8`	自动脱开阈值。`0xFF` 表示永久棘轮。
`auto_disengage_default`	`u8`	OpenLogi 建模的默认阈值。参见未确认的细节。

`WheelMode`

变体	值	说明
`Freespin`	`1`	自由滚动模式。
`Ratchet`	`2`	棘轮模式。

事件

此封装未声明事件。

线格式

每次封装调用都发送 3 字节 HID++ 短报告负载。FeatureEndpoint::call() 固定使用此负载长度。封装在解析回复前调用 extend_payload()。因此，短回复会补零至 16 字节，而不会进行长度验证。

`get_ratchet_control_mode`（fn 0）

请求没有参数。OpenLogi 写入 [0x00, 0x00, 0x00]。

回复字节	字段	说明
0	`wheel_mode`	`1` = `Freespin`；`2` = `Ratchet`。其他值返回 `UnsupportedResponse`。
1	`auto_disengage`	`0x01`～`0xFE` 是每秒四分之一转的阈值。`0xFF` 表示永久棘轮。
2	`auto_disengage_default`	OpenLogi 将此字段解析为默认阈值。Options+ 2.8 和 Solaar 只使用字节 0～1。

`set_ratchet_control_mode`（fn 1）

请求是 [wheel_mode, auto_disengage, auto_disengage_default]。

请求字节	来源	说明
0	`wheel_mode`	`None` 编码为 `0`，以保留当前模式。`1` 选择自由滚动。`2` 选择棘轮。
1	`auto_disengage`	`None` 编码为 `0`，以保留阈值。`0x01`～`0xFE` 是阈值。`0xFF` 选择永久棘轮。
2	`auto_disengage_default`	`None` 编码为 `0`。设备层始终传入 `None`，所以写入 `0`。直接调用封装可以发送非零值。

OpenLogi 用 getter 的布局解析回复，并返回 RatchetControlMode。设备层将字节 0～1 与写入字段比较。原始封装返回回复，但不执行该比较。

OpenLogi 的用法

OpenLogi 先探测 0x2111。如果功能缺失，OpenLogi 会再次探测，然后回退到 0x2110。传输错误和协议错误不会触发回退。两个功能封装都没有版本 0 以外的版本门控。

设备层会在更新灵敏度或切换模式前读取当前状态。设备层同时写入所选模式和阈值。设备层始终将字节 2 写为 0。所以在 OpenLogi 的模型中，设备会保留该字段。只有回显的模式和阈值匹配时，设备层才接受写入。发生瞬态错误时，设备层会用相同目标重试一次。

桌面端会在每次面板写入后再次读取。只有完整返回状态匹配时，桌面端才标记写入成功。SmartShift 状态是易失状态，因此 OpenLogi 会保存设置，并在重连后重新应用。应用退出时，OpenLogi 不会恢复之前的 SmartShift 状态。

未确认的细节

OpenLogi 及其引用的 HID++ 来源将字节 2 建模为 auto_disengage_default。Options+ 2.8 和 Solaar 只发送和使用两个语义字节。没有硬件抓包或公开来源能确定字节 2 是有效字段、保留字节，还是实现专有扩展。因此，OpenLogi 在原始封装中公开此字段，但设备层写入 0。
已审阅的来源没有确定 SmartShift 专用 HID++ 通知布局。OpenLogi 没有为此功能定义事件类型。

Rust 用法

use hidpp::{
    device::Device,
    feature::smartshift::{SmartShiftFeature, WheelMode},
};
use std::num::NonZeroU8;

// `device` 是已初始化的 `&mut Device`。
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<SmartShiftFeature>() {
    let current = feature.get_ratchet_control_mode().await?;
    println!("current mode: {:?}", current.wheel_mode);

    let applied = feature
        .set_ratchet_control_mode(
            Some(WheelMode::Freespin),
            NonZeroU8::new(16),
            None,
        )
        .await?;
    println!("applied threshold: {}", applied.auto_disengage);
}

0x2110 · smartShift

本页目录