OpenLogi

0x2111 · smartShiftEnhanced

读取或更新 SmartShift Enhanced 滚轮的模式、自动脱开阈值和可调棘轮扭矩。

smartShiftEnhanced 控制较新的 SmartShift 滚轮,包括 MX Master 3、3S 和 4。OpenLogi 会先使用此功能,然后才考虑回退到旧版 0x2110 smartShift。

**规格:**Logitech HID++ 2.0 —— x2111 smartShift Enhanced。**交叉核对:**Logi Options+ 2.8(静态分析)、Solaar。用于:SmartShift。

函数参考

SmartShiftEnhancedFeature 是功能 0x2111 的版本 0 封装。

方法

函数HID++ fn签名返回值
get_capabilities0()SmartShiftEnhancedInfo
get_ratchet_control_mode1()SmartShiftEnhancedStatus
set_ratchet_control_mode2(change: SmartShiftEnhancedStatusChange)SmartShiftEnhancedStatus

所有方法都是 async。所有方法都返回 Result<…, Hidpp20Error>。

类型

SmartShiftEnhancedInfo

字段类型说明
capabilitiesSmartShiftEnhancedCapabilities能力位。OpenLogi 保留未知位。
auto_disengage_defaultu8默认自动脱开阈值。
default_tunable_torqueu8默认扭矩,以最大力的百分比表示。
max_forceu8最大力,单位为克力。

SmartShiftEnhancedStatus

字段类型说明
wheel_modeWheelMode当前请求的滚轮模式。
auto_disengageu8当前自动脱开阈值。
current_tunable_torqueu8当前扭矩,以最大力的百分比表示。

SmartShiftEnhancedStatusChange

None 在线路上编码为 0,表示不更改。

字段类型说明
wheel_modeOption<WheelMode>要应用的滚轮模式,或用 None 保留现有模式。
auto_disengageOption<NonZeroU8>要应用的阈值,或用 None 保留现有阈值。
tunable_torqueOption<NonZeroU8>要应用的扭矩字节,或用 None 保留现有扭矩。

SmartShiftEnhancedCapabilities

标志位说明
TUNABLE_TORQUE0设备声明支持可调棘轮扭矩。

WheelMode

WheelMode 从 0x2110 smartShift 重新导出。

变体值说明
Freespin1自由滚动模式。
Ratchet2棘轮模式。

事件

此封装未声明事件。

线格式

三个封装方法都发送 3 字节 HID++ 短报告负载。每个封装在解析回复前调用 extend_payload()。因此,短回复会补零至 16 字节。协议封装不会验证回复长度。

get_capabilities(fn 0)

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

回复字节字段说明
0capabilities位 0 是 TUNABLE_TORQUE。OpenLogi 保留未知位。
1auto_disengage_default默认自动脱开阈值。
2default_tunable_torque默认扭矩,以最大力的百分比表示。
3max_force最大力,单位为克力。
4~15/OpenLogi 没有对应字段。字节 4 参见未确认的细节。

get_ratchet_control_mode(fn 1)

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

回复字节字段说明
0wheel_mode1 = Freespin;2 = Ratchet。其他值返回 UnsupportedResponse。
1auto_disengage0x01~0xFE 是每秒四分之一转的阈值。0xFF 表示永久棘轮。
2current_tunable_torque0 表示没有扭矩级别。设备层接受 1~100 %,并拒绝更高值。

set_ratchet_control_mode(fn 2)

请求是 [wheel_mode, auto_disengage, tunable_torque]。

请求字节来源说明
0change.wheel_modeNone 编码为 0,以保留模式。1 选择自由滚动。2 选择棘轮。
1change.auto_disengageNone 编码为 0,以保留阈值。0x01~0xFE 是阈值。0xFF 选择永久棘轮。
2change.tunable_torqueNone 编码为 0,以保留扭矩。原始封装接受任意 NonZeroU8。OpenLogi 设备层只提供 1~100 %。

回复采用 getter 的布局。原始封装返回解析后的状态。设备层将每个写入字段与回显值比较。

OpenLogi 的用法

OpenLogi 先探测 0x2111。如果功能缺失,OpenLogi 会再次探测,然后回退到 0x2110。其他功能错误、传输错误和协议错误会继续返回。两个功能封装都注册为版本 0。

切换模式时,OpenLogi 读取当前状态,再写入相反模式。更新灵敏度时,OpenLogi 读取状态,再写入当前模式和新阈值。这两种操作都将扭矩字节 2 写为 0,所以会保留扭矩。显式更新扭矩时,OpenLogi 将字节 0~1 写为 0。

OpenLogi 会在写入显式扭矩值前读取能力。只有位 0 是 TUNABLE_TORQUE 时,OpenLogi 才发送非零扭矩。没有此位时,模式或阈值写入仍会成功,且字节 2 为 0。显式扭矩请求会返回 FeatureUnsupported。

TunableTorque 将 OpenLogi 的设备、配置和 IPC 值限制为 1~100 %。状态回复为 0 时,OpenLogi 将其视为没有扭矩值。状态回复大于 100 时,OpenLogi 返回 UnsupportedResponse。完整的已保存配置只在扭矩不同于当前值时写入扭矩。

只有设备回复匹配每个写入字段时,设备层才接受写入。发生瞬态错误时,设备层会用相同目标重试一次。桌面端随后再次读取状态,并比较完整值。SmartShift 状态是易失状态,因此 OpenLogi 会保存设置,并在重连后重新应用。应用退出时,OpenLogi 不会恢复之前的 SmartShift 状态。

未确认的细节

  • Options+ 2.8 的低层能力 getter 可能有第五个输出字节。其高层调用者只使用字节 0~3。OpenLogi 也只使用字节 0~3。没有公开规格或硬件抓包能确定字节 4 的含义。
  • 已审阅的来源没有确定 SmartShift 专用 HID++ 通知布局。OpenLogi 没有为此功能定义事件类型。

Rust 用法

use hidpp::{
    device::Device,
    feature::{
        smartshift::WheelMode,
        smartshift_enhanced::{
            SmartShiftEnhancedFeature,
            SmartShiftEnhancedStatusChange,
        },
    },
};
use std::num::NonZeroU8;

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

    let applied = feature
        .set_ratchet_control_mode(SmartShiftEnhancedStatusChange {
            wheel_mode: Some(WheelMode::Ratchet),
            auto_disengage: NonZeroU8::new(16),
            tunable_torque: None,
        })
        .await?;
    println!("applied mode: {:?}", applied.wheel_mode);
}

本页目录