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_capabilities | 0 | () | SmartShiftEnhancedInfo |
get_ratchet_control_mode | 1 | () | SmartShiftEnhancedStatus |
set_ratchet_control_mode | 2 | (change: SmartShiftEnhancedStatusChange) | SmartShiftEnhancedStatus |
所有方法都是 async。所有方法都返回 Result<…, Hidpp20Error>。
类型
SmartShiftEnhancedInfo
| 字段 | 类型 | 说明 |
|---|---|---|
capabilities | SmartShiftEnhancedCapabilities | 能力位。OpenLogi 保留未知位。 |
auto_disengage_default | u8 | 默认自动脱开阈值。 |
default_tunable_torque | u8 | 默认扭矩,以最大力的百分比表示。 |
max_force | u8 | 最大力,单位为克力。 |
SmartShiftEnhancedStatus
| 字段 | 类型 | 说明 |
|---|---|---|
wheel_mode | WheelMode | 当前请求的滚轮模式。 |
auto_disengage | u8 | 当前自动脱开阈值。 |
current_tunable_torque | u8 | 当前扭矩,以最大力的百分比表示。 |
SmartShiftEnhancedStatusChange
None 在线路上编码为 0,表示不更改。
| 字段 | 类型 | 说明 |
|---|---|---|
wheel_mode | Option<WheelMode> | 要应用的滚轮模式,或用 None 保留现有模式。 |
auto_disengage | Option<NonZeroU8> | 要应用的阈值,或用 None 保留现有阈值。 |
tunable_torque | Option<NonZeroU8> | 要应用的扭矩字节,或用 None 保留现有扭矩。 |
SmartShiftEnhancedCapabilities
| 标志 | 位 | 说明 |
|---|---|---|
TUNABLE_TORQUE | 0 | 设备声明支持可调棘轮扭矩。 |
WheelMode
WheelMode 从 0x2110 smartShift 重新导出。
| 变体 | 值 | 说明 |
|---|---|---|
Freespin | 1 | 自由滚动模式。 |
Ratchet | 2 | 棘轮模式。 |
事件
此封装未声明事件。
线格式
三个封装方法都发送 3 字节 HID++ 短报告负载。每个封装在解析回复前调用 extend_payload()。因此,短回复会补零至 16 字节。协议封装不会验证回复长度。
get_capabilities(fn 0)
请求没有参数。OpenLogi 写入 [0x00, 0x00, 0x00]。
| 回复字节 | 字段 | 说明 |
|---|---|---|
| 0 | capabilities | 位 0 是 TUNABLE_TORQUE。OpenLogi 保留未知位。 |
| 1 | auto_disengage_default | 默认自动脱开阈值。 |
| 2 | default_tunable_torque | 默认扭矩,以最大力的百分比表示。 |
| 3 | max_force | 最大力,单位为克力。 |
| 4~15 | / | OpenLogi 没有对应字段。字节 4 参见未确认的细节。 |
get_ratchet_control_mode(fn 1)
请求没有参数。OpenLogi 写入 [0x00, 0x00, 0x00]。
| 回复字节 | 字段 | 说明 |
|---|---|---|
| 0 | wheel_mode | 1 = Freespin;2 = Ratchet。其他值返回 UnsupportedResponse。 |
| 1 | auto_disengage | 0x01~0xFE 是每秒四分之一转的阈值。0xFF 表示永久棘轮。 |
| 2 | current_tunable_torque | 0 表示没有扭矩级别。设备层接受 1~100 %,并拒绝更高值。 |
set_ratchet_control_mode(fn 2)
请求是 [wheel_mode, auto_disengage, tunable_torque]。
| 请求字节 | 来源 | 说明 |
|---|---|---|
| 0 | change.wheel_mode | None 编码为 0,以保留模式。1 选择自由滚动。2 选择棘轮。 |
| 1 | change.auto_disengage | None 编码为 0,以保留阈值。0x01~0xFE 是阈值。0xFF 选择永久棘轮。 |
| 2 | change.tunable_torque | None 编码为 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);
}